Hand and End-Effector Interface

About 4100 wordsAbout 14 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 hand and end-effector interface are used to operate end-effectors (finger joint control/ two-finger gripper opening and closing force control).

(1) Hand

Real Device

Topic	/feedback/hand/left
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Real-time acquisition of the state of the left hand, including information such as position, velocity, current, and force
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, default ["THUMBMCP", "THUMBCMC", "INDEXMCP", "MIDDLEMCP", "RINGMCP", "LITTLEMCP"], corresponding to [Thumb Bend, Thumb Swing, Index Bend, Middle Bend, Ring Bend, Little Bend]
	float64[] position: Finger position status, formatted as [thumb swing degree, thumb bend degree, index finger bend degree, middle finger bend degree, ring finger bend degree, little finger bend degree], with the unit being percentage (%), and the value range being [0.0, 100.0]
	float64[] velocity: Finger joint movement speed, formatted as [thumb movement speed, thumb swing movement speed, index finger movement speed, middle finger movement speed, ring finger movement speed, little finger movement speed], with the unit of %/s and a value range of [0.0, 100.0]
	float64[] current: Finger joint motor current, formatted as [thumb flexion current, thumb swing current, index finger flexion current, middle finger flexion current, ring finger flexion current, little finger flexion current], with the unit of percentage (%), and the value range is [0.0, 100.0]
	uint8[] state: Finger joint motor state, formatted as [Thumb bending motor state, Thumb swinging motor state, Index finger bending motor state, Middle finger bending motor state, Ring finger bending motor state, Little finger bending motor state], with a value range of [0, 1, 2, 3], where 0: IDLE (Idle / Stopped at position), 1: RUNNING (In motion), 2: STALL (Stalled / Protected stop), 3: UNKNOWN (Not connected)

Topic	/feedback/hand/right
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Real-time acquisition of the state of the right hand, including information such as position, velocity, current, force, etc.
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, default ["THUMBMCP", "THUMBCMC", "INDEXMCP", "MIDDLEMCP", "RINGMCP", "LITTLEMCP"], corresponding to [Thumb Bend, Thumb Swing, Index Bend, Middle Bend, Ring Bend, Little Bend]
	float64[] position: Finger position status, formatted as [thumb swing degree, thumb bend degree, index finger bend degree, middle finger bend degree, ring finger bend degree, little finger bend degree], with the unit being percentage (%), and the value range being [0.0, 100.0]
	float64[] velocity: Finger joint movement speed, formatted as [thumb movement speed, thumb swing movement speed, index finger movement speed, middle finger movement speed, ring finger movement speed, little finger movement speed], with the unit of %/s and a value range of [0.0, 100.0]
	float64[] current: Finger joint motor current, formatted as [thumb flexion current, thumb swing current, index finger flexion current, middle finger flexion current, ring finger flexion current, little finger flexion current], with the unit of percentage (%), and the value range is [0.0, 100.0]
	uint8[] state: Finger joint motor state, formatted as [Thumb bending motor state, Thumb swinging motor state, Index finger bending motor state, Middle finger bending motor state, Ring finger bending motor state, Little finger bending motor state], with a value range of [0, 1, 2, 3], where 0: IDLE (Idle / Stopped at position), 1: RUNNING (In motion), 2: STALL (Stalled / Protected stop), 3: UNKNOWN (Not connected)

