1 Interface Overview
The joint command and whole-body control interface is the lowest-level interface for robot motion control. It directly sends joint-level control commands (position, velocity, torque) via the /hardware/joint_command topic, and reads joint state feedback via the /hardware/joint_state topic. This interface is the foundation for advanced control implementations such as PD controller standing and RL policy deployment.
The "joint command/state interface" and "whole-body joint control interface" described in the protocol specification use the same set of topics and messages. The former focuses on message field definitions, while the latter focuses on parameters and torque formulas. They are described together here.
2 Message Fields
Communication Interface:
| Topic Name | Message Type | Direction | Description |
|---|---|---|---|
/hardware/joint_command | JointCommand.msg | Client → Joint Controller | Publish joint control message |
/hardware/joint_state | JointState.msg | Joint Controller → Client | Read joint state feedback |
JointCommand message contains the following parameters:
| Parameter | Description |
|---|---|
position | Target joint position [rad], ordered according to the model joint sequence |
velocity | Target joint velocity, ordered according to the model joint sequence |
feed_forward_torque | Feed-forward torque [N·m] |
torque | Not supported yet |
stiffness | Stiffness kp [N·m/rad] |
damping | Damping kd [N·m·s/rad] |
parallel_parser_type | Parallel joint parser type: 0 = CLASSIC_PARSER (classic parser), 1 = RL_PARSER (reinforcement learning parser) |
JointState.msg field definition (see GitHub Message Directory for the complete definition):
PLAIN |
| Field | Type | Description |
|---|---|---|
position | float64[] | Current joint position (rad) |
velocity | float64[] | Current joint velocity (rad/s) |
torque | float64[] | Current joint torque (N·m) |
The total joint torque is calculated by the following formula:
PLAIN |
Here, position corresponds to q_cmd (target position) in the formula, stiffness corresponds to kp, and damping corresponds to kd; q and qd are the current joint position and velocity, read from /hardware/joint_state. The length of all arrays must be consistent with the robot's total number of joints, num_total_joints.
3 Control Frequency and QoS
| Item | Requirement |
|---|---|
| Recommended control frequency | 100~500 Hz |
| QoS policy | Best Effort (to reduce latency) |
| Array length | All arrays must equal the robot's total number of joints |
| Joint index | Starting from 0 |
| Trajectory interpolation steps | Affects motion smoothness; more steps result in smoother motion |
4 Prerequisites
You must first switch to the joint_bridge (joint passthrough) mode before the joint command interface will respond. See Chapter 1 for the switching method.
| Motion Mode | Gamepad Button |
|---|---|
| Joint pass-through mode (joint_bridge) | [BACK, A] |
5 Example A: PD Controller Standing
File Name: joint_bridge_example.py
This example reads the target position and control parameters from a YAML configuration file, generates a smooth joint trajectory, and sends control commands at a high frequency of 500 Hz, achieving precise joint position control.
Run Command:
Bash |
Configuration File Format (YAML, see GitHub Configuration Directory for example files):
PM01 (24 DOF)
YAML |
T800 Development Edition** (25 DOF)**
YAML |
T800 Pro (43 DOF, with dexterous hands)
YAML |
The three robot models have different numbers of joint groups (PM01/T800 have 6 groups, T800 Pro has 8 groups, including 7 joints in each of the left and right dexterous hands). Please select the corresponding configuration file according to the robot model you are using.
Linear Interpolation Algorithm: For each joint, generate a smooth trajectory according to the following formula:
PLAIN |
This ensures a smooth linear transition from the starting position to the target position.
6 Example B: RL Policy Deployment
Launch File: rl_basic_example.launch.py (located in the GitHub Example Directory)
This example demonstrates how to deploy a reinforcement learning whole-body control policy. Unlike PD controller standing, the joint commands of the RL policy do not come from a YAML configuration file, but are computed in real time by the policy network based on multi-sensor observations.
Communication Interface:
| Topic Name | Message Type | Direction |
|---|---|---|
/hardware/joint_command | JointCommand.msg | Client → Joint Controller |
/hardware/joint_state | JointState.msg | Joint Controller → Client |
/hardware/gamepad_keys | GamepadKeys.msg | Sensor → Client |
/hardware/imu_info | ImuInfo.msg | Sensor → Client |
Run Command:
Bash |
Operation Procedure:
- The robot enters PD standing mode (
pd_stand), standing in a flat and open area; note to install a gantry for protection - Evacuate personnel within 3 meters around the robot
- Enter joint bridge mode (
joint_bridge) - Run the launch file from the command line
- After the experiment ends, return to PD standing or Passive mode
7 Example C: Dexterous Hand Loose Fist
File Name: t800pro/loose_fist_example.py
This example demonstrates using the T800Pro robot's three-fingered dexterous hands to perform a loose fist action, and to return from the loose fist action back to the extended state. It supports controlling the left hand, right hand, or both hands simultaneously.
Run Command:
Bash |
Operation Procedure:
- The robot enters PD standing mode (
pd_stand), standing in a flat and open area; note to install a gantry for protection - Evacuate personnel within 3 meters around the robot
- Enter joint bridge mode (
joint_bridge) - Run the script from the command line; it is recommended to hoist the robot during testing to prevent falls and damage to components
8 Comparison of Two Implementation Paths
| Comparison Dimension | PD Controller Standing | RL Policy Deployment |
|---|---|---|
| Control Objective | Maintain a fixed target joint position | Deploy a reinforcement learning policy to achieve whole-body motion |
| Core Algorithm | Linear interpolation + PD position servo | Reinforcement learning policy network |
| Command Source | YAML configuration file | Computed in real time by the policy network based on observations |
| Required Inputs | Only joint state feedback is required | Joint state + gamepad + IMU |
| Control Frequency | 500 Hz | Determined by the policy inference frame rate (≤500 Hz) |
| Safety Requirements | Target position within the safe range | Flat open area, gantry protection, 3-meter clearance |
| Applicable Scenarios | Static pose holding, bridge testing | Dynamic whole-body motion, RL policy verification |
Commonalities of the two: both need to enter joint_bridge mode, both publish commands through /hardware/joint_command, and both need to ensure that the hardware interface node has been started.
9 Notes
- You must enter
joint_bridgemode before sending joint commands; do not run the example program before entering - The control frequency must be high enough to ensure control stability; 100~500 Hz is recommended
- The length of all arrays must equal the robot's total number of joints
- The
kp(stiffness) andkd(damping) parameters need to be adjusted according to joint characteristics; excessively high stiffness may cause system oscillation - The target position must be within the joint's safe motion range
- 500 Hz high-frequency control places certain demands on system performance
- You can safely exit using Ctrl+C; it is recommended to wait for the motion to complete
- After the RL policy deployment experiment ends, you should return to PD standing or Passive mode
📎 Source files in the open-source repository for this chapter (click file name to jump to GitHub): GamepadKeys.msg · ImuInfo.msg