# 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`