> ## 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>
  本页按症状给出排查步骤。设备的停机行为、急停与清故障流程，以及维护与存放要求见[维护](/docs/wuji-hand/latest/maintenance)。SDK 安装、连接与订阅类问题见 [Wuji SDK 故障排查](/docs/wuji-sdk/troubleshooting/)。
</Info>

## 无法发现设备

1. 检查手背状态灯是否点亮。无任何灯效时，先检查供电与 XT30 电源接口
2. 检查网线两端是否插紧
3. 确认电脑网卡已设置为同网段静态 IP（默认网段 `192.168.1.x`，见[快速开始](/docs/wuji-hand/latest/quick-start#步骤四：配置电脑网卡)）
4. `ping` 设备 IP：左手 `192.168.1.110`，右手 `192.168.1.111`

电脑有多张网卡时，先把 Wuji SDK 升级到最新版本，再禁用其他网卡重试。仍未恢复时，导出日志并联系技术支持（见下文[导出日志并联系技术支持](#导出日志并联系技术支持)）。

## 无法连接或 IP 冲突

同网段接入两台同手性设备时，默认 IP 相同会冲突：

1. 先只接入一台设备
2. 按 [SDK 接口](/docs/wuji-hand/latest/sdk-reference/device-operations#ip（set/get）)修改其中一台的 IP
3. 再将两台设备同时组网，连接时用序列号（`sn`）区分

多只同手性设备在网时，`connect(handedness=...)` 会抛 `AmbiguousHandedness`，改用 `sn` 指定设备。

IP 无冲突仍连不上时，检查本机 50001 端口是否被其他程序占用，并把 Wuji SDK 升级到最新版本。

## 状态灯显示告警或故障

状态灯等级含义见[产品介绍](/docs/wuji-hand/latest/product-introduction#手背状态灯)，按灯效分级处理：

* **黄色慢闪（告警）**：订阅 `joint_diagnostics` 检查活跃错误码并用 `WujiHand2.describe_error(code)` 解码。告警类多为预警，排除原因（散热、接线、负载）后可继续使用
* **红色慢闪（故障）**：按上文[清故障与安全复位流程](/docs/wuji-hand/latest/maintenance#清故障与安全复位流程)处理——解码错误码、排除原因、清除故障后重新使能。反复出现时联系技术支持
* **红色常亮（致命）**：断电重启。复现则停止使用并联系技术支持，按提示返修

## 使能后通信中断，设备停止运动

1. 检查网线两端与网络设备，确认与上位机的链路恢复
2. 订阅 `joint_diagnostics` 读取活跃错误码，用 `WujiHand2.describe_error(code)` 解码后按提示排除原因
3. 重新调用 `enable()` 使能，确认状态灯转为白色常亮

通信恢复后设备不会自动恢复运动，停机与恢复的完整口径见上文[通信中断行为](/docs/wuji-hand/latest/maintenance#通信中断行为)。反复中断时，按下文[导出日志并联系技术支持](#导出日志并联系技术支持)处理。

## 关节离线（在线关节数少于 20）

1. `hand.online_joints_count().get()` 确认在线关节数
2. 订阅 `joint_diagnostics` 流，用 `nid` 定位离线关节
3. 下电后检查该手指排线与接插件是否松动
4. 重新插接后上电自检

单指故障不影响其余关节继续使用，设备会持续告警。重新插接后仍未恢复的多为硬件问题，这类故障按整指更换处理，可维护范围见下文[用户可维护边界](/docs/wuji-hand/latest/maintenance#用户可维护边界)。备件与更换步骤暂不提供，联系技术支持获取。

## 使能失败

1. 订阅 `joint_diagnostics` 流检查活跃错误码，用 `WujiHand2.describe_error(code)` 解码
2. 按返回的 `clear_policy` 处理：
   * `AutoClear` 类：排除原因后等待自动消除
   * `ManualClear` 类：排除原因后执行 `clear_fault()`，再重新使能
   * `NonClearable` 类：断电重启，复现则停止使用并联系技术支持
3. 重新 `enable()`，确认状态灯转为白色常亮

## 出现过温或过流故障

* **过温**：等待设备冷却后自动恢复。改善散热条件，降低负载或占空比
* **过流**：检查负载与接线，清除故障后重试。反复出现时检查电机与负载状态，仍复现则联系技术支持

## 编码器相关告警

1. 订阅 `joint_diagnostics` 确认告警来源关节与错误码
2. 下电检查该关节区域接线与信号质量，确认关节区域远离磁性物体
3. 清除故障后重新使能验证
4. 反复出现属硬件问题，联系技术支持

## 固件升级失败

1. 按升级工具的报错提示处理（固件 v2.1.0 起提供详细报错，更低版本仅有概要提示）
2. 升级过程中断电可能损坏固件数据，清除故障后重新升级
3. 持续失败时联系技术支持

升级流程见 [Wuji CLI 固件升级](/docs/wuji-cli/firmware-upgrade/)。

## 导出日志并联系技术支持

```python theme={null}
result = hand.export_flash_logs()
print(result["path"])      # 导出 JSONL 文件的绝对路径
print(result["frames"])    # 导出的日志记录数
```

日志默认导出到 `~/.wuji/logs`，用法详见 [SDK 接口](/docs/wuji-hand/latest/sdk-reference/diagnostics#flash-日志导出（诊断）)。设备本地保留至少 1 周的完整日志，超出这个窗口的故障需要复现后再导出。

联系 [support@wuji.tech](mailto:support@wuji.tech) 时请附上：

* 日志包
* 错误码与状态灯灯效
* 固件与 SDK 版本
* 复现步骤


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