5.1.5 Upper Body Control

Control the robot’s head, arms, and hand joints by publishing to the /mc/upper_body_command topic.

Switch to the corresponding motion mode before use. See Motion Mode Switching.

Topic Interface

Topic Name

Message Type

Description

QoS

Frequency

/mc/upper_body_command

aimdk_msgs/msg/UpperBodyCommandArray

Upper body control command

BEST_EFFORT+VOLATILE

User (recommended 50 Hz)

Warning

The header.stamp timestamp must not differ from the motion control module’s receive time by more than 200 ms, otherwise the command will be discarded. If header.stamp is 0, the motion control module uses the receive time as the timestamp.

  • UpperBodyCommandArray ros2-msg @ mc/openapi/msg/UpperBodyCommandArray.msg

    MessageHeader header             # Message header
string source                    # Command source identifier (any non-empty string)
uint8 hand_sub_mode              # Hand sub-mode (1 (HAND_CLAW_OPEN_CLOSE claw open/close), 2 (HAND_DEXTEROUS_JOINT dexterous hand joints), 3 (HAND_DEXTEROUS_GESTURE dexterous hand gesture))
float64[2] head_pos              # Head joint target positions (unit: rad)
float64[14] arm_pos              # Arm joint target positions (left 7 + right 7, unit: rad)
float64[] hand_pos               # Hand targets; length varies with hand_sub_mode

Joint Index

Head (head_pos, length 2) — X2 Ultra only

Index

Joint

0

head_yaw_joint

1

head_pitch_joint

Arms (arm_pos, length 14)

Index

Joint

Index

Joint

0

left_shoulder_pitch_joint

7

right_shoulder_pitch_joint

1

left_shoulder_roll_joint

8

right_shoulder_roll_joint

2

left_shoulder_yaw_joint

9

right_shoulder_yaw_joint

3

left_elbow_joint

10

right_elbow_joint

4

left_wrist_yaw_joint

11

right_wrist_yaw_joint

5

left_wrist_pitch_joint

12

right_wrist_pitch_joint

6

left_wrist_roll_joint

13

right_wrist_roll_joint

Hand (hand_pos, length depends on hand_sub_mode)

hand_sub_mode

Length

Description

1: Claw open/close

2

[left_open, right_open], value range 0.0–1.0

2: Dexterous hand joint

20

Left hand 10 joints + right hand 10 joints; see HandCommand[] for the joint order.

3: Dexterous hand gesture

4

[left_gesture, left_open, right_gesture, right_open], open/close control

Usage

Step 1: Switch to the corresponding mode

Head control (Ultra only; X2 EDU has no head-neck DoF):

ros2 run examples set_mc_action SD   # → STAND_DEFAULT
ros2 run examples set_mc_action HO   # → HEAD_ONLY

Upper body + hand control:

ros2 run examples set_mc_action SD   # → STAND_DEFAULT
ros2 run examples set_mc_action URS  # → UPPERBODY_REMOTE_SPLIT

Note

Head control requires switching to HEAD_ONLY mode first. Head commands are ignored in UPPERBODY_REMOTE_SPLIT mode. The X2 EDU has no head-neck DoF and does not support head control.

Step 2: Run the example

# Head control (HEAD_ONLY mode)
ros2 run py_examples upper_body_control head

# Claw (gripper) control (UPPERBODY_REMOTE_SPLIT mode)
ros2 run py_examples upper_body_control claw

# Dexterous hand joints (UPPERBODY_REMOTE_SPLIT mode)
ros2 run py_examples upper_body_control joint

# Dexterous hand gesture (UPPERBODY_REMOTE_SPLIT mode)
ros2 run py_examples upper_body_control gesture

Programming Examples