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 / 模型权重二进制。
devices/robots/ —— 机械臂
厂商物料放置要求
每个品牌一个子目录，物料放在该子目录下的 rdk/（或厂商自定的物料目录，须在 manifest.yaml
的 assets 里声明）。
通用要求：
| 项 | 要求 |
|---|---|
| 格式 | 厂商原始发布格式，不要自行转换、不要重新打包成 zip/tar 后不展开 |
| 命名 | 保持厂商原目录名和原文件名，一律不要改名。改名会导致 RDK 内部的 include 路径、CMake 查找路径、Python 包名全部失效 |
| 版本 | 在 manifest.yaml 的 version 字段里记录版本号，方便日后排查 |
| 编译产物 | 不要把编译产物（.a .so build/）提交进 git；离线库放 vendor/ |
| 生效 | 放好物料 → 编译一次 → 改 devices/registry.yaml 选型 → 重启 scripts/run_real.sh |
目录结构
robots/
├── README.md
├── flexiv/ # 非夕（当前在用）
│ ├── manifest.yaml
│ ├── rdk/ # 厂商 RDK 源码或安装包，原样放置
│ └── driver/ # 适配器：把 RDK API 翻译成框架接口
└── <新品牌>/
├── manifest.yaml
├── rdk/ 或 sdk/
└── driver/
适配器必须实现的接口契约
框架上层（伺服、跟踪、装配状态机、手眼标定）只调用下面这组接口，不认识任何厂商 SDK。
契约定义在 src/arm_interfaces/，每个方法对应的 ROS 2 话题/服务/action 也在那里声明。
| 能力 | 用途 | 谁在用 |
|---|---|---|
get_arm_state |
读关节角 + 末端位姿 | 手眼标定、状态记录 |
follow_joint_trajectory |
关节轨迹（点到点、多路点） | 手眼标定走点、装配移动 |
servo_joint |
高频关节伺服 | 视觉伺服 servo_node |
servo_cartesian |
笛卡尔位姿伺服 | 跟踪、悬停 |
compliant_descent |
柔顺下臂（接触力约束） | 装配接触阶段 |
set_tool / switch_tool |
设置/切换工具坐标系（如 tool1） | 全局工具系锁定 |
home |
回到初始位姿 | 每个循环开始、异常复位 |
enable / clear_fault |
使能、清故障 | 启动自检、异常恢复 |
缺哪个能力就在 manifest 的 capabilities 里不写哪个，框架启动时会检查上层要用的能力是否都被支持，
不支持就明确报错，而不是运行时莫名其妙失败。
当前状态（迁移参考）
非夕臂的现有实现分散在这些地方，P1 之后会收敛到 flexiv/driver/ 下：
- 硬件接口：
src/flexiv_hardware/（ros2_control 插件，上游官方） - bringup：
src/arm_bringup/stack.launch.py的backend:=real分支 - 轨迹适配：
src/arm_control/arm_control/real_trajectory_adapter.py - 几何 IK 与手眼加载：
src/arm_application/arm_application/geom_ik.py - 软拖拽：
scripts/rdk_drag_bridge.py - 工具系切换：
scripts/rdk_switch_tool.py