arm_dev
02516fe567
两条独立的静默坑，都不报错、不告警，只会"永远收不到数据"：
1) world 里没声明 contact-system 系统插件。
gz-sim 的 <sensor type="contact"> 不由 ignition-sensors 库实现，而是由
ignition-gazebo6-contact-system 插件实现 —— 所以环境里根本没有
libignition-sensors6-contact.so（相机/IMU/lidar 的后端都在，唯独缺它），
那不是包缺失。不声明插件的症状：话题不出现、日志空白。
实测：加上插件后 /tactile/left/raw、/tactile/right/raw 立刻出现。
2) 接触传感器的三个必备写法，错一个就静默失效：
- <contact><collision> 必须写 URDF→SDF 自动生成的 collision 名；
留空 <contact/> 会被补成 SDF 规范的默认值 __default__（不存在的
collision）。实测生成名：
sim_left_finger_mount_fixed_joint_lump__sim_left_finger_tip_collision
- 话题必须写在 <contact><topic> 里，写在外层 <sensor><topic> 无效，
gz 会静默改用默认 scoped 话题名。
- 传感器必须挂在有碰撞体的 link 上（指尖），不是另建的空 link。
两处均已按实测结果修正，并把"为什么这么写"写进文件注释。
Co-authored-by: Cursor <cursoragent@cursor.com>
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. 一个新品牌要接进来，只需要四步
- 丢物料：把厂商的 RDK / SDK / 驱动包放进
<类别>/<品牌>/下对应文件夹 （格式和命名要求写在该类别的README.md里，必须按它要求放）。 - 填 manifest：复制同类别的
manifest.yaml改四个字段（id / label / driver.package / config_schema）。 - 写适配器：在
driver/下实现框架的接口契约（见src/arm_interfaces/）。 这一步的工作量取决于厂商 —— 如果厂商本来就提供符合契约的 ROS 2 驱动，这一步几乎为零。 - 改一行选型：把
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 个节点没声明的参数、调参静默失效」那类问题的机制。