Arm Motion Service Interface

Adam supports upper-body interaction via motion files and full-body tracking via trajectory files, exposed through gRPC SetMotion and SetTrackingMotion. For the full gRPC reference, see RL gRPC Interface; for client setup, see gRPC Example.

Unlike Arm Control Example (DDS real-time joints), this service plays pre-recorded .txt files on the robot—no per-frame joint commands from the client.

Item	Description
Transport	gRPC, port `50051`
Service	`RobotControl`
Action discovery	No separate `GetActionList`; use `GetRobotState` for FSM and `available_actions`
Client project	pnd_grpc

Motion File Deployment

Item	Description
Control program root	`/etc/pndbotics/pnd_adam_dds/`
Motion directory (relative)	`Sources/motion/`
Motion directory (absolute)	`/etc/pndbotics/pnd_adam_dds/Sources/motion/`
Path resolution	Relative paths resolve from the control program root (`PndControl` working directory); absolute paths are supported

For SetMotion, motion_file must point to a real .txt on the robot. A local copy on the client does not guarantee playback.

API Summary

API	Description	Parameters	Example values	Required FSM
`SetMotion`	Play upper-body motion file	`command`, `motion_file`	`PLAY`, `"Sources/motion/Greeting.txt"`	`MULTI_AGENT`
`SetMotion`	Stop current motion playback	`command`	`STOP`	`MULTI_AGENT`
`SetTrackingMotion`	Switch full-body trajectory file	`motion_file`	See "Trajectory File List"	`MOTION_TRACK`
`GetRobotState`	Query state, available APIs, playback progress	—	—	Any

Prerequisites

Before calling SetMotion / SetTrackingMotion, confirm GetRobotState().available_actions includes the target API and fsm_state matches the table above.

Typical flow:

STOP → ZERO → STAND_WALK → MULTI_AGENT (SetMotion)
                         → MOTION_TRACK (SetTrackingMotion)

API Description

pnd.robot.RobotControl (Motion and Tracking)

The APIs below belong to the RobotControl service. For the full RPC list, see RL gRPC Interface.

API	SetMotion
Prototype	rpc SetMotion (SetMotionRequest) returns (SetMotionResponse)
Description	Play or stop an upper-body motion file in `MULTI_AGENT`.
Parameters	`command` (enum): `PLAY` / `STOP` `motion_file` (string): required for `PLAY`; must be an existing `.txt` on the robot
Return	`SetMotionResponse`: `success` (bool), `message` (string), `current_motion` (string), `is_playing` (bool)
Note	Callable only when `available_actions` includes `SetMotion`; relative paths resolve from `/etc/pndbotics/pnd_adam_dds/`. CLI: `robot> motion play Sources/motion/Greeting.txt`

API	SetTrackingMotion
Prototype	rpc SetTrackingMotion (SetTrackingMotionRequest) returns (SetTrackingMotionResponse)
Description	Switch full-body trajectory tracking file in `MOTION_TRACK`.
Parameters	`motion_file` (string): trajectory file path on the robot
Return	`SetTrackingMotionResponse`: `success` (bool), `message` (string), `current_tracking_motion` (string)
Note	Callable only when `available_actions` includes `SetTrackingMotion`. See trajectory notes below.

API	GetRobotState
Prototype	rpc GetRobotState (GetRobotStateRequest) returns (GetRobotStateResponse)
Description	Query FSM, available APIs, and motion/tracking playback progress.
Parameters	None
Return	Motion-related fields: `fsm_state`, `available_actions`, `motion_playing`, `current_motion_file`, `tracking_playing`, `current_tracking_motion`
Note	Call before sending motion commands; poll `motion_playing` / `current_motion_file` after playback.

Preset Upper-Body Motions

PND gRPC uses motion file paths (not action IDs) with SetMotion. Paths below are relative to /etc/pndbotics/pnd_adam_dds/.

Motion name	File path	Description
Greeting	`Sources/motion/Greeting.txt`	Wave/hello gesture
Chest Expansion	`Sources/motion/Chest Expansion.txt`	Chest expansion
Stretching	`Sources/motion/Stretching.txt`	Stretching
Gentleman's Salute	`Sources/motion/Gentleman's Salute.txt`	Gentleman's salute
hello_everyone	`Sources/motion/hello_everyone.txt`	Group greeting
太极	`Sources/motion/太极.txt`	Tai chi
弹吉他	`Sources/motion/弹吉他.txt`	Play guitar
弹钢琴	`Sources/motion/弹钢琴.txt`	Play piano
热身	`Sources/motion/热身.txt`	Warm-up
金蛇狂舞	`Sources/motion/金蛇狂舞.txt`	Golden Snake Dance

Filenames

When filenames contain spaces or non-ASCII characters, motion_file must match the on-disk name exactly.

Trajectory File List

SetTrackingMotion plays full-body trajectory tracking files. Trajectory files are typically mocap recordings; deployment paths may vary by software version and configuration.

Note
`motion_file` must point to a real `.txt` on the robot
Trajectory files are typically mocap recordings and must be deployed to a path accessible to the control program before calling
Custom trajectory directories may vary by software version and configuration

Usage Examples

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"

# Relative path (recommended)
resp = stub.SetMotion(pb2.SetMotionRequest(
    command=pb2.SetMotionRequest.PLAY,
    motion_file="Sources/motion/Greeting.txt",
))

# Or absolute path
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>

Motion File Format

Item	Description
Format	`.txt` suffix
Location	`/etc/pndbotics/pnd_adam_dds/Sources/motion/`
Path resolution	Relative to `/etc/pndbotics/pnd_adam_dds/`; absolute paths supported
Example	`Sources/motion/Greeting.txt`

Errors and Troubleshooting

Symptom	Likely cause	Suggestion
`success=false`	Wrong FSM	Check `fsm_state` and `switchable_states`
`success=false`	API not in `available_actions`	`SetMode` to the correct FSM first
`success=false`	File missing	Use `Sources/motion/<filename>.txt`
Command OK, no motion	Async execution	Poll `motion_playing` / `current_motion_file`
Conflict with DDS	Same joints via `rt/lowcmd`	Confirm control-source priority

Doc	Description
RL gRPC Interface	Full RPC and FSM reference
gRPC Example	Client setup and CLI
Arm Control Example	DDS real-time upper-body control
Hand Control	DDS finger control