> ## 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.
# 快速开始
本页按手头设备的情况分三节：仿真验证不需要实机，实机运行覆盖从开箱到固件升级的完整路径，跨产品遥操作接入 Wuji Hand 2。每节独立成立，条件不满足就跳到下一节。
## 开始前
| 手头有什么 | 从哪节开始 | 大约耗时 |
| - | - | - |
| 暂无设备 | [仿真验证](#仿真验证) | 10 分钟 |
| 一只 Wuji Glove | [实机运行](#实机运行) | 30 分钟 |
| Wuji Glove 加 Wuji Hand 2 | 先完成实机运行，再做[跨产品遥操作](#跨产品遥操作) | 45 分钟 |
环境要求 Ubuntu 22.04 及以上、Python 3.10 及以上。
## 仿真验证
本节需要 Git、Python 与任意 URDF 查看器，不需要设备。
Wuji Glove 提供 21 自由度手部骨骼模型，用于验证坐标、关节与数据映射：
```bash theme={null}
git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description
pip install urdf-viz
urdf-viz glove/body/urdf/right.urdf
```
窗口打开后确认骨骼完整、没有缺失网格，关节数为 21。
左手模型、EMF 模块 STL、发射器顶盖 STEP 与三个安装附件的用途，见[坐标系与模型](/docs/wuji-glove/hardware-integration#坐标系与模型)。
**完成标准**：骨骼模型正常显示，21 个旋转关节齐全。
模型加载成功说明资产与可视化链路可用。触觉、EMF 与 IMU 数据需要接入设备后获取，继续读下一节。
## 实机运行
本节需要一只 Wuji Glove、采集主板与随附线缆，以及一台 Ubuntu 主机。
### 步骤一：开箱检查
对照[内容物清单](/docs/wuji-glove/introduction#内容物清单)核对包装内的全部物件：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 快速开始](/docs/wuji-sdk/quick-start/)与 [Wuji CLI 安装](/docs/wuji-cli/getting-started/#安装)。
### 步骤三：连接采集主板
使用 USB-C to USB-C 线束连接采集主板与 USB-C 转网口供电适配器。
USB-C to USB-C 线束注意**正反面一致性**。线缆两端的同一面上有**白色矩形标识（下图以蓝块指示）**，便于快速区分正反。如果线缆正面朝上插入采集主板，就需要正面朝上插入 USB-C 转网口供电适配器，否则将只供电而没有数据传输。
### 步骤四：接入网线和电源
借助 USB-C 转网口供电适配器接入网线与供电线，供电线建议使用 USB-A to USB-C 线缆。接通后确认采集主板指示灯状态正常。
### 步骤五：配置电脑网络
确保电脑与手套在同一网段（默认网段为 192.168.1.x），IP 地址前三段必须一致，并将子网掩码配置为 255.255.255.0。左手手套默认 IP 为 192.168.1.100，右手为 192.168.1.101，电脑 IP 地址避免使用这两个地址以免冲突。
配置方式有两种，任选一种：
| 方式 | 适用场景 | 重启后 |
| - | - | - |
| [图形界面](#方式一：图形界面) | Ubuntu 桌面环境 | 保持 |
| [命令行](#方式二：命令行) | 无桌面环境或远程终端 | 失效 |
以下以连接右手手套为例，请根据目标手套调整 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` 验证连通性
#### 方式二：命令行
命令中的网口名称需替换为实际网口名称。此方式配置的地址在系统重启后失效。
**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
```
此命令会清除该网口上所有现有 IP 地址。如果该网口正用于其他网络连接，执行后会断开。
**4. 设置静态 IP 与子网掩码**
```bash theme={null}
sudo ip addr add 192.168.1.50/24 dev eth0
```
`/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，并通过手臂绑带调整采集主板的位置。
穿戴或脱下手套时，在掌心处施力，请勿拉扯手腕处。
脱下手套时，推荐在指腹的布料上施力，请勿拉扯 EMF 模块及整个手背。
**重要提示：穿戴后，连接软件前，请确保：**
* 保持手指微弯，自然放松状态
* 不要交叉指尖 EMF 模块，不要握拳
**安全须知：**
* 避免在潮湿环境使用
* 不要过度弯折传感器区域
* 存放于干燥阴凉处
### 步骤七：安装 Tracker（可选）
如需外接 Tracker 进行空间追踪，揭开手背 EMF 发射模块表面的软片，将 Tracker 固定到下方安装座。
不同型号的 Tracker 需要不同的转接件。转接件 STEP 与装配说明见[安装附件 STEP](/docs/wuji-glove/hardware-integration#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 的设备连接](/docs/wuji-sdk/device-connection/)。
同一时刻只有一个客户端占用手套连接。`wuji viz` 或另一个 SDK 脚本正在连接同一只手套时，本次连接无法建立，先退出正在运行的一方再重试，见[释放被占用的设备连接](/docs/wuji-glove/maintenance#释放被占用的设备连接)。
采集主板指示灯同步反映连接状态：主机已连接但未拉取数据时为黄色极慢闪，数据流传输中为青色心跳。红色快闪表示以太网断连，红色常亮表示传感器硬件故障，处理方式见[连接状态与指示灯](/docs/wuji-glove/maintenance#连接状态与指示灯)。
### 步骤十：完成标定
手部模型标定按用户隔离，默认用户（Default）无法执行。先创建并切换到命名 Profile，再执行标定：
```bash theme={null}
wuji user create operator --switch
wuji calib hand-model
```
标定前保持手指微弯自然放松，不要交叉指尖模块或握拳。标定产物保存到当前用户 Profile 并立即生效，产出当前用户对应的左右手模型。
标定影响关节角、骨骼与指尖位姿的精度。需要接触检测时，再执行[触觉标定](/docs/wuji-cli/tactile-calibration/)。完整参数与错误处理见 [Wuji CLI 手部模型标定](/docs/wuji-cli/hand-model-calibration/)。
### 步骤十一：获取首帧数据
```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 持续漂移时，见[故障排查](/docs/wuji-glove/troubleshooting)。
各数据流的含义、结构、坐标系与时间戳见 [SDK 数据参考](/docs/wuji-glove/sdk-data-reference)。
想直观确认数据，运行 `wuji viz` 在浏览器中查看手骨架、EMF 接收器、触觉点云与原始触觉矩阵。命令用法见 [Wuji CLI 实时可视化](/docs/wuji-cli/visualization/)。
### 步骤十二：停止与脱卸
读取结束后断开连接，把手套释放给其他客户端：
```python theme={null}
manager.disconnect_all()
```
脱下手套时在指腹的布料上施力，不要拉扯 EMF 模块及整个手背。取下后置于干燥阴凉处，避免传感器区域受折，完整要求见[存放与环境要求](/docs/wuji-glove/maintenance#存放与环境要求)。
### 步骤十三：升级固件
获取首帧数据后，建议把固件升级到最新版本：
```bash theme={null}
wuji upgrade --check
wuji upgrade --type wuji_glove
```
`--check` 为只读，列出哪些设备有固件更新。`--type wuji_glove` 把范围内的全部手套升级到各自最新版本，刷写完成后设备自动重启进入新固件。完整范围与动作参数见 [Wuji CLI 固件升级](/docs/wuji-cli/firmware-upgrade/)。
标定接口对固件与 SDK 版本有下限要求，版本对应关系见[发布记录](/release-notes)的配套版本表。
**完成标准**：设备在线、健康检查通过、手部模型标定完成，至少获取一帧带时间戳与手性信息的有效数据，固件为最新版本。
## 跨产品遥操作
本节需要一只已完成实机运行的 Wuji Glove，以及一台已完成[快速开始](/docs/wuji-hand/latest/quick-start/)、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 用户](/docs/wuji-sdk/retargeting/#选择-teleop-的-sdk-用户)。
示例默认按右手装配运行。左手装配时修改脚本顶部的 `SIDE` 常量。
示例默认扫描并连接扫描到的设备。网段内有多台灵巧手时，先确认连接的是目标设备，避免驱动他人正在使用的设备。
### 完成跨产品动作
1. 清空灵巧手的工作空间，确认无人接触
2. 戴好手套，手指微弯自然放松
3. 运行示例，从低速、小幅度的动作开始
4. 观察动作是否连续、方向是否正确、是否触发错误码
5. 按 Ctrl+C 停止，示例退出时自动失能并断开连接
出现姿态异常、通信中断或错误码时立即停止，按[故障排查](/docs/wuji-glove/troubleshooting)处理。
重定向接口的参数、输入格式与坐标约定见 [Wuji SDK 的手部重定向](/docs/wuji-sdk/retargeting/)。手部追踪数据的坐标系与时间戳对齐方式见 [SDK 数据参考](/docs/wuji-glove/sdk-data-reference)。
**完成标准**：手套数据持续更新，灵巧手完成与手指动作一致的受控跟随。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
