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)
- 设备配置：[`../../../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/server/src/grpc_arm_service.cpp`](../../../service/grpc/server/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 和程序启动请求均按不安全状态拒绝；
- 硬件急停会立即使当前运动 generation 失效，并在急停输入有效期间保持锁存。
  AUBO SDK 将示教器/控制柜急停报告为 `RobotEmergencyStop`，将控制器系统急停
  （外部系统急停输入）报告为 `SystemEmergencyStop`；两者在本后端都属于硬件急停。
  检测到任一硬件急停输入消失且控制器重新报告 `Normal`/`ReducedMode` 后，后端自动
  执行 `poweron()` 和 `startup()`，恢复到 `Running` 后再完成安全确认并开放新的 gRPC
  控制指令；防护停机和 Safety Fault/Violation 仍保持显式恢复语义；
- `emergencyStop()` 使用独立的 `SoftwareEmergencyStop` 锁存。即使软件急停在真实
  硬件急停有效期间触发，后续硬件采样也不能覆盖该锁存，释放硬件急停开关不会
  自动清除软件急停；它只能通过显式安全恢复流程解除；
- 锁存后会终止直接运动与程序、关闭 servo 模式并清理控制器轨迹。硬件急停
  自动恢复先上电到 `Idle`，在刹车释放前清理 runtime、servo 和轨迹队列，再执行
  `startup()`；到达 `Running` 后还会再次确认 `ExecId == -1`、普通队列和轨迹队列
  均为空、运行时已停止且机械臂稳定，全部成立后才能解除锁存；
- 当前 AUBO 配置通过 `auto_power_on_after_hardware_estop_release: true` 显式启用自动
  上电。自动确认失败时继续保持 fail-closed，并允许通过 `torqueOn`/`clearFault`/
  `unlockProtectiveStop` 显式重试；本轮释放期间收到 `stopMotion()` 或 `torqueOff()`
  会取消自动上电，显式停止始终优先；
- 恢复流程只调用 `poweron()` 和 `startup()`，不会调用 `resume`、`arbitraryResume`、
  `startMove`，也不会重新提交急停前的目标、速度、servo 指令或程序；
- AUBO SDK 未在本地文档中保证急停期间 `clearPath` 的可用性，也未说明释放
  急停开关后的控制器恢复时序。因此自动恢复必须在释放后再次清队列并完成上述
  安全确认；无法确认时不得解除锁存。“释放开关后零位移”的最终保证仍需真机
  验证及控制器侧安全配置配合；
- 只访问控制柜 Standard 数字 IO，不访问工具端 IO、可配置 IO 或安全 IO；
- `set_do` 不修改输出 runstate；
- 只有 `StandardOutputRunState::None` 的通道允许写入，否则返回
  `output_managed_by_runstate`；
- 普通访问不会调用会重置全部输出配置的
  `setDigitalOutputRunstateDefault()`；
- 模拟量 IO 涉及 domain、单位和量程，当前 JSON 接口不开放；
- gRPC/JSON 返回成功不代表目标 IO 具备功能安全等级；
- 真实写测试前应确认通道用途、负载、电气隔离、默认电平和控制器程序所有权。