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

# Configuration

## Launch Commands

| Command | Description |
| :- | :- |
| `ros2 launch wujihand_bringup wujihand.launch.py` | Launch driver only |
| `ros2 launch wujihand_bringup wujihand.launch.py rviz:=true` | Launch driver with RViz visualization |
| `ros2 launch wujihand_bringup wujihand_dual.launch.py` | Launch and auto-connect both hands |

## Configurable Parameters

<Info>
  Handedness (left/right) is automatically detected from hardware. No manual specification required.
</Info>

| Parameter | Default | Description |
| :- | :- | :- |
| `hand_name` | `hand_0` | Namespace for distinguishing multiple hands. <br /> Example: `ros2 launch wujihand_bringup wujihand.launch.py hand_name:=my_hand` |
| `serial_number` | `""` | Device serial number (auto-detect if empty) |
| `hand_side` | `""` | Connect by handedness when no serial\_number: `""` (unique device), `left`, `right` |
| `name_by_handedness` | `false` | When true, roots topics and services under `/hand_<handedness>/`, overriding `hand_name`. Dual-hand launch enables this automatically |
| `publish_rate` | `1000.0` | Joint state publishing rate (Hz) |
| `filter_cutoff_freq` | `10.0` | Low-pass filter cutoff frequency (Hz) |
| `diagnostics_rate` | `10.0` | Diagnostics publishing rate (Hz) |
| `rviz` | `false` | Whether to launch RViz visualization |

## Multi-hand Configuration

When controlling multiple dexterous hands simultaneously, use serial numbers and namespaces to distinguish them.

### List Connected Device Serial Numbers

List the serial numbers of all WujiHand devices currently on the USB bus, then plug them into the `serial_number` parameter in the launch commands below:

```bash theme={null}
ros2 run wujihand_driver wujihand_list
```

If opening a new terminal, you need to source the ROS2 environment again

```bash theme={null}
# Source ROS2 environment, replace <distro> with your ROS2 distribution
source /opt/ros/<distro>/setup.bash
# If built from source, overlay the workspace (Deb package users can skip)
# Replace <workspace> with your workspace path, e.g., ~/wujihandros2
source <workspace>/install/setup.bash
```

```bash theme={null}
# Terminal 1: Launch left hand
ros2 launch wujihand_bringup wujihand.launch.py \
    hand_name:=left_hand serial_number:=ABC123

# Terminal 2: Launch right hand
ros2 launch wujihand_bringup wujihand.launch.py \
    hand_name:=right_hand serial_number:=DEF456
```

### Launch Both Hands with One Command

One command auto-discovers and connects every plugged-in hand — no serial numbers needed. Each hand is named by its detected handedness, publishing topics under `/hand_left/*` and `/hand_right/*`:

```bash theme={null}
ros2 launch wujihand_bringup wujihand_dual.launch.py
```

Optional visualization:

```bash theme={null}
# One RViz window per hand
ros2 launch wujihand_bringup wujihand_dual.launch.py rviz:=true

# A single Foxglove Bridge
ros2 launch wujihand_bringup wujihand_dual.launch.py foxglove:=true
```

### Run Multi-hand Demos

When running demo scripts in a multi-hand environment, specify the target hand with `--ros-args -p hand_name:=<hand-name>`:

```bash theme={null}
# Run wave demo on the left hand
ros2 run wujihand_bringup wave_demo.py --ros-args -p hand_name:=left_hand

# Run wave demo on the right hand
ros2 run wujihand_bringup wave_demo.py --ros-args -p hand_name:=right_hand
```

<Info>
  The `hand_name` must match the name specified when launching the driver.
</Info>

### Topic Namespaces

After launch, each hand has its own topic namespace:

```text theme={null}
# Left hand topics
/left_hand/joint_states
/left_hand/joint_commands
/left_hand/hand_diagnostics
/left_hand/robot_description
/left_hand/tf
/left_hand/tf_static

# Right hand topics
/right_hand/joint_states
/right_hand/joint_commands
/right_hand/hand_diagnostics
/right_hand/robot_description
/right_hand/tf
/right_hand/tf_static
```

## Joint Identification

The dexterous hand has 20 joints (5 fingers × 4 joints per finger).

### Finger and Joint IDs

[Service Calls](/en/docs/wujihandros2/ros2-interface#service-calls) use `finger_id` and `joint_id`:

| Parameter | Values and Meanings |
| :- | :- |
| `finger_id` | <ul><li>0: Thumb</li><li>1: Index</li><li>2: Middle</li><li>3: Ring</li><li>4: Pinky</li><li>255: All fingers</li></ul> |
| `joint_id` | <ul><li>0-3: Individual joints (0 → 3: proximal → distal)</li><li>255: All joints</li></ul> |

### Joint Name Format

[Topic Control](/en/docs/wujihandros2/ros2-interface#topic-control) uses full joint names: `{handedness}_finger{1-5}_joint{1-4}`

| Index | Joint Name (handedness=right) | Finger |
| :- | :- | :- |
| 0-3 | right\_finger1\_joint1\~4 | Thumb |
| 4-7 | right\_finger2\_joint1\~4 | Index |
| 8-11 | right\_finger3\_joint1\~4 | Middle |
| 12-15 | right\_finger4\_joint1\~4 | Ring |
| 16-19 | right\_finger5\_joint1\~4 | Pinky |

### Index Calculation

```text theme={null}
index = finger_id * 4 + joint_id
```

For example: The index finger (finger\_id=1) third joint (joint\_id=2) has index `1 * 4 + 2 = 6`.


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