wuji-sdk (Python)

Python SDK for Wuji series devices. Provides automatic device discovery, connection management, and real-time data streaming for Wuji Glove, Wuji Hand 2, and other Wuji peripherals. Features a type-safe semantic API with native async/await and callback-based subscription support, multi-channel MCAP recording, and rich hand tracking data including joint angles, skeleton, and fingertip poses.

For detailed documentation, see the Wuji Docs Center.

Looking for the C SDK? See the C SDK README.

Installation

pip install wuji-sdk

Quick Start

import time
from wuji_sdk import SdkManager, DeviceType

manager = SdkManager.instance()
# scan() reports each device's type, so connect only the glove.
gloves = [d for d in manager.scan() if d.device_type == DeviceType.WujiGlove]
if not gloves:
    print("No Wuji Glove found")
    exit()
glove = manager.connect(sn=gloves[0].sn, device_name="glove")

sub = glove.tactile().subscribe_with_callback(
    callback=lambda frame: print(f"Max pressure: {max(frame.data):.2f}")
)

time.sleep(10)
sub.close()

More examples: examples/python/.

Examples

• wuji_glove/0.subscribe_callback.py: subscribe to glove streams with callbacks; pass --hand-model-path to set a custom online-IK URDF first.
• wuji_glove/1.subscribe_async.py: subscribe to glove streams with async/await; pass --hand-model-path to set a custom online-IK URDF first.
• wuji_glove/2.recording.py: record glove data to MCAP.
• wuji_glove/3.offline_pipeline.py: run hand tracking from offline frames.
• wuji_glove/4.user.py: inspect, create, and switch local SDK users.
• wuji_glove/5.calibration.py: run IK calibration with terminal guidance or API-style callbacks.
• wuji_glove/6.set_stream_rate.py: lower the glove's raw pose output rate at runtime with subscription.set_rate() on emf_poses; derived streams follow automatically.
• wuji_glove/7.tactile_calibration.py: run the recommended guided tactile-calibration flow.
• wuji_glove/8.tactile_contact_view.py: independently observe the live tactile_binary contact grid after calibration; it is not a calibration workflow.
• wuji_glove/9.tactile_residual_view.py: observe the continuous signed tactile_residual grid after calibration and apply an adjustable contact threshold.
• retargeting/0.retarget_session.py: map hand keypoints (21×3) to a joint command with RetargetSession — no hardware needed.
• retargeting/1.teleop_real.py: live teleoperation — drive a Wuji Hand / Wuji Hand 2 from a Wuji Glove (an example built on RetargetSession; swap the glove read for any (21,3) keypoint source). It lists the SDK users and asks which one to teleoperate under: press Enter to keep the current user, pick the default user for the built-in hand URDF, or pick a named user to use that user's calibrated hand model — an uncalibrated named user falls back to the built-in URDF.

Retargeting

Map human hand keypoints to Wuji Hand joint commands. Retargeting works out of the box — numpy is the only extra dependency (keypoint/qpos arrays):

pip install wuji-sdk numpy

The SDK exposes the pure retarget interface — one frame at a time, supply keypoints from any source:

import numpy as np
from wuji_sdk import Handedness, HandModel, RetargetSession

# The hand model selects the builtin tuning config internally — no config path to manage.
session = RetargetSession.for_hand(HandModel.WujiHand2, side=Handedness.Right)

# A synthetic open right hand, (21, 3) in meters, MediaPipe landmark order —
# replace with your real keypoint source (camera / glove / replay).
# (All-zero / degenerate frames are rejected with an exception.)
keypoints = np.zeros((21, 3), dtype=np.float32)
for finger, x in enumerate([-0.04, -0.03, -0.01, 0.01, 0.03]):  # thumb..pinky
    for k in range(4):
        keypoints[1 + finger * 4 + k] = [x, 0.03 * (k + 1), 0.0]
keypoints[1] = [-0.03, 0.02, 0.01]  # thumb CMC nearer the palm

qpos = session.step(keypoints)  # -> (20,) joint command (firmware order)

Driving a hand live (read → retarget → send) is plain application code built on this interface — see retargeting/1.teleop_real.py for a complete glove → hand loop.

Retargeting is available on Linux x86_64 / aarch64.

License

MIT