Quick Start

Getting Started

To connect a ROS 2 application, complete device safety preparation and physical connections, then follow ROS 2 Integration. For direct SDK use, continue with this page. The integration page provides the ROS 2 environment and installation requirements.

Before You Start

Linux and Macs with Apple silicon are supported. See the SDK system requirements. The examples use Python 3.10 or later.

Simulation Check

This section needs Git, Rust/Cargo, and urdf-viz. No device required.

Wuji Glove ships a 21-DOF hand skeleton model for checking frames, joints, and data mapping:

Install Rust/Cargo before running cargo install. See the urdf-viz installation guide.

git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description
cargo install urdf-viz

urdf-viz glove/body/urdf/right.urdf

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

For the left-hand model and EMF module STL files, see Model Assets and Loading. For the transmitter cover STEP and the three mounting attachments, see Mechanical Integration.

Done when: the skeleton model renders correctly with all 21 revolute joints.

A model that loads confirms the assets and the visualization path work. Tactile, EMF, and IMU data need a connected device, so continue with the next section.

Real-Device Run

This section needs one Wuji Glove, the data acquisition board, the supplied cables, and a computer that meets the SDK system requirements.

Step 1: Unboxing Check

Check everything in the box against the package contents: the USB-C to USB-C cable, the USB-C to Ethernet power adapter, the USB-A to USB-C cable, and the Ethernet cable.

Step 2: Install the Software

pip install wuji-sdk
curl -fsSL https://get.wuji.tech/cli | bash

The Wuji SDK reads glove data from code, and the Wuji CLI scans devices, runs calibration, and runs health checks from a terminal. For installation and environment requirements, see the Wuji SDK quick start and Wuji CLI installation.

Step 3: Connect the Data Acquisition Board

Use the USB-C to USB-C cable to connect the data acquisition board to the USB-C to Ethernet power adapter.

Step 4: Connect Ethernet and Power

Use the USB-C to Ethernet power adapter to connect the Ethernet cable and power cable. For the power cable, we recommend a USB-A to USB-C cable. After connecting, check that the data acquisition board indicator looks normal.

Step 5: Configure Computer Network

Verify the computer and glove are on the same network segment (default segment is 192.168.1.x). The first three octets of the IP address must match, and set the subnet mask to 255.255.255.0. The default IP is 192.168.1.100 for the left hand and 192.168.1.101 for the right hand. Avoid assigning these addresses to the computer to prevent conflicts.

On macOS 13 or later, open System Settings › Network › Ethernet › Details › TCP/IP. On macOS 11–12, open System Preferences › Network › Ethernet › Advanced › TCP/IP. Set Configure IPv4 to Manually, and enter an IP on the same subnet and the subnet mask above. For network permissions, see Device Discovery and Connection.

On Ubuntu, choose either method:

Method 1: Graphical Interface

1. Open Settings and go to Network
2. Click the gear icon in the Wired row
3. Switch to the IPv4 tab and select Manual for IPv4 Method
4. Under Addresses, enter Address 192.168.1.50 and Netmask 255.255.255.0
5. Click Apply
6. Run ping 192.168.1.101 in a terminal to confirm connectivity

Method 2: Command Line

Replace the interface name in the commands with your actual interface name. An address set this way is lost after a system reboot.

1. Identify the network interface name

ip link show

Find the Ethernet interface name, for example eth0, enp3s0, or eno1.

2. Verify the Ethernet cable is connected

ethtool eth0 | grep "Link detected"

The output should show Link detected: yes.

3. Clear existing IP addresses

sudo ip addr flush dev eth0

4. Set a static IP and subnet mask

sudo ip addr add 192.168.1.50/24 dev eth0

5. Bring up the interface

sudo ip link set eth0 up

6. Verify the IP and subnet mask

ip addr show eth0

Confirm the output contains inet 192.168.1.50/24.

7. Test connectivity

# Right-hand glove example
ping 192.168.1.101

If connecting to the left-hand glove, use ping 192.168.1.100 instead. Receiving a response indicates a successful connection.

Step 6: Wear the Wuji Glove

Put on the Wuji Glove and adjust the position of the data acquisition board using the arm strap.

