故障、恢复与维护
本页覆盖 Wuji Hand 2 的三部分内容：一是故障等级、停机行为、急停与清故障复位流程，二是故障排查的处理步骤，三是用户可维护边界、日常检查与存放运输要求。SDK 安装、连接与订阅类问题另见 Wuji SDK 故障排查。Beta 2 阶段部分维护数据暂不提供，将在后续更新。
安全停止与异常恢复
故障等级决定停机方式，通信中断、急停与清故障复位各有固定流程，危险区域、与机械臂联合运行的责任边界也有明确划分。
故障等级与停机行为
设备错误码经 WujiHand2.describe_error(code) 解码后携带故障等级（severity）与清除策略（clear_policy）。故障等级对应的停机行为：
| 等级 | 停机行为 | 典型触发 |
|---|---|---|
Warning | 不停机，可继续运行 | 温度接近上限、编码器误码率升高、堵转等预警类异常 |
DeferredStop | 当前动作完成后停机 | 通信超时、过温等需有序停止的异常 |
ImmediateStop | 立即停机 | 欠压过压、过流、驱动故障、编码器失效等 |
Fatal | 停机且不可清除 | 反复过流、硬件损伤、上电自检失败等 |
清除策略分三类：AutoClear（排除原因后自动消除）、ManualClear（需执行清故障）、NonClearable（需断电重启，复现则停止使用）。
通信中断行为
使能状态下与上位机通信中断时，设备停止电机并上报故障。恢复通信后设备不会自动恢复运动，需重新调用 enable() 使能（固件 v2.1.0 起）。
急停
- 软件急停：
hand.emergency_stop()，整手立即停止，不接受掩码 - 硬件急停接口：当前版本不提供
与机械臂联合使用时，建议评估将灵巧手供电接入机械臂急停回路。具体接线方案暂不提供，将在后续更新。
故障后的力矩状态
Warning 告警不触发停机，设备继续运行。DeferredStop、ImmediateStop 与 Fatal 故障触发停机后，关节进入自由态。各等级的含义见上文故障等级与停机行为。持握物体的应用场景请评估跌落风险。
清故障与安全复位流程
- 订阅
joint_diagnostics读取活跃错误码，并调用info = describe_error(code)解码 - 若
code为0，表示当前无活跃故障，继续监测即可 - 若
info为None，保留原始错误码并联系技术支持确认处理方式。不要继续执行后续清故障步骤 - 否则从
info读取cause与resolution，按提示排除原因并继续处理 - 清除故障：
AutoClear类等待自动消除，ManualClear类执行clear_fault()（可带 20 位掩码指定关节） - 重新使能：
enable()，确认状态灯转为白色常亮 NonClearable（Fatal）类：断电重启。复现则停止使用并联系技术支持
危险区域
- 夹点：指间与关节缝隙。运行时须始终佩戴软体与皮肤层，运动中严禁靠近
- 高温区：掌部电机区域，高负载后勿直接触摸
- 线缆区：手指表面排线与腕部出线，避免刮擦、拉扯
与机械臂联合运行的安全责任边界
- 灵巧手不感知机械臂的运动规划。臂侧碰撞检测、速度限制与工作空间隔离由集成方负责
- 手侧提供自身的超力矩、超温与断通信保护，并记录冲击检测事件
完整的责任划分细则暂不提供，将在后续更新。
故障排查
设备发现、连接、状态灯、关节与温度故障、固件升级各有对应的检查顺序与处理动作，仍未恢复时导出日志联系技术支持。
无法发现设备
- 检查手背状态灯是否点亮。无任何灯效时，先检查供电与 XT30 电源接口
- 检查网线两端是否插紧
- 确认电脑网卡已设置为同网段静态 IP（默认网段
192.168.1.x，见快速开始） ping设备 IP：左手192.168.1.110，右手192.168.1.111
电脑有多张网卡时，先把 Wuji SDK 升级到最新版本，再禁用其他网卡重试。仍未恢复时，导出日志并联系技术支持（见下文导出日志并联系技术支持）。
无法连接或 IP 冲突
同网段接入两台同手性设备时，默认 IP 相同会冲突：
- 先只接入一台设备
- 按 SDK 接口修改其中一台的 IP
- 再将两台设备同时组网，连接时用序列号（
sn）区分
多只同手性设备在网时，connect(handedness=...) 会抛 AmbiguousHandedness，改用 sn 指定设备。
IP 无冲突仍连不上时，检查本机 50001 端口是否被其他程序占用，并把 Wuji SDK 升级到最新版本。
状态灯显示告警或故障
状态灯等级含义见产品介绍，按灯效分级处理：
- 黄色慢闪（告警）：订阅
joint_diagnostics检查活跃错误码并用WujiHand2.describe_error(code)解码。告警类多为预警，排除原因（散热、接线、负载）后可继续使用 - 红色慢闪（故障）：按上文清故障与安全复位流程处理——解码错误码、排除原因、清除故障后重新使能。反复出现时联系技术支持
- 红色常亮（致命）：断电重启。复现则停止使用并联系技术支持，按提示返修
使能后通信中断，设备停止运动
- 检查网线两端与网络设备，确认与上位机的链路恢复
- 订阅
joint_diagnostics读取活跃错误码，用WujiHand2.describe_error(code)解码后按提示排除原因 - 重新调用
enable()使能，确认状态灯转为白色常亮
通信恢复后设备不会自动恢复运动，停机与恢复的完整口径见上文通信中断行为。反复中断时，按下文导出日志并联系技术支持处理。
关节离线（在线关节数少于 20）
hand.online_joints_count().get()确认在线关节数- 订阅
joint_diagnostics流，用nid定位离线关节 - 下电后检查该手指排线与接插件是否松动
- 重新插接后上电自检
单指故障不影响其余关节继续使用，设备会持续告警。重新插接后仍未恢复的多为硬件问题，这类故障按整指更换处理，可维护范围见下文用户可维护边界。备件与更换步骤暂不提供，联系技术支持获取。
使能失败
- 订阅
joint_diagnostics流检查活跃错误码，用WujiHand2.describe_error(code)解码 - 按返回的
clear_policy处理：AutoClear类：排除原因后等待自动消除ManualClear类：排除原因后执行clear_fault()，再重新使能NonClearable类：断电重启，复现则停止使用并联系技术支持
- 重新
enable()，确认状态灯转为白色常亮
出现过温或过流故障
- 过温：等待设备冷却后自动恢复。改善散热条件，降低负载或占空比
- 过流：检查负载与接线，清除故障后重试。反复出现时检查电机与负载状态，仍复现则联系技术支持
编码器相关告警
- 订阅
joint_diagnostics确认告警来源关节与错误码 - 下电检查该关节区域接线与信号质量，确认关节区域远离磁性物体
- 清除故障后重新使能验证
- 反复出现属硬件问题，联系技术支持
固件升级失败
- 按升级工具的报错提示处理（固件 v2.1.0 起提供详细报错，更低版本仅有概要提示）
- 升级过程中断电可能损坏固件数据，清除故障后重新升级
- 持续失败时联系技术支持
升级流程见 Wuji Studio 固件升级。
导出日志并联系技术支持
import asyncio
result = asyncio.run(hand.dump_hand_logs(bank="current"))
print(result["session_dir"]) # 日志会话目录，含 joint{0..19}.log 及 sboard.log日志默认导出到 ~/.wuji/hand_logs，用法详见 SDK 接口。设备本地保留至少 1 周的完整日志，超出这个窗口的故障需要复现后再导出。
联系 support@wuji.tech 时请附上：
- 日志包
- 错误码与状态灯灯效
- 固件与 SDK 版本
- 复现步骤
维护与耗材
皮肤、软体与整根手指可自行拆装更换，主板类部件禁止拆解。日常检查、存放运输与保修各有对应要求。
用户可维护边界
| 部件 | 用户可操作 | 说明 |
|---|---|---|
| 皮肤层 | 可自行拆装、更换 | 运行时须始终佩戴皮肤，不可脱离皮肤使用 |
| 指甲 | 可更换 | — |
| 软体 | 可更换 | 拆装步骤见硬件集成 |
| 整根手指 | 支持下电拆装更换 | 单指具备独立的机械与通信接口，可整指更换。更换步骤暂不提供 |
| 掌部主板 / 驱动板 | 禁止拆解 | 拆解影响保修，保修条款暂不提供 |
拆装皮肤与软体时设备须处于下电状态。手指表面排线脆弱，拆装过程避免刮擦、挤压（见用户须知）。
日常检查与维护周期
每日使用前检查：
- 外观无破损，皮肤佩戴完好
- 线缆无损伤、接口无松动
- 上电自检通过（状态灯进入白色呼吸）
存放与运输
- 存放：下电后在干燥环境中存放，手指平展放置在箱内
- 运输：使用原包装。原包装按高温高湿、跌落、堆码与振动条件设计
保修与技术支持
保修范围与返修流程暂不提供，将在后续更新。样机出现损坏请第一时间联系对接人或 support@wuji.tech。