# CLion 搭建睿尔曼 RealMan C++ SDK

本文档说明当前项目中睿尔曼 RealMan RM_API2 C++ SDK 的 CLion 配置方式。

## 当前配置

本项目的 CMake 已接入睿尔曼 C++ SDK：

| 项目 | 当前值 |
| --- | --- |
| 首选 SDK 根目录 | `/home/mashiro/RM_API2/C++` |
| 头文件目录 | `/home/mashiro/RM_API2/C++/include` |
| x86_64 动态库 | `/home/mashiro/RM_API2/C++/linux/linux_x86_c++_vv1.1.5/libapi_cpp.so` |
| fallback SDK | `third_party/Robotic_Arm` |
| CMake imported target | `realman_api_cpp` |

CMake 会优先使用 `REALMAN_RM_API2_ROOT` 指定的 SDK；如果该路径不可用，会回退到项目内置的 `third_party/Robotic_Arm`。

## CLion 打开项目

1. 打开 CLion。
2. 选择 `Open`。
3. 打开目录：

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

4. 选择 CMake preset：

   ```text
   CLion Debug
   ```

   或：

   ```text
   CLion Release
   ```

5. 点击 `Reload CMake Project`。

## 可运行目标

CLion 中会出现以下睿尔曼相关 targets：

| Target | 说明 |
| --- | --- |
| `realman_minimal_demo` | 连接机械臂，读取 API/软件/基础信息，不发送运动指令 |
| `realman_slow_motion_demo` | 低速小幅关节往返运动，默认 `J2 ±5°`，速度 `10%` |
| `realman_joint_pose_config_demo` | 在源码顶部修改关节目标/偏移参数，用于 CLion 内调姿态 |
| `realman_metrics_test` | 采集六维力/力矩、关节电流、电压、温度和低速运动跟踪指标，并生成报告 |
| `realman_trajectory_record` | 录制关节角/TCP 位姿到 CSV，只读不发送运动指令 |
| `realman_trajectory_replay` | 从 CSV 低速逐点回放关节角，默认 dry-run，显式 execute 才运动 |
| `realman_hw_test_connection` | 独立连接/基础信息硬件测试 |
| `realman_hw_test_joint_telemetry` | 独立关节遥测硬件测试 |
| `realman_hw_test_force_sensor` | 独立六维力/力矩传感器硬件测试 |
| `realman_hw_test_controller_state` | 独立控制器状态硬件测试 |
| `realman_hw_test_motion_tracking` | 独立低速运动跟踪硬件测试 |
| `realman_hw_test_force_retreat` | 手动外力方向退让测试，检测末端受力后小步后退 |
| `realman_hw_test_force_retreat_hold` | 持续外力方向退让保持模式，被推就小步退让，直到手动停止 |

## CMake Presets

`CMakePresets.json` 已配置：

```json
"REALMAN_RM_API2_ROOT": "/home/mashiro/RM_API2/C++"
```

命令行也可以直接构建：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-debug
cmake --build --preset realman-demo-debug
cmake --build --preset realman-slow-motion-debug
cmake --build --preset realman-joint-pose-config-debug
cmake --build --preset realman-metrics-test-debug
cmake --build --preset realman-trajectory-record-debug
cmake --build --preset realman-trajectory-replay-debug
cmake --build --preset realman-hw-tests-debug
cmake --build --preset realman-hw-force-retreat-debug
cmake --build --preset realman-hw-force-retreat-hold-debug
```

Release：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-release
cmake --build --preset realman-demo-release
cmake --build --preset realman-slow-motion-release
cmake --build --preset realman-joint-pose-config-release
cmake --build --preset realman-metrics-test-release
cmake --build --preset realman-trajectory-record-release
cmake --build --preset realman-trajectory-replay-release
cmake --build --preset realman-hw-tests-release
cmake --build --preset realman-hw-force-retreat-release
cmake --build --preset realman-hw-force-retreat-hold-release
```

## 最小连接验证

在 CLion 里运行：

```text
realman_minimal_demo
```

默认参数等价于：

```bash
./cmake-build-debug/realman_minimal_demo 192.168.1.18 8080 1000
```

成功时会打印机械臂型号、自由度、软件版本等信息。

当前环境已验证：

| 项目 | 结果 |
| --- | --- |
| 运行目标 | `realman_minimal_demo` |
| 动态库 | `/home/mashiro/RM_API2/C++/linux/linux_x86_c++_vv1.1.5/libapi_cpp.so` |
| API 版本 | `v1.1.5` |
| 控制器地址 | `192.168.1.18:8080` |
| 机械臂型号 | `RM75-6FB` |
| 自由度 | `7` |
| 运行结果 | 成功 |

## 低速运动验证

