High-level whole-body coordination and control interface
About 4519 wordsAbout 15 min
Developers can conveniently access robot status, send control commands, and implement complex task programming and integration through standard ROS 2 communication mechanisms, including Topics, Services, and Actions.
Topic: A subscription‑based communication mechanism. Subscribers register for a specific topic, and publishers send messages to all registered subscribers based on the subscription list. This mechanism is primarily used for medium‑to‑high frequency or continuous data exchange.
Service: A request‑reply communication mechanism. Data retrieval or operations are performed via service requests. It is suitable for low‑frequency interactions or mode‑switching operations.
Action: A persistent, stateful communication mechanism designed for long‑running tasks. It supports real‑time status feedback and task cancellation during execution, making it ideal for complex motion control and task execution.
Interface Description
The high-level whole-body coordination and control interface is used to configure robot operating parameters (TCP coordinate system/load/speed), execute Cartesian space motion (joint motion/linear motion/trajectory tracking), call the built-in kinematic solver (forward/inverse kinematics), and switch to advanced modes (zero-force dragging/impedance control/teleoperation).
Real Device
| Service | /control/set_property |
|---|---|
| Effective Version | ≥V0.3.0 |
| Access Method | Service Call
|
| Interface Description | Dynamically configure robot operating parameters, supporting functions such as speed ratio, end-effector pose, error clearing, zero-force drag enable, operation mode switching, impedance parameter setting, etc. |
| Interface Parameters | string property_type{ // Operation type, enumeration "SpeedRatio"; // Set the operating speed ratio of the robot "TcpPrimary"; // Set the position and orientation of the left arm end effector, represented by a quaternion "TcpSecondary"; // Set the position and orientation of the end effector of the right arm, represented by a quaternion "ClearError"; // Clear the robot's error status "SafeLevel"; // Sets the safety level, uniformly regulating a series of safety behaviors of the robot such as collision detection, motion limitation, force control threshold, etc. The larger the value, the stricter the safety restrictions "EnableDrag"; // Enable and disable the zero-force drag function "EnableSleep"; // Whether to enter sleep (standby) mode "SwitchRunMode"; // Switch operating mode "JointStiffness"; // Sets the joint stiffness in joint impedance mode. The larger the value, the stronger the joint rigidity. "JointDamping"; // Sets the joint damping in joint impedance mode. The larger the value, the greater the joint damping. "CartStiffness"; // Sets the stiffness coefficient of the robot in Cartesian space in Cartesian impedance mode. "CartDampingRatio"; // Sets the damping ratio of the robot in Cartesian space in Cartesian impedance mode. }; |
| string value{ // The value of value is associated with property_type } - If property_type is SpeedRatio, the value range is [0.01, 1.0], the data type is float64, example: "value": "0.5"; - If property_type is TcpPrimary, the format of value is "x, y, z, qw, qx, qy, qz", the data type is float64, the unit of position is meters, the unit of pose is radians, represented by quaternions, example: "value": "x, y, z, qw, qx, qy, qz"; - If property_type is TcpSecondary, the format of value is "x, y, z, qw, qx, qy, qz", the data type is float64, the unit of position is meters, the unit of attitude is radians, represented by quaternions, example: "value": "x, y, z, qw, qx, qy, qz"; - If property_type is ClearError, value is an empty string, example: "value": " "; - If property_type is SafeLevel, the value range is [0.1, 1.0], the data type is float64, example: "value": "0.3"; - If property_type is EnableDrag, the data type of value is bool, where "1" indicates enabling the zero-force drag function, "0" indicates disabling the zero-force drag function, example: "value": "1"; - If property_type is EnableSleep, the data type of the value range is bool, where "1" indicates enabling sleep, "0" indicates disabling sleep (wake-up), example: "value":"1"; - If property_type is SwitchRunMode, the data type of value is double, where "0" represents position mode, "1" represents joint impedance mode, "2" represents drag mode, and "3" represents Cartesian impedance mode; - If property_type is JointStiffness, the data type of value is float64, with the unit of Newton-meter per radian (Nm/rad), example: value: '50';The stiffness of each joint of the arm joints can also be set separately. The number of data must be 14, which is the degrees of freedom of both arms. It is invalid when the length is incorrect. Example: value: '50, 50, 10, 10, 10, 10, 10, 50, 50, 10, 10, 10, 10, 10'; - If property_type is JointDamping, the data type of value is float64, with the unit of Newton meter second per radian (Nm·s/rad), example: value: '50', must be used in conjunction with JointStiffness to form a complete impedance control together; - If property_type is CartStiffness, the data type of value is float64, with the unit of Newton meters per radian (Nm/rad), example: value: '200'; - If property_type is CartDampingRatio, the data type of value is float64, example: value: '0.8'; } | |
| uint64 request_id: Returns the instruction number of this instruction, used to track the execution status of the instruction |
| Action | /control/move_robot |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Action Call
|
| Interface Description | Controls multi-modal motion of the robot, covering joint motion, linear motion, real-time flow control (joint/end pose), and supports single-arm/double-arm/whole-body joint control |
| Interface Parameters | string type{ // Set motion control mode, enumeration "MoveJoint"; // Controls each joint of the robot to move to a specified angle, achieving joint space motion "MoveLine"; // Controls the end effector to move linearly to the target pose "StartJointStreaming"; // Continuously receive joint position commands and dynamically adjust joint states "StartEEPoseStreaming"; // Continuously receive end-effector pose commands and dynamically adjust the end-effector position "StopMove"; // Stop movement }; |
| string motion_group{ // Specifies the robot parts participating in motion control, enumeration "Primary"; // Left arm, with 7 joints, suitable for single-arm independent tasks "Secondary"; // Right arm, with 7 joints, suitable for single-arm independent tasks "BothArms"; // Both arms, with 14 joints, suitable for dual-arm collaborative tasks "Torso"; // Torso, number of joints is 3 "WholeBody"; // Whole body joints, with a joint count of 20, suitable for whole body coordinated movement }; | |
| float32[] target{ // The value of target is associated with type and motion_group - If type is MoveJoint, target is an array of joint angles, formatted as [joint 1 position, …, joint n position], where n is determined by motion_group. For example, when selecting Primary (left arm), n is 7, and when selecting BothArms (both arms), n is 14. The unit of the angles is radians. - If type is MoveLine, target is the end-effector target pose or torso pose, where the end-effector target pose is in the format [x, y, z, qw, qx, qy, qz], the torso pose is in the format [x, z, ry], the unit of position is meters, and the unit of orientation is radians. - If type is StartJointStreaming / StartEEPoseStreaming, dynamically target data is passed in real-time according to the corresponding control logic. }; | |
| bool success: Returns a boolean value, where "1" indicates successful execution of this instruction, and "0" indicates failed execution of this instruction | |
| uint64 request_id: Returns the instruction number of this command, used to track the instruction execution process, associate logs, or query status |
| Topic | /feedback/robot_server_state |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Subscribe |
| Interface Description | Obtain the current state of the robot server, including operating mode, task queue, and poses of joints and end-effectors |
| Interface Parameters | uint64 timestamp: Timestamp |
| string status{ // Enum, current status of the robot server Running; // In progress, can be used in conjunction with latest_queued_id/latest_finished_id to track the task flow Init; // Initial state, will also switch to this state if OP is dropped Error; //Exception, need to combine with latest_errordrop_id to locate the error request Idle; // Idle, no task queue }; | |
| string run_mode{ // Enum, robot operating mode Position; // Position Mode Drag; // Drag Mode Impedance; // Impedance Mode Sleep; // Sleep mode (will disable) }; | |
| uint64 latest_queued_id: The ID of the latest queued request, representing the ID of the latest request that has entered the queue and is waiting to be executed. It reflects the priority of tasks to be executed and the length of the queue. If the queue continues to grow (latest_queued_id is frequently updated), the task execution efficiency needs to be investigated. | |
| uint64 latest_finished_id: The ID of the latest completed request, representing the ID of the latest request that has been executed, used to verify the task execution result | |
| uint64 latest_errordrop_id: The latest error reporting instruction number, which is a key clue for troubleshooting | |
| string[] motor_status: Operating status of 20 joint motors, "OP" indicates normal operation, formatted as ["OP", "OP",...] | |
| float64[] motor_temperature: Temperatures of 20 joint motors, formatted as [33, 33, 33,...], unit: °C | |
| uint8[] motor_error_code: Motor error code, formatted as [0, 0, 0,...], where 0: No error, 10: Speed error exceeds the limit value, 20: Position error exceeds the limit value, 30: Master station offline | |
| float64[] joint_position: The current position of each joint of the robot, formatted as [-0.0015, -0.0015, -0.0011,...], with the unit of radians (rad) | |
| float64[] joint_velocity: Joint velocities of the 20 joints of the robot, formatted as [0.0000, 0.0000, 0.0000,...], with the unit of radians per second | |
| float64[] joint_torque: The actual joint torques of the robot's 20 joints, formatted as [-2.0010, 1.3920, -2.6100,...], with the unit of Nm | |
| float64[] force_sensor: Six-dimensional force sensor data, formatted as [0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000], with the first six digits for the left hand and the last six digits for the right hand | |
| float64[] ee_pose: The pose of the end-effector, represented by quaternions, with the format [x, y, z, qw, qx, qy, qz, x, y, z, qw, qx, qy, qz]. The first 7 elements [x, y, z, qw, qx, qy, qz] represent the pose of the left arm, and the last 7 elements [x, y, z, qw, qx, qy, qz] represent the pose of the right arm. The unit of position is meters, and the unit of orientation is radians. | |
| float64[] torso_pose_X_Z_RY: Torso pose [X coordinate, Z coordinate, RY rotation], formatted as [-0.0022, 1.1298, -0.0041], with X/Z coordinates in meters and RY rotation in radians |
| Topic | /control/streaming_command |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Publish
|
| Interface Description | Send continuous control commands to drive the movement of the robot's left and right arms |
| Interface Parameters | uint64 request_id: A unique ID bound to the start streaming request, used for instruction identification. The robot server uses this ID to distinguish different flow control tasks and avoid confusion among multi-task instructions |
| bool streaming_finished: Marks whether the current instruction is the last frame of the flow control sequence. True indicates that the current flow control will be terminated immediately after sending, and the robot will stop receiving subsequent instructions, which can be used to end a trajectory or reset the arm; False indicates that the flow control mode will remain continuously activated, and the robot will wait for the next frame of instruction to maintain continuous motion (e.g., trajectory tracking requires high-frequency sending of multiple frames of instructions). | |
float32[] position: Supports two methods and must strictly match the motion_group configuration.
|
Simulation Environment
| Service | /control/set_property_sim |
|---|---|
| Effective Version | ≥V0.3 |
| Access Method | Service Call
|
| Interface Description | Dynamically configure robot operating parameters, supporting functions such as speed ratio, end-effector pose, error clearing, and zero-force drag enable |
| Interface Parameters | string property_type{ // Operation type, enumeration "SpeedRatio"; // Set the operating speed ratio of the robot "TcpPrimary"; // Set the position and orientation of the left arm end effector, represented by a quaternion "TcpSecondary"; // Set the position and orientation of the end effector of the right arm, represented by a quaternion "ClearError"; // Clear the robot's error status "SafeLevel"; // Sets the safety level, uniformly regulating a series of safety behaviors of the robot such as collision detection, motion limitation, force control threshold, etc. The larger the value, the stricter the safety restrictions "EnableDrag"; // Enable and disable the zero-force drag function "EnableSleep"; // Whether to enter sleep (standby) mode "SwitchRunMode"; // Switch operating mode "JointStiffness"; // Sets the joint stiffness in joint impedance mode. The larger the value, the stronger the joint rigidity. "JointDamping"; // Sets the joint damping in joint impedance mode. The larger the value, the greater the joint damping. "CartStiffness"; // Sets the stiffness coefficient of the robot in Cartesian space in Cartesian impedance mode. "CartDampingRatio"; // Sets the damping ratio of the robot in Cartesian space in Cartesian impedance mode. }; |
| string value{ // The value of value is associated with property_type } - If property_type is SpeedRatio, the value range is [0.01, 1.0], the data type is float64, example: "value": "0.5"; - If property_type is TcpPrimary, the format of value is "x, y, z, qw, qx, qy, qz", the data type is float64, the unit of position is meters, the unit of pose is radians, represented by quaternions, example: "value": "x, y, z, qw, qx, qy, qz"; - If property_type is TcpSecondary, the format of value is "x, y, z, qw, qx, qy, qz", the data type is float64, the unit of position is meters, the unit of attitude is radians, represented by quaternions, example: "value": "x, y, z, qw, qx, qy, qz"; - If property_type is ClearError, value is an empty string, example: "value": " "; - If property_type is SafeLevel, the value range is [0.1, 1.0], the data type is float64, example: "value": "0.3"; - If property_type is EnableDrag, the data type of value is bool, where "1" indicates enabling the zero-force drag function, "0" indicates disabling the zero-force drag function, example: "value": "1"; - If property_type is EnableSleep, the data type of the value range is bool, where "1" indicates enabling sleep, "0" indicates disabling sleep (wake-up), example: "value":"1"; - If property_type is SwitchRunMode, the data type of value is double, where "0" represents position mode, "1" represents joint impedance mode, "2" represents drag mode, and "3" represents Cartesian impedance mode; - If property_type is JointStiffness, the data type of value is float64, with the unit of Newton-meter per radian (Nm/rad), example: value: '50'; - If property_type is JointDamping, the data type of value is float64, with the unit of Newton meter second per radian (Nm·s/rad), example: value: '50', must be used in conjunction with JointStiffness to form a complete impedance control together; - If property_type is CartStiffness, the data type of value is float64, with the unit of Newton meters per radian (Nm/rad), example: value: '200'; - If property_type is CartDampingRatio, the data type of value is float64, example: value: '0.8'; } | |
| uint64 request_id: Returns the instruction number of this instruction, used to track the execution status of the instruction |
| Action | /control/move_robot_sim |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Action Call
|
| Interface Description | Controls multi-modal motion of the robot, covering joint motion, linear motion, real-time flow control (joint/end pose), and supports single-arm/double-arm/whole-body joint control |
| Interface Parameters | string type{ // Set motion control mode, enumeration "MoveJoint"; // Controls each joint of the robot to move to a specified angle, achieving joint space motion "MoveLine"; // Controls the end effector to move linearly to the target pose "StartJointStreaming"; // Continuously receive joint position commands and dynamically adjust joint states "StartEEPoseStreaming"; // Continuously receive end-effector pose commands and dynamically adjust the end-effector position "StopMove"; // Stop movement }; |
| string motion_group{ // Specifies the robot parts participating in motion control, enumeration "Primary"; // Left arm, with 7 joints, suitable for single-arm independent tasks "Secondary"; // Right arm, with 7 joints, suitable for single-arm independent tasks "BothArms"; // Both arms, with 14 joints, suitable for dual-arm collaborative tasks "Torso"; // Torso, number of joints is 3 "WholeBody"; // Whole body joints, with a joint count of 20, suitable for whole body coordinated movement }; | |
| float32[] target{ // The value of target is associated with type and motion_group - If type is MoveJoint, target is an array of joint angles, formatted as [joint 1 position, …, joint n position], where n is determined by motion_group. For example, when selecting Primary (left arm), n is 7, and when selecting BothArms (both arms), n is 14. The unit of the angles is radians. - If type is MoveLine, target is the end-effector target pose or torso pose, where the end-effector target pose is in the format [x, y, z, qw, qx, qy, qz], the torso pose is in the format [x, z, ry], the unit of position is meters, and the unit of orientation is radians. - If type is StartJointStreaming / StartEEPoseStreaming, dynamically target data is passed in real-time according to the corresponding control logic. }; | |
| bool success: Returns a boolean value, where "1" indicates successful execution of this instruction, and "0" indicates failed execution of this instruction | |
| uint64 request_id: Returns the instruction number of this command, used to track the instruction execution process, associate logs, or query status |
| Topic | /feedback/robot_server_state_sim |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Subscribe |
| Interface Description | Obtain the current state of the robot server, including operating mode, task queue, and poses of joints and end-effectors |
| Interface Parameters | uint64 timestamp: Timestamp |
| string status{ // Enum, current status of the robot server Running; // In progress, can be used in conjunction with latest_queued_id/latest_finished_id to track the task flow Init; // Initial state, will also switch to this state if OP is dropped Error; //Exception, need to combine with latest_errordrop_id to locate the error request Idle; // Idle, no task queue }; | |
| string run_mode{ // Enum, robot operating mode Position; // Position Mode Drag; // Drag Mode Impedance; // Impedance Mode Sleep; // Sleep mode (will disable) }; | |
| uint64 latest_queued_id: The ID of the latest queued request, representing the ID of the latest request that has entered the queue and is waiting to be executed. It reflects the priority of tasks to be executed and the length of the queue. If the queue continues to grow (latest_queued_id is frequently updated), the task execution efficiency needs to be investigated. | |
| uint64 latest_finished_id: The ID of the latest completed request, representing the ID of the latest request that has been executed, used to verify the task execution result | |
| uint64 latest_errordrop_id: The latest error reporting instruction number, which is a key clue for troubleshooting | |
| string[] motor_status: Operating status of 20 joint motors, "OP" indicates normal operation, formatted as ["OP", "OP",...] | |
| float64[] motor_temperature: Temperatures of 20 joint motors, formatted as [33, 33, 33,...], unit: °C | |
| uint8[] motor_error_code: Motor error code, formatted as [0, 0, 0,...], where 0: No error, 10: Speed error exceeds the limit value, 20: Position error exceeds the limit value, 30: Master station offline | |
| float64[] joint_position: The current position of each joint of the robot, formatted as [-0.0015, -0.0015, -0.0011,...], with the unit of radians (rad) | |
| float64[] joint_velocity: Joint velocities of the 20 joints of the robot, formatted as [0.0000, 0.0000, 0.0000,...], with the unit of radians per second | |
| float64[] joint_torque: The actual joint torques of the robot's 20 joints, formatted as [-2.0010, 1.3920, -2.6100,...], with the unit of Nm | |
| float64[] force_sensor: Six-dimensional force sensor data, formatted as [0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000], with the first six digits for the left hand and the last six digits for the right hand | |
| float64[] ee_pose: The pose of the end-effector, represented by quaternions, with the format [x, y, z, qw, qx, qy, qz, x, y, z, qw, qx, qy, qz]. The first 7 elements [x, y, z, qw, qx, qy, qz] represent the pose of the left arm, and the last 7 elements [x, y, z, qw, qx, qy, qz] represent the pose of the right arm. The unit of position is meters, and the unit of orientation is radians. | |
| float64[] torso_pose_X_Z_RY: Torso pose [X coordinate, Z coordinate, RY rotation], formatted as [-0.0022, 1.1298, -0.0041], with X/Z coordinates in meters and RY rotation in radians |
| Topic | /control/streaming_command_sim |
|---|---|
| Effective Version | ≥V0.2 |
| Access Method | Publish
|
| Interface Description | Send continuous control commands to drive the movement of the robot's left and right arms |
| Interface Parameters | uint64 request_id: A unique ID bound to the start streaming request, used for instruction identification. The robot server uses this ID to distinguish different flow control tasks and avoid confusion among multi-task instructions |
| bool streaming_finished: Marks whether the current instruction is the last frame of the flow control sequence. True indicates that the current flow control will be terminated immediately after sending, and the robot will stop receiving subsequent instructions, which can be used to end a trajectory or reset the arm; False indicates that the flow control mode will remain continuously activated, and the robot will wait for the next frame of instruction to maintain continuous motion (e.g., trajectory tracking requires high-frequency sending of multiple frames of instructions). | |
float32[] position: Supports two methods and must strictly match the motion_group configuration.
|