故障日志与错误码

连接 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
C

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"] 优先使用中文处理建议。

#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 的断电前记录与保存范围见诊断与日志。设备故障日志与设备日志导出保存的内容不同，报障时可一并提供。

概览

硬件

软件

更多

故障日志与错误码

查看故障记录

识别状态与完整码

查询错误码

查询结果

查询整数故障码

区分设备历史和主机日志

​查看故障记录

​识别状态与完整码

​查询错误码

​查询结果

​查询整数故障码

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

查看故障记录

识别状态与完整码

查询错误码

查询结果

查询整数故障码

区分设备历史和主机日志