在 CLion 里运行：

```text
realman_slow_motion_demo
```

默认参数等价于：

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

含义：

| 参数 | 含义 |
| --- | --- |
| `192.168.1.18` | 机械臂控制器 IP |
| `8080` | SDK 控制端口 |
| `1000` | SDK 超时时间，单位 ms |
| `2` | 关节序号 J2 |
| `5` | 运动幅度 5° |
| `10` | 速度比例 10% |

## 源码参数调姿态

在 CLion 中运行：

```text
realman_joint_pose_config_demo
```

修改文件顶部的参数：

```text
examples/realman_joint_pose_config_demo.cpp
```

常用修改点：

| 参数 | 说明 |
| --- | --- |
| `kTargetMode` | `kRelativeJointOffset` 为相对当前姿态偏移，`kAbsoluteJointAngles` 为绝对关节角 |
| `kRelativeJointOffsetsDeg` | 相对偏移，单位度，例如 `{0, 5, 0, 0, 0, 0, 0}` 表示 `J2 +5°` |
| `kAbsoluteTargetJointsDeg` | 绝对目标关节角，单位度 |
| `kSpeedPercent` | 速度比例 |
| `kReturnToStartAfterMove` | 是否执行后回到起点 |
| `kDryRunOnly` | 只打印目标，不发送运动指令 |

详细说明见 [睿尔曼机械臂源码参数调姿态 Demo](REALMAN_JOINT_POSE_CONFIG_DEMO.md)。

## 力/力矩与关节指标测试

在 CLion 中运行：

```text
realman_metrics_test
```

运行后生成：

```text
reports/REALMAN_METRICS_TEST_RESULT.md
reports/realman_metrics_latest.csv
```

详细说明见 [睿尔曼机械臂力/力矩与关节指标测试 README](REALMAN_METRICS_TEST_README.md)。

## 轨迹录制与回放

在 CLion 中可以分别运行：

```text
realman_trajectory_record
realman_trajectory_replay
```

命令行示例：

```bash
./cmake-build-debug/realman_trajectory_record reports/realman_trajectories/demo.csv 15 100
./cmake-build-debug/realman_trajectory_replay reports/realman_trajectories/demo.csv dry-run
./cmake-build-debug/realman_trajectory_replay reports/realman_trajectories/demo.csv execute 5 5 5
```

详细说明见 [RM75 轨迹录制与回放](REALMAN_TRAJECTORY_RECORD_REPLAY.md)。

## 独立硬件模块测试

这套测试类似单元测试组织方式，但对象是真实机械臂硬件。每个模块都是独立进程，单独连接、单独断开、单独出报告。

只运行只读测试：

```bash
ctest --test-dir cmake-build-debug --output-on-failure --label-regex readonly
```

运行单个模块：

```bash
ctest --test-dir cmake-build-debug --output-on-failure -R realman_hw_test_force_sensor
```

运行全部硬件测试：

```bash
ctest --test-dir cmake-build-debug --output-on-failure --label-regex realman
```

手动运行外力方向退让测试：

```bash
ctest --test-dir cmake-build-debug --output-on-failure -R realman_hw_test_force_retreat
```

持续保持外力方向退让状态：

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

详细说明见 [睿尔曼 RealMan 硬件模块测试](../tests/realman_hardware/README.md)。

## Web 示教器

控制器 Web 示教器入口：

```text
http://192.168.1.18/
```

8080 是 SDK 控制端口，不是 Web 页面入口。

## 更换 SDK 路径

如果后续 SDK 放到其他目录，在 CLion 的 CMake cache 或 `CMakePresets.json` 中修改：

```text
REALMAN_RM_API2_ROOT=/path/to/RM_API2/C++
```

目录应包含：

```text
include/rm_interface.h
linux/linux_x86_c++_*/libapi_cpp.so
```

## 常见问题

| 现象 | 处理 |
| --- | --- |
| CLion 看不到 RealMan target | `Reload CMake Project` |
| 找不到 `rm_interface.h` | 检查 `REALMAN_RM_API2_ROOT` 是否指向 `RM_API2/C++` |
| 运行时报 `libapi_cpp.so` 找不到 | 使用本项目 target 构建，CMake 已设置 rpath |
| 修改源码后 CLion 仍运行旧动作 | 重新 Build `realman_joint_pose_config_demo`，不要运行旧的 `realman_slow_motion_demo` |
| 指标测试后找不到报告 | 查看项目根目录下 `reports/REALMAN_METRICS_TEST_RESULT.md` |
| 连接失败 | 检查 `192.168.1.18:8080`、网线、网段和控制器电源 |
| Web 示教器打不开 | 浏览器访问 `http://192.168.1.18/`，并绕过代理 |
