arm_dev
6edb8d39ab
在开始'设备契约层 + 目录重构 + 通止规装配'改造之前，先钉住当前可运行状态， 使后续任何删除/重构都可回退。 本基线包含： - 现有 ROS 2 工作区全部源码（arm_application / arm_control / arm_bringup 等） - 官方 flexiv_ros2 栈（含 flexiv_hardware / flexiv_controllers 等符号链接） - 设备契约层 src/arm_interfaces（新增，46 项单测通过） - devices/ 设备选型与品牌清单（新增） - scripts/gen_site_example.py 与由它生成的 config/site.example.yaml 按 .gitignore 排除：build/ / install/ / log/ / config/site.yaml / 模型权重二进制。
63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
# devices/ —— 设备与外部文件总目录
|
||
|
||
这个目录存在的唯一目的：**把「换个硬件」从改代码变成改配置**。
|
||
|
||
## 设计原则（务必先读）
|
||
|
||
### 1. 选型与数值分离
|
||
|
||
| 关注点 | 放在哪 | 谁改 |
|
||
|--------|--------|------|
|
||
| **用哪个品牌的哪个驱动** | `devices/registry.yaml` | 集成工程师（很少改） |
|
||
| **设备号 / 速度 / 阈值 / 悬高** | `config/site.yaml` | 现场操作人员（经常改） |
|
||
|
||
**`devices/` 下不允许出现任何现场数值。** 数值只有 `config/site.yaml` 一个来源。
|
||
这样可以避免现在这种「同一个值三处定义、改了不生效」的问题。
|
||
|
||
### 2. 目录约定
|
||
|
||
```
|
||
devices/
|
||
├── registry.yaml # 选型开关（唯一入口）
|
||
├── robots/ # 机械臂：RDK + 适配器
|
||
├── grippers/ # 夹爪
|
||
├── sensors/
|
||
│ └── orisys/ # ★ 视触觉核心，长期迭代，单独占一个大文件夹
|
||
├── cameras/ # 相机
|
||
└── sim/ # 仿真平台（当前 Gazebo）
|
||
```
|
||
|
||
每个品牌一个子目录，子目录内固定结构：
|
||
|
||
```
|
||
<类别>/<品牌>/
|
||
├── manifest.yaml # 我是谁 / 支持什么能力 / 需要哪些配置 / 外部文件放哪
|
||
├── driver/ # 适配器（把厂商 API 翻译成框架接口）
|
||
└── <厂商物料>/ # 如 rdk/、sdk/，原样放置，不要改名
|
||
```
|
||
|
||
### 3. 一个新品牌要接进来，只需要四步
|
||
|
||
1. **丢物料**：把厂商的 RDK / SDK / 驱动包放进 `<类别>/<品牌>/` 下对应文件夹
|
||
（格式和命名要求写在该类别的 `README.md` 里，**必须按它要求放**）。
|
||
2. **填 manifest**：复制同类别的 `manifest.yaml` 改四个字段（id / label / driver.package / config_schema）。
|
||
3. **写适配器**：在 `driver/` 下实现框架的接口契约（见 `src/arm_interfaces/`）。
|
||
这一步的工作量取决于厂商 —— 如果厂商本来就提供符合契约的 ROS 2 驱动，这一步几乎为零。
|
||
4. **改一行选型**：把 `registry.yaml` 里对应类别的值改成新品牌 id。
|
||
|
||
> **诚实说明**：第 3 步无法完全避免。Flexiv 的 RDK 是 C++/Python 库而不是 ROS 2 驱动，
|
||
> 所以它外面永远需要一层薄适配器。框架能做的是把这层适配器写到最薄（只做 API 翻译，
|
||
> 不含任何业务逻辑），而不是让你零代码接入。
|
||
|
||
### 4. 启动时的校验
|
||
|
||
框架启动会依次读 `registry.yaml` → 各 `manifest.yaml` → `config/site.yaml`，
|
||
校验三件事：
|
||
|
||
- 选中的品牌目录存在，且 `manifest.yaml` 可解析；
|
||
- manifest 里 `assets` 声明的必需物料文件都在；
|
||
- `config_schema` 里标记 `required: true` 的配置键，在 `site.yaml` 里都有值。
|
||
|
||
任何一项不满足**立即报错并明确指出该去哪个文件补什么**，不允许静默降级。
|
||
这是替代现在「`run_handeye.sh` 传了 5 个节点没声明的参数、调参静默失效」那类问题的机制。
|