> ## 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 或 Wuji Glove 后，SDK 自动记录设备上报的错误码出现与清除状态，附完整错误码、说明和处理建议。设备固件需支持故障码上报，未提供该能力时设备仍可正常连接。

## 查看故障记录

使用 SDK 默认日志配置时，故障信息保存在以下位置：

| 位置 | 内容 |
| - | - |
| 终端 | 同一故障、同一状态涉及的多个部件合并显示，附故障说明和处理建议 |
| `~/.wuji/logs/sdk_<日期>.log` | 按部件记录明细，并包含连接摘要和仍活跃的故障摘要 |
| `~/.wuji/logs/error_codes.log` | 按部件保存故障变化和设备提供的历史摘要，跨进程重启和设备断连追加写入 |

`error_codes.log` 不受普通 SDK 日志级别过滤，也不参与按日期清理。本次追加会使文件超过 50 MiB 时，SDK 先将其轮转为 `error_codes.log.1`，保留当前文件和 1 份备份。需要长期留存时，定期备份这两个文件。

设备以 1 Hz 上报该秒内曾活跃的故障。SDK 在故障出现、解除时记录明细，持续故障每收到 10 帧输出一次摘要，正常连续接收时约为 10 秒。该摘要写入终端和 `sdk_<日期>.log`，不重复写入 `error_codes.log`。

## 识别状态与完整码

| 日志内容 | 含义 |
| - | - |
| `state=active` | 接收到此前未记录为活跃的故障，包含该秒内出现后又解除的瞬时故障 |
| `state=cleared` | 后续状态确认故障已解除，瞬时故障的解除记录通常晚 1 帧 |
| `state=active_before_power_off` | Wuji Hand 2 保存的断电前活跃故障，不代表本次连接时仍活跃 |
| `state=history` | Wuji Glove 本次上电期间的故障汇总，需结合其中的 `active` 字段判断状态 |
| `still active` | 最近状态仍包含的故障摘要 |

同一秒内反复出现、解除的过程可能合并在一个状态周期中。日志适合定位故障，不应作为每次状态切换的完整时间线。若日志提示有遗漏，保存提示和上下文一并提供给技术支持。

完整码写作 `AA-BB-CCCC`。终端输出可带 `E-` 前缀。同一码值来自多个部件时，`BB` 用 `/` 连接这些部件的编号。

| 字段 | 含义 |
| - | - |
| `AA` | 两位十六进制产品代码。`01` 对应 Wuji Hand 2，`11` 对应 Wuji Glove。当前 SDK 查询这两类产品的故障码 |
| `BB` | 十进制部件编号，格式允许 `0–255`，日志至少显示两位，如 `06`。主机日志的 `component_id` 保存相同编号，终端同时显示部件名称。编号对应的实际部件以日志中的名称为准 |
| `CCCC` | 四位十六进制原始故障码，格式范围为 `0000–FFFF`。`0000` 表示无故障，非零码值按 `AA` 对应的产品码表查询。严重程度和清除方式以查询结果的 `severity`、`clear_policy` 为准 |

例如，`E-01-06-2102` 表示 Wuji Hand 2 的部件 `06` 上报原始码 `2102`，终端将该部件显示为 `index_mcp_flex (F1S1)`。`E-01-06/11-2102` 表示部件 `06` 和 `11` 上报同一码值。`E-11-32-0102` 表示 Wuji Glove 的部件 `32` 上报原始码 `0102`，终端将该部件显示为 `Index IMU`。

