Hardware and Software Integration

This page is organized in two parts, mechanical mounting and electrical and network setup, and covers the interfaces, specifications, and limits you need to mount Wuji Hand 2 on a robot arm or fixture and bring up its power and network.

The mechanical part covers mounting interfaces and drawings, the coordinate frames and models part covers model assets, loading, and verification, and the electrical part covers the power supply, power sequencing, network configuration, and connection reliability. For step-by-step first-connection instructions, see Quick Start.

Mechanical Integration

Wuji Hand 2 mounts to an arm or fixture through the wrist flange or the palm interface, and the mounting dimensions, model coordinate frames, handedness differences, and load and cable limits together set what a workable mounting design looks like.

Wrist Mounting Interface

The wrist ships with a standard flange, plus an adapter mount and adapter flange in the box (see package contents). These parts cover desktop fixturing and common flange mating out of the box.

Palm Mounting Interface

The bottom of the palm provides a standard mounting interface for machining an arm-side adapter plate. The interface is the same on the left and right hands, and identical on 2.1 and 2.2:

Item	Specification
Threaded hole 1	M3×0.5 fine thread 6H, thread depth over 5.5 mm, ⌀4 (0/+0.05) counterbore 2.35 ± 0.03 deep
Threaded holes 2 and 3	M4×0.5 fine thread 6H, thread depth over 4 mm, ⌀7 (0/+0.06) counterbore 1 mm deep
Datum references	Located by datum dimensions 28.00 (0/−0.05) and 5.15 (+0.15/−0.05)

The STEP assembly of the palm mounting interface (palm shell and harness) and a single-page A3 dimensioned drawing ship with the wuji-description repository. For how to get them, see Full-Hand STEP and Drawings.

Remove and Refit the Soft Pad

Power the device down before you remove or refit the soft pad:

Remove the Phillips screws at the palm and thumb web.
Lay the hand flat and push the thumb upward until all five fingers come together.
Push the palm plastic outward until the palm soft pad lifts and exposes the adapter-mount screws.
Remove the adapter-mount screws for disassembly. To refit the soft pad, press the palm plastic back into place, then tighten the two screws at the palm and thumb web.

Left and Right Hand Differences

The left and right hands are mirrored parts, and the model meshes are symmetric. Factory default IPs differ by handedness (see Network Configuration below).

Load and Cable Limits

The integration limits below aren’t available yet and will be added later: permitted wrist load, bending moment and shock limits, minimum cable bend radius and exit direction, motion clearance, and mounting screw specifications with recommended torque. Confirm the limits with support before you finalize an integration design.

Assess wrist load, bending moment, and shock for the actual application. Avoid high loads and shock until you confirm the limits.
Leave room for the cable bend radius, exit direction, and motion clearance required by your integration.
Always run the hand with the soft pad and skin fitted. The exposed flex cables on the finger surface are fragile, so work on them only briefly during maintenance and protect them from scratches (see User Notice)
For the safety boundary when running with a robot arm, see Maintenance

Full-Hand STEP and Drawings

The full-hand assembly and palm mounting interface CAD ship with wuji-description v2026.8.14 and later.

Resource	Path and use
Full-hand STEP assembly (with mount)	`hand2/hand2_beta2/body/step/wuji-hand2-description-{left,right}_beta2_with_mount_step.STEP`, for envelope and mounting-interface design. The assembly excludes the fingertip soft pads, so contact simulation should use the models under `body/`
Palm mounting interface STEP	`hand2/hand2_beta2/attachment/wuji-hand2-description-{left,right}-mount_beta2_step.STEP`, the palm shell and wire harness only, for machining a custom arm-side adapter or fixture
A3 dimensioned drawing	`hand2/hand2_beta2/attachment/wuji-hand2-description-{left,right}-mount_beta2.pdf`, dimensioning the threaded holes a custom adapter bolts into. Specs are in Palm Mounting Interface

Left and right files mirror each other. The full-hand STEP and the palm mounting interface files are identical between 2.2 and 2.1 — the version marker in each filename only aligns with its directory, since the palm mounting interface didn’t change between revisions. attachment/ sits outside the ROS 2 package root at body/, so colcon doesn’t install it.

