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

# 启动与配置

## 启动命令

| 命令 | 说明 |
| :- | :- |
| `ros2 launch wujihand_bringup wujihand.launch.py` | 仅启动驱动 |
| `ros2 launch wujihand_bringup wujihand.launch.py rviz:=true` | 启动驱动并通过 RViz 可视化 |
| `ros2 launch wujihand_bringup wujihand_dual.launch.py` | 一键启动并自动连接左右两只手 |

## 可配置参数

<Info>
  左右手类型从硬件自动检测，无需手动指定。
</Info>

| 参数 | 默认值 | 说明 |
| :- | :- | :- |
| `hand_name` | `hand_0` | 命名空间，用于区分多手。 <br /> 示例：`ros2 launch wujihand_bringup wujihand.launch.py hand_name:=my_hand` |
| `serial_number` | `""` | 设备序列号（空则自动检测） |
| `hand_side` | `""` | 无序列号时按左右手连接：`""`（唯一设备）、`left`、`right` |
| `name_by_handedness` | `false` | 开启后话题与服务根命名空间使用硬件检测到的左右手（`/hand_left/`、`/hand_right/`），覆盖 `hand_name`。双手启动会自动开启 |
| `publish_rate` | `1000.0` | 关节状态发布频率 (Hz) |
| `filter_cutoff_freq` | `10.0` | 低通滤波截止频率 (Hz) |
| `diagnostics_rate` | `10.0` | 诊断信息发布频率 (Hz) |
| `rviz` | `false` | 是否启动 RViz 可视化 |

## 多手配置

当需要同时控制多只灵巧手时，可通过序列号和命名空间区分。

### 查询已连接设备的序列号

列出当前 USB 上所有 WujiHand 设备的序列号，填入下方启动命令的 `serial_number`：

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

如果打开新终端，需要重新加载 ROS2 环境

```bash theme={null}
# 加载 ROS2 环境，替换 <distro> 为实际安装的 ROS2 发行版
source /opt/ros/<distro>/setup.bash
# 如使用源码编译，请叠加工作空间（Deb 包安装可跳过）
# 将 <workspace> 替换为实际工作空间路径，如 ~/wujihandros2
source <workspace>/install/setup.bash
```

```bash theme={null}
# 终端 1：启动左手
ros2 launch wujihand_bringup wujihand.launch.py \
    hand_name:=left_hand serial_number:=ABC123

# 终端 2：启动右手
ros2 launch wujihand_bringup wujihand.launch.py \
    hand_name:=right_hand serial_number:=DEF456
```

### 一键启动双手

一条命令自动发现并连接所有已插入的手，无需手动指定序列号。每只手按硬件检测到的左右手，话题发布在 `/hand_left/*` 与 `/hand_right/*`：

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

可选可视化：

```bash theme={null}
# 每只手一个 RViz 窗口
ros2 launch wujihand_bringup wujihand_dual.launch.py rviz:=true

# 单个 Foxglove Bridge
ros2 launch wujihand_bringup wujihand_dual.launch.py foxglove:=true
```

### 运行多手演示

多手环境下运行演示脚本时，通过 `--ros-args -p hand_name:=<hand-name>` 指定目标手：

```bash theme={null}
# 对左手运行波浪演示
ros2 run wujihand_bringup wave_demo.py --ros-args -p hand_name:=left_hand

# 对右手运行波浪演示
ros2 run wujihand_bringup wave_demo.py --ros-args -p hand_name:=right_hand
```

<Info>
  `hand_name` 需与启动驱动时指定的名称一致。
</Info>

### 话题命名空间

启动后，每只手会拥有独立的话题命名空间：

```text theme={null}
# 左手话题
/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/joint_states
/right_hand/joint_commands
/right_hand/hand_diagnostics
/right_hand/robot_description
/right_hand/tf
/right_hand/tf_static
```

## 关节标识

灵巧手共有 20 个关节（5 根手指 × 4 个关节/手指）。

### 手指与关节编号

[服务调用](/docs/wujihandros2/ros2-interface#服务调用)使用 `finger_id` 和 `joint_id`：

| 参数 | 值与含义 |
| :- | :- |
| `finger_id` | <ul><li>0：拇指</li><li>1：食指</li><li>2：中指</li><li>3：无名指</li><li>4：小指</li><li>255：所有手指</li></ul> |
| `joint_id` | <ul><li>0-3：各关节（0 → 3：近端 → 远端）</li><li>255：所有关节</li></ul> |

### 关节名格式

[话题控制](/docs/wujihandros2/ros2-interface#话题控制)使用完整关节名：`{handedness}_finger{1-5}_joint{1-4}`

| 索引 | 关节名 (handedness=right) | 手指 |
| :- | :- | :- |
| 0-3 | right\_finger1\_joint1\~4 | 拇指 |
| 4-7 | right\_finger2\_joint1\~4 | 食指 |
| 8-11 | right\_finger3\_joint1\~4 | 中指 |
| 12-15 | right\_finger4\_joint1\~4 | 无名指 |
| 16-19 | right\_finger5\_joint1\~4 | 小指 |

### 索引计算

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

例如：食指（finger\_id=1）第三个关节（joint\_id=2）的索引为 `1 * 4 + 2 = 6`。


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