Wuji Hand Community

What Python package do I need to read data from the Wuji hand?

Install wujihandpy, the official Wuji SDK Python package:

pip install wujihandpy numpy

The wuji_hand_sdk_stream.py bridge script imports it via import wujihandpy and calls hand.read_joint_actual_position(timeout=0.4) to get the 5×4 joint position array. Verify the install: python3 -c "import wujihandpy; print(wujihandpy.__version__)".

What does the 5×4 joint position array represent?

The Wuji hand has 5 fingers (thumb, index, middle, ring, little), each with 4 joints. The read_joint_actual_position() call returns a flat list of 20 floats representing joint angles in radians. The bridge script reshapes this into a 5×4 array, computes the mean across each finger's 4 joints, and normalizes from the [0, π/2] range to [0, 1] to produce the per-finger bends value used in teleop and recording.

The pressure map is always zeros. Is that normal?

It can be. If only the joint position hardware is connected without a tactile sensor module, the pressure_map_24x32 field is a zero-filled placeholder. Use mock_wuji_stream.py to verify the heatmap rendering pipeline works correctly. For production use, confirm your Wuji firmware version includes tactile sensor support and that the tactile module is powered and connected.

How do I run without physical hardware?

Use the included mock_wuji_stream.py script to generate synthetic JSONL frames with animated finger bends, a Gaussian pressure-blob tactile map, 6-axis IMU data, and EMF readings 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 with --wuji-cmd:

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"

All platform features work identically in mock mode.

What is the difference between wuji_glove_agent.py and wuji_hand_sdk_stream.py?

wuji_hand_sdk_stream.py is a data source: it imports wujihandpy, reads raw joint positions from the hardware, and emits JSONL frames to stdout at configurable Hz. wuji_glove_agent.py is the platform bridge: it launches the stream script as a subprocess, parses the JSONL output, and forwards the decoded sensor data to the Fearless Platform via WebSocket. The agent also handles session registration, telemetry buffering, reconnection, and latency pings.

How do I select left vs right hand?

Pass --glove left, --glove right, or --glove auto (default) to wuji_glove_agent.py. In auto mode the agent reads the hand_side field from the first JSONL frame. The stream script accepts --hand-side left or --hand-side right, defaulting to right. For bilateral recording, run two agent processes with distinct --node-id values and different --glove settings, connected to the same session ID.

The agent fails to connect to the platform WebSocket. What should I check?

Confirm the Fearless backend is running: curl http://localhost:8000/health. If using a remote backend, pass the correct URL: --backend ws://HOST:PORT. The agent uses exponential backoff (1 s min, 10 s max) for reconnection — watch the terminal output for reconnect attempts and the specific error message.