Wuji Dexterous Hand — SDK Setup & Teleop Guide

1. Overview

The Wuji dexterous hand is a high-DOF robotic end effector designed for contact-rich manipulation teleoperation and imitation learning data collection. It provides 5 fingers with 4 joints each (5×4 = 20 joint positions), a 24×32 tactile pressure map, an IMU channel, and an EMF (electromagnetic field) sensor channel for auxiliary contact sensing. Together these signals give a rich state representation suitable for training manipulation policies that generalize across grasp types and object geometries.

The Wuji SDK ecosystem consists of two layers. The lower layer is the wujihandpy Python package that communicates directly with the hardware over USB (VID 0x0483 by default). The upper layer is the JSONL bridge pipeline used by the RoboticsCenter teleop infrastructure: wuji_hand_sdk_stream.py reads from wujihandpy and emits one JSON object per line to stdout; wuji_glove_agent.py launches this script as a subprocess, parses the JSONL, and forwards decoded sensor data to the Fearless Platform via WebSocket.

Wuji Studio (GUI application, v0.7.0 for amd64 Linux) provides standalone visualization of joint positions and pressure maps without the platform pipeline — useful for hardware bring-up and calibration verification.

2. Full Specifications

3. Quick Start

Install SDK and connect

1. Install the Wuji SDK Python package.

   pip install wujihandpy numpy

2. Plug in the Wuji hand via USB. Confirm the device appears. On Linux: lsusb | grep 0483. Add your user to the dialout group if needed.
3. Start the JSONL stream.

   python3 wuji_hand_sdk_stream.py --hand-side right --hz 30

   You should see JSON objects printed to stdout at 30 Hz, each containing bends, joint_actual_position_5x4, pressure_map_24x32, imu, and emf.
4. Launch the teleop agent connected to the platform.

   python3 wuji_glove_agent.py \
     --session YOUR_SESSION_ID \
     --node-id wuji-right \
     --glove right

   The agent auto-launches the stream script as a subprocess and begins forwarding data to the platform WebSocket.

Mock mode (no hardware)

Use the included mock_wuji_stream.py to generate synthetic JSONL frames. This emits animated finger bends, a Gaussian pressure-blob tactile map, 6-axis IMU data, and EMF readings — all at configurable Hz:

python3 mock_wuji_stream.py --hz 30 --hand-side right --seed 42

To use the mock stream with the agent, override the default stream command:

python3 wuji_glove_agent.py \
  --session YOUR_SESSION_ID \
  --node-id wuji-mock \
  --wuji-cmd "python3 mock_wuji_stream.py --hz 30 --hand-side right"

4. SDK / Python Usage

JSONL frame format

Every frame emitted by wuji_hand_sdk_stream.py contains the following fields:

The bends values are derived from joint_actual_position_5x4 by averaging the 4 joint angles per finger and normalizing from the [0, π/2] range to [0, 1]:

import numpy as np, math

pos = np.array(hand.read_joint_actual_position(timeout=0.4)).reshape(5, 4)
bends = {}
for i, finger in enumerate(["thumb","index","middle","ring","little"]):
    val = float(np.mean(pos[i]))
    bends[finger] = min(1.0, max(0.0, val / (math.pi / 2.0)))

Bridge agent internals

wuji_glove_agent.py wraps linker_glove_agent.py with a Wuji-specific argument set. Key parameters:

The agent uses source: "wuji_jsonl" internally to route JSONL parsing through the Wuji-specific decoder in linker_glove_agent.py, which handles the bends, joint_angles, and emf field variants that different Wuji firmware versions may emit.

Bilateral (left + right) setup

Run two agent processes simultaneously with different node IDs connected to the same session:

# Terminal 1 — right hand
python3 wuji_glove_agent.py \
  --session RC-XXXX-XXXX --node-id wuji-right --glove right \
  --wuji-cmd "python3 wuji_hand_sdk_stream.py --hand-side right --serial-number SN001"

# Terminal 2 — left hand
python3 wuji_glove_agent.py \
  --session RC-XXXX-XXXX --node-id wuji-left --glove left \
  --wuji-cmd "python3 wuji_hand_sdk_stream.py --hand-side left --serial-number SN002"

5. Platform Integration

The Fearless Platform WebSocket endpoint at /api/teleop/ws accepts the Wuji agent registration handshake. The agent sends:

{
  "role": "robot",
  "session_id": "RC-XXXX-XXXX",
  "member_id": "wuji-right",
  "node_id": "wuji-right",
  "node_role": "robot",
  "device_type": "wuji_hand",
  "capabilities": ["glove", "tactile", "telemetry"],
  "source_host": "hostname"
}

After receiving type: "ready", the agent streams telemetry frames. The platform maps the Wuji telemetry into the GloveWorkbench UI panel, which renders:

• Real-time bend bars for all 5 fingers (from the normalized bends dict).
• 24×32 tactile heatmap (from pressure_map_24x32), downsampled to display resolution as needed.
• 6-joint display values mapped from bends (thumb→j1, index→j2, middle→j3, ring→j4, little→j5, average→j6).
• Gesture state inferred from the overall close ratio (fist / half-close / open).

Episode recording

During an active recording session, every telemetry frame is archived as JSONL. Each row contains the full joints, pressure_map_24x32, imu, and emf payload alongside the session ID and millisecond timestamp. Episodes are available in the platform episode browser for playback, download, or direct ingestion into training pipelines.

6. Troubleshooting

7. Related Hardware

The Wuji hand is used in combination with other hardware for complete teleoperation setups:

• LinkerBot O6 — Alternative 5-finger dexterous hand with glove controller and 16-region tactile sensing; uses the same linker_glove_agent under the hood.
• Paxini PX-6AX GEN3 — Discrete fingertip and palm tactile sensors that can supplement the Wuji hand's built-in pressure map with 6-axis force/torque data.
• Damiao AGV — Mobile base for whole-body manipulation setups; the Wuji hand and Damiao AGV can be used in the same teleop session with each registered as a separate node.