# 快速上手

更完整的目录说明：[WORKSPACE.md](WORKSPACE.md)。

## 依赖

从一台空机器装到和本机一样：见 **[ENVIRONMENT.md](ENVIRONMENT.md)**（2026-10-09 快照：RoboStack Humble、`ros_flexiv` / `ros_gz_sim`、RDK 1.9.1）。

- Ubuntu 22.04 + ROS 2 Humble（本机 ROS 在 conda 里，没有 `/opt/ros`）
- Conda 环境 `ros_flexiv`（本仓库脚本默认这个名字）
- Flexiv RDK Python：`/home/cc/rdk_py310/bin/python`（flexivrdk 1.9.x）
- 工控机与机器人在同一网段（例：`192.168.2.10` ↔ `192.168.2.101`）
- Intel RealSense D405，`pyrealsense2`
- YOLO：`ultralytics`；TensorRT：`tensorrt-cu12`（不要装 meta 包 `tensorrt`）
- 夹爪：`pyserial`，USB–RS485 → `/dev/ttyUSB0`（PGEA）`/dev/ttyUSB1`（RGI）

每次新开终端：

```bash
conda activate ros_flexiv
source ~/ros2/scripts/env.sh
```

## 配置

```bash
cp ~/ros2/config/site.example.yaml ~/ros2/config/site.yaml
```

必填：`robot.sn`、`robot.robots[].ip`、`camera.serial`（多相机时）、`paths.yolo_weights`。

查看解析结果：

```bash
bash ~/ros2/scripts/show_site_config.sh
```

## 编译

```bash
cd ~/ros2
./scripts/build_all.sh
source scripts/env.sh
```

只改 Python 应用时，develop 安装会直接读 `src/`。改了 `setup.py` 的 `console_scripts` 后需要再编一次 `arm_application`。

## 第一次实机

**开工前先体检**（不需要机械臂能动，只读）：

```bash
bash ~/ros2/scripts/run_real_preflight.sh --arm 89
```

它按"现场该处理的顺序"给结论，最后汇总**要人工做的事**。它专门盯这几类
"报错的地方不是坏的地方"的问题：

| 检查项 | 抓的是 |
| --- | --- |
| 现场配置 | 这一轮到底在读哪份 site.yaml、认哪台臂 |
| 遗留进程 | 上一轮没退干净的 ros2_control（它占着 RDK，会让 RDK 报"连不上"） |
| 机器人在网 | ping 不通；以及**两个 IP 指向同一个 MAC**（两台臂出厂 MAC 相同时会互相抢转发） |
| 机械臂 RDK | 连不上 / 示教器在 Manual（这个 SW 切不了，只能人到现场拨） |
| 腕部相机 | 本臂配置的那只 D405 **在不在 USB 上** —— 它掉了以后报错会变成"点云为空" |
| 触觉 / USB / 几何 | 触觉是"没插"还是"内核卡死"、RealSense 协商速率、手眼矩阵与悬停高度 |

结论是 `NO-GO` 时**不要往下走**：硬阻断项（RDK、腕部相机）会让后面每一步
都以别的样子失败。

然后是常规步骤：

1. 示教器：AUTO + Remote Ethernet，清故障。关 Studio。
2. `bash ~/ros2/scripts/test_rdk_python.sh`（可选）
3. T1 `run_real.sh`，T2 `run_camera_d405.sh --preview`
4. 手眼：见 [HANDEYE.md](HANDEYE.md)
5. T3 `run_visual_servo_rt.sh` 先观察，再 `--control`

回零：

```bash
bash ~/ros2/scripts/go_home.sh
```

会先杀掉 perception/servo，避免轨迹抢臂。

## Mock（无机器人）

```bash
bash ~/ros2/scripts/run_sim.sh
ros2 run arm_application demo_named_poses
```