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

# 快速开始

需要接入 ROS 2 应用时，完成设备安全准备与物理连接后，转到 [ROS 2 集成](https://docs.wuji.tech/docs/zh/wuji-glove/latest/ros2-integration.md)。直接使用 SDK 运行设备，继续本页流程。ROS 2 的运行环境和安装步骤见集成页。

> [!NOTE]
>
> 本页按手头设备的情况分三节：仿真验证不需要实机，实机运行覆盖从开箱到固件升级的完整路径，跨产品遥操作接入 Wuji Hand 2。每节独立成立，条件不满足就跳到下一节。

## 开始前

| 手头有什么 | 从哪节开始 | 大约耗时 |
| - | - | - |
| 暂无设备 | [仿真验证](#仿真验证) | 10 分钟 |
| 一只 Wuji Glove | [实机运行](#实机运行) | 30 分钟 |
| Wuji Glove 加 Wuji Hand 2 | 先完成实机运行，再做[跨产品遥操作](#跨产品遥操作) | 45 分钟 |

支持 Linux 和搭载 Apple 芯片的 Mac，详见 [SDK 系统要求](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/quick-start.md#系统要求)。示例使用 Python 3.10 及以上版本。

## 仿真验证

本节需要 Git、Rust/Cargo 和 `urdf-viz`，不需要设备。

Wuji Glove 提供 21 自由度手部骨骼模型，用于验证坐标、关节与数据映射：

运行 `cargo install` 前需安装 Rust/Cargo，详见 [urdf-viz 安装说明](https://github.com/openrr/urdf-viz#install)。

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

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

窗口打开后确认骨骼完整、没有缺失网格，关节数为 21。

左手模型与 EMF 模块 STL 见[模型资产与加载](https://docs.wuji.tech/docs/zh/wuji-glove/latest/model-integration.md)。发射器顶盖 STEP 与三个安装附件见[机械集成](https://docs.wuji.tech/docs/zh/wuji-glove/latest/hardware-integration.md)。

**完成标准**：骨骼模型正常显示，21 个旋转关节齐全。

模型加载成功说明资产与可视化链路可用。触觉、EMF 与 IMU 数据需要接入设备后获取，继续读下一节。

## 实机运行

本节需要一只 Wuji Glove、采集主板与随附线缆，以及一台符合 SDK 系统要求的电脑。

### 步骤一：开箱检查

对照[内容物清单](https://docs.wuji.tech/docs/zh/wuji-glove/latest/introduction.md#内容物清单)核对包装内的全部物件：USB-C to USB-C 线束、USB-C 转网口供电适配器、USB-A to USB-C 线束与网线。

### 步骤二：安装软件

```bash theme={null}
pip install wuji-sdk
curl -fsSL https://get.wuji.tech/cli | bash
```

Wuji SDK 用于在代码中读取手套数据，Wuji CLI 用于在终端扫描设备、执行标定与健康检查。安装与环境要求见 [Wuji SDK 快速开始](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/quick-start.md)与 [Wuji CLI 安装](https://docs.wuji.tech/docs/zh/wuji-cli/latest/getting-started.md#安装)。

### 步骤三：连接采集主板

使用 USB-C to USB-C 线束连接采集主板与 USB-C 转网口供电适配器。

> [!WARNING]
>
> USB-C to USB-C 线束注意**正反面一致性**。线缆两端的同一面上有**白色矩形标识（下图以蓝块指示）**，便于快速区分正反。如果线缆正面朝上插入采集主板，就需要正面朝上插入 USB-C 转网口供电适配器，否则将只供电而没有数据传输。

![连接正反面对比](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/wuji-glove-step1-connect.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=63cbc9dcb98f5a32a4d99eb30f1e4d6f)

### 步骤四：接入网线和电源

借助 USB-C 转网口供电适配器接入网线与供电线，供电线建议使用 USB-A to USB-C 线缆。接通后确认采集主板指示灯状态正常。

![连接步骤二](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/wuji-glove-step2.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=17667bdd8ade2664c3f74c665d618a24)

### 步骤五：配置电脑网络

确保电脑与手套在同一网段（默认网段为 192.168.1.x），IP 地址前三段必须一致，并将子网掩码配置为 255.255.255.0。左手手套默认 IP 为 192.168.1.100，右手为 192.168.1.101，电脑 IP 地址避免使用这两个地址以免冲突。

macOS 13 及以上版本进入**系统设置 › 网络 › 以太网 › 详细信息 › TCP/IP**，macOS 11–12 进入**系统偏好设置 › 网络 › 以太网 › 高级 › TCP/IP**。将 IPv4 配置设为**手动**，填入同网段 IP 和上述子网掩码。网络权限见[设备发现与连接](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/device-connection.md)。

Ubuntu 上可选择以下任一方式：

| 方式 | 适用场景 | 重启后 |
| - | - | - |
| [图形界面](#方式一：图形界面) | Ubuntu 桌面环境 | 保持 |
| [命令行](#方式二：命令行) | 无桌面环境或远程终端 | 失效 |

> [!NOTE]
>
> 以下以连接右手手套为例，请根据目标手套调整 IP 地址。

#### 方式一：图形界面

1. 打开 **Settings**，进入 **Network**
2. 在 **Wired** 一栏点击齿轮图标
3. 切换到 **IPv4** 标签，**IPv4 Method** 选择 **Manual**
4. 在 **Addresses** 填入 Address `192.168.1.50`，Netmask `255.255.255.0`
5. 点击 **Apply**
6. 在终端执行 `ping 192.168.1.101` 验证连通性

<video controls width="100%">
  <source src="https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/network-config-gui.mp4?fit=max&auto=format&n=3uhnC3cY-ox8e3b-&q=85&s=421220790a35c87d434ef876c96ebd30" type="video/mp4" />
</video>

#### 方式二：命令行

命令中的网口名称需替换为实际网口名称。此方式配置的地址在系统重启后失效。

**1. 确认网口名称**

```bash theme={null}
ip link show
```

找到以太网口名称，例如 `eth0`、`enp3s0` 或 `eno1`。

**2. 确认网线已连通**

```bash theme={null}
ethtool eth0 | grep "Link detected"
```

应显示 `Link detected: yes`。

**3. 清除旧 IP**

```bash theme={null}
sudo ip addr flush dev eth0
```

> [!WARNING]
>
> 此命令会清除该网口上所有现有 IP 地址。如果该网口正用于其他网络连接，执行后会断开。

**4. 设置静态 IP 与子网掩码**

```bash theme={null}
sudo ip addr add 192.168.1.50/24 dev eth0
```

> [!NOTE]
>
> `/24` 即子网掩码 `255.255.255.0`。

**5. 启用网口**

```bash theme={null}
sudo ip link set eth0 up
```

**6. 验证 IP 与子网掩码**

```bash theme={null}
ip addr show eth0
```

确认输出包含 `inet 192.168.1.50/24`。

**7. 测试连通性**

```bash theme={null}
# 右手手套示例
ping 192.168.1.101
```

若连接左手手套，请改为 `ping 192.168.1.100`。收到响应表示连接成功。

### 步骤六：穿戴 Wuji Glove

穿戴 Wuji Glove，并通过手臂绑带调整采集主板的位置。

> [!WARNING]
>
> 穿戴或脱下手套时，在掌心处施力，请勿拉扯手腕处。

![穿戴示意](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/caution1.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=4e8f001d2366a9acb81c6b8c78e9004a)

> [!WARNING]
>
> 脱下手套时，推荐在指腹的布料上施力，请勿拉扯 EMF 模块及整个手背。

![脱下手套注意事项](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/caution2.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=c755e652b987786ad8b810a23e398701)

> [!NOTE]
>
> **重要提示：穿戴后，连接软件前，请确保：**
>
> * 保持手指微弯，自然放松状态
> * 不要交叉指尖 EMF 模块，不要握拳

![穿戴注意事项](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/notice.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=4e80a8fa6ab34d84486c90e4e3e2caae)

> [!WARNING]
>
> **安全须知：**
>
> * 避免在潮湿环境使用
> * 不要过度弯折传感器区域
> * 存放于干燥阴凉处

### 步骤七：安装 Tracker（可选）

如需外接 Tracker 进行空间追踪，揭开手背 EMF 发射模块表面的软片，将 Tracker 固定到下方安装座。

![安装 Tracker](https://mintcdn.com/wuji-0bbde051/3uhnC3cY-ox8e3b-/shared/assets/source/images/zh/wuji-glove/tracker-mount.png?fit=max\&auto=format\&n=3uhnC3cY-ox8e3b-\&q=85\&s=35f6f1664ffd184f12b107b2b55e2047)

不同型号的 Tracker 需要不同的转接件。转接件 STEP 与装配说明见[安装附件 STEP](https://docs.wuji.tech/docs/zh/wuji-glove/latest/hardware-integration.md#attachment-step)。

### 步骤八：确认设备在线

```bash theme={null}
wuji devices
wuji ping
wuji doctor
```

`wuji devices` 列出同网段内的设备，`wuji ping` 返回设备类型、序列号、固件版本与 IP，`wuji doctor` 执行健康检查，可定位 EMF 断线与触觉坏点、坏行、坏列。

列表为空时，先检查设备是否上电，以及主机是否与手套处于同一网段。

### 步骤九：连接设备并检查状态

```python theme={null}
from wuji_sdk import SdkManager

manager = SdkManager.instance()
glove = manager.auto_connect(device_name="glove")

print(glove.sn().get())         # 序列号
print(glove.version().get())    # 固件版本
print(glove.hand_side().get())  # 手别
```

网段内有多台设备时改用 `manager.connect(sn="<序列号>")`。按地址、按手性等其他连接方式见 [Wuji SDK 的设备连接](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/device-connection.md)。

同一时刻只有一个客户端占用手套连接。`wuji viz` 或另一个 SDK 脚本正在连接同一只手套时，本次连接无法建立，先退出正在运行的一方再重试，见[释放被占用的设备连接](https://docs.wuji.tech/docs/zh/wuji-glove/latest/maintenance.md#释放被占用的设备连接)。

采集主板指示灯同步反映连接状态：主机已连接但未拉取数据时为黄色极慢闪，数据流传输中为青色心跳。红色快闪表示以太网断连，红色常亮表示传感器硬件故障，处理方式见[连接状态与指示灯](https://docs.wuji.tech/docs/zh/wuji-glove/latest/maintenance.md#连接状态与指示灯)。

### 步骤十：完成标定

手部模型标定按用户隔离，默认用户（Default）无法执行。先创建并切换到命名 Profile，再执行标定：

```bash theme={null}
wuji user create operator --switch
wuji calib hand-model
```

标定前保持手指微弯自然放松，不要交叉指尖模块或握拳。标定产物保存到当前用户 Profile 并立即生效，产出当前用户对应的左右手模型。

标定影响关节角、骨骼与指尖位姿的精度。需要接触检测时，再执行[触觉标定](https://docs.wuji.tech/docs/zh/wuji-cli/latest/tactile-calibration.md)。完整参数与错误处理见 [Wuji CLI 手部模型标定](https://docs.wuji.tech/docs/zh/wuji-cli/latest/hand-model-calibration.md)。

### 步骤十一：获取首帧数据

```bash theme={null}
wuji sub tactile --count 1
wuji sub emf_poses --count 1
wuji sub imu_data/palm --count 1
```

`--count 1` 表示收满一帧后自动退出。在应用中读取时，用 Wuji SDK 连接手套并订阅 `tactile`、`emf_poses` 或 `hand_skeleton`。

触觉数值全为 0 或 -1、EMF 置信度偏低或 IMU 持续漂移时，见[故障排查](https://docs.wuji.tech/docs/zh/wuji-glove/latest/troubleshooting.md)。

各数据流的含义、结构、坐标系与时间戳见 [SDK 数据参考](https://docs.wuji.tech/docs/zh/wuji-glove/latest/sdk-data-reference/index.md)。

想直观确认数据，运行 `wuji viz` 在浏览器中查看手骨架、EMF 接收器、触觉点云与原始触觉矩阵。命令用法见 [Wuji CLI 实时可视化](https://docs.wuji.tech/docs/zh/wuji-cli/latest/visualization.md)。

### 步骤十二：停止与脱卸

读取结束后断开连接，把手套释放给其他客户端：

```python theme={null}
manager.disconnect_all()
```

脱下手套时在指腹的布料上施力，不要拉扯 EMF 模块及整个手背。取下后置于干燥阴凉处，避免传感器区域受折，完整要求见[存放与环境要求](https://docs.wuji.tech/docs/zh/wuji-glove/latest/maintenance.md#存放与环境要求)。

### 步骤十三：升级固件

获取首帧数据后，建议把固件升级到最新版本：

```bash theme={null}
wuji upgrade --check
wuji upgrade --type wuji_glove
```

`--check` 为只读，列出哪些设备有固件更新。`--type wuji_glove` 把范围内的全部手套升级到各自最新版本，刷写完成后设备自动重启进入新固件。完整范围与动作参数见 [Wuji CLI 固件升级](https://docs.wuji.tech/docs/zh/wuji-cli/latest/firmware-upgrade.md)。

标定接口对固件与 SDK 版本有下限要求，版本对应关系见[发布记录](https://docs.wuji.tech/docs/zh/release-notes.md)的配套版本表。

**完成标准**：设备在线、健康检查通过、手部模型标定完成，至少获取一帧带时间戳与手性信息的有效数据，固件为最新版本。

## 跨产品遥操作

本节需要一只已完成实机运行的 Wuji Glove，以及一台已完成[快速开始](https://docs.wuji.tech/docs/zh/wuji-hand/latest/quick-start.md)、20 个关节在线的 Wuji Hand 2。两台设备接在同一网段，手性一致。

戴上手套后，手套持续输出手部关键点，重定向算法将其转换为 20 维关节角度发送给灵巧手，灵巧手实时跟随手指动作。

### 确认两台设备都在线

```bash theme={null}
wuji devices
wuji ping
```

列表中应同时出现 `wuji_hand_2` 与 `wuji_glove`，核对序列号、固件版本与手性。网段内有其他同类设备时记下目标序列号，下一步要用。

### 运行遥操作示例

重定向与遥操作的完整实现在 Wuji SDK 仓的示例中，随接口一起更新：

```bash theme={null}
git clone https://github.com/wuji-technology/wuji-sdk.git
cd wuji-sdk/examples/python/retargeting
pip install wuji-sdk numpy

python 1.teleop_real.py
```

示例启动后先列出 SDK 用户供选择，首次运行按 Enter 保持默认用户。用户选择对手部模型的影响见[选择 teleop 的 SDK 用户](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/retargeting.md#选择-teleop-的-sdk-用户)。

示例默认按右手装配运行。左手装配时修改脚本顶部的 `SIDE` 常量。

示例默认扫描并连接扫描到的设备。网段内有多台灵巧手时，先确认连接的是目标设备，避免驱动他人正在使用的设备。

### 完成跨产品动作

1. 清空灵巧手的工作空间，确认无人接触
2. 戴好手套，手指微弯自然放松
3. 运行示例，从低速、小幅度的动作开始
4. 观察动作是否连续、方向是否正确、是否触发错误码
5. 按 Ctrl+C 停止，示例退出时自动失能并断开连接

出现姿态异常、通信中断或错误码时立即停止，按[故障排查](https://docs.wuji.tech/docs/zh/wuji-glove/latest/troubleshooting.md)处理。

重定向接口的参数、输入格式与坐标约定见 [Wuji SDK 的手部重定向](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/retargeting.md)。手部追踪数据的坐标系与时间戳对齐方式见 [SDK 数据参考](https://docs.wuji.tech/docs/zh/wuji-glove/latest/sdk-data-reference/index.md)。

**完成标准**：手套数据持续更新，灵巧手完成与手指动作一致的受控跟随。


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