# 对外接口

三层：操作员脚本、ROS 话题/服务、可 import 的 Python。业务代码不要直接调 `rizon_arm_controller`。

---

## 1. 操作员脚本（推荐）

所有脚本在 `scripts/`。先 `source scripts/env.sh`。

| 脚本 | 输入 | 输出 / 行为 |
|------|------|-------------|
| `env.sh` | — | conda + Humble + `install/setup.bash` + `SITE_*` |
| `build_all.sh` | 源码 | colcon 编 `arm_*` + `flexiv_*` |
| `run_real.sh [--sn SN]` | `site.yaml` robot | 实机 stack，`backend:=real` |
| `run_camera_d405.sh [--preview]` | `camera.*` | 发布图像；可选 Qt 四宫格 |
| `run_visual_servo_rt.sh [--control]` | `paths` `yolo` `servo` | perception + servo + 手眼 TF |
| `go_home.sh` | `go_home.*` | 杀伺服后 `/set_named_pose` |
| `run_handeye.sh teach\|merge\|calibrate\|show` | `handeye.*` | 示教 / 写入 poses / 解 T |
| `run_gripper.sh --arm 89\|91 --cli …` | `robots[].gripper` + `gripper.*` | PGEA / RGI Modbus |
| `run_dual_gripper.sh` | 两侧 `robots[].gripper` | 双爪 ROS 节点 |
| `run_hole_detect.sh --arm …` | `hole_detect.*` `camera` | 入孔像素 |
| `run_tactile.sh [--cli]` | `tactile.*` | Orisys 左右指 |
| `export_yolo_trt.sh [onnx] [imgsz]` | 权重 | 同名 `.engine` |
| `show_site_config.sh` | `site.yaml` | 打印解析结果 |
| `rdk_switch_tool.sh --list` | SN | Studio 工具列表 |
| `run_sim.sh` | — | mock stack |
| `convert_traj.sh FILE.traj` | Flexiv 轨迹 | `*_trajectory.yaml` |

环境变量契约由 `scripts/lib/export_site_env.py` 定义：`flatten()`、`perception_overrides()`、`servo_overrides()`、`gripper_overrides()`。

---

## 2. ROS 接口（稳定）

### 机械臂（`run_real.sh`）

| 名称 | 类型 | 方向 | 说明 |
|------|------|------|------|
| `/set_named_pose` | `arm_msgs/srv/SetNamedPose` | 应用 → 控制 | `home` `ready` `inspect` `pos_left` |
| `/get_arm_state` | `arm_msgs/srv/GetArmState` | 查询 | 关节 + EE 位姿 |
| `/arm_status` | `arm_msgs/msg/ArmStatus` | 状态 | 模式 / 是否在动 |
| `/follow_joint_trajectory` | `arm_msgs/action/FollowJointTrajectory` | 应用 → 适配器 | 应用只走这个 |
| `/rizon_arm_controller/joint_trajectory` | `trajectory_msgs/JointTrajectory` | 伺服 → 驱动 | **仅 servo_node 写** |
| `/joint_states` | `sensor_msgs/JointState` | 驱动 → 全局 | |
| `/tf` `/tf_static` | TF | | 基座 / 连杆 / 法兰 / 手眼 |

命名位姿表：`src/arm_control/config/named_poses.yaml`。

```bash
ros2 service call /set_named_pose arm_msgs/srv/SetNamedPose \
  "{pose_name: 'home', velocity_scale: 0.25, acceleration_scale: 0.25}"
```

### 相机（`realsense_color_pub`）

| 话题 | 类型 | 说明 |
|------|------|------|
| `/d405/color/image_raw` | `sensor_msgs/Image` bgr8 | 彩图 |
| `/d405/color/camera_info` | `sensor_msgs/CameraInfo` | 内参 |
| `/d405/aligned_depth_to_color/image_raw` | `sensor_msgs/Image` 16UC1 | 对齐深度，毫米 |

