强化学习 gRPC 接口说明

高层运动控制通过 gRPC 接口实现。强化学习（RL）客户端为独立程序，与控制程序分离部署；服务端随机器人控制程序运行，不支持二次开发。

使用前请先完成机器人快速开始。客户端获取与例程见 gRPC 例程；完整工程将发布于 pnd_grpc。

项目	说明
服务端口	50051（固定，请勿修改）
连接地址	本机 localhost:50051；远程 <机器人 IP>:50051
调用流程	GetRobotState → 检查 switchable_states / available_actions → 下发指令
动作文件路径	Sources/motion/<文件名>.txt（相对 /etc/pndbotics/pnd_adam_dds/）

---

接口说明

pnd.robot.RobotControl

RobotControl 服务提供 Adam 高层运动控制的 gRPC 接口，客户端通过 Stub 调用下列 RPC。

服务名	RobotControl
包名	pnd.robot
默认端口	50051

接口定义（Proto）

syntax = "proto3";
package pnd.robot;

service RobotControl {
  rpc SetMode         (SetModeRequest)         returns (SetModeResponse);
  rpc SetVelocity     (SetVelocityRequest)     returns (SetVelocityResponse);
  rpc SetHeight       (SetHeightRequest)       returns (SetHeightResponse);
  rpc SetMotion       (SetMotionRequest)       returns (SetMotionResponse);
  rpc SetTrackingMotion (SetTrackingMotionRequest) returns (SetTrackingMotionResponse);
  rpc GetRobotState   (GetRobotStateRequest)   returns (GetRobotStateResponse);
  rpc SetControlMode  (SetControlModeRequest)  returns (SetControlModeResponse);
  rpc GetControlState (GetControlStateRequest) returns (GetControlStateResponse);
  rpc Shutdown        (ShutdownRequest)        returns (ShutdownResponse);
}

函数名	GetRobotState
接口原型	rpc GetRobotState (GetRobotStateRequest) returns (GetRobotStateResponse)
功能描述	获取机器人当前 FSM 状态、速度/站高反馈、动作与轨迹播放状态，以及可切换状态与可用接口列表。
参数	无（GetRobotStateRequest 为空消息）
返回值	GetRobotStateResponse：success (bool)、fsm_state (string)、vx / vy / vyaw (double)、height (double)、current_motion_file (string)、motion_playing (bool)、current_tracking_motion (string)、tracking_playing (bool)、switchable_states (repeated string)、available_actions (repeated string)
备注	可在任意时刻调用。下发其他指令前应优先调用；switchable_states / available_actions 为动态列表，以本次返回为准。

函数名	SetMode
接口原型	rpc SetMode (SetModeRequest) returns (SetModeResponse)
功能描述	切换机器人 FSM 状态。
参数	target_state (string)：目标 FSM 状态，取值见下文「SetMode 状态取值参考」
返回值	SetModeResponse：success (bool)、message (string)、current_state (string)
备注	仅可切换到 switchable_states 中的状态；success=true 表示命令已接受，实际切换异步完成，需轮询 fsm_state；ZERO → STAND_WALK 会在零位归零完成后才真正切换。典型流程：STOP → ZERO → STAND_WALK → MULTI_AGENT / MOTION_TRACK / ...

函数名	SetMotion
接口原型	rpc SetMotion (SetMotionRequest) returns (SetMotionResponse)
功能描述	在 MULTI_AGENT 状态下播放或停止上半身动作文件。
参数	command (enum)：PLAY / STOP motion_file (string)：PLAY 时必填，动作文件路径
返回值	SetMotionResponse：success (bool)、message (string)、current_motion (string)、is_playing (bool)
备注	仅当 available_actions 包含 SetMotion 时可调用。motion_file 须为机器人侧 .txt 文件，预设动作位于 Sources/motion/。完整列表见 手臂动作服务接口。

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

函数名	SetVelocity
接口原型	rpc SetVelocity (SetVelocityRequest) returns (SetVelocityResponse)
功能描述	设置行走速度。
参数	vx (double)：前进/后退，归一化 [-1.0, 1.0] vy (double)：左移/右移 vyaw (double)：转向
返回值	SetVelocityResponse：success (bool)、message (string)
备注	当前为预留接口，暂未接入；行走请使用手柄控制。

