☰

AIMA开放平台文档中心AimDK A3-ultra

7.1 Motion Control

7.1 Motion Control

7.1.2 State Machine Switching and Query RPC Interfaces

Interface Name	`pb:/aimdk.protocol.MotionControlActionService/SetAction`
Function Overview	Switch the 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 it from the GetAvailableActions interface ext_action: Obtain it from the 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
Notes	This is an asynchronous interface. Completion of the call does not mean the switch has completed. Use the GetAction interface to check whether the switch is complete. This interface has no Action restrictions

Interface Name	`pb:/aimdk.protocol.MotionControlActionService/GetAction`
Function Overview	Query the 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: The currently running Action ext_action: Extended Action, generally not used status: Action status, generally not used
Example Script	example/mc/S_GetAction.py
Notes	This interface has no Action restrictions

7.1.3 RPC Interface for Querying Available Robot Actions

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 a switchable action ext_action: Action code name corresponding to the `action` output field
Example Script	examples/mc/S_SetAction.py
Notes	In general, you first use GetAvailableActions to query the currently switchable actions, and then use SetAction to set the action state.

7.1.4 Walking Control Command Topic Interface

Interface Name	`/motion/control/locomotion_velocity`
Function Overview	Walking 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 navigation mode forward_velocity: Forward velocity scale factor. The sent scale factor ranges from -1.0 to 1.0. `+` means forward and `-` means backward. The actual speed is calculated by `mc`. lateral_velocity: Lateral velocity scale factor. The sent scale factor ranges from -1.0 to 1.0. `+` means moving left and `-` means moving right. The actual speed is calculated by `mc`. angular_velocity: Angular velocity scale factor. The sent scale factor ranges from -1.0 to 1.0. `+` means rotating left and `-` means rotating right. The actual speed is calculated by `mc`.
Example Script	examples/mc/walk.py
Notes	The ROS2 message type is `ros2_plugin_proto/msg/RosMsgWrapper`. Run `source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash` before using it. This interface has invocation restrictions and can only be called 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 fixed 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. You must fill in the angle values of all 14 joints. velocity: Invalid field. Set it to 0.0. effort: Invalid field. Set it to 0.0.
Example Script	examples/mc/arm.py
Notes	It is recommended to call this interface at 100 Hz. Ensure that the interval between adjacent commands does not exceed 30 ms, the speed does not exceed 4 rad/s, and the commands remain as smooth as possible. Otherwise, jitter may occur. At a minimum, use a basic low-pass filter: y(k) = (1 - a) * y(k - 1) + a * x(k). The angle limits are as follows (unit: rad) left_shoulder_pitch_joint: ±2.87979 left_shoulder_roll_joint: -0.08727 ~ 2.61799 left_shoulder_yaw_joint: ±2.79253 left_elbow_joint: -0.95993 ~ 1.74533 left_wrist_roll_joint: ±2.79253 left_wrist_pitch_joint: ±1.62316 left_wrist_yaw_joint: ±1.62316 right_shoulder_pitch_joint: ±2.87979 right_shoulder_roll_joint: -2.61799 ~ 0.08727 right_shoulder_yaw_joint: ±2.79253 right_elbow_joint: -0.95993 ~ 1.74533 right_wrist_roll_joint: ±2.79253 right_wrist_pitch_joint: ±1.62316 right_wrist_yaw_joint: ±1.62316 This interface has invocation restrictions and can only be called in the MOTION state. Because the `motion_player` module continuously sends commands to the `motion_control` module, stop the `motion_player` module before sending commands.

Interface Name	`/motion/control/arm_joint_state`
Function Overview	Arm joint state topic
Interface Type	ROS2 Topic
Output Parameters	sensor_msgs::msg::JointState name: Names of the 14 joints position: Angles of the 14 joints velocity: Velocities of the 14 joints effort: Torques of the 14 joints
Example Script	examples/mc/joint_state.py
Notes	This interface has no Action restrictions

7.1.6 Waist Posture Control Topic Interface

Interface Name	`/motion/control/move_waist`
Function Overview	Waist posture control
Interface Type	ros2 topic
Input Parameters	text `{ "header": { "timestamp": { "seconds": 1763681490, "nanos": 943287000, "ms_since_epoch": 1763681490943 }, "control_source": "ControlSource_MANUAL" }, "waist_pitch": 0.1, "waist_roll": 0, "waist_yaw": 0, "waist_height": -0.1, }` The parameter ranges are as follows: double waist_pitch // range: [0.0, 0.4] unit: rad double waist_roll // range: [-0.314, 0.314] unit: rad double waist_yaw // range: [-1.6, 1.6] unit: rad double waist_height // range: [-0.3, 0.0] unit: m
Example Script	examples/mc/move_waist.py
Notes	The ROS2 message type is `ros2_plugin_proto/msg/RosMsgWrapper`. Run `source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash` before using it. Because the `motion_player` module continuously sends commands to the `motion_control` module, stop the `motion_player` module before sending commands.

7.1.7 Neck Control Command and State Topic Interfaces