Coordinate Frames and Models

Root link: the root link of the base-free model is {l,r}_wrist, consistent across URDF, MJCF, and USD
Variant with mount: files with the _with_mount suffix use the arm flange mount {l,r}_mount (69 g) as the root link, keep the wrist shell as a separate body, and keep the wrist flange frame addressable
Kinematic equivalence: once the fixed mounting offset is subtracted, fingertip poses agree between the two variants to within 0.006 mm
Actuator naming: {l,r}_{THJ|FFJ|MFJ|RFJ|LFJ}{0-3}, with the anatomical naming map in the Joint Table

Use the URDF definition as the source of truth for the relationship between the wrist mounting frame and root link. The CAD assets include simplified left- and right-hand STEP models, detailed STEP models of the wrist and standard flange, and a PDF of the engineering requirements for the wrist and standard flange. The models in each format (URDF / MJCF / USD) and the CAD assets ship with the wuji-description repository. For how to get them, see Full-Hand STEP and Drawings. Use the whole-hand STEP for envelope and mounting-interface design.

Model Assets

Models and CAD resources ship with wuji-description v2026.8.14 and later.

Category	Contents
Simulation models	Left and right hand URDF (including ROS variants), MJCF, USD, and meshes
With-mount variant	Filenames carry the `_with_mount` suffix, rooted at `{l,r}_mount`
ROS 2 package	`wuji_hand2_beta2_description`, rooted at `hand2/hand2_beta2/body/`

Models are named wujihand2-beta2-{side}, and the USD entry point is wujihand2_beta2.usd.

Requirements

Use	Requirement
MuJoCo visualization	Python 3.8+, MuJoCo 2.3+
ROS 2 visualization (RViz)	ROS 2 (Kilted Kaiju / Jazzy Jalisco), Ubuntu 24.04+
Isaac Sim USD	Isaac Sim 2024.x+
STEP / CAD	Any CAD tool that reads STEP, such as FreeCAD or SolidWorks

Get and Load

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

MuJoCo:

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

# Left hand
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/left.xml

# With-mount variant
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right_with_mount.xml

MJCF collision geometry is the convex hull of each link mesh. Every link participates in collision with only 10 assembly-overlap pairs excluded, so inter-finger and fingertip-to-palm contacts stay live. Display layers are group 1 visual, group 2 collision, and group 3 fingertip sites. ROS 2 and RViz: clone the whole repository into your workspace src/, then build the description package on its own.

cd ~/ros2_ws
colcon build --packages-select wuji_hand2_beta2_description
source install/setup.bash

After the build, the package:// paths in the ROS URDFs (hand2/hand2_beta2/body/urdf/{left,right}-ros.urdf) resolve, and you can load them from a custom launch file or robot_state_publisher. The with-mount variant shares the same prefix as the no-mount model, so one build serves both. Isaac Sim USD:

Variant	Path
Left hand	`hand2/hand2_beta2/body/usd/left/wujihand2_beta2.usd`
Right hand	`hand2/hand2_beta2/body/usd/right/wujihand2_beta2.usd`
With mount	`hand2/hand2_beta2/body/usd/{left,right}_with_mount/wujihand2_beta2.usd`

The USD is a layered asset with base, physics, robot, and sensor sublayers plus the logo texture. The no-mount root prim is wujihand2_beta2_{side}, and the with-mount variant is wujihand2_beta2_{side}_mount. On Play, the drive gains hold the current pose. Current kp / kv gains carry over from the Wuji Hand platform calibration and will be updated once system identification on Wuji Hand 2 hardware is complete. URDF preview:

pip install urdf-viz
urdf-viz hand2/hand2_beta2/body/urdf/right.urdf

Verify

Confirm MuJoCo or the URDF viewer opens with no missing meshes
Confirm the model shows 20 revolute joints
Confirm the directory and ROS 2 package name match 2.2

Loading the model confirms that the assets, paths, and visualization pipeline work. Firmware, networking, sensors, and real device control need a connected device to verify.

Electrical and Network Integration