Topic	/control/hand/left
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to control the state of the left hand
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name{ // List of joint names (order can be customized during control), default corresponding to 6 finger joints: "THUMBMCP"; // Thumb flexion "THUMBCMC"; // Thumb Swing "INDEXMCP"; // Index finger flexion "MIDDLEMCP"; // Middle finger flexion "RINGMCP"; // Ring finger flexion "LITTLEMCP"; // Little finger flexion };
	uint8 mode{ // Control mode, enumeration 0: POSITION; // Position control 1: VELOCITY; // Speed control 2: CURRENT; // Current control };
	float64[] value: The format is an array [q1,q2,q3,q4,q5,q6], where the number of joints is determined by `name`, corresponding one-to-one with `name`, defaulting to 6, and the meaning is determined by `mode`, with the unit being percentage (%) When`mode`=0`value`represents the "bending degree ratio" of each joint, with a value range of [0.0, 100.0]; When`mode`=1`value`is the "motion speed ratio" of each joint, with a value range of [-100, 100]; When`mode`=2`value`is the "current output ratio" of each joint, with a value range of [-100, 100]

Topic	/control/hand/right
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to control the state of the right hand
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
Interface Parameters	string[] name{ // List of joint names (order can be customized during control), default corresponding to 6 finger joints: "THUMBMCP"; // Thumb flexion "THUMBCMC"; // Thumb Swing "INDEXMCP"; // Index finger flexion "MIDDLEMCP"; // Middle finger flexion "RINGMCP"; // Ring finger flexion "LITTLEMCP"; // Little finger flexion };
	uint8 mode{ // Control mode, enumeration 0: POSITION; // Position control 1: VELOCITY; // Speed control 2: CURRENT; // Current control };
	float64[] value: The format is an array [q1,q2,q3,q4,q5,q6], where the number of joints is determined by `name`, corresponding one-to-one with `name`, defaulting to 6, and the meaning is determined by `mode`, with the unit being percentage (%) When`mode`=0`value`represents the "bending degree ratio" of each joint, with a value range of [0.0, 100.0]; When`mode`=1`value`is the "motion speed ratio" of each joint, with a value range of [-100, 100]; When`mode`=2`value`is the "current output ratio" of each joint, with a value range of [-100, 100]

Simulation Environment

Topic	/feedback_sim/hand/left
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Real-time acquisition of the state of the left hand, including information such as position, velocity, current, and force
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, default ["THUMBMCP", "THUMBCMC", "INDEXMCP", "MIDDLEMCP", "RINGMCP", "LITTLEMCP"], corresponding to [Thumb Bend, Thumb Swing, Index Bend, Middle Bend, Ring Bend, Little Bend]
	float64[] position: Finger position status, formatted as [thumb swing degree, thumb bend degree, index finger bend degree, middle finger bend degree, ring finger bend degree, little finger bend degree], with the unit being percentage (%), and the value range being [0.0, 100.0]
	float64[] velocity: Finger joint movement speed, formatted as [thumb movement speed, thumb swing movement speed, index finger movement speed, middle finger movement speed, ring finger movement speed, little finger movement speed], with the unit of %/s and a value range of [0.0, 100.0]
	float64[] current: Finger joint motor current, formatted as [thumb flexion current, thumb swing current, index finger flexion current, middle finger flexion current, ring finger flexion current, little finger flexion current], with the unit of percentage (%), and the value range is [0.0, 100.0]
	uint8[] state: Finger joint motor state, formatted as [Thumb bending motor state, Thumb swinging motor state, Index finger bending motor state, Middle finger bending motor state, Ring finger bending motor state, Little finger bending motor state], with a value range of [0, 1, 2, 3], where 0: IDLE (Idle / Stopped at position), 1: RUNNING (In motion), 2: STALL (Stalled / Protected stop), 3: UNKNOWN (Not connected)

Topic	/feedback_sim/hand/right
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Real-time acquisition of the state of the right hand, including information such as position, velocity, current, force, etc.
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, default ["THUMBMCP", "THUMBCMC", "INDEXMCP", "MIDDLEMCP", "RINGMCP", "LITTLEMCP"], corresponding to [Thumb Bend, Thumb Swing, Index Bend, Middle Bend, Ring Bend, Little Bend]
	float64[] position: Finger position status, formatted as [thumb swing degree, thumb bend degree, index finger bend degree, middle finger bend degree, ring finger bend degree, little finger bend degree], with the unit being percentage (%), and the value range being [0.0, 100.0]
	float64[] velocity: Finger joint movement speed, formatted as [thumb movement speed, thumb swing movement speed, index finger movement speed, middle finger movement speed, ring finger movement speed, little finger movement speed], with the unit of %/s and a value range of [0.0, 100.0]
	float64[] current: Finger joint motor current, formatted as [thumb flexion current, thumb swing current, index finger flexion current, middle finger flexion current, ring finger flexion current, little finger flexion current], with the unit of percentage (%), and the value range is [0.0, 100.0]
	uint8[] state: Finger joint motor state, formatted as [Thumb bending motor state, Thumb swinging motor state, Index finger bending motor state, Middle finger bending motor state, Ring finger bending motor state, Little finger bending motor state], with a value range of [0, 1, 2, 3], where 0: IDLE (Idle / Stopped at position), 1: RUNNING (In motion), 2: STALL (Stalled / Protected stop), 3: UNKNOWN (Not connected)

Topic	/control_sim/hand/left
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to control the state of the left hand
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
Interface Parameters	string[] name{ // List of joint names (order can be customized during control), default corresponding to 6 finger joints: "THUMBMCP"; // Thumb flexion "THUMBCMC"; // Thumb Swing "INDEXMCP"; // Index finger flexion "MIDDLEMCP"; // Middle finger flexion "RINGMCP"; // Ring finger flexion "LITTLEMCP"; // Little finger flexion };
	uint8 mode{ // Control mode, enumeration 0: POSITION; // Position control 1: VELOCITY; // Speed control 2: CURRENT; // Current control };
	float64[] value: The format is an array [q1,q2,q3,q4,q5,q6], where the number of joints is determined by `name`, corresponding one-to-one with `name`, defaulting to 6, and the meaning is determined by `mode`, with the unit being percentage (%) When`mode`=0`value`represents the "bending degree ratio" of each joint, with a value range of [0.0, 100.0]; When`mode`=1`value`is the "motion speed ratio" of each joint, with a value range of [-100, 100]; When`mode`=2`value`is the "current output ratio" of each joint, with a value range of [-100, 100]

Topic	/control_sim/hand/right
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to control the state of the right hand
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
Interface Parameters	string[] name{ // List of joint names (order can be customized during control), default corresponding to 6 finger joints: "THUMBMCP"; // Thumb flexion "THUMBCMC"; // Thumb Swing "INDEXMCP"; // Index finger flexion "MIDDLEMCP"; // Middle finger flexion "RINGMCP"; // Ring finger flexion "LITTLEMCP"; // Little finger flexion };
	uint8 mode{ // Control mode, enumeration 0: POSITION; // Position control 1: VELOCITY; // Speed control 2: CURRENT; // Current control };
	float64[] value: The format is an array [q1,q2,q3,q4,q5,q6], where the number of joints is determined by `name`, corresponding one-to-one with `name`, defaulting to 6, and the meaning is determined by `mode`, with the unit being percentage (%) When`mode`=0`value`represents the "bending degree ratio" of each joint, with a value range of [0.0, 100.0]; When`mode`=1`value`is the "motion speed ratio" of each joint, with a value range of [-100, 100]; When`mode`=2`value`is the "current output ratio" of each joint, with a value range of [-100, 100]

(2) Gripper

Real Device

Topic	/feedback/gripper/left
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Obtain the status of the left gripper in real time
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/feedback/gripper/right
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Get the status of the right gripper in real time
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/control/gripper/left
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue a command to switch the state of the left gripper
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/control/gripper/right
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue a command to switch the state of the right gripper
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Simulation Environment

Topic	/feedback_sim/gripper/left
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Obtain the status of the left gripper in real time
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/feedback_sim/gripper/right
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Get the status of the right gripper in real time
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/control_sim/gripper/left
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue a command to switch the state of the left gripper
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }

Topic	/control_sim/gripper/right
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue a command to switch the state of the right gripper
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	string[] name: List of joint names, by default only contains ["FINGER"]
	float64[] position: The closing degree of the gripper, with the unit being percentage (%), and the value range is [0.0, 100.0] (0% = fully open, 100% = fully closed)
	uint8[] state{ // Operating state of the gripper motor, enumeration 0: IDLE; //Idle, position in place and stopped 1: RUNNING; // In motion (unfolding / grasping) 2: STALL; // Stalled / Protection Stop 3: UNKNOWN; // Not connected }