5.1.9 Joint Control

The joint control interfaces provide precise control over each robot joint, supporting multiple control modes and joint groups.

Key Features

Control Modes

Position Control: Drive a joint to a specified target angle.
Velocity Control: Drive a joint at a specified angular velocity.
Torque Control: Command a joint to output a specified torque.

Supported Joints

Left Arm Joints: 7-DoF (3 shoulder joints, 1 elbow joint, 3 wrist joints).
Right Arm Joints: 7-DoF (3 shoulder joints, 1 elbow joint, 3 wrist joints).
Left Leg Joints: 6-DoF (3 hip joints, 1 knee joint, 2 ankle joints).
Right Leg Joints: 6-DoF (3 hip joints, 1 knee joint, 2 ankle joints).
Waist Joints: Yaw, pitch, and roll.
Head Joints: Pitch^N.Y.A., and yaw

Joint Control Topics

Joints are controlled by body part (arms, legs, waist, head), and closed-loop control can be implemented using status feedback.

Topic Name	Data Type	Description	QoS	Frequency
`/aima/hal/joint/*/command`	`JointCommandArray`	Joint control commands	`BEST_EFFORT`+`VOLATILE`	User (on-demand)
`/aima/hal/joint/*/state`	`JointStateArray`	Joint state feedback	`BEST_EFFORT`+`TRANSIENT_LOCAL`	See note below

Here, * can be head (requires supported head hardware), arm, waist, or leg.

Warning

The low-level joint command topic /aima/hal/joint/*/command has no timeout or fail-safe protection: when the sender stops publishing, the robot does not automatically zero the command or enter a safe state. When using low-level control, you must keep publishing commands at a stable, fixed frequency yourself, and explicitly publish a zero command or a safe pose on exit, to avoid instability caused by an interrupted command stream.

Joint state feedback frequency: The publish frequency of state topics varies by hardware downsampling configuration:

arm, leg, waist: 500 Hz

head: 333 Hz

JointCommandArray ros2-msg @ hal/msg/JointCommandArray.msg

# Joint control command array
MessageHeader header             # Message header
JointCommand[] joints            # Joint command array

JointCommand ros2-msg @ hal/msg/JointCommand.msg

# Joint control command
string name                      # Joint name (optional)
float64 position                 # Position (rad)
float64 velocity                 # Velocity (rad/s)
float64 effort                   # Torque (N·m)
float64 stiffness                # Stiffness (N·m/rad)
float64 damping                  # Damping (N·m·s/rad)

The length and ordering of JointCommand[] are defined in the table below.

Joint group	Length	Contents	Notes
head	2	`head_yaw`, `head_pitch`	X2 Ultra: only yaw is active; X2 Ultra(new version): both yaw and pitch are active; X2 EDU: head joints not supported
waist	3	`waist_yaw`, `waist_pitch`, `waist_roll`
arm	7*2	`shoulder_pitch`, `shoulder_roll`, `shoulder_yaw`, `elbow`, `wrist_yaw`, `wrist_pitch`, `wrist_roll`	All left-side joints first, then all right-side joints
leg	6*2	`hip_pitch`, `hip_roll`, `hip_yaw`, `knee`, `ankle_pitch`, `ankle_roll`	All left-side joints first, then all right-side joints

JointStateArray ros2-msg @ hal/msg/JointStateArray.msg

# Joint state array
MessageHeader header             # Message header
DomainErrorState state           # Joint group error state (state.value: 1 (DAMPING damping mode), 2 (POWERDOWN power-down mode), 3 (DISABLE disable mode), 4 (DISCONNECT communication disconnected), others (no state))
JointState[] joints              # Joint state array

JointState ros2-msg @ hal/msg/JointState.msg

# Joint state information
string name                      # Joint name; see the joint order table below
float64 position                 # Position (rad)
float64 velocity                 # Velocity (rad/s)
float64 effort                   # Torque (N·m, for arm/leg/waist only; use HandCommand for hands)
uint16 error_code                # Error code

The length and ordering of JointState[] follow the JointCommand[] joint ordering described in Joint Order.

Joint State Query Service

Service Name	Data Type	Description
`/aimdk_5Fmsgs/srv/GetAllJointState`	`GetAllJointState`	Actively query joint states

GetAllJointState ros2-srv @ hal/srv/GetAllJointState.srv

# Get all joint states
# Service: /aimdk_5Fmsgs/srv/GetAllJointState

# Request
CommonRequest request            # Common request

---

# Response
CommonResponse reponse           # Common response (not enabled; read the joint-state fields below directly)
JointState[] head_joints         # Head joint states
JointState[] arm_joints          # Arm joint states
JointState[] waist_joints        # Waist joint states
JointState[] leg_joints          # Leg joint states

The length and ordering of JointState[] follow the JointCommand[] joint ordering description above.

Note

The reponse field of this service is not enabled. Read head_joints/arm_joints/waist_joints/leg_joints directly, and do not rely on reponse.header.code/status to determine success or failure.

Programming Examples

For detailed examples and code explanations, refer to:

C++ Example: Joint Motor Control
Python Example: Joint Motor Control

Safety Notes

Warning

Joint Limits

All joints have motion range limits; exceeding them may cause mechanical damage.
Check that joint angles are within their safe ranges before sending commands.
Be especially cautious about safety limits when using torque control.

Caution

As standard ROS DO NOT handle cross-host service (request-response) well, please refer to SDK examples to use open interfaces in a robust way (with protection mechanisms e.g. exception safety and retransmission)

While the robot is in Stable Standing Mode or Locomotion Mode, DO NOT launch ROS nodes in rapid bulk (no more than 2 nodes per second is recommended), as a large number of nodes joining DDS discovery within a short period causes communication congestion and degrades motion control real-time performance, which may cause the robot to lose balance and fall

Note

Best Practices

Use smooth trajectory planning to avoid sudden joint motions.
Implement joint state monitoring and anomaly detection.
Ensure the robot is in a safe state before issuing control commands.