Replaying a Thumb Opposition

SDK Practice

Overview

Read the recording shipped with the example, pick the left- or right-hand file by device handedness, and replay 30000 joint-angle frames straight through at 1 kHz.

This is the larger of the two motion examples, meant for observing the hand’s full range. The example does no interpolation, no resampling, no smoothing, and adds no recovery motion. What the recording holds is what goes out.

Matching examples: examples/python/wuji_hand_2/6_opposition/opposition.py and examples/c/wuji_hand_2/6_opposition/opposition.c.

For API and field definitions, see JointCommand.

Prerequisites

Hardware

Software

Replay Files

The example directory ships data/right.replay and data/left.replay. Copy the entire 6_opposition/ directory, since taking only the source file fails when it can’t find the data.

Data Flow

File Format

A fixed-length container with a 16-byte header followed by 84 bytes per frame.

Handedness ID is 1 for right and 2 for left. The shipped files measure 30000 frames and 2520016 bytes, matching 16 + 30000 x 84 exactly.

Validation completes before enabling. If any of magic, version, handedness, joint count, or file length fails, the example reports an error and exits without enabling the motors.

Integration Steps

1. Connect and Validate the Replay File

Read handedness after connecting, and select left.replay or right.replay. After opening the file, validate the magic, version, handedness marker, joint count, and file length. Don’t enable the device if validation fails.

hand = manager.auto_connect("hand_2_opposition")
if hand.online_joints_count().get() != 20:
    raise RuntimeError("expected 20 online joints")
stream, frame_count = _open_replay(_side_for_hand(hand), data_dir=data_dir)

2. Check Online Joints and Prepare the Publisher

Confirm all 20 joints are online, then call enable() and create a joint_command publisher. Read one current joint_states frame and use a cosine transition to reach the first replay frame smoothly.

hand.enable()
publisher = hand.joint_command().publish()
start = _capture_start_positions(hand)

C uses wuji_hand_2_online_joints_count(), wuji_hand_2_enable(), and wuji_hand_2_joint_command_publish(). It selects the replay file with wuji_hand_2_get_handedness().

3. Publish Replay Frames at 1 kHz

Read 20 position values per frame, create JointCommand(position, 0, 0) entries, and send them at 1 ms intervals. The replay loop must handle stop requests and file-read errors.

def send(qpos):
    publisher.send([wuji_sdk.JointCommand(float(v), 0.0, 0.0) for v in qpos])
_play_replay(stream, frame_count, send, ramp_start=start,
             stop_requested=lambda: _STOP_REQUESTED)

The functions with leading underscores are helpers in Python example. _open_replay() validates the complete container, _capture_start_positions() orders joints by nid, and _play_replay() handles the starting transition and frame-by-frame playback.

C uses open_replay_path(), capture_start_positions(), send_ramp(), and play_replay(). They send a fixed 20-joint array through wuji_joint_command_publisher_send().

4. Disable and Release Resources

On normal completion or an error, disable first, close the publisher and replay file, then disconnect. C uses wuji_hand_2_disable(device, NULL) and wuji_joint_command_publisher_close(publisher), closes the replay file, disconnects and releases the device, and calls wuji_shutdown().

hand.disable()
publisher.close()
stream.close()
manager.disconnect_all()

Place cleanup in finally. Collect errors individually, as shown in Python example and C example, so a failure in one cleanup operation doesn’t prevent releasing the remaining resources.

Running It

• Python

• C

python examples/python/wuji_hand_2/6_opposition/opposition.py

./build/hand2-opposition/6_opposition

Measurements

A complete run on a right-hand Wuji Hand 2 with all 20 joints online:

Python held the 1 ms target interval reliably, and accumulated error across 30000 frames is negligible.

The hand settles on its own at the end. The recording’s last frame already returns to an open position, so a normal run needs no extra homing. That comes from the recording’s content rather than anything the example does, and an interrupted run gets no such guarantee.

Range of Motion per Finger

Per-joint travel computed offline from the right-hand replay file:

The index finger’s third joint travels furthest at 1.428 rad, about 81.8 degrees.

Notes

On interrupt the hand holds its current posture rather than opening automatically. Stopping mid-motion can leave it clenched, which needs handling by hand.

Adapting It

Name an SN on a Shared Network

As with the MIT joint sweep, auto_connect() refuses to connect when it finds several devices and lists every serial number rather than guessing. Change it to manager.connect(sn="WH2KA00XXXXXXXXX", device_name="hand_2_opposition").

Replay Your Own Recording

Generate a file in the same container format and the whole replay path works unchanged: a 16-byte header plus 84 bytes per frame. The frame index is skipped during replay, and only the 20 joint angles drive control. Make sure side_id matches the target device’s handedness, or container validation fails.

Changing Playback Speed

The interval is hard-coded at 1 ms. Increasing it slows the whole motion, but since nothing is resampled the joint-angle sequence stays the same and each posture simply holds longer. Real speed changes need you to resample the trajectory yourself.

Recovering After an Interrupt

Ctrl+C triggers no return motion. After stopping mid-run, the hand holds its posture, and the smooth homing routine in Publishing Control Commands brings it gently back to zero. Don’t send pos=0 directly, since a large error under MIT impedance snaps the hand back hard.

Related

• Publishing Control Commands: general joint_command usage and smooth homing
• Running an MIT Joint Sweep: the smallest command-path check
• Subscribing With Callbacks: read actual joint state during replay
• Common Data Types: the JointCommand structure