arm_dev
36a59c81bf
三处都是"看着像硬件问题、其实是判据问题"的假警报：
1. S00 自检假阴性（gauge_boot.py）
探测等待时用 time.sleep 不 spin → 订阅回调根本没机会执行，
于是**健康的硬件也会被判"没有数据"**。改成等待期间持续 spin。
2. S07 触觉假断流（stage3_search_node.py）
判据原本是 |fnormal| > 1.0，但力本来就可能是零或很小（真机轻触、
仿真刚接触）→ 明明在发数据却判"触觉断流"。
改成"数据够新（TACTILE_MAX_AGE_S 内）+ connected" —— 判活看的是
**有没有在发**，不是**数值大不大**。
3. S07 下探静默卡死（gauge_fsm.py / gauge_assembly_node.py）
_goto 的到位容差 ≥ 步长时，每一步都被判成"已在容差内"，臂一步都不走，
而外层只看到"没进度"→ 死循环到超时，日志里看不出原因。
新增 descend_tol_m / descend_iter_budget / descend_progress：
容差从步长推导（不该手工调大），并显式判"连续 N 步零位移"。
容差 ≥ 步长的反例已进 site 回归测试，防止再犯。
4. site 分段化（export_site_env.py）：89/91 两臂的 servo/handeye/点位
各一段，避免"改 91 影响 89"。
另：run_unit_tests.sh 作为统一测试入口（932→933 项），
devices/sim/gazebo/README.md 同步。
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 个节点没声明的参数、调参静默失效」那类问题的机制。