The device runs on nominal 12 V DC power and an Ethernet link with a static IP, with fixed conventions for power sequencing, addressing several devices, and recovering from a lost connection.

Power Supply

Item	Value
Input voltage	11–13 V DC (12 V nominal)
Power requirement	Rated 200 W or more, the included adapter is 12 V 20 A
Power connector	XT30, with a male-to-female extension cable included (14 AWG, 2 m)
Communication interface	RJ45, 100BASE-TX

Never reverse-connect. Never plug or unplug the power or communication cables while the hand runs. The product has over-voltage and over-current protection, but don’t rely on protection tripping as part of normal operation.

The external interface form and the supply voltage range will change in later versions (no longer the XT30 + RJ45 two-cable direct layout). Leave room in your integration design.

The electrical data below isn’t available yet and will be added later: the XT30 pin polarity diagram, operating / peak / standby power, and recommendations for inrush current, power protection, fusing, and grounding.

Power-Up and Power-Down Sequence

Power up: connect the XT30 at the device end first, then plug in the adapter. Connect once the status light goes from blue breathing (self-check) to white breathing (ready)
Power down: stop motion, call disable(), confirm the device is at rest, disconnect power, then unplug the cables
Hot swap: neither the communication cable nor the power cable supports hot swapping. After an accidental disconnect, follow Timeouts, Disconnection, and Reconnection below

Network Configuration

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
Port	50001	50001

Set your computer’s network adapter to a static IP on the same subnet (such as 192.168.1.50). For the full round-trip of changing a device IP (write to flash, reboot to apply, reconnect at the new address), see SDK Reference.

Multiple Devices and Clients

When several hands share a subnet, connect by serial number (sn) or handedness (handedness). With multiple devices of the same handedness on the network, use sn, otherwise the call raises AmbiguousHandedness
Multiple clients at once (a visualization tool, a recording script, and your application all connected) is the default behavior (enable_bridge=True). To switch to exclusive single-client mode, see Device Connection in the Wuji SDK

Timeouts, Disconnection, and Reconnection

Connection parameters: ConnectOptions(timeout_ms=1000, retry_count=3)
Communication loss while enabled: the device stops the motors and reports a fault. It doesn’t resume motion on its own once communication returns—call enable() again (firmware v2.1.0 and later)

To recover the connection:

Check both ends of the network cable and the network equipment, and confirm that the link to the host has recovered.
Subscribe to joint_diagnostics, read the active error codes, decode them with WujiHand2.describe_error(code), and remove the reported causes.
Call enable() again and confirm that the status light turns solid white.

Overview

Hardware

Software

More

Hardware and Software Integration

Mechanical Integration

Wrist Mounting Interface

Palm Mounting Interface

Remove and Refit the Soft Pad

Left and Right Hand Differences

Load and Cable Limits

Full-Hand STEP and Drawings

Coordinate Frames and Models

Model Assets

Requirements

Get and Load

Verify

Electrical and Network Integration

Power Supply

Power-Up and Power-Down Sequence

Network Configuration

Multiple Devices and Clients

Timeouts, Disconnection, and Reconnection

​Mechanical Integration

​Wrist Mounting Interface

​Palm Mounting Interface

​Remove and Refit the Soft Pad

​Left and Right Hand Differences

​Load and Cable Limits

​Full-Hand STEP and Drawings

​Coordinate Frames and Models

​Model Assets

​Requirements

​Get and Load

​Verify

​Electrical and Network Integration

​Power Supply

​Power-Up and Power-Down Sequence

​Network Configuration

​Multiple Devices and Clients

​Timeouts, Disconnection, and Reconnection

Mechanical Integration

Wrist Mounting Interface

Palm Mounting Interface

Remove and Refit the Soft Pad

Left and Right Hand Differences

Load and Cable Limits

Full-Hand STEP and Drawings

Coordinate Frames and Models

Model Assets

Requirements

Get and Load

Verify

Electrical and Network Integration

Power Supply

Power-Up and Power-Down Sequence

Network Configuration

Multiple Devices and Clients

Timeouts, Disconnection, and Reconnection