快速开始

本页覆盖从开箱到第一次运动的完整路径：开箱检查、安装软件、接线上电、配置网络、连接设备、检查状态、使能并执行第一个安全动作，收尾升级固件。全程约 30 分钟。环境要求 Ubuntu 22.04 及以上、Python 3.10 及以上。开始前请先阅读用户须知。

开箱检查

对照内容物清单核对包装内的全部物件：电源适配器、AC 线材、RJ45 网线、XT30 延长线、转接座与转接法兰。缺件先联系 support@wuji.tech 再继续。

安装软件

安装 Wuji SDK（Python）：

pip install wuji-sdk

安装与环境要求详见 Wuji SDK 快速开始。

首次使用推荐同时安装 Wuji CLI，可在终端扫描和连接设备、读写参数、检查设备状态并升级固件。也可以安装 Wuji Studio，不写代码即可扫描和连接设备、查看关节状态并升级固件。

接线与上电

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

接口位置见产品介绍。上电超过 30 秒仍未进入白色呼吸时，见故障排查。

配置电脑网卡

设备使用静态 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.100），子网掩码 255.255.255.0。配置完成后验证连通：

ping 192.168.1.110   # 左手，右手为 192.168.1.111

发现并连接设备

from wuji_sdk import SdkManager

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

更多连接方式（按序列号、按地址、多设备）见 SDK 接口。

检查状态与故障

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

from wuji_sdk import WujiHand2

print(hand.online_joints_count().get())   # 预期 20，少于 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()

存在活跃错误码时，先按故障排查处理，再继续后续步骤。

使能关节

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()

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

执行第一个安全动作

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

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()

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

停止、失能与下电

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

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

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

升级固件

跑通第一个动作后，建议把固件升级到最新版本。两个官方工具都按设备硬件型号推送匹配的固件包，无需手动选包：

Wuji Studio（推荐首次使用）：图形界面引导式升级，见 Wuji Studio 固件升级
Wuji CLI（适合脚本与批量场景）：命令行升级并输出结构化报告，见 Wuji CLI 固件升级

升级过程中请勿断电。固件与 SDK 的版本对应关系见版本识别与兼容性。