# 睿尔曼机械臂力/力矩与关节指标测试 README

本文档说明如何使用 `realman_metrics_test` 对当前睿尔曼机械臂做保守指标测试，并生成 CSV 原始数据和 Markdown 报告。

## 测试对象

| 项目 | 当前值 |
| --- | --- |
| 控制器地址 | `192.168.1.18:8080` |
| SDK | `/home/mashiro/RM_API2/C++` |
| 动态库 | `/home/mashiro/RM_API2/C++/linux/linux_x86_c++_vv1.1.5/libapi_cpp.so` |
| CLion target | `realman_metrics_test` |

## 已测试指标

| 类别 | 指标 | 数据来源 |
| --- | --- | --- |
| 末端六维力/力矩 | `Fx/Fy/Fz/Mx/My/Mz` 原始值与清零后系统外受力 | `rm_get_force_data` |
| 关节负载代理量 | 关节电流均值、标准差、峰值、峰峰值 | `rm_get_current_joint_current` |
| 关节状态 | 关节角度、电压、温度 | `rm_get_current_arm_state`、`rm_get_current_joint_voltage`、`rm_get_current_joint_temperature` |
| 控制器状态 | 控制器电压、电流、温度、错误码 | `rm_get_controller_state` |
| 低速运动指标 | J2 `+3° -> 原位 -> -3° -> 原位` 的耗时与到位误差 | `rm_movej` + 到位后状态读取 |

## 未自动测试的指标

以下项目需要额外治具或外部传感器，本程序不会自动执行：

| 指标 | 原因 |
| --- | --- |
| 接触式力位混合控制闭环精度 | 需要固定接触面、接触方向限位和外部测力基准 |
| 外部负载下输出力矩精度 | 需要力矩传感器、已知力臂或标定负载 |
| 碰撞阈值/柔顺控制边界 | 涉及真实接触风险，需要急停监护和保护工装 |
| 裸关节力矩指令跟踪 | 当前 RM_API2 C++ 头文件未暴露直接关节力矩命令接口 |

因此本文中的“关节侧力矩相关表现”以关节电流变化作为负载代理量；末端力矩使用六维力传感器的 `Mx/My/Mz`。

## 安全策略

程序默认只做低风险动作：

```text
静态采样 -> 5 秒安全倒计时 -> J2 +3° -> 原位 -> J2 -3° -> 原位 -> 静态采样
```

内置限制：

| 参数 | 默认值 | 限制 |
| --- | ---: | --- |
| `kMotionDeltaDeg` | `3.0` | 不超过 `5°` |
| `kMotionSpeedPercent` | `5` | 不超过 `10%` |
| `kSamplePeriodMs` | `50` | 不低于 `20ms` |

如需只采样、不运动，在源码中改：

```cpp
constexpr bool kRunMotionTrackingTest = false;
```

如需只预览动作、不发送 `rm_movej`：

```cpp
constexpr bool kDryRunOnly = true;
```

## CLion 使用

1. 打开项目：

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

2. 点击 `Reload CMake Project`。
3. 选择运行目标：

   ```text
   realman_metrics_test
   ```

4. 运行结束后查看：

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

## 命令行构建与运行

Debug：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-debug
cmake --build --preset realman-metrics-test-debug
./cmake-build-debug/realman_metrics_test
```

Release：

```bash
cd /home/mashiro/project/linkerhand-cpp-sdk
cmake --preset clion-release
cmake --build --preset realman-metrics-test-release
./cmake-build-clion-release/realman_metrics_test
```

## 本次实测结果

已生成最新报告：

```text
reports/REALMAN_METRICS_TEST_RESULT.md
```

本次结果摘要：

| 指标 | 结果 |
| --- | --- |
| 总样本数 | `205` |
| 六维力接口失败次数 | `0` |
| 关节电流接口失败次数 | `0` |
| 控制器状态接口失败次数 | `0` |
| J2 `+3°` 到位最大误差 | `0.004°` |
| J2 返回原位最大误差 | `0.004°` |
| J2 `-3°` 到位最大误差 | `0.003°` |
| 最终返回原位最大误差 | `0.007°` |
| 控制器电压均值 | `23.3421 V` |
| 控制器温度均值 | `45.8516 C` |

详细统计以 `reports/REALMAN_METRICS_TEST_RESULT.md` 和 CSV 原始数据为准。

## 后续扩展建议

如果要进一步测试真实力控能力，建议增加以下前置条件后再启用 `rm_set_force_position` 或 `rm_force_position_move_*`：

- 固定机械臂底座和接触工件。
- 明确接触方向，设置机械限位或软限位。
- 使用外部六维力传感器、力矩传感器或标定砝码做基准。
- 每次只测试一个轴向，目标力从 `1N..3N` 小值开始。
- 测试期间保持急停按钮可触达。
