7.1 Motion Control Section

7.1.1 Overall Introduction

The A3 robot comes pre-installed with a motion control program. Users only need to send high-level commands to directly control the robot’s movement, without needing to develop low-level control models for functions such as walking.

The Zhiyuan Yunkong program features an internal state machine that switches between different models depending on the current state. The state machine is illustrated in the figure below:

The descriptions for each status are as follows:

The descriptions for each state are as follows:

Action Type	Action Code	Chinese Name	Detailed Description	Available Control Interfaces
Safe Action	PASSIVE	Default Mode	The default action after motion control starts
Safe Action	DAMPING	Damping Mode	Joints can still move, but with high damping, can be fixed
Position Control Action	PD_STAND	Position Control Stand Mode	The robot stands in position control; joint initialization before entering force control mode
Force Control Action	MOTION	Motion Mode	In this mode, the robot can walk, perform upper limb movements, dance, etc.	/motion/control/arm_joint_command
Force Control Action	SIT_DOWN	Sit Down Mode	Used together with STAND_UP mode
Force Control Action	STAND_UP	Stand Up Mode	Used together with SIT_DOWN mode
Force Control Action	LIE_DOWN	Lie Down Mode	Used together with GET_UP mode
Force Control Action	GET_UP	Get Up Mode	Used together with LIE_DOWN mode
Force Control Action	PACKAGE_LIE_DOWN	Package Lie Down Mode	Used together with PACKAGE_GET_UP mode
Force Control Action	PACKAGE_GET_UP	Package Get Up Mode	Used together with PACKAGE_LIE_DOWN mode

In general, it is not recommended to use the program to switch between non-force control states. Only switching between force control states is recommended programmatically. Other switches, such as lifting or placing the robot, should only be performed manually.

Control interfaces usually have Action requirements. Interfaces without specified Action requirements and query interfaces generally have no Action restrictions.

7.1.2 State Machine Switching and Query RPC Interfaces

Interface Name	`pb:/aimdk.protocol.MotionControlActionService/SetAction`
Function Overview	Switch motion control state machine
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/SetAction
Input Parameters	text `{ "header": { "timestamp": { "seconds": 1763614279, "nanos": 847810000, "ms_since_epoch": 1763614279847 }, "control_source": "ControlSource_SAFE" }, "command": { "action": "MotionControlAction_GET_UP", "ext_action": "GET_UP" } }` action: Obtain from GetAvailableActions interface ext_action: Obtain from GetAvailableActions interface
Output Parameters	text `{ "header": { "code": "0", "msg": "called successfully.", "timestamp": { "seconds": "1763643079", "nanos": 849593506, "ms_since_epoch": "0" }, "trace_id": "", "domin": "" }, "state": "CommonState_SUCCESS" }` state: Request status
Example Script	examples/mc/S_SetAction.py
Remarks	This is an asynchronous interface. Completion of the call does not mean the switch is complete. Use the GetAction interface to check if the switch is finished. This interface has no Action restrictions.

Interface Name	`pb:/aimdk.protocol.MotionControlActionService/GetAction`
Function Overview	Query motion control state machine
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/GetAction
Input Parameters	text `{}`
Output Parameters	text `{ "header": { "code": "0", "msg": "called successfully.", "timestamp": { "seconds": "1763643026", "nanos": 8207141, "ms_since_epoch": "0" }, "trace_id": "", "domin": "" }, "info": { "current_action": "MotionControlAction_PASSIVE", "ext_action": "", "status": "MotionControlActionStatus_RUNNING" } }` current_action: Currently running Action ext_action: Extended Action, generally not used status: Action status, generally not used
Example Script	example/mc/S_GetAction.py
Remarks	This interface has no Action restrictions.

7.1.3 Robot Available Actions Query RPC Interface

