Quick Start

This page splits into three sections by what’s on hand: simulation check needs no device, real-device run covers the full path from unboxing to a first motion, and cross-product teleoperation brings in Wuji Glove. Each section stands on its own, so skip to the next one when the prerequisites don’t apply.

Before You Start

What’s on hand	Where to start	Approximate time
No device yet	Simulation Check	10 minutes
One Wuji Hand 2	Real-Device Run	30 minutes
Wuji Hand 2 plus Wuji Glove	Finish the real-device run, then Cross-Product Teleoperation	45 minutes

You need Ubuntu 22.04 or later and Python 3.10 or later. Read the User Notice before you work with hardware.

Simulation Check

This section needs Git, Python, and MuJoCo. No device required. Install MuJoCo and load the right-hand model:

git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description
pip install mujoco

python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right.xml

Once the window opens, confirm the model is complete with no missing meshes and that it has 20 joints. For the left-hand model, the variant with a mount, URDF preview, ROS 2 and Isaac Sim loading, the full-hand STEP, and palm mounting interface drawings, see Coordinate Frames and Models. Done when: the model renders correctly with all 20 revolute joints. A model that loads confirms the assets and the visualization path work. Firmware, networking, and real-device control need a device to verify, so continue with the next section.

Real-Device Run

This section needs one Wuji Hand 2, the supplied power supply and cables, and an Ubuntu host.

Step 1: Unboxing Check

Check everything in the box against the package contents: power adapter, AC cable, RJ45 cable, XT30 extension cable, adapter mount, and adapter flange.

Step 2: Install the Software

pip install wuji-sdk

For installation details and environment requirements, see the Wuji SDK quick start. For a first run, also install Wuji CLI to scan and connect devices, read and write parameters, check device health, and upgrade firmware from a terminal.

Step 3: Connect the Cables and Power On

Connect the device network port to your computer’s network port with the supplied RJ45 cable.
Connect the device to the power adapter with the supplied XT30 extension cable: connect the device end first, then plug in the adapter.
After power-up, watch the back-of-hand status light: blue breathing (self-check) → white breathing (ready).

For interface locations, see Product Introduction. If the light hasn’t turned to white breathing after 30 seconds, see Troubleshooting.

Step 4: Configure the Host Network Adapter

The device uses a static IP and doesn’t support DHCP. Factory default addresses:

Item	Left hand	Right hand
IP	192.168.1.110	192.168.1.111
Gateway	192.168.1.1	192.168.1.1
Subnet mask	255.255.255.0	255.255.255.0

Set your computer’s network adapter to a static IP on the same subnet (such as 192.168.1.50), with subnet mask 255.255.255.0. Then verify connectivity:

ping 192.168.1.110 # left hand. The right hand is 192.168.1.111

Step 5: Confirm the Device Is Online

wuji devices
wuji ping

wuji devices lists the devices on the same subnet, and wuji ping returns device type, serial number, firmware version, and IP. When the list comes back empty, check power, the network cable, and the adapter configuration, then run it again. With several devices on one subnet, pass --sn to target one and avoid connecting to the wrong device.

Step 6: Connect the Device

from wuji_sdk import SdkManager

manager = SdkManager.instance()
hand = manager.auto_connect(device_name="wuji_hand_2")

With several devices on the subnet, use manager.connect(sn="<serial number>") instead. For other ways to connect, such as by address or by handedness, see Device Connection in the Wuji SDK.

Step 7: Check the State

Confirm that all 20 joints are online with no active error codes:

from wuji_sdk import WujiHand2

print(hand.online_joints_count().get()) # expect 20

sub = hand.joint_diagnostics().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
for j in frame.joints:
    if j.error_code_current:
        print(j.nid, WujiHand2.describe_error(j.error_code_current))
sub.close()

When fewer than 20 joints are online, or an error code is active, work through Troubleshooting before you continue.

Step 8: Enable the Joints

import time

hand.enable()

# Wait until all online joints reach the Enabled state
sub = hand.joint_diagnostics().subscribe()
deadline = time.monotonic() + 5.0
while time.monotonic() < deadline:
    frame = sub.recv()
    if frame is not None and frame.joints and all(
        j.status_word.ext_state == 2 for j in frame.joints
    ):
        break
else:
    sub.close()
    raise TimeoutError("Joint enable timed out")
sub.close()

Enabled joints carry torque. Before enabling, make sure the finger workspace is clear and nobody is touching the hand.

Step 9: Run Your First Safe Motion

Return smoothly from the current pose to zero. The example first reads every joint’s current position, then uses 1.5 seconds of linear interpolation to reduce the target positions gradually instead of sending a zero-position step:

import time
from wuji_sdk import JointCommand

# Read the current pose. nid uses groups of five slots, with joints in the first four
sub = hand.joint_states().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
start = [0.0] * 20
for j in frame.joints:
    bus, node_index = divmod(j.nid - 1, 5)
    if bus < 5 and node_index < 4:
        start[bus * 4 + node_index] = float(j.position)
sub.close()

# Use the conservative parameters from the latest SDK example
hand.effort_limit().set(1.5)
hand.mit_params().set((3.0, 0.05))

