# 睿尔曼机械臂低速运动 Demo 操作手册

本文档说明如何使用 `realman_slow_motion_demo` 让睿尔曼机械臂做一次小幅、低速、可观察的关节空间往返运动。

该 Demo 的默认动作是：

```text
读取当前关节角 -> J2 +5 deg -> 回到起始角 -> J2 -5 deg -> 回到起始角
```

默认速度比例为 `10%`。程序使用 `rm_movej` 阻塞运动，不执行笛卡尔空间轨迹、不做轨迹融合、不连续抖动。

## 文件位置

| 文件 | 说明 |
| --- | --- |
| `examples/realman_slow_motion_demo.cpp` | 低速小幅运动 Demo |
| `CMakeLists.txt` | 已注册 `realman_slow_motion_demo` target |
| `CMakePresets.json` | 已注册 Debug/Release 构建 preset |
| `/home/mashiro/RM_API2/C++` | 首选睿尔曼 RM_API2 C++ SDK |
| `third_party/Robotic_Arm` | fallback SDK 路径 |

## 安全前置检查

运行前必须确认：

1. 机械臂工作空间内无人、无松散物体。
2. 急停按钮可触达。
3. 机械臂末端、线缆、夹具不会与桌面、支架、相机、电脑等发生碰撞。
4. 控制器 IP 和端口正确，默认是 `192.168.1.18:8080`。
5. 首次运行保持默认参数，不要直接增大角度或速度。

程序内置 5 秒倒计时，倒计时期间可以用 `Ctrl+C` 取消。

## CLion 运行

1. 用 CLion 打开项目：

   ```bash
   /home/mashiro/project/linkerhand-cpp-sdk
   ```

2. 选择 CMake preset：

   - `CLion Debug`
   - 或 `CLion Release`

3. 选择运行目标：

   ```text
   realman_slow_motion_demo
   ```

4. 默认无需填写 Program arguments。若要显式指定参数：

   ```text
   192.168.1.18 8080 1000 2 5 10
   ```

## 命令行构建

Debug：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-debug
cmake --build --preset realman-slow-motion-debug
```

Release：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-release
cmake --build --preset realman-slow-motion-release
```

## 命令行运行

使用默认参数：

```bash
./cmake-build-debug/realman_slow_motion_demo
```

完整参数格式：

```bash
./cmake-build-debug/realman_slow_motion_demo [robot_ip] [port] [timeout_ms] [joint] [delta_deg] [speed_percent]
```

示例：

```bash
./cmake-build-debug/realman_slow_motion_demo 192.168.1.18 8080 1000 2 5 10
```

更保守的动作：

```bash
./cmake-build-debug/realman_slow_motion_demo 192.168.1.18 8080 1000 2 3 5
```

## 参数说明

| 参数 | 默认值 | 范围 | 说明 |
| --- | --- | --- | --- |
| `robot_ip` | `192.168.1.18` | 有效 IP | 机械臂控制器 IP |
| `port` | `8080` | `1..65535` | 控制器端口 |
| `timeout_ms` | `1000` | `>0` | SDK 接收超时时间 |
| `joint` | `7` | `1..当前自由度` | 1-based 关节序号 |
| `delta_deg` | `2` | `(0, 5]` | 往返运动角度，单位度 |
| `speed_percent` | `5` | `1..20` | 速度比例。此 Demo 限制在低速范围 |

## 程序流程

1. 初始化 RM_API2，设置日志和超时时间。
2. 连接机械臂。
3. 读取机械臂自由度和当前关节角。
4. 打印起始关节角。
5. 5 秒安全倒计时。
6. 执行 `+delta`、回原位、`-delta`、回原位。
7. 读取并打印最终关节角。
8. 断开连接并销毁 SDK 线程。

任一步 `rm_movej` 失败时，程序会调用 `rm_set_arm_stop`，随后断开连接。

## 预期输出

```text
RealMan API version: 1.1.0
Connecting to 192.168.1.18:8080...
Connected. Arm DOF: 7, selected joint: J2, delta: 5 deg, speed: 10%
Current joints: [J1=..., J2=..., ...]

Safety countdown before motion. Clear the workspace and keep E-stop reachable.
Moving in 5...
...
Step 1 target (+delta): [...]
Step 2 return home: [...]
Step 3 target (-delta): [...]
Step 4 return home: [...]
Final joints: [...]
Slow motion demo finished successfully.
```

## 本机实测记录

已在当前连接的睿尔曼机械臂上执行成功：

```bash
./cmake-build-debug/realman_slow_motion_demo 192.168.1.18 8080 1000 2 5 10
```

实测信息：

| 项目 | 结果 |
| --- | --- |
| 控制器地址 | `192.168.1.18:8080` |
| API 版本 | `1.1.0` |
| 机械臂自由度 | `7` |
| 运动关节 | `J2` |
| 运动幅度 | `+5° -> 原位 -> -5° -> 原位` |
| 速度比例 | `10%` |
| 执行结果 | 成功 |

实测起始关节角：

```text
[J1=0.001, J2=0.002, J3=0.004, J4=0.000, J5=-0.001, J6=0.005, J7=-0.001] deg
```

实测结束关节角：

```text
[J1=0.001, J2=-0.001, J3=0.005, J4=0.000, J5=0.000, J6=0.001, J7=-0.001] deg
```

## 问题定位记录

如果程序返回成功但肉眼看不到动作，优先检查以下点：

1. 旧默认动作是 `J7 ±2°`。J7 是末端腕部旋转，小角度时没有工具或末端标记会很不明显。
2. 当前控制器已确认不是仿真模式：`run_mode=1`。
3. 当前 7 个关节均已使能，错误码均为 `0`，抱闸均为打开状态。
4. 已用 `J2 +5° -> 回原位` 实测验证，编码器读数从 `J2=0.002°` 到 `J2=5.001°`，再回到 `J2=-0.001°`。

因此默认动作已改为更容易观察的 `J2 ±5°`、速度 `10%`，并在每一步后读取实际关节角。

## 故障处理

| 现象 | 处理 |
| --- | --- |
| 连接失败 | 检查控制器 IP、端口、网线、电脑网段、电源状态 |
| 目标运行失败 | 降低 `delta_deg`，例如 `1`；降低速度，例如 `3` |
| CLion 看不到 target | 点击 `Reload CMake Project` |
| 动态库加载失败 | 使用本项目 CMake target 构建运行，target 已设置 rpath |

## 后续扩展

确认本 Demo 稳定后，再考虑新增更复杂动作。建议保持以下策略：

- 先读当前关节角，再基于当前位置做相对小幅运动。
- 优先关节空间 `movej`，避免一开始使用笛卡尔空间大轨迹。
- 运动参数配置化，不把生产动作硬编码进示例。
- 每次新增动作后先以 `delta_deg <= 2`、`speed_percent <= 5` 验证。