函数名	SetHeight
接口原型	rpc SetHeight (SetHeightRequest) returns (SetHeightResponse)
功能描述	设置站立高度。
参数	height (double)：归一化 [-1.0, 1.0]，0 为默认站高
返回值	SetHeightResponse：success (bool)、message (string)
备注	当前为预留接口，暂未接入。

函数名	SetControlMode
接口原型	rpc SetControlMode (SetControlModeRequest) returns (SetControlModeResponse)
功能描述	切换控制范式（Traditional / RL）。
参数	domain_id (int32)：0=Traditional，1=RL
返回值	SetControlModeResponse：success (bool)、message (string)
备注	切换后建议调用 GetControlState 确认是否生效。

函数名	GetControlState
接口原型	rpc GetControlState (GetControlStateRequest) returns (GetControlStateResponse)
功能描述	查询当前控制范式。
参数	无（GetControlStateRequest 为空消息）
返回值	GetControlStateResponse：success (bool)、message (string)、domain_id (int32)
备注	domain_id=-1 表示尚未收到状态反馈。

函数名	Shutdown
接口原型	rpc Shutdown (ShutdownRequest) returns (ShutdownResponse)
功能描述	请求关闭机器人控制器。
参数	force (bool)：是否强制关闭
返回值	ShutdownResponse：success (bool)、message (string)
备注	—

---

接口一览表

函数名	功能描述	调用参数	赋值示例
GetRobotState	查询机器人当前状态与可用能力	无	—
SetMode	切换 FSM 状态	target_state	"ZERO", "STAND_WALK", "MULTI_AGENT", "STOP"
SetMotion	播放/停止上半身动作（MULTI_AGENT）	command, motion_file	PLAY, "Sources/motion/Greeting.txt"
SetTrackingMotion	切换全身轨迹文件（MOTION_TRACK）	motion_file	见 手臂动作服务接口
SetVelocity	设置行走速度（预留）	vx, vy, vyaw	0.5, 0.0, 0.0
SetHeight	设置站高（预留）	height	-0.1
SetControlMode	切换控制范式	domain_id	0（Traditional）, 1（RL）
GetControlState	查询控制范式	无	—
Shutdown	关闭控制器	force	false

---

FSM 状态说明

FSM 状态	说明	可用接口（available_actions）
STOP	急停	（无）
ZERO	零位校准	（无）
STAND_WALK	基础站立行走	SetVelocity
MULTI_AGENT	上半身动作叠加	SetVelocity, SetHeight, SetMotion
MOTION_TRACK	全身轨迹跟踪	SetVelocity, SetTrackingMotion
JOG	慢跑	SetVelocity
VISION_TERRAIN	视觉地形	SetVelocity

状态切换说明

从 STAND_WALK 可进入哪些策略态由机器人侧授权决定，实际可切换目标以 GetRobotState().switchable_states 为准。SetVelocity / SetHeight 虽列于部分状态的 available_actions，但目前为预留接口。

---

SetMode 状态取值参考

取值	说明
STOP	急停
ZERO	零位校准
STAND_WALK	基础站立行走
MULTI_AGENT	上半身动作叠加（可调用 SetMotion）
MOTION_TRACK	全身轨迹跟踪（可调用 SetTrackingMotion）
JOG	慢跑
VISION_TERRAIN	视觉地形

---

SetControlMode 取值参考

domain_id	说明
0	Traditional（传统控制）
1	RL 控制
-1	仅出现在 GetControlState 响应，表示尚未收到反馈

---

注意事项

1. 启动顺序：先启动机器人控制程序，再启动客户端。
2. 先查状态再下发：通过 GetRobotState 检查 switchable_states 和 available_actions。
3. 模式切换异步：SetMode 成功后需轮询 fsm_state 确认是否到达目标状态。
4. 上肢动作与轨迹：动作文件、轨迹文件说明见 手臂动作服务接口。
5. 实时上肢控制：见 手臂控制例程（DDS）；灵巧手见 灵巧手控制说明。

---

相关文档

文档	说明
传统控制 gRPC 接口说明	传统控制（MPC）模式 gRPC 接口定义与参数说明
gRPC 例程	客户端获取、环境配置与交互示例
手臂动作服务接口	SetMotion / SetTrackingMotion 与动作文件
手臂控制例程	DDS 实时上肢控制
灵巧手控制说明	DDS 手指控制