DexHand Interface

The DexHand interface module provides high-level control of dexterous robotic hands.

Base Interface

class pyzlg_dexhand.dexhand_interface.DexHandBase(config, base_id, zcan=None)[source]

Base class for dexterous hand control

NUM_MOTORS

Total number of motors in the hand (12)

NUM_BOARDS

Number of control boards (6)

joint_names

List of joint names in order:

  • th_dip: Thumb distal joint

  • th_mcp: Thumb metacarpophalangeal joint

  • th_rot: Thumb rotation

  • ff_spr: Four-finger spread

  • ff_dip: Index finger distal joint

  • ff_mcp: Index finger metacarpophalangeal

  • mf_dip: Middle finger distal joint

  • mf_mcp: Middle finger metacarpophalangeal

  • rf_dip: Ring finger distal joint

  • rf_mcp: Ring finger metacarpophalangeal

  • lf_dip: Little finger distal joint

  • lf_mcp: Little finger metacarpophalangeal

__init__(config, base_id, zcan=None)[source]

Initialize dexterous hand interface

Parameters:

  • config_path – Path to hand’s YAML config file

  • base_id (int) – Base board ID (0x01 for left, 0x07 for right)

  • zcan (Optional[ZCANWrapper]) – Optional existing ZCANWrapper instance to share between hands

clear_errors(clear_all=True)[source]

Clear all errors for the hand

Parameters:

clear_all – If True, attempt to clear errors for all boards even if not in error state

close()[source]

Close CAN communication

get_errors()[source]

Get error information for whole hand

Return type:

Dict[int, Optional[ErrorInfo]]

Returns:

Dict mapping board index to ErrorInfo if an error is present

get_feedback()[source]

Get feedback from all joints and tactile sensors

Return type:

HandFeedback

Returns:

HandFeedback object.

init(device_index=0)[source]

Initialize CAN communication

Parameters:

device_index (int) – Device index for ZCAN device

Returns:

True if initialization successful

Return type:

bool

move_joints(th_rot=None, th_mcp=None, th_dip=None, ff_spr=None, ff_mcp=None, ff_dip=None, mf_mcp=None, mf_dip=None, rf_mcp=None, rf_dip=None, lf_mcp=None, lf_dip=None, control_mode=ControlMode.CASCADED_PID)[source]

Move hand joints to specified angles.

For each finger, there are two independent DOFs: - MCP (metacarpophalangeal) joint: Controls base joint flexion - DIP (coupled): Controls coupled motion of PIP and DIP joints

Additional DOFs: - th_rot: Thumb rotation/opposition - ff_spr: Four-finger spread (abduction between fingers)

Parameters:

  • th_rot (Optional[float]) – Thumb rotation angle in degrees

  • th_mcp (Optional[float]) – Thumb MCP flexion angle

  • th_dip (Optional[float]) – Thumb coupled PIP-DIP flexion

  • ff_spr (Optional[float]) – Four-finger spread angle

  • ff_mcp (Optional[float]) – Index MCP flexion

  • ff_dip (Optional[float]) – Index coupled PIP-DIP flexion

  • mf_mcp (Optional[float]) – Middle MCP flexion

  • mf_dip (Optional[float]) – Middle coupled PIP-DIP flexion

  • rf_mcp (Optional[float]) – Ring MCP flexion

  • rf_dip (Optional[float]) – Ring coupled PIP-DIP flexion

  • lf_mcp (Optional[float]) – Little MCP flexion

  • lf_dip (Optional[float]) – Little coupled PIP-DIP flexion

  • control_mode (ControlMode) – Motor control mode

reset_joints()[source]

Reset all joints to their zero positions.

This is equivalent to setting all joint angles to 0 degrees. Uses CASCADED_PID control mode.

set_feedback_mode(mode, period_ms, enable)[source]

Configure feedback mode for all boards

Parameters:

  • mode (FeedbackMode) – Feedback mode

  • period_ms (int) – Period in milliseconds (if periodic)

  • enable (bool) – Enable flag

Returns:

True if command sent successfully

Return type:

bool

Hand Implementations

class pyzlg_dexhand.dexhand_interface.LeftDexHand(zcan=None)[source]

