Quick Start

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. If anything is missing, contact support@wuji.tech before you continue.

Install the Software

Install the Wuji SDK (Python):

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. You can instead install Wuji Studio to scan and connect devices, view joint states, and upgrade firmware without writing code.

Connect the Cables and Power On

1. Connect the device network port to your computer's network port with the supplied RJ45 cable.
2. Connect the device to the power adapter with the supplied XT30 extension cable: connect the device end first, then plug in the adapter.
3. 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.

Configure the Host Network Adapter

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

Set your computer's network adapter to a static IP on the same subnet (such as 192.168.1.100), 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

Discover and Connect the Device

from wuji_sdk import SdkManager

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

For more ways to connect (by serial number, by address, or with multiple devices), see SDK Reference.

Check State and Faults

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. If fewer, see Troubleshooting

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()

If an error code is active, work through Troubleshooting before you continue.

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()

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.

Stop, Disable, 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.

Upgrade the Firmware

Once the first motion works, upgrade the firmware to the latest version. Both official tools push the firmware package that matches your device's hardware model, so you never pick a package by hand:

• Wuji Studio (recommended for a first run): a guided upgrade in a graphical interface, see Wuji Studio firmware upgrade
• Wuji CLI (for scripts and batch scenarios): a command-line upgrade with 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 Compatibility.