arm_dev
d93dab31c9
P3 把 handeye 相关文件从 src/arm_application/config/ 迁到了仓库根的 handeye/， 但文档还写着老路径。这类"代码改了、文档没跟"的偏差最麻烦：新人照着文档敲 命令会直接报文件不存在，然后开始怀疑人生。 同步内容 - docs/HANDEYE.md / WORKSPACE.md / SITE_CONFIG.md / ARCHITECTURE.md： 手眼结果与示教点位改指 handeye/results|poses/<臂号>_<模式>.yaml， 临时目录改指 handeye/tmp/<臂号>/，并补上 --mode / --points / --auto-solve。 - docs/INTERFACES.md / TRACKING.md / docs/HOLE_DETECT.md / README.md： 权重那一行从 export_yolo_trt.sh 改为 weights.sh，并注明前者已是兼容转发壳。 - docs/HOLE_DETECT.md：hole_weights / workpiece_weights 的实际取值改为 models/hole_insert/detect_best_1.onnx（原文档写的是不存在的 best.pt）。 - scripts/merge_handeye_poses.py：只更新文件头注释里的示例路径。 多处改为指向 models/README.md 与 handeye/README.md，避免同一套规则在 七八个文件里各写一遍、然后各自漂移。 验证：rg 扫 docs/ README.md，已无 handeye_poses_/handeye_result_/ /tmp/handeye 之类过期路径残留。 Co-authored-by: Cursor <cursoragent@cursor.com>
151 lines
6.0 KiB
Markdown
151 lines
6.0 KiB
Markdown
# 对外接口
|
||
|
||
三层：操作员脚本、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 左右指 |
|
||
| `weights.sh list\|labels\|convert\|doctor\|show` | 权重模块 | 管理权重与标签，见 `models/README.md` |
|
||
| `export_yolo_trt.sh [onnx] [imgsz]` | 权重 | **旧命令**，转发壳 → `weights.sh convert --to 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。
|