> ## 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.

# 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.

<Info>
  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](/en/docs/wuji-hand/latest/quick-start).
</Info>

## 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](/en/docs/wuji-hand/latest/product-introduction#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](https://github.com/wuji-technology/wuji-description). For how to get them, see [Full-Hand STEP and Drawings](#full-hand-step-and-drawings).

### Remove and Refit the Soft Pad

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

1. Remove the Phillips screws at the palm and thumb web.
2. Lay the hand flat and push the thumb upward until all five fingers come together.
3. Push the palm plastic outward until the palm soft pad lifts and exposes the adapter-mount screws.
4. 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](#network-configuration) below).

### Load and Cable Limits

<Warning>
  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.
</Warning>

* 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](/en/docs/wuji-hand/latest/user-notice#cable-and-flex-cable-protection))
* For the safety boundary when running with a robot arm, see [Maintenance](/en/docs/wuji-hand/latest/maintenance#safety-responsibilities-when-running-with-a-robot-arm)

### 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](#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](/en/docs/wuji-hand/latest/control-guide#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](https://github.com/wuji-technology/wuji-description). For how to get them, see [Full-Hand STEP and Drawings](#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

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

MuJoCo:

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

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

```bash theme={null}
pip install urdf-viz
urdf-viz hand2/hand2_beta2/body/urdf/right.urdf
```

### Verify

1. Confirm MuJoCo or the URDF viewer opens with no missing meshes
2. Confirm the model shows 20 revolute joints
3. 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 |

<Warning>
  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.
</Warning>

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

### 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](#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](/en/docs/wuji-hand/latest/sdk-reference/device-operations#ip-set/get).

### 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](/en/docs/wuji-sdk/device-connection/)

### 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:

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


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