pub = hand.joint_command().publish()
steps = 300 # 1.5 seconds × 200 Hz
for i in range(1, steps + 1):
    ratio = i / steps
    positions = [position * (1.0 - ratio) for position in start]
    pub.send([JointCommand(position, 0.0, 0.0) for position in positions])
    time.sleep(1.0 / 200)
pub.close()

Expected behavior: all joints return smoothly from the current pose to zero without snapping back or colliding. For unit conventions, MIT control mode, and parameter safety limits, see the Control Guide. To see the motion directly, run wuji viz and watch it in your browser. A 3D hand model follows the joint states. For the full command, see Live Visualization.

Step 10: Stop and Power Down

hand.disable() # disables all joints. The status light turns white breathing
manager.disconnect_all() # disconnects

Power-down order: confirm the device is at rest → disconnect power → unplug the cables. In an emergency, call hand.emergency_stop() at any time. The whole hand stops immediately and the call takes no mask.

Step 11: Upgrade the Firmware

Once the first motion works, upgrade the firmware to the latest version. Wuji CLI pushes the firmware package that matches your device’s hardware model, so you never pick a package by hand, and prints a structured report. See Wuji CLI firmware upgrade. Don’t cut power during the upgrade. For how firmware and SDK versions pair up, see Version Identification and Differences. Done when: all 20 joints are online with no active error codes, one smooth return to zero completes, and the firmware is up to date.

Cross-Product Teleoperation

This section needs one Wuji Hand 2 that has finished the real-device run, plus one calibrated Wuji Glove that streams data. Both devices sit on the same subnet and share the same handedness. Once the glove is on, it streams hand keypoints continuously. Retargeting converts them into 20 joint angles and sends them to the hand, which follows the finger motion in real time.

Confirm Both Devices Are Online

wuji devices
wuji ping

The list should show both wuji_hand_2 and wuji_glove. Check the serial numbers, firmware versions, and handedness. With other devices of the same type on the subnet, note the target serial number for the next step.

Run the Teleoperation Example

The full retargeting and teleoperation implementation lives in the Wuji SDK repository examples and updates together with the interface:

git clone https://github.com/wuji-technology/wuji-sdk.git
cd wuji-sdk/examples/python/retargeting
pip install wuji-sdk numpy

python 1.teleop_real.py

The example lists the SDK users first. On a first run, press Enter to keep the default user. For how the choice affects the hand model, see Choose the SDK user for teleop. The example runs against a right-hand assembly by default. For a left-hand assembly, change the SIDE constant at the top of the script. The example scans and connects to the device it finds. With several hands on the subnet, confirm the target device first so you don’t drive one someone else is using.

Complete a Cross-Product Motion

Clear the hand’s workspace and confirm nobody is touching it.
Put the glove on with fingers relaxed and slightly curled.
Run the example, starting with slow, small motions.
Watch whether motion stays continuous, directions match, and no error code fires.
Press Ctrl+C to stop. On exit, the example disables the hand and disconnects.

Stop right away on an abnormal pose, a communication break, or an error code, then work through Troubleshooting. For retargeting parameters, input format, and frame conventions, see hand retargeting in the Wuji SDK. Done when: glove data keeps updating and the hand follows the finger motion under control.

Overview

Hardware

Software

More

Before You Start

Simulation Check

Real-Device Run

Step 1: Unboxing Check

Step 2: Install the Software

Step 3: Connect the Cables and Power On

Step 4: Configure the Host Network Adapter

Step 5: Confirm the Device Is Online

Step 6: Connect the Device

Step 7: Check the State

Step 8: Enable the Joints

Step 9: Run Your First Safe Motion

Step 10: Stop and Power Down

Step 11: Upgrade the Firmware

Cross-Product Teleoperation

Confirm Both Devices Are Online

Run the Teleoperation Example

Complete a Cross-Product Motion

​Before You Start

​Simulation Check

​Real-Device Run

​Step 1: Unboxing Check

​Step 2: Install the Software

​Step 3: Connect the Cables and Power On

​Step 4: Configure the Host Network Adapter

​Step 5: Confirm the Device Is Online

​Step 6: Connect the Device

​Step 7: Check the State

​Step 8: Enable the Joints

​Step 9: Run Your First Safe Motion

​Step 10: Stop and Power Down

​Step 11: Upgrade the Firmware

​Cross-Product Teleoperation

​Confirm Both Devices Are Online

​Run the Teleoperation Example

​Complete a Cross-Product Motion

Before You Start

Simulation Check

Real-Device Run

Step 1: Unboxing Check

Step 2: Install the Software

Step 3: Connect the Cables and Power On

Step 4: Configure the Host Network Adapter

Step 5: Confirm the Device Is Online

Step 6: Connect the Device

Step 7: Check the State

Step 8: Enable the Joints

Step 9: Run Your First Safe Motion

Step 10: Stop and Power Down

Step 11: Upgrade the Firmware

Cross-Product Teleoperation

Confirm Both Devices Are Online

Run the Teleoperation Example

Complete a Cross-Product Motion