Interface Name	`pb:/aimdk.protocol.MotionControlActionService/GetAvailableActions`
Function Overview	Get available actions
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/GetAvailableActions
Input Parameters	text `{ "header": { "timestamp": { "seconds": "0", "nanos": 0, "ms_since_epoch": "1744598548952" } } }`
Output Parameters	text `{ "header": { "code": "0", "msg": "called successfully.", "timestamp": { "seconds": "1775639638", "nanos": 585833612, "ms_since_epoch": "0" }, "trace_id": "module_mc", "domin": "" }, "commands": [ { "action": "MotionControlAction_DAMPING", "ext_action": "DAMPING" }, { "action": "MotionControlAction_GET_UP", "ext_action": "GET_UP" }, { "action": "MotionControlAction_LIE_DOWN", "ext_action": "LIE_DOWN" }, ...... ] }` action: Name of the switchable action ext_action: Action code name, corresponds to action output parameter
Example Script	examples/mc/S_SetAction.py
Remarks	Usually, the current switchable action state is queried through the GetAvailableActions interface, and then the action state is set through the SetAction interface.

7.1.4 Locomotion Control Command Topic Interface

Interface Name	`/motion/control/locomotion_velocity`
Function Overview	Locomotion control command
Interface Type	ROS2 Topic
Input Parameters	text `{ "data": { "mode": MotionControl_LocomotionMode_DEFAULT, "forward_velocity": 0.1, "lateral_velocity": 0.0, "angular_velocity": 0.0 } }` mode: Velocity control mode MotionControl_LocomotionMode_DEFAULT is the default mode MotionControl_LocomotionMode_NAVIGATION is the navigation mode forward_velocity: Forward velocity ratio, range -1.0~1.0. Positive for forward, negative for backward. The actual speed is calculated by mc. lateral_velocity: Lateral velocity ratio, range -1.0~1.0. Positive for left movement, negative for right movement. The actual speed is calculated by mc. angular_velocity: Angular velocity ratio, range -1.0~1.0. Positive for left rotation, negative for right rotation. The actual speed is calculated by mc.
Example Script	examples/mc/walk.py
Remarks	The ROS2 type of this message is ros2_plugin_proto/msg/RosMsgWrapper. You need to source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash before using it. This interface has call restrictions and can only be used in the MOTION state.

7.1.5 Arm Control Command and State Topic Interfaces

Interface Name	`/motion/control/arm_joint_command`
Function Overview	Arm joint control command
Interface Type	ROS2 Topic
Input Parameters	sensor_msgs::msg::JointState name: Joint names, must be set as ["left_shoulder_pitch_joint","left_shoulder_roll_joint","left_shoulder_yaw_joint", "left_elbow_joint", "left_wrist_roll_joint", "left_wrist_pitch_joint", "left_wrist_yaw_joint", "right_shoulder_pitch_joint", "right_shoulder_roll_joint", "right_shoulder_yaw_joint", "right_elbow_joint", "right_wrist_roll_joint", "right_wrist_pitch_joint", "right_wrist_yaw_joint"] position: Joint angles, must provide 14 joint angle values velocity: Invalid field, set to 0.0 effort: Invalid field, set to 0.0
Example Script	examples/mc/arm.py
Remarks	This interface is recommended to be called at a frequency of 100 Hz. The interval between adjacent commands should not exceed 30 ms, ensure the speed does not exceed 4 rad/s, and keep the commands as smooth as possible to avoid jitter. It is recommended to use at least a basic low-pass filter: y(k) = (1 - a) * y(k - 1) + a * x(k). Joint angle limits (unit: rad): left_shoulder_pitch_joint: ±2.967 left_shoulder_roll_joint: ±1.588 left_shoulder_yaw_joint: ±2.793 left_elbow_joint: -1.047 ~ 2.444 left_wrist_roll_joint: ±0.576 left_wrist_pitch_joint: ±1.623 left_wrist_yaw_joint: ±2.793 right_shoulder_pitch_joint: ±2.967 right_shoulder_roll_joint: ±1.588 right_shoulder_yaw_joint: ±2.793 right_elbow_joint: -1.047 ~ 2.444 right_wrist_roll_joint: ±0.576 right_wrist_pitch_joint: ±1.623 right_wrist_yaw_joint: ±2.793 This interface has call restrictions and can only be used in the MOTION state.

Interface Name	`/motion/control/arm_joint_state`
Function Overview	Arm joint state topic
Interface Type	ROS2 Topic
Output Parameters	sensor_msgs::msg::JointState name: 14 joint names position: 14 joint angles velocity: 14 joint velocities effort: 14 joint torques
Example Script	examples/mc/joint_state.py
Remarks	This interface has no Action restrictions.