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

# 快速开始

<Info>
  本页按手头设备的情况分三节：仿真验证不需要实机，实机运行覆盖从开箱到第一个动作的完整路径，跨产品遥操作接入 Wuji Glove。每节独立成立，条件不满足就跳到下一节。
</Info>

## 开始前

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

环境要求 Ubuntu 22.04 及以上、Python 3.10 及以上。使用实机前先阅读[用户须知](/docs/wuji-hand/latest/user-notice)。

## 仿真验证

本节需要 Git、Python 与 MuJoCo，不需要设备。

安装并加载右手模型：

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

python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right.xml
```

窗口打开后确认模型完整、没有缺失网格，关节数为 20。

左手模型、带安装座变体、URDF 预览、ROS 2 与 Isaac Sim 的加载方式，以及整机 STEP 与掌心安装接口图纸，见[坐标系与模型](/docs/wuji-hand/latest/hardware-integration#坐标系与模型)。

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

模型加载成功说明资产与可视化链路可用。固件、网络与真实设备控制需要接入设备后验证，继续读下一节。

## 实机运行

本节需要一台 Wuji Hand 2、随附电源与线缆，以及一台 Ubuntu 主机。

### 步骤一：开箱检查

对照[内容物清单](/docs/wuji-hand/latest/product-introduction#内容物清单)核对包装内的全部物件：电源适配器、AC 线材、RJ45 网线、XT30 延长线、转接座与转接法兰。

### 步骤二：安装软件

```bash theme={null}
pip install wuji-sdk
```

安装与环境要求详见 [Wuji SDK 快速开始](/docs/wuji-sdk/quick-start/)。

首次使用推荐同时安装 [Wuji CLI](/docs/wuji-cli/)，可在终端扫描和连接设备、读写参数、检查设备状态并升级固件。

### 步骤三：接线与上电

1. 用随附 RJ45 网线连接设备网口与电脑网口
2. 用随附 XT30 延长线连接设备与电源适配器：先连接设备端，再接通电源适配器
3. 上电后观察手背状态灯：蓝色呼吸（自检中）→ 白色呼吸（就绪）

接口位置见[产品介绍](/docs/wuji-hand/latest/product-introduction#通信与电源接口示意图)。上电超过 30 秒仍未进入白色呼吸时，见[故障排查](/docs/wuji-hand/latest/troubleshooting)。

### 步骤四：配置电脑网卡

设备使用静态 IP，不支持 DHCP。出厂默认地址：

| 项 | 左手 | 右手 |
| - | - | - |
| IP | 192.168.1.110 | 192.168.1.111 |
| 网关 | 192.168.1.1 | 192.168.1.1 |
| 子网掩码 | 255.255.255.0 | 255.255.255.0 |

将电脑网卡设置为同网段静态 IP（如 `192.168.1.50`），子网掩码 `255.255.255.0`。配置完成后验证连通：

```bash theme={null}
ping 192.168.1.110   # 左手，右手为 192.168.1.111
```

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

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

`wuji devices` 列出同网段内的设备，`wuji ping` 返回设备类型、序列号、固件版本与 IP。列表为空时，先检查供电、网线与网卡配置，再重新运行。

多台设备在同一网段时，用 `--sn` 指定目标，避免连错设备。

### 步骤六：连接设备

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

manager = SdkManager.instance()
hand = manager.auto_connect(device_name="wuji_hand_2")
```

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

### 步骤七：检查状态

确认 20 个关节全部在线，且无活跃错误码：

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

print(hand.online_joints_count().get())   # 预期 20

sub = hand.joint_diagnostics().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
for j in frame.joints:
    if j.error_code_current:
        print(j.nid, WujiHand2.describe_error(j.error_code_current))
sub.close()
```

在线关节少于 20，或存在活跃错误码时，先按[故障排查](/docs/wuji-hand/latest/troubleshooting)处理再继续。

### 步骤八：使能关节

```python theme={null}
import time

hand.enable()

# 等待所有在线关节进入 Enabled 状态
sub = hand.joint_diagnostics().subscribe()
deadline = time.monotonic() + 5.0
while time.monotonic() < deadline:
    frame = sub.recv()
    if frame is not None and frame.joints and all(
        j.status_word.ext_state == 2 for j in frame.joints
    ):
        break
else:
    sub.close()
    raise TimeoutError("关节使能超时")
sub.close()
```

<Warning>
  使能后关节带力矩。使能前确保手指工作空间无遮挡、无人接触。
</Warning>

### 步骤九：执行第一个安全动作

从当前姿态平滑回到零位。示例先读取全部关节的当前位置，再用 1.5 秒线性插值逐步减小目标位置，避免直接下发零位阶跃：

```python theme={null}
import time
from wuji_sdk import JointCommand

# 读取当前姿态。nid 按 5 个槽位为一组，关节占每组的前 4 个槽位
sub = hand.joint_states().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
start = [0.0] * 20
for j in frame.joints:
    bus, node_index = divmod(j.nid - 1, 5)
    if bus < 5 and node_index < 4:
        start[bus * 4 + node_index] = float(j.position)
sub.close()

# 使用最新 SDK 示例中的保守参数
hand.effort_limit().set(1.5)
hand.mit_params().set((3.0, 0.05))

pub = hand.joint_command().publish()
steps = 300   # 1.5 秒 × 200 Hz
for i in range(1, steps + 1):
    ratio = i / steps
    positions = [position * (1.0 - ratio) for position in start]
    pub.send([JointCommand(position, 0.0, 0.0) for position in positions])
    time.sleep(1.0 / 200)
pub.close()
```

预期行为：全部关节从当前姿态平缓回到零位，过程中没有突然回弹或撞击。

单位约定、[MIT 控制模式](/docs/wuji-hand/latest/control-guide#mit-控制模式)与[参数安全边界](/docs/wuji-hand/latest/control-guide#参数安全边界)见控制指南。

想直观确认动作效果，运行 `wuji viz` 在浏览器中查看。三维手部模型跟随关节状态运动。命令用法见 [Wuji CLI 实时可视化](/docs/wuji-cli/visualization/)。

### 步骤十：停止与下电

```python theme={null}
hand.disable()              # 失能全部关节，状态灯转为白色呼吸
manager.disconnect_all()    # 断开连接
```

下电顺序：确认设备静止 → 断开电源 → 拔下线缆。

紧急情况随时执行 `hand.emergency_stop()`，整手立即停止，不接受掩码。

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

跑通第一个动作后，建议把固件升级到最新版本。Wuji CLI 按设备硬件型号推送匹配的固件包，无需手动选包，命令行升级并输出结构化报告，见 [Wuji CLI 固件升级](/docs/wuji-cli/firmware-upgrade/)。

升级过程中请勿断电。固件与 SDK 的版本对应关系见[版本识别与兼容性](/docs/wuji-hand/latest/version-identification-and-compatibility#硬件与软件兼容矩阵)。

**完成标准**：20 个关节在线且无活跃错误码，完成一次平滑回零，固件为最新版本。

## 跨产品遥操作

本节需要一台已完成实机运行的 Wuji Hand 2，以及一台已完成标定并能输出数据的 [Wuji Glove](/docs/wuji-glove/)。两台设备接在同一网段，手性一致。

戴上手套后，手套持续输出手部关键点，重定向算法将其转换为 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-hand/latest/troubleshooting)处理。

重定向接口的参数、输入格式与坐标约定见 [Wuji SDK 的手部重定向](/docs/wuji-sdk/retargeting/)。

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


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