`d405` 来自 `camera.name`。QoS：SensorData（BEST_EFFORT）。

### 感知 / 伺服

| 名称 | 类型 | 说明 |
|------|------|------|
| `/visual_servo/filtered_point` | `geometry_msgs/PointStamped` | 相机系工件点，perception → servo |
| `/workpiece/detection` | `std_msgs/Float32MultiArray` | `[x1,y1,x2,y2,conf,cls,cx,cy,z]`，空=清绿框 |
| `/cmd_vel` | `geometry_msgs/Twist` | 伺服调试用，真机动臂走轨迹 |

`PointStamped.header.frame_id` = `d405_color_optical_frame`。

### 夹爪（IPC Modbus，`arm_msgs`）

PGEA 单爪节点（`--arm 89` 无 `--cli`）：

| 服务 | 类型 |
|------|------|
| `/gripper/open` | `std_srvs/srv/Trigger` |
| `/gripper/close` | `std_srvs/srv/Trigger` |

双爪 / 右爪 RGI：

| 名称 | 类型 |
|------|------|
| `/dual_gripper_driver/{left,right}/command` | `arm_msgs/msg/GripperCommand` |
| `/dual_gripper_driver/{left,right}/status` | `arm_msgs/msg/GripperStatus` |
| `/dual_gripper_driver/{left,right}/execute` | `arm_msgs/srv/GripperExecute` |

开合力/速在 `site.yaml` → `gripper` 与 `robots[].gripper`。

### 入孔检测（`hole_detect`）

| 话题 | 类型 |
|------|------|
| `/hole_detect/result` | `arm_msgs/msg/HoleDetections` |
| `/hole_detect/holes` | `std_msgs/Float32MultiArray` |
| `/hole_detect/overlay` | `sensor_msgs/Image` |

### 视触觉（`tactile` 节点）

| 话题 | 类型 |
|------|------|
| `/tactile/left/status` | `arm_msgs/msg/TactileStatus` |
| `/tactile/right/status` | `arm_msgs/msg/TactileStatus` |

---

## 3. `site.yaml` 契约

字段说明见 [SITE_CONFIG.md](SITE_CONFIG.md)。Launch 覆盖键：

- 感知：`perception_overrides()` → `weights` `conf` `imgsz` `backend` …
- 伺服：`servo_overrides()` → `ee_z_m` `xy_track` `v_max_xy` `kp_xy` …

改 yaml **不会**热加载权重 / 分辨率 / 锁高（`overlay_hold_sec` 相机会跟）。重启对应脚本。

---

## 4. Python（二次开发）

```python
from arm_application.yolo_detector import YoloDetector, resolve_weights, pick_best
from arm_application.dh_pgea import DhPgeaGripper
from arm_application.dual_gripper import DualArmGripperManager, load_from_site
from arm_application.hole_detector import HoleDetector
from arm_application.orisys_tactile import make_tactile, load_orisys_from_site
from arm_application.geom_ik import load_handeye_T, geometric_jacobian, dls_twist
from arm_application.handeye_lib import calibrate_hand_eye
from arm_application.plane_feature import geometric_center_on_plane
```

模块职责写在 `src/arm_application/arm_application/__init__.py`。

不要从业务节点里 `import flexivrdk`（ABI 在 `rdk_py310`）。夹爪走 Modbus；示教拖拽走 `scripts/rdk_drag_bridge.py` 子进程。

---

## 5. 坐标系

| 帧 | 谁发布 | 含义 |
|----|--------|------|
| `{SN}_base_link` | robot_state_publisher | 基座 |
| `{SN}_flange` | robot_state_publisher | 法兰 |
| `d405_color_optical_frame` | 手眼 static TF | 相机光心，Z 朝外 |

`hover`：基座 XY 上法兰对齐工件。`ee_z_m`：法兰在基座 Z。