Integration Guide

System Requirements

Installation

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

Simulation and Visualization

The repository provides model assets for mainstream simulation/visualization ecosystems. Pick the section matching your tool.

3.2.1 MuJoCo

Wuji Hand

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

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

Wuji Hand soft-pad variant

# Right hand
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/right.xml

# Left hand
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/left.xml

# Simplified-collision variant (faster contact simulation)
python -m mujoco.viewer --mjcf=hand/body-with-soft/mjcf/right_simplified.xml

Wuji Hand 2 (Beta 1)

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

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

Impact-resistant Adapter

python -m mujoco.viewer --mjcf=hand/attachment/impact-resistant-attachment/mjcf/docking.xml

MuJoCo Viewer Controls

Result

Uses the left hand as an example. Load other models with the commands above.

3.2.2 ROS2 / RViz

Installation

hand/body/ is the ROS2 package source (wuji_description). Installation also pulls in hand/attachment/, hand/body-with-soft/, and hand2_beta/ into the package share, so clone the entire repository into your workspace src/ rather than copying hand/body/ alone.

# 1. Source ROS2 environment, replace <distro> with your installed ROS2 distribution
source /opt/ros/<distro>/setup.bash

# 2. Create workspace (if not exists)
mkdir -p ~/ros2_ws/src

# 3. Clone repository
cd ~/ros2_ws/src
git clone https://github.com/wuji-technology/wuji-description.git

# 4. Initialize rosdep (first time only, skip if already initialized)
sudo rosdep init
rosdep update

# 5. Install dependencies
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y

# 6. Build and source
colcon build --packages-select wuji_description
source install/setup.bash

Visualization

# Left hand (default)
ros2 launch wuji_description display.launch.py

# Right hand
ros2 launch wuji_description display.launch.py hand:=right

display.launch.py loads the standard Wuji Hand model. After the build, the package:// paths in the soft-pad variant and Wuji Hand 2 (Beta 1) ROS URDFs (hand/body-with-soft/urdf/{left,right}-ros.urdf and hand2_beta/body/urdf/{left,right}-ros.urdf) also resolve, so you can load them from a custom launch file or robot_state_publisher.

RViz Controls

Result

3.2.3 Isaac Sim USD

The repository provides the following Isaac Sim USD assets:

Wuji Hand

• Left hand: hand/body/usd/left/wujihand.usd
• Right hand: hand/body/usd/right/wujihand.usd

Wuji Hand soft-pad variant

• Left hand: hand/body-with-soft/usd/left/wujihand.usd
• Right hand: hand/body-with-soft/usd/right/wujihand.usd
• Simplified-collision variants: hand/body-with-soft/usd/{left,right}_simplified/wujihand.usd

Wuji Hand 2 (Beta 1)

• Left hand: hand2_beta/body/usd/left/wujihand.usd
• Right hand: hand2_beta/body/usd/right/wujihand.usd

Open the corresponding .usd file directly in Isaac Sim. For a complete simulation example, see isaaclab-sim.

3.2.4 URDF Preview (non-ROS)

Without ROS installed, preview URDF models directly with any URDF viewer such as urdf-viz.

Wuji Hand soft-pad variant

urdf-viz hand/body-with-soft/urdf/right.urdf

Wuji Hand 2 (Beta 1)

urdf-viz hand2_beta/body/urdf/right.urdf

Impact-resistant Adapter

urdf-viz hand/attachment/impact-resistant-attachment/urdf/docking.urdf

Wuji Glove

glove/body/ provides the Wuji Glove model used for hand motion tracking. Each hand is described by a URDF skeleton with 21 revolute joints across the five fingers, an EMF transmitter base on the wrist (base_link_TX.STL), and a receiver coil on every fingertip (base_link_RX.STL). The transmitter top-cover STEP and assembly PDF are under glove/body/step/. For mounting attachment STEP files, see 3.3.4 Wuji Glove Mounting Attachments.

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

Mechanical Integration

3.3.1 Robot Arm Adapter

hand/attachment/step/ provides two adapters for mounting Wuji Hand on a robot arm end-effector flange:

For the impact-resistant adapter's working principle and component names, see 5.3 Impact-resistant Adapter.

Integration steps

1. Open the STEP file with any CAD tool that supports STEP (FreeCAD, SolidWorks, Creo)
2. Adapt the design to your target robot arm's flange hole pattern
3. Reference the assembly PDF drawing (wuji-hand&Direct-Adapter-assembled-v1.pdf or wuji-hand&Impact-Resistant-Adapter-assembled-v1.pdf, matching your adapter) to confirm the assembly relationships
4. Follow Adapter-Installation-Instructions.md to complete installation

3.3.2 Wuji Hand 2 (Beta 1) Structural Assemblies and Adapter Mount

hand2_beta/body/step/ ships the Wuji Hand 2 (Beta 1) STEP source files for mechanical integration and downstream design:

Integration steps

1. Open the STEP file with any CAD tool that supports STEP (FreeCAD, SolidWorks, Creo)
2. Reference the left and right structural assemblies to confirm the mounting face and alignment
3. Adapt the adapter mount to your target robot arm's flange hole pattern and complete the assembly

3.3.3 Unitree G1 Adapter

hand/attachment/unitree-g1-attachment/unitree-g1-docking-adapter.stl mounts Wuji Hand on the Unitree G1 humanoid robot's end-effector.

Integration notes

The STL is ready for 3D printing (nylon or PETG recommended for rigidity). One end mates with the G1 end-effector flange. The other connects to Wuji Hand's standard mounting interface.

3.3.4 Wuji Glove Mounting Attachments

glove/attachment/ provides STEP assemblies (AP214) of the Wuji Glove mounting attachments for mechanical integration:

Integration steps

1. Open the STEP file with any CAD tool that supports STEP (FreeCAD, SolidWorks, Creo)
2. Reference the assembly to confirm the mounting face and alignment
3. Adapt the mounting holes to your target device and complete the assembly