复制日志中的完整码，通过 [查询错误码](#查询错误码) 查询原因与处理建议。查询用 `AA` 选择产品码表，再用 `CCCC` 匹配条目。`BB` 用于定位部件，不改变查询结果。Python 与 C 均提供查询接口，无需连接设备。

## 查询错误码

按日志中的完整码查询故障名称、原因和处理建议，无需连接设备。完整码可以带 `E-` 前缀，也可以包含聚合部件编号，例如 `E-01-06/11-2102`。

**Python**

```python theme={null}
import wuji_sdk

full_code = "E-01-06-2102"
info = wuji_sdk.describe_error(full_code)
if info is None:
    print(f"No catalog entry for {full_code}")
else:
    print(f"code: {full_code}")
    for field in ("name", "severity", "clear_policy", "resolution"):
        print(f"{field}: {info[field]}")
```

格式错误、未知产品或未收录的故障码返回 `None`。`ErrorInfo` 是字典，使用 `info["name"]` 访问字段。

`desc`、`cause`、`resolution` 为英文说明。中文说明位于 `desc_zh`、`cause_zh`、`resolution_zh`，未提供中文时为空字符串。例如，`info["resolution_zh"] or info["resolution"]` 优先使用中文处理建议。

**C**

```c theme={null}
#include <stdio.h>
#include "wuji_sdk.h"

int main(void) {
    const char *full_code = "E-01-06-2102";
    WujiErrorInfo info = {0};
    WujiStatus status = wuji_describe_error(full_code, &info);
    if (status != WUJI_STATUS_OK) {
        const char *message = wuji_last_error();
        fprintf(stderr, "%s: %s\n", full_code,
                message != NULL ? message : "Lookup failed");
        return 1;
    }
    printf("code: %s\n", full_code);
    printf("name: %s\n", info.name);
    printf("severity: %s\n", info.severity);
    printf("clear_policy: %s\n", info.clear_policy);
    printf("resolution: %s\n", info.resolution);
    return 0;
}
```

`wuji_describe_error(const char *full_code, WujiErrorInfo *out)` 返回 `WUJI_STATUS_OK` 时，`out` 包含查询结果。完整码格式错误或必填指针为 `NULL` 时返回 `WUJI_STATUS_ERR_INVALID_ARG`。格式合法但产品或故障码未知时，返回 `WUJI_STATUS_ERR_NOT_FOUND`。失败时用 `wuji_last_error()` 查询原因。

`WujiErrorInfo` 使用结构内的固定字符串缓冲区，无需释放。`desc`、`cause`、`resolution` 为英文，结构中没有 `_zh` 字段。

### 查询结果

| 字段 | 含义 |
| - | - |
| `code` | 原始整数故障码 |
| `name` | 故障符号名 |
| `severity` | Wuji Hand 2 为 `Warning`、`DeferredStop`、`ImmediateStop` 或 `Fatal`，Wuji Glove 为 `Warning` 或 `Error` |
| `clear_policy` | `AutoClear`、`ManualClear` 或 `NonClearable` |
| `desc` / `cause` / `resolution` | 故障描述、原因和处理建议 |

### 查询整数故障码

Wuji Glove 可使用上方的完整码接口查询。Wuji Hand 2 还通过 `joint_diagnostics` 的 `error_code_current` 等字段提供原始 `u16` 整数码，可直接使用 `WujiHand2.describe_error(code)` 或 `wuji_hand_2_describe_error(code, &info)` 查询。Python 返回相同的字典结构，C 返回相同的 `WujiErrorInfo`。

原始码 `0` 表示无活跃故障，Python 返回 `None`，C 返回 `WUJI_STATUS_ERR_NOT_FOUND`。非零未知码也返回这两个结果，应保留码值用于报障。编码器标定的 `enc1_error_code` / `enc2_error_code` 和 Wuji Hand 的 `u32` 错误位域属于其他类别，不可传入这些查询接口。

## 区分设备历史和主机日志

Wuji Glove 在连接时补记本次上电期间的故障汇总，包括 SDK 断连期间出现的故障。手套断电后清除这份设备侧历史。已写入电脑的 `error_codes.log` 继续保留，并按文件大小轮转。

Wuji Hand 2 的断电前记录与保存范围见 [诊断与日志](https://docs.wuji.tech/docs/zh/wuji-hand/latest/sdk-reference/diagnostics.md#故障日志)。设备故障日志与[设备日志导出](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/advanced.md#设备日志)保存的内容不同，报障时可一并提供。


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