feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand Module

RH56F1 EtherCAT Hand Controller - Python API Real-time per-finger control via C++ wrapper using ctypes

class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.FingerData(finger_id, position, angle, force, current, temperature, error, status)

Bases: object

Complete data for a single finger

Parameters:
finger_id: int
position: int
angle: int
force: int
current: int
temperature: int
error: int
status: int
class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.TactileSensor(normal_force, tangential_force, direction, proximity_low, proximity_high)

Bases: object

Tactile sensor data for one sensor

Parameters:

  • normal_force (int)

  • tangential_force (int)

  • direction (int)

  • proximity_low (int)

  • proximity_high (int)

normal_force: int
tangential_force: int
direction: int
proximity_low: int
proximity_high: int
class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.HandState(fingers, tactile_sensors, timestamp)

Bases: object

Complete hand state

Parameters:
fingers: List[FingerData]
tactile_sensors: List[TactileSensor]
timestamp: float
class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.FingerID(value)

Bases: IntEnum

Finger ID enumeration for RH56F1 hand

LITTLE = 1
RING = 2
MIDDLE = 3
INDEX = 4
THUMB_BEND = 5
THUMB_SIDESWAY = 6
class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.TactileSensorID(value)

Bases: IntEnum

Sensor ID enumeration for RH56F1 hand

LITTLE = 1
RING = 2
MIDDLE = 3
INDEX = 4
THUMB = 5
PALM_LEFT = 6
PALM_MIDDLE = 7
PALM_RIGHT = 8
class feathersdk.robot.actuators.rh56f1_hand.rh56f1_hand.RH56F1Hand(lib_path=None, master_index=0, slave_position=0)

Bases: object

Python wrapper for RH56F1 EtherCAT hand controller with per-finger data access

This class provides a Pythonic interface to the C++ EtherCAT library, giving you C++ real-time performance with Python convenience.

Finger Numbering (from user manual):

1: Little finger 2: Ring finger 3: Middle finger 4: Index finger 5: Thumb (bend) 6: Thumb (sidesway)

Parameter Ranges:

  • Angle: 0-3600 (0.1 degree units, e.g., 1700 = 170.0°)

  • Force: 0-1000 (device-specific units)

  • Speed: 0-5000 (device-specific units)

Parameters:

  • lib_path (str | None)

  • master_index (int)

  • slave_position (int)

ANGLE_MIN = 600
ANGLE_MAX = 1800
FORCE_MIN = 0
FORCE_MAX = 1000
SPEED_MIN = 0
SPEED_MAX = 5000
FINGER_ANGLE_LIMITS = {FingerID.LITTLE: (900, 1740), FingerID.RING: (900, 1740), FingerID.MIDDLE: (900, 1740), FingerID.INDEX: (900, 1740), FingerID.THUMB_BEND: (1100, 1450), FingerID.THUMB_SIDESWAY: (600, 1800)}
PDO_MAP = {'angle': (6, 6), 'current': (18, 6), 'error': (24, 6), 'force': (12, 6), 'position': (0, 6), 'status': (30, 6), 'tactile': 42, 'temperature': (36, 6)}
PDO_OUTPUT_MAP = {'angle_cmd': (1, 6), 'enable_set': 0, 'force_cmd': (7, 6), 'speed_cmd': (13, 6)}
__init__(lib_path=None, master_index=0, slave_position=0)

Initialize the hand controller

Parameters:

  • lib_path (str | None) – Path to librh56f1.so (auto-detected if None)

  • master_index (int) – EtherCAT master index (default: 0)

  • slave_position (int) – EtherCAT slave position (default: 0)

initialize()

Initialize the EtherCAT controller. Retries once after 2.5s if master is busy (e.g. after previous Robot aborted).

Return type:

bool

start()

Start the real-time control loop

Return type:

bool

stop()

Stop the real-time control loop and clear all outputs

Return type:

bool

property is_initialized: bool

True if the controller has been initialized and not yet cleaned up.

cleanup()

Stop the control loop and deactivate the master, but keep the reservation so start() can be called again without re-requesting the master (avoids ‘Device or resource busy’ on abort/restart).

destroy()

Release the EtherCAT master and free resources. Call when the hand will not be used again (e.g. process exit).

calculate_array_index(finger_id, pdo_name)
Parameters:
Return type:

int

get_finger_position(finger_id)

Returns the actuator position for a specific finger (0x6000:01-06 POSACT)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_angle(finger_id)

Returns the angle of actuator for a specific finger (0x6000:07-0C ANGLEACT) in 0.1 degree units (e.g., 1700 = 170.0 degrees)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_force(finger_id)

Returns the force value for a specific finger (0x6000:0D-12 FORCEACT)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_current(finger_id)

Returns the current for a specific finger (0x6000:13-18 CURACT)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_temperature(finger_id)

Returns the temperature in °C for a specific finger (0x6000:25-2A TEMP)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_error(finger_id)

Returns the error code for a specific finger (0x6000:19-1E ERROR), 0 = no error

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_status(finger_id)

Returns the status for a specific finger (0x6000:1F-24 STATUS)

Parameters:

finger_id (FingerID)

Return type:

int | None

get_finger_data(finger_id)

Returns FingerData object for a specific finger

Parameters:

finger_id (FingerID)

Return type:

FingerData | None

get_all_fingers_data()

Returns a list of FingerData objects for all fingers

Return type:

List[FingerData]

set_finger_control(finger_id, angle, force, speed, enable=True)

Control a specific finger

Parameters:

  • finger_id (FingerID) – FingerID (1-6)

  • angle (int) – Target angle (0-3600 = 0-360 degrees in 0.1 degree units)

  • force (int) – Force/torque limit (0-1000)

  • speed (int) – Speed limit (0-5000)

  • enable (bool) – Enable motor (default: True)

Returns:

True if successful, False otherwise

Return type:

bool

set_all_fingers_control(angles, forces, speeds, enable=True)

Control all 6 fingers at once

Parameters:

  • angles (List[int]) – List of 6 target angles [little, ring, middle, index, thumb_bend, thumb_sidesway]

  • forces (List[int]) – List of 6 force limits (one per finger)

  • speeds (List[int]) – List of 6 speed limits (one per finger)

  • enable (bool) – Enable all motors (default: True)

Returns:

True if all successful, False otherwise

Return type:

bool

move(open_percent, force=None, speed=None, enable=True)

Control all 6 fingers by open percentage (0 = fully closed, 1 = fully open).

Parameters:

  • open_percent (List[float]) – List of 6 values in [0, 1] for [little, ring, middle, index, thumb_bend, thumb_sidesway].

  • force (int | List[int] | None) – Force limit(s). Single int (0-1000) for all fingers, or list of 6 ints. Default: FORCE_MAX.

  • speed (int | List[int] | None) – Speed limit(s). Single int (0-5000) for all fingers, or list of 6 ints. Default: SPEED_MAX.

  • enable (bool) – Enable all motors (default: True).

Returns:

True if all successful, False otherwise.

Return type:

bool

enable_hand()

Enable motion control for all fingers. Returns True if successful, False otherwise.

Return type:

bool

disable_hand()

Disable hand motion control. Returns True if successful, False otherwise.

Return type:

bool

clear_all_outputs()

Clear all output values and disable motion

This stops all movement by: 1. Setting ENABLE_SET to 0 (disable) 2. Zeroing all angle, force, and speed commands

Use this when you want to stop the hand from moving.

Returns:

True if successful

Return type:

bool

get_tactile_sensor(sensor_id)

Get tactile sensor data (0x6000:2B-4C)

Based on PDO table: - Finger sensors (1-5): 5 values each (Normal, Tangential, Direction, ProximityL, ProximityH) - Palm sensors (6-8): 3 values each (Normal, Tangential, Direction) - NO proximity values

Parameters:

sensor_id (TactileSensorID) – Sensor ID (1-5 for finger sensors, 6-8 for palm sensors)

Returns:

TactileSensor object with NormalForce, TangentialForce, Direction, ProximityValue or None

Return type:

TactileSensor | None

get_all_tactile_sensors()

Returns a list of TactileSensor objects for all tactile sensors (5 finger sensors + 3 palm sensors)

Return type:

List[TactileSensor]

get_hand_state()

Returns a HandState object with all finger and sensor data

Return type:

HandState

get_all_angles()

Get angles for all fingers

Return type:

List[int]

get_finger_open_percent(finger_id)

Get the actual open percentage (0 = fully closed, 1 = fully open) for a specific finger.

Inverse of the percent->angle mapping used by move(), based on the measured angle (ANGLEACT). Returns None if the angle could not be read.

Parameters:

finger_id (FingerID)

Return type:

float | None

get_all_open_percents()

Get the actual open percentage (0-1) for all fingers.

Returns a list of 6 values in the same order as move(): [little, ring, middle, index, thumb_bend, thumb_sidesway].

Return type:

List[float]

get_all_forces()

Get forces for all fingers

Return type:

List[int]

get_all_temperatures()

Get temperatures for all fingers

Return type:

List[int]

get_all_currents()

Get currents for all fingers

Return type:

List[int]

get_errors()

Get error codes for all fingers (only non-zero errors)

Return type:

Dict[int, int]

print_hand_state()

Print a formatted view of the complete hand state

get_all_inputs()

Get all 76 input values (raw)

Return type:

List[int] | None

get_input(index)

Get specific input value by index (0-75)

Parameters:

index (int)

Return type:

int | None

set_output(index, value)

Set specific output value by index (0-18)

Parameters:
Return type:

bool

get_output(index)

Get cached output value by index (0-18)

Parameters:

index (int)

Return type:

int

print_output_state()

Print current output values being sent to the device

is_running()

Check if controller is running

Return type:

bool

get_error()

Get last error message

Return type:

str | None

read_sdo(index, subindex)

Read an SDO (Service Data Object) from the device

Parameters:
Return type:

int | None

write_sdo(index, subindex, value)

Write an SDO (Service Data Object) to the device

Parameters:
Return type:

bool

clear_errors()

Clear all device errors (SDO 0x2000:03), returns True if successful, False otherwise.

Return type:

bool

wait_for_operational(timeout=5.0, check_interval=0.1)

Wait for the device to enter operational state and start providing data

Parameters:

  • timeout (float) – Maximum time to wait in seconds (default: 5.0)

  • check_interval (float) – How often to check for data in seconds (default: 0.1)

Returns:

True if device is operational (providing non-zero data), False if timeout

Return type:

bool

Note

The EtherCAT device typically takes 2-3 seconds to transition through INIT → PREOP → SAFEOP → OPERATIONAL states after starting.