接口参考：
REST 与命令服务 提醒
本页面引用的 examples/ 脚本请通过正式交付渠道提供的交付包获取，并使用与软件版本匹配的交付包版本；文档中的路径仅用于说明脚本结构。
共通契约
基础地址为 http://$ROBOT_IP:9091，一律使用 JSON POST。REST 控制面没有被本手册证实具有适合公网的身份认证、TLS 和限流，因此不得直接暴露公网。跨主机调用应通过私有 LAN、ACL 和经审批的安全代理。
响应应解析为 JSON 对象，且 code 必须是整数 200；布尔值、字符串 "200" 或浮点 200.0 都不等价。即使 HTTP 和业务码均成功，运动结果仍必须由 /robot_slave/states、/odom、错误位和超时联合判定。响应丢失时命令结果未知，先停止和读回，不盲目重发。
说明
控制 Service 的安全闭环固定为：
取得独占控制权 → 读当前值与限位 → 小步低速下发 → 状态反馈判定 → 发部位精确停止 → 回复原值并二次读回。
Service 响应为空或返回“成功”，都不是运动完成证据。
REST 索引
| 端点 | 关键请求 | 响应/错误判断 | 停止方式 | 反馈判据 | 单位 | 风险 | 状态 |
|---|---|---|---|---|---|---|---|
/robot/version | {} | 整数 code=200；data 须可解析且版本字段非空 | 不适用 | 型号与软硬件版本和附录软件版本兼容矩阵对齐 | 字符串 | 只读 | 正式发布 |
/joints/getJointLimit | {"device":N} | code 严格判定；上/下限数组长度与设备自由度一致 | 不适用 | 取驱动器限位与软限位交集 | 返回值按端点定义转为度 | 只读 | 正式发布 |
/move/moveJ | {"device":N,"joint":[...],"v":1} | code=200 只表示请求被接受；超时/断连为结果未知 | /move/setArmStop，使用同一 device | position、joint_err、sys_err、到位超时 | joint 为 0.001°；v 为速度档 | 可控风险 | 正式发布 |
/move/setArmStop | {"device":N} | 严格 code=200；失败时上报人工停机通道 | 本身即部位停止 | 连续两次状态位置无继续趋势，错误位无新增 | 无 | 可控风险 | 正式发布 |
/joints/setJointsEnable | device 与关节选择 | 响应不代表设备可安全运动 | 根据方案断使能和实体急停 | joint_en、错误位、现场急停状态 | 布尔/枚举，以正式协议为准 | 高风险 | 参考信息 |
/joints/clearJointsErr / /robot/clearArmErr | {"device":N} | 清错成功不表示根因消失 | 停止当前部位 | 错误位归零且故障原因已处理 | 无 | 高风险 | 参考信息 |
/joints/setZeroJoints 及限位写入端点 | 参数取决于部位 | 任何非 200 或读回不一致即停止 | 实体急停/部位停止 | 写前快照、写后读回、已验证回滚 | 度/编码以该端点正式定义为准 | 高风险 | 参考信息 |
/robot/setRobotPower | 分路与开关参数 | 响应不代表负载上电正常 | 按审批的反向操作 | RobotPower 分路值、负载状态与故障位 | 0.01 V 编码 | 高风险 | 参考信息 |
device 编码在本手册中统一为：
| device | 部位 |
|---|---|
0 | 左臂 |
1 | 右臂 |
2 | 腰部 |
3 | 头部 |
客户封装应使用枚举而非分散数字，并按附录设备编号与关节限位校验自由度。
/robot/command wrapper
/robot/command 的 ROS2 请求字段只有一个 string data。应用程序应先构造包含外层 device 和内层 payload 的 JSON 对象，再把整个对象序列化为 data 字符串；payload 在序列化前是 JSON 对象，不是再次手工转义的字符串。
头/腰 movej 的 payload 还要带同值 device。
扁平 JSON、两层 device 不一致、数组长度错误，或头腰 movej 少 trajectory_connect，即使 Service 有响应也不得判为执行。
| 外层 device | 对象 | payload 结构 | 当前发布边界 |
|---|---|---|---|
0 | 左臂 | movej + 7 个关节目标 | 报文结构供参考 |
1 | 右臂 | movej + 7 个关节目标 | safe_staged_actuator_control.py 只开放单关节相对最大 0.5°，回原后 set_arm_stop |
2 | 腰部 | movej + 内层 device=2 + 5 个关节目标 | safe_staged_actuator_control.py 只开放单关节相对最大 0.2°，回原后 set_stop_teach |
3 | 头部 | movej + 内层 device=3 + 2 个关节目标 | 上限为相对 3°、速度档 1 |
1（当前设备） | 右侧单自由度末端 | hand_follow_pos + 单元素 hand_pos | 只开放相对增大最大 50/1000，回原后 set_rm_plus_ctrl_mode=0 |
下面使用符号目标值说明封装形状，故意不提供全零或历史姿态作为可复制目标：
{
"device": 3,
"payload": {
"command": "movej",
"joint": ["J1", "J2"],
"v": "V",
"r": 0,
"trajectory_connect": 0,
"device": 3
}
}实际发送时 J1、J2 和 V 必须是通过当前值、实时限位和项目安全范围校验后的整数，不得保留为字符串。外层对象序列化后才放入 StringCmd.data。
现行 Python 示例对头腰使用同一 device 的 set_stop_teach，payload 包含 v=5、r=0；右臂使用 set_arm_stop；右侧单自由度末端使用 set_rm_plus_ctrl mode=0。服务响应为 false、超时、反馈不新鲜、状态错误或回原超差均判失败，不重发旧运动目标，不自动清错。
文档中的 C++ 样例只构建和显示头部 wrapper，不执行实机服务请求。
双臂、腰部和末端工具在完成各自的停止、回原和状态一致性验收前，不提供可直接复制的 ros2 service call。
统一停止与成功判据
| 控制对象 | 停止 | 必须同时满足的状态反馈 |
|---|---|---|
| 左臂/右臂 | POST /move/setArmStop + 原 device；直连路径按对应机械臂协议停止 | 位置进入容差带、joint_err 全 0、sys_err=0；恢复时再次核对原值 |
| 腰/头 | ROS2 wrapper 内发送 set_stop_teach，保持内外层同一 device，并带 v=5、r=0 | 连续两次位置无继续趋势，joint_err 全 0、sys_err=0，并回到本次采样起点 |
| 底盘 | 停止唯一启用的 /teleop_cmd_vel 或 /cmd_vel 非零发布，重复发送零 Twist；现场授权方案再调用 /StopMotor | /odom.twist.twist 速度趋近 0，位姿无继续变化 |
错误位非零、反馈超时、响应无法解析或位置向限位外趋动，任一项发生都执行对应停止，保留现场记录，不进入下一步。