Interface Name	`/motion/control/neck_joint_command`
Function Overview	Neck control command
Interface Type	ROS2 Topic
Input Parameters	sensor_msgs::msg::JointState name: Joint names. Must be fixed as ["head_yaw_joint", "head_pitch_joint"] position: Joint angles. The first value represents the yaw degree of freedom, ranging from -1.04720 to 1.04720. The second value represents the pitch degree of freedom, ranging from -0.43633 to 0.26180. velocity: Invalid field. Leave it empty. effort: Invalid field. Leave it empty.
Example Script	examples/mc/neck.py
Notes	Note: this interface can only be called in the motion state.

Interface Name	`/motion/control/neck_joint_state`
Function Overview	Neck state topic
Interface Type	ROS2 Topic
Output Parameters	sensor_msgs::msg::JointState position: Joint angles. The first value represents the yaw degree of freedom, ranging from -1.04720 to 1.04720. The second value represents the pitch degree of freedom, ranging from -0.43633 to 0.26180.
Example Script	examples/mc/joint_state.py
Notes	Because the `motion_player` module continuously sends commands to the `motion_control` module, stop the `motion_player` module before sending commands.

7.1.8 Finger Control Command and State Topic Interfaces

Interface Name	`/motion/control/hand_joint_command`
Function Overview	Finger control command
Interface Type	ROS2 Topic
Input Parameters	sensor_msgs::msg::JointState frame_id: Hand type of A3. A3 supports two types: AgiHand and O10Hand. If left empty, AgiHand is used by default. The current hand type can be identified from the `header.frame_id` field in the `hand_joint_state` topic. name: Joint names. This field may be left empty to use the default values, or obtained from the `name` field of the `hand_joint_state` topic. position: Joint angles. The order corresponds to the joints listed in the `name` field. The range is 0 to 4096 This is an abstract unitless value, where 0 means fully open and 2000 means fully closed. velocity: Invalid field. Leave it empty. effort: Joint torque, currently unavailable and will be supported in a future release
Example Script	examples/mc/hand.py
Notes	This interface has invocation restrictions and can only be called in the `motion` state. Because the `motion_player` module continuously sends commands to the `motion_control` module, stop the `motion_player` module before sending commands.

Interface Name	`/motion/control/hand_joint_state`
Function Overview	Finger state topic
Interface Type	ROS2 Topic
Output Parameters	sensor_msgs::msg::JointState name: Joint names of each finger frame_id: A2 hand type position: Joint angles of each finger, ranging from 0 to 4096 velocity: Invalid field effort: Joint torque, currently unavailable and will be supported in a future release. For AgiHand, the output contains 12 dimensions corresponding to each joint. For O10Hand, the output is formed by concatenating multidimensional arrays. It also includes pressure sensor array data for both hands, arranged as follows: - Left-hand pressure: 16-dim thumb + 16-dim index + 16-dim middle + 16-dim ring + 16-dim pinky + 25-dim palm + 25-dim back_of_hand - Right-hand pressure: Same structure and order as the left hand, appended after the left-hand data
Example Script	examples/mc/joint_state.py
Notes	Due to zero-position offset, the position range may drift slightly. This is normal.

7.1.9 Enable Arm Compliance

Interface Name	`pb:/aimdk.protocol.MotionControlMotionService/EnableArmCompliance`
Function Overview	Enable arm compliance mode
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/EnableArmCompliance
Input Parameters	text `{ }`
Output Parameters	text `{ "header":{ "code":"1", "msg":"enabled", "timestamp":{"seconds":"1790144293","nanos":597150317,"ms_since_epoch":"0"}, "trace_id":"module_mc", "domin":"" }, "state":"CommonState_SUCCESS" }` `msg: enabled` indicates that arm compliance is enabled.
Example Script	examples/mc/EnableArmCompliance.sh
Notes	Arm compliance mode can improve arm control accuracy.

7.1.10 Disable Arm Compliance

Interface Name	`pb:/aimdk.protocol.MotionControlMotionService/DisableArmCompliance`
Function Overview	Disable arm compliance mode
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/DisableArmCompliance
Input Parameters	text `{ }`
Output Parameters	text `{ "header":{ "code":"1", "msg":"disabled", "timestamp":{"seconds":"1790144293","nanos":597150317,"ms_since_epoch":"0"}, "trace_id":"module_mc", "domin":"" }, "state":"CommonState_SUCCESS" }` `msg: disabled` indicates that arm compliance is disabled.
Example Script	examples/mc/DisableArmCompliance.sh
Notes

7.1.11 Check Arm Compliance

Interface Name	`pb:/aimdk.protocol.MotionControlMotionService/CheckArmCompliance`
Function Overview	Query the arm compliance mode status
Interface Type	HTTP JSON RPC
URL	http://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/DisableArmCompliance
Input Parameters	text `{ }`
Output Parameters	text `{ "header":{ "code":"1", "msg":"disabled", "timestamp":{"seconds":"1790144293","nanos":597150317,"ms_since_epoch":"0"}, "trace_id":"module_mc", "domin":"" }, "state":"CommonState_SUCCESS" }` `msg: disabled` indicates the disabled state, while `enabled` indicates the enabled state.
Example Script	examples/mc/CheckArmCompliance.sh
Notes