Step 7: Install the Tracker (Optional)

To use an external Tracker for spatial tracking, peel back the soft cover on the EMF transmitter module on the back of the glove and mount the Tracker on the exposed mounting plate.

Different Tracker models need different adapters. For adapter STEP files and assembly notes, see Attachment STEP Files.

Step 8: Confirm the Device Is Online

wuji devices
wuji ping
wuji doctor

wuji devices lists the devices on the same subnet, wuji ping returns device type, serial number, firmware version, and IP, and wuji doctor runs a health check that locates EMF disconnections along with tactile dead points, rows, and columns.

When the list comes back empty, check that the device has power and that the host sits on the same subnet as the glove.

Step 9: Connect to the Device and Check the State

from wuji_sdk import SdkManager

manager = SdkManager.instance()
glove = manager.auto_connect(device_name="glove")

print(glove.sn().get())         # serial number
print(glove.version().get())    # firmware version
print(glove.hand_side().get())  # hand side

With several devices on the subnet, use manager.connect(sn="<serial number>") instead. For connecting by address, by handedness, and other options, see device connection in the Wuji SDK.

Only one client holds the glove connection at a time. When wuji viz or another SDK script already holds the same glove, this connection can’t be established, so exit the running client and try again. See Free Up an Occupied Device Connection.

The indicator light on the data acquisition board tracks the connection. Yellow very slow flash means the host is connected but not pulling data, and cyan heartbeat means data is streaming. Red fast flash means the Ethernet link is down, and red solid means a sensor hardware fault. For how to handle each state, see Connection States and the Indicator Light.

Step 10: Run the Calibration

Hand model calibration is isolated per user, and the Default user can’t run it. Create a named profile, switch to it, then calibrate:

wuji user create operator --switch
wuji calib hand-model

Before calibrating, keep fingers slightly bent and relaxed, without crossing the fingertip modules or making a fist. The calibration output saves to the current user profile and takes effect right away, producing the left- and right-hand models for that user.

Calibration drives the accuracy of joint angles, skeleton, and fingertip poses. For contact detection, also run tactile calibration. For full parameters and error handling, see Wuji CLI hand model calibration.

Step 11: Get the First Data Frame

wuji sub tactile --count 1
wuji sub emf_poses --count 1
wuji sub imu_data/palm --count 1

--count 1 exits after one full frame arrives. To read data in an application, connect to the glove with the Wuji SDK and subscribe to tactile, emf_poses, or hand_skeleton.

When tactile values read all 0 or -1, EMF confidence runs low, or the IMU drifts continuously, see Troubleshooting.

For what each stream means and its structure, frames, and timestamps, see SDK Data Reference.

To check the data visually, run wuji viz and view the hand skeleton, EMF receivers, tactile point cloud, and raw tactile matrix in your browser. For the full command, see Live Visualization.

Step 12: Stop and Take Off the Glove

Once reading finishes, disconnect to free the glove for other clients:

manager.disconnect_all()

When taking the glove off, apply force on the fabric at the finger pads and don’t pull on the EMF modules or the back of the hand. Store it in a dry, cool place and avoid folding the sensor areas. For the full requirements, see Storage and Environment.

Step 13: Upgrade the Firmware

Once the first data frame arrives, upgrade the firmware to the latest version:

wuji upgrade --check
wuji upgrade --type wuji_glove

--check is read-only and lists which devices have a firmware update. --type wuji_glove upgrades every glove in scope to its own latest version, and each device reboots into the new firmware once flashing finishes. For the full scope and action options, see Wuji CLI firmware upgrade.

The calibration interfaces have minimum firmware and SDK versions. For the pairing, see the component version table in Release Notes.

Done when: the device is online, the health check passes, hand model calibration completes, at least one valid frame arrives with a timestamp and handedness, and the firmware is up to date.

Cross-Product Teleoperation

This section needs one Wuji Glove that has finished the real-device run, plus one Wuji Hand 2 that has finished its quick start with all 20 joints online. 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

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.

For retargeting parameters, input format, and frame conventions, see hand retargeting in the Wuji SDK. For hand-tracking frame conventions and timestamp alignment, see SDK Data Reference.

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