cmvr-es/cmvr-es/devices/arm/aubo_arm/README.md

# AUBO RobotArm 与控制柜 IO

`AuboArm` 是 AUBO SDK v0.27.1 的 `RobotArm` 后端。控制柜 Standard 数字 IO
通过设备通用的 `executeJsonCommand` 接口访问，远程调用复用
`cmvr.api.ArmService/ExecuteJsonCommand`，不经过 `SystemService` 或
`MotorService`。该 RPC 只路由到 `RobotArm`，不会把 JSON 命令转发给其他设备类型。
旧的 `cmvr.api.SystemService/ExecuteJsonCommand` 不再注册，调用方必须更新服务路径；
请求和响应消息结构保持不变。

返回 [Devices 模块指南](../../README.md) 或 [项目总览](../../../../README.md)。

## 代码与配置

- 实现：[`aubo_arm.h`](aubo_arm.h)、[`aubo_arm.cpp`](aubo_arm.cpp)
- 测试：[`tests/aubo_arm_json_command_test.cpp`](tests/aubo_arm_json_command_test.cpp)
- 设备配置：[`../../../config/devices/arm/aubo_arm.pb.txt`](../../../config/devices/arm/aubo_arm.pb.txt)
- DeviceManager 配置：
  [`../../../config/manager/device_manager.pb.txt`](../../../config/manager/device_manager.pb.txt)
- ArmService 实现：
  [`../../../service/grpc/src/grpc_arm_service.cpp`](../../../service/grpc/src/grpc_arm_service.cpp)
- Proto：[`../../../../protos/cmvr/api/arm_service.proto`](../../../../protos/cmvr/api/arm_service.proto)

仓库配置使用 SDK RPC 端口 `30004`。现场部署必须填写真实控制器地址和凭据，
不要把生产密码提交到默认配置。

## 控制柜 Standard 数字 IO

当前支持：

| `operation` | 说明 | 必填字段 |
| --- | --- | --- |
| `get_di` | 读取控制柜数字输入 | `index` |
| `get_do` | 读取控制柜数字输出及其 runstate | `index` |
| `set_do` | 设置控制柜数字输出 | `index`、`value` |

JSON 命令：

```json
{"command":"cabinet_io","operation":"get_di","index":0}
{"command":"cabinet_io","operation":"get_do","index":0}
{"command":"cabinet_io","operation":"set_do","index":0,"value":true}
```

`index` 从 `0` 开始，运行时根据控制器返回的 IO 数量检查范围。
`set_do.value` 必须是 JSON 布尔值 `true` 或 `false`，不接受 `0/1` 或字符串。
`set_do` 成功响应中的 `requested_value` 只表示 SDK 已接受请求；确认实际输出时
必须再调用 `get_do`。

读取成功响应示例：

```json
{
  "success": true,
  "command": "cabinet_io",
  "operation": "get_di",
  "index": 0,
  "count": 16,
  "value": false
}
```

## 通过 gRPC 调用

默认 gRPC 端口为 `50052`。读取 DI0：

```shell
grpcurl -plaintext \
  -d '{
    "header":{"deviceId":"aubo_arm"},
    "requestJson":"{\"command\":\"cabinet_io\",\"operation\":\"get_di\",\"index\":0}"
  }' \
  127.0.0.1:50052 \
  cmvr.api.ArmService/ExecuteJsonCommand
```

设置 DO0 为高电平：

```shell
grpcurl -plaintext \
  -d '{
    "header":{"deviceId":"aubo_arm"},
    "requestJson":"{\"command\":\"cabinet_io\",\"operation\":\"set_do\",\"index\":0,\"value\":true}"
  }' \
  127.0.0.1:50052 \
  cmvr.api.ArmService/ExecuteJsonCommand
```

使用源码默认配置时：

1. 在 `cmvr-es/config/devices/arm/aubo_arm.pb.txt` 填写正确地址和登录信息；
2. 在 `cmvr-es/config/manager/device_manager.pb.txt` 将 `aubo_arm.enable`
   改为 `true`；
3. 重新安装配置并启动安装产物。

```shell
cmake --install build
./output/bin/cmvr_es
```

`output/bin/cmvr_es` 默认读取 `output/bin/config/`。使用 `--config` 时，应修改
对应外部配置根。设备未启用或初始化失败时，gRPC 返回
`Device not found: aubo_arm`。

## 安全与语义边界

- 后端使用独立 SDK RPC 会话持续读取控制器的 `SafetyModeType`、
  `RobotModeType` 和硬件急停来源；首次有效样本前、监控断线或样本过期时，
  所有 Move、Speed、Servo 和程序启动请求均按不安全状态拒绝；
- 硬件急停、防护停机、Safety Fault/Violation 会锁存安全事件，并使当前运动
  generation 失效。控制器重新报告 `Normal`/`ReducedMode` 不会自动解除锁存；
- 锁存后会终止直接运动与程序、关闭 servo 模式并清理控制器轨迹。只有确认
  `ExecId == -1`、普通队列和轨迹队列均为空、运行时已停止且机械臂稳定后，
  显式 `torqueOn`/`clearFault`/`unlockProtectiveStop` 才可能恢复运动权限；
- 恢复流程不会调用 `resume`、`arbitraryResume`、`startMove`，也不会重新提交
  急停前的目标、速度、servo 指令或程序；
- AUBO SDK 未在本地文档中保证急停期间 `clearPath` 的可用性，也未说明释放
  急停开关后的控制器恢复时序。因此本实现保持 fail-closed 并在释放后再次清队列，
  但“释放开关后零位移”的最终保证仍需真机验证及控制器侧安全配置配合；
- 只访问控制柜 Standard 数字 IO，不访问工具端 IO、可配置 IO 或安全 IO；
- `set_do` 不修改输出 runstate；
- 只有 `StandardOutputRunState::None` 的通道允许写入，否则返回
  `output_managed_by_runstate`；
- 普通访问不会调用会重置全部输出配置的
  `setDigitalOutputRunstateDefault()`；
- 模拟量 IO 涉及 domain、单位和量程，当前 JSON 接口不开放；
- gRPC/JSON 返回成功不代表目标 IO 具备功能安全等级；
- 真实写测试前应确认通道用途、负载、电气隔离、默认电平和控制器程序所有权。

## 测试

```bash
cmake --build build --target \
  aubo_safety_state_test \
  aubo_motion_state_test \
  aubo_arm_json_command_test -j4
ctest --test-dir build \
  -R 'aubo_(safety_state|motion_state|arm_json_command)_test' \
  --output-on-failure
```

该测试覆盖 JSON 校验和无硬件错误路径，不代表已在真实 AUBO 控制柜完成 DI/DO
读取、写入或 runstate 拒绝验证。