arm_dev
ddf30e57f8
现象（非常隐蔽，容易被误判成阈值问题）：
通止规的通端长 30mm，工件是 12mm 厚板、孔是**贯通孔** —— 真机上通端要
穿过板再伸出去 18mm，靠**台肩落到工件上表面**那一下判"到底了"。
但台面原本是一整块、工件平放在上面 → 孔下方被堵死，规只能进 12mm 就顶
在台面上。于是 S07 一路压到上限都等不到台肩落面的大接触力，报
"下探 N mm 都没触发接触判据"然后 ABORT。
力也不是完全没有（顶台面时切向读 30~45N），所以看起来像"阈值调太高"。
修法：台面沿 Y 开一道 90mm 宽通槽（|y| ≤ 45mm），南北两块各留 5mm 承压面
（工件 100mm 宽，跨在槽上；板是刚体只受重力，够用）。桌腿视觉同步分两块，
别把通槽在画面上堵回去。槽**只开在工件孔位所在的 Y 带**，台面高度一点没动
→ 相机距离、孔检测像素门槛、site 的悬停高度全都不用改。
顺带：contact_max_depth_mm 25 → 35。判"到底了"的是台肩，而台肩在规尖上方
30mm（通端长 30），25mm 的上限**根本到不了**，只会白报超时。
35 = 30（台肩落面）+ 5（对位残差/板厚公差余量）。
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 个节点没声明的参数、调参静默失效」那类问题的机制。