Bases: DexHandBase

Control interface for left dexterous hand

__init__(zcan=None)[source]

Initialize dexterous hand interface

Parameters:

  • config_path – Path to hand’s YAML config file

  • base_id – Base board ID (0x01 for left, 0x07 for right)

  • zcan (Optional[ZCANWrapper]) – Optional existing ZCANWrapper instance to share between hands

class pyzlg_dexhand.dexhand_interface.RightDexHand(zcan=None)[source]

Bases: DexHandBase

Control interface for right dexterous hand

__init__(zcan=None)[source]

Initialize dexterous hand interface

Parameters:

  • config_path – Path to hand’s YAML config file

  • base_id – Base board ID (0x01 for left, 0x07 for right)

  • zcan (Optional[ZCANWrapper]) – Optional existing ZCANWrapper instance to share between hands

Data Classes

class pyzlg_dexhand.dexhand_interface.HandConfig(channel, hall_scale)[source]

Configuration for hand hardware

channel: int
hall_scale: List[float]
class pyzlg_dexhand.dexhand_interface.JointFeedback(timestamp, angle, encoder_position=None)[source]

Feedback for a specific joint command

angle: float
encoder_position: Optional[int] = None
timestamp: float
class pyzlg_dexhand.dexhand_interface.StampedTactileFeedback(timestamp, normal_force, normal_force_delta, tangential_force, tangential_force_delta, direction, proximity, temperature)[source]

Timestamped tactile feedback for a fingertip

direction: int
normal_force: float
normal_force_delta: int
proximity: int
tangential_force: float
tangential_force_delta: int
temperature: int
timestamp: float
class pyzlg_dexhand.dexhand_interface.HandFeedback(query_timestamp, joints, tactile)[source]

Feedback data for whole hand

joints: Dict[str, JointFeedback]
query_timestamp: float
tactile: Dict[str, StampedTactileFeedback]

Enumerations

class pyzlg_dexhand.dexhand_interface.ControlMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Motor control modes

CASCADED_PID = 68
CURRENT = 17
HALL_POSITION = 51
PROTECT_HALL_POSITION = 85
SPEED = 34
ZERO_TORQUE = 0

Example Usage

Basic Joint Control

from pyzlg_dexhand import RightDexHand, ControlMode

# Initialize hand
hand = RightDexHand()
hand.init()

# Move thumb
hand.move_joints(
    th_rot=30,     # Thumb rotation
    th_mcp=45,     # Thumb MCP flexion
    th_dip=45,     # Thumb coupled distal flexion
    control_mode=ControlMode.CASCADED_PID
)

Feedback Handling

# Get feedback
feedback = hand.get_feedback()

# Access joint feedback
thumb_angle = feedback.joints['th_rot'].angle
thumb_encoder = feedback.joints['th_rot'].encoder_position

# Access tactile feedback
thumb_force = feedback.tactile['th'].normal_force
thumb_dir = feedback.tactile['th'].direction

Error Handling

# Clear any error states
hand.clear_errors(clear_all=True)

# Check for specific errors
errors = hand.get_errors()
for board_idx, error in errors.items():
    if error:
        print(f"Board {board_idx} error: {error.description}")

Notes

Control Modes

  • CASCADED_PID: Default mode for precise position control. Provides highest stiffness and position accuracy.

  • HALL_POSITION: Direct hall sensor position control. Less precise but faster response.

  • PROTECT_HALL_POSITION: Safe hall position control requiring zero position at startup.

  • CURRENT: Direct current control for force-based applications.

  • SPEED: Velocity control mode.

  • ZERO_TORQUE: Disables motor torque, allowing free movement.

Joint Limits

Default joint angle limits (in degrees):

  • Thumb rotation (th_rot): 0-150

  • Metacarpophalangeal joints (mcp): 0-90

  • Distal joints (dip): 0-90

  • Four-finger spread (ff_spr): 0-30

Error Handling

When a finger encounters an obstacle or abnormal condition:

  1. The board may enter an error state

  2. Motors on that board become unresponsive

  3. clear_errors() must be called to restore operation

  4. Consider clearing errors after each command for robust operation