手臂动作服务接口

Adam 支持基于动作文件的上半身互动与轨迹文件的全身跟踪，通过 gRPC SetMotion 与 SetTrackingMotion 调用。整机 gRPC 说明见强化学习 gRPC 接口说明；客户端例程见 gRPC 例程。

与手臂控制例程（DDS 实时关节控制）不同，本服务播放机器人侧预录 .txt 文件，无需逐帧下发关节指令。

项目	说明
通信方式	gRPC，端口 `50051`
服务名称	`RobotControl`
动作发现	无独立 `GetActionList`；通过 `GetRobotState` 查询 FSM 与 `available_actions`
客户端工程	pnd_grpc

动作文件部署说明

项目	说明
控制程序根目录	`/etc/pndbotics/pnd_adam_dds/`
动作文件目录（相对路径）	`Sources/motion/`
动作文件目录（绝对路径）	`/etc/pndbotics/pnd_adam_dds/Sources/motion/`
路径解析规则	相对路径以控制程序根目录（`PndControl` 工作目录）为基准；也可传入绝对路径

调用 SetMotion 时，motion_file 须指向机器人侧真实存在的 .txt 文件。客户端本地有同名文件不代表可播放。

接口一览表

接口名称	功能描述	调用参数	赋值示例	所需 FSM
`SetMotion`	播放/停止上半身动作文件	`command`, `motion_file`	`PLAY`, `"Sources/motion/Greeting.txt"`	`MULTI_AGENT`
`SetMotion`	停止当前动作播放	`command`	`STOP`	`MULTI_AGENT`
`SetTrackingMotion`	切换全身轨迹跟踪文件	`motion_file`	见「轨迹跟踪文件列表」	`MOTION_TRACK`
`GetRobotState`	查询状态、可用接口与播放进度	无	—	任意

前置条件

调用 SetMotion / SetTrackingMotion 前，须确认 GetRobotState().available_actions 包含对应接口名，且 fsm_state 处于上表所需状态。

典型切换流程：

STOP → ZERO → STAND_WALK → MULTI_AGENT（SetMotion）
                         → MOTION_TRACK（SetTrackingMotion）

接口说明

pnd.robot.RobotControl（动作与轨迹）

下列接口隶属于 RobotControl 服务，完整 RPC 列表见强化学习 gRPC 接口说明。

函数名	SetMotion
接口原型	rpc SetMotion (SetMotionRequest) returns (SetMotionResponse)
功能描述	在 `MULTI_AGENT` 状态下播放或停止上半身动作文件。
参数	`command` (enum)：`PLAY` / `STOP` `motion_file` (string)：`PLAY` 时必填，须为机器人侧存在的 `.txt` 文件路径
返回值	`SetMotionResponse`：`success` (bool)、`message` (string)、`current_motion` (string)、`is_playing` (bool)
备注	仅当 `available_actions` 包含 `SetMotion` 时可调用；相对路径以 `/etc/pndbotics/pnd_adam_dds/` 为基准。CLI：`robot> motion play Sources/motion/Greeting.txt`

函数名	SetTrackingMotion
接口原型	rpc SetTrackingMotion (SetTrackingMotionRequest) returns (SetTrackingMotionResponse)
功能描述	在 `MOTION_TRACK` 状态下切换全身轨迹跟踪文件。
参数	`motion_file` (string)：轨迹文件路径，须存在于机器人侧
返回值	`SetTrackingMotionResponse`：`success` (bool)、`message` (string)、`current_tracking_motion` (string)
备注	仅当 `available_actions` 包含 `SetTrackingMotion` 时可调用。轨迹文件说明见下文。

函数名	GetRobotState
接口原型	rpc GetRobotState (GetRobotStateRequest) returns (GetRobotStateResponse)
功能描述	查询 FSM、可用接口及动作/轨迹播放进度。
参数	无
返回值	与动作相关的字段：`fsm_state`、`available_actions`、`motion_playing`、`current_motion_file`、`tracking_playing`、`current_tracking_motion`
备注	下发动作前应调用；播放后可轮询 `motion_playing` / `current_motion_file` 确认是否生效。

预设上半身动作列表

PND gRPC 通过动作文件路径（非动作 ID）调用 SetMotion。下表路径均相对于控制程序根目录 /etc/pndbotics/pnd_adam_dds/。

动作名称	动作文件路径	说明
Greeting	`Sources/motion/Greeting.txt`	打招呼
Chest Expansion	`Sources/motion/Chest Expansion.txt`	扩胸
Stretching	`Sources/motion/Stretching.txt`	伸展
Gentleman's Salute	`Sources/motion/Gentleman's Salute.txt`	绅士礼
hello_everyone	`Sources/motion/hello_everyone.txt`	问候众人
太极	`Sources/motion/太极.txt`	太极
弹吉他	`Sources/motion/弹吉他.txt`	弹吉他
弹钢琴	`Sources/motion/弹钢琴.txt`	弹钢琴
热身	`Sources/motion/热身.txt`	热身
金蛇狂舞	`Sources/motion/金蛇狂舞.txt`	金蛇狂舞

文件名说明

文件名含空格或中文时，motion_file 须与磁盘文件名完全一致。

轨迹跟踪文件列表

SetTrackingMotion 用于播放全身轨迹跟踪文件。轨迹文件通常为动捕录制数据，部署路径因软件版本与配置而异。

说明
`motion_file` 须为机器人侧真实存在的 `.txt` 文件
轨迹文件通常为动捕录制数据，需部署至控制程序可访问的路径后再调用
自定义轨迹文件的存放目录因软件版本与配置而异

调用示例

import grpc
from comm.grpc import robot_control_pb2 as pb2
from comm.grpc import robot_control_pb2_grpc as pb2_grpc

stub = pb2_grpc.RobotControlStub(grpc.insecure_channel("192.168.1.100:50051"))

state = stub.GetRobotState(pb2.GetRobotStateRequest())
assert "SetMotion" in state.available_actions
assert state.fsm_state == "MULTI_AGENT"

# 相对路径（推荐）
resp = stub.SetMotion(pb2.SetMotionRequest(
    command=pb2.SetMotionRequest.PLAY,
    motion_file="Sources/motion/Greeting.txt",
))

# 或使用绝对路径
resp = stub.SetMotion(pb2.SetMotionRequest(
    command=pb2.SetMotionRequest.PLAY,
    motion_file="/etc/pndbotics/pnd_adam_dds/Sources/motion/Greeting.txt",
))
print(resp.success, resp.message, resp.is_playing)

resp = stub.SetMotion(pb2.SetMotionRequest(
    command=pb2.SetMotionRequest.STOP,
))

python3 tools/grpc_client.py --addr 192.168.1.100:50051
robot> mode MULTI_AGENT
robot> motion play Sources/motion/Greeting.txt
robot> motion stop
robot> mode MOTION_TRACK
robot> tracking <trajectory_file_path>

动作文件规范

项目	说明
文件格式	`.txt` 后缀
存放位置	`/etc/pndbotics/pnd_adam_dds/Sources/motion/`
路径解析	相对路径以 `/etc/pndbotics/pnd_adam_dds/` 为基准；支持绝对路径
示例	`Sources/motion/Greeting.txt`

错误与排查

现象	可能原因	处理建议
`success=false`	FSM 不在目标状态	检查 `fsm_state` 与 `switchable_states`
`success=false`	`available_actions` 不含目标接口	先 `SetMode` 切换至正确 FSM
`success=false`	动作/轨迹文件不存在	确认路径为 `Sources/motion/<文件名>.txt`
命令成功但无动作	异步执行中	轮询 `motion_playing` / `current_motion_file`
与 DDS 控制冲突	同时通过 `rt/lowcmd` 控制同一关节	确认控制源优先级

文档	说明
强化学习 gRPC 接口说明	整机 RPC 与 FSM
gRPC 例程	客户端运行与 CLI
手臂控制例程	DDS 实时上肢控制
灵巧手控制说明	DDS 手指控制