feathersdk.robot.actuators.rh56f1_hand Package

RH56F1 Hand Controller Package

class feathersdk.robot.actuators.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_MAX = 1800
ANGLE_MIN = 600
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)}
FORCE_MAX = 1000
FORCE_MIN = 0
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)}
SPEED_MAX = 5000
SPEED_MIN = 0
__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)

calculate_array_index(finger_id, pdo_name)
Parameters:
Return type:

int

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).

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

clear_errors()

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

Return type:

bool

destroy()

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

disable_hand()

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

Return type:

bool

enable_hand()

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

Return type:

bool

get_all_angles()

Get angles for all fingers

Return type:

List[int]

get_all_currents()

Get currents for all fingers

Return type:

List[int]

get_all_fingers_data()

Returns a list of FingerData objects for all fingers

Return type:

List[FingerData]

get_all_forces()

Get forces for all fingers

Return type:

List[int]

get_all_inputs()

Get all 76 input values (raw)

Return type:

List[int] | 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_tactile_sensors()

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

Return type:

List[TactileSensor]

get_all_temperatures()

Get temperatures for all fingers

Return type:

List[int]

get_error()

Get last error message

Return type:

str | None

get_errors()

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

Return type:

Dict[int, int]

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_current(finger_id)

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

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_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_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_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_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_status(finger_id)

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

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_hand_state()

Returns a HandState object with all finger and sensor data

Return type:

HandState

get_input(index)

Get specific input value by index (0-75)

Parameters:

index (int)

Return type:

int | None

get_output(index)

Get cached output value by index (0-18)

Parameters:

index (int)

Return type:

int

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

initialize()

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

Return type:

bool

property is_initialized: bool

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

is_running()

Check if controller is running

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

print_hand_state()

Print a formatted view of the complete hand state

print_output_state()

Print current output values being sent to the device

read_sdo(index, subindex)

Read an SDO (Service Data Object) from the device

Parameters:
Return type:

int | None

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

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_output(index, value)

Set specific output value by index (0-18)

Parameters:
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

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.

write_sdo(index, subindex, value)

Write an SDO (Service Data Object) to the device

Parameters:
Return type:

bool

class feathersdk.robot.actuators.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.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.HandState(fingers, tactile_sensors, timestamp)

Bases: object

Complete hand state

Parameters:
fingers: List[FingerData]
tactile_sensors: List[TactileSensor]
timestamp: float

Modules