> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

To connect a ROS 2 application, complete device safety preparation and physical connections, then follow [ROS 2 Integration](https://docs.wuji.tech/docs/en/wuji-hand/beta1/ros2-integration.md). For direct SDK use, continue with this page. The integration page provides the ROS 2 environment and installation requirements.

> [!NOTE]
>
> 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. This page covers 2.1 devices. For 2.2, see the [Wuji Hand 2.2 quick start](https://docs.wuji.tech/docs/en/wuji-hand/latest/quick-start.md).

## Before You Start

| What's on hand | Where to start | Approximate time |
| - | - | - |
| No device yet | [Simulation Check](#simulation-check) | 10 minutes |
| One Wuji Hand 2.1 | [Real-Device Run](#real-device-run) | 30 minutes |
| Wuji Hand 2.1 plus Wuji Glove | Finish the real-device run, then [Cross-Product Teleoperation](#cross-product-teleoperation) | 45 minutes |

You need Ubuntu 22.04 or later and Python 3.10 or later. Read the [User Notice](https://docs.wuji.tech/docs/en/wuji-hand/beta1/user-notice.md) before you work with hardware.

## Simulation Check

This section needs Git, Python, and MuJoCo. No device required.

The 2.1 model assets live under `hand2/hand2_1/`, alongside the `hand2/hand2_2/` assets for 2.2. The two ROS 2 packages have different names, so both install into one workspace.

```bash theme={null}
git clone --depth 1 https://github.com/wuji-technology/wuji-description.git
cd wuji-description
pip install mujoco

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

Once the window opens, confirm the model is complete with no missing meshes and that it has 20 joints.

The left-hand model is `hand2/hand2_1/body/mjcf/left.xml`. Both models include the arm flange mount. For URDF preview, ROS 2 and Isaac Sim loading, and palm mounting interface STEP files and drawings, see [Hardware and Software Integration](https://docs.wuji.tech/docs/en/wuji-hand/beta1/hardware-integration).

> [!WARNING]
>
> 2.1 provides rigid-body models that include the soft-pad geometry. Deformable-body simulation isn't supported yet.

**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.1, the supplied power supply and cables, and an Ubuntu host.

### Step 1: Unboxing Check

Check everything in the box against the [package contents](https://docs.wuji.tech/docs/en/wuji-hand/beta1/overview.md#package-contents).

### Step 2: Install the Software

```bash theme={null}
pip install wuji-sdk
```

For installation details and environment requirements, see the [Wuji SDK quick start](https://docs.wuji.tech/docs/en/wuji-sdk/latest/quick-start.md).

For a first run, also install [Wuji CLI](https://docs.wuji.tech/docs/en/wuji-cli/latest/index.md) to scan and connect devices, read and write parameters, and check device health from a terminal.

### Step 3: 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 (power-up and self-check) → white breathing (ready).

> [!WARNING]
>
> 2.1 supports 12 V DC only. Connect exactly 12 V, because other voltage ranges aren't compatible. Use a supply rated at 200 W or higher, which the bundled adapter meets. See [Electrical and Power](https://docs.wuji.tech/docs/en/wuji-hand/beta1/usage-constraints.md#electrical-and-power-strong-constraints) in Usage Constraints.

For interface locations, see [Product Introduction](https://docs.wuji.tech/docs/en/wuji-hand/beta1/overview.md#communication-and-power-interface). If the light hasn't turned to white breathing after 30 seconds, see [Troubleshooting](https://docs.wuji.tech/docs/en/wuji-hand/beta1/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:

```bash theme={null}
ping 192.168.1.110 # left hand. The right hand is 192.168.1.111
```

### Step 5: Confirm the Device Is Online

```bash theme={null}
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

```python theme={null}
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, see [Device Connection in the Wuji SDK](https://docs.wuji.tech/docs/en/wuji-sdk/latest/device-connection.md).

### Step 7: Check the State

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

```python theme={null}
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](https://docs.wuji.tech/docs/en/wuji-hand/beta1/troubleshooting) before you continue.

### Step 8: Enable the Joints

```python theme={null}
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()
```

> [!WARNING]
>
> 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:

```python theme={null}
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](https://docs.wuji.tech/docs/en/wuji-hand/beta1/control-guide#mit-control-mode), and [parameter safety limits](https://docs.wuji.tech/docs/en/wuji-hand/beta1/control-guide#parameter-safety-limits), see the Control Guide.

To see the motion directly, run `wuji viz` and watch a 3D hand model follow the joint states in your browser. 2.1 has no fingertip tactile sensors, so the Viewer shows the hand model only. For the full command, see [Live Visualization](https://docs.wuji.tech/docs/en/wuji-cli/latest/visualization.md).

### Step 10: Stop and Power Down

```python theme={null}
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: Confirm the Firmware Version

```bash theme={null}
wuji ping
```

The 2.1 firmware stays on v1.2.4 and receives no further updates. The SDK upgrades to the latest version, and the capabilities that depend on 2.2 hardware stay unavailable on 2.1. For the version pairing and the list of differences, see [Version Identification and Differences](https://docs.wuji.tech/docs/en/wuji-hand/beta1/version-identification-and-compatibility).

**Done when**: all 20 joints are online with no active error codes, and one smooth return to zero completes.

## Cross-Product Teleoperation

This section needs one Wuji Hand 2.1 that has finished the real-device run, plus one calibrated [Wuji Glove](https://docs.wuji.tech/docs/en/wuji-glove/latest/index.md) 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

```bash theme={null}
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:

```bash theme={null}
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](https://docs.wuji.tech/docs/en/wuji-sdk/latest/retargeting.md#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

1. Clear the hand's workspace and confirm nobody is touching it.
2. Put the glove on with fingers relaxed and slightly curled.
3. Run the example, starting with slow, small motions.
4. Watch whether motion stays continuous, directions match, and no error code fires.
5. 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](https://docs.wuji.tech/docs/en/wuji-hand/beta1/troubleshooting).

For retargeting parameters, input format, and frame conventions, see [hand retargeting in the Wuji SDK](https://docs.wuji.tech/docs/en/wuji-sdk/latest/retargeting.md).

**Done when**: glove data keeps updating and the hand follows the finger motion under control.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.