Fault Logs and Error Codes

After connecting to Wuji Hand 2 or Wuji Glove, the SDK automatically logs the appearance and clearance of reported fault codes, including the full code, description, and suggested action. The device firmware must support fault-code reporting. Devices without this capability still connect normally.

Find Fault Records

With the SDK’s default logger, fault information appears in these locations:

Location	Contents
Terminal	Groups components with the same fault and state, with the description and suggested action
`~/.wuji/logs/sdk_<date>.log`	Per-component records, connection summaries, and summaries of faults that remain active
`~/.wuji/logs/error_codes.log`	Per-component fault changes and device history summaries, appended across process restarts and device disconnections

error_codes.log is independent of the SDK log level and date-based cleanup. Before a write would exceed 50 MiB, the SDK rotates it to error_codes.log.1, keeping the current file and one backup. Back up both files regularly if longer retention is needed. The device reports faults that were active during each second at 1 Hz. The SDK records fault appearances and clearances, then summarizes persistent faults every 10 received frames, about 10 seconds during continuous reception. This summary goes to the terminal and sdk_<date>.log, without repeating it in error_codes.log.

Read States and Full Codes

Log Content	Meaning
`state=active`	A received fault wasn’t previously recorded as active, including a transient fault that appeared and cleared within the second
`state=cleared`	A later status confirms the fault has cleared. A transient fault’s clearance normally appears one frame later
`state=active_before_power_off`	A fault Wuji Hand 2 saved as active before power loss. It doesn’t establish that the fault is still active on this connection
`state=history`	A Wuji Glove fault summary from this power-on period. Check its `active` field for the state
`still active`	A summary of faults still present in the latest status

Repeated appearances and clearances within one second can be combined into one status period. Use the log to locate faults, rather than as a complete timeline of every transition. If the log reports omitted records, include that message and its context when contacting support. A full code has the form AA-BB-CCCC. Terminal output may add an E- prefix. When several components report the same code, their BB values are joined with /.

Field	Meaning
`AA`	Two-digit hexadecimal product code. `01` identifies Wuji Hand 2, and `11` identifies Wuji Glove. The current SDK looks up fault codes for these two products
`BB`	Decimal component ID. The format accepts `0–255`, and logs use at least two digits, such as `06`. The host log records the same ID in `component_id`, while the terminal shows the component name. Use that name to identify the actual component
`CCCC`	Four-digit hexadecimal native fault code, from `0000` to `FFFF`. `0000` means no fault. Look up nonzero codes in the catalog selected by `AA`. Read severity and clearing behavior from the result’s `severity` and `clear_policy` fields

For example, E-01-06-2102 means component 06 on Wuji Hand 2 reported native code 2102. The terminal names this component index_mcp_flex (F1S1). E-01-06/11-2102 means components 06 and 11 reported the same native code. E-11-32-0102 means component 32 on Wuji Glove reported native code 0102. The terminal names this component Index IMU. Copy the full code into the error code lookup to get its cause and suggested action. The lookup uses AA to select the product catalog and CCCC to match an entry. BB identifies the component without changing the lookup result. Both Python and C provide this lookup without a device connection.

Look Up Error Codes

Look up a full code from the log to get the fault name, cause, and suggested action. No device connection is needed. The code accepts an E- prefix and grouped component numbers, such as 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]}")

An invalid format, unknown product, or unlisted fault code returns None. ErrorInfo is a dictionary. Access fields with info["name"].desc, cause, and resolution contain English text. Chinese text is in desc_zh, cause_zh, and resolution_zh, with an empty string when unavailable. For example, info["resolution_zh"] or info["resolution"] prefers the Chinese suggested action.

#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;
}

When wuji_describe_error(const char *full_code, WujiErrorInfo *out) returns WUJI_STATUS_OK, out contains the result. An invalid code format or a required NULL pointer returns WUJI_STATUS_ERR_INVALID_ARG. A valid format with an unknown product or fault code returns WUJI_STATUS_ERR_NOT_FOUND. Use wuji_last_error() for failure details.WujiErrorInfo contains fixed string buffers and needs no release call. desc, cause, and resolution contain English text. The structure has no _zh fields.

Lookup Results

Field	Meaning
`code`	Native integer fault code
`name`	Fault symbol name
`severity`	`Warning`, `DeferredStop`, `ImmediateStop`, or `Fatal` for Wuji Hand 2. `Warning` or `Error` for Wuji Glove
`clear_policy`	`AutoClear`, `ManualClear`, or `NonClearable`
`desc` / `cause` / `resolution`	Fault description, cause, and suggested action

Look Up Integer Fault Codes

Use the full-code lookup above for Wuji Glove. Wuji Hand 2 also exposes native u16 integer codes in fields such as error_code_current in joint_diagnostics. Query these integers directly with WujiHand2.describe_error(code) or wuji_hand_2_describe_error(code, &info). Python returns the same dictionary structure, and C returns the same WujiErrorInfo. Native code 0 means no active fault. Python returns None, and C returns WUJI_STATUS_ERR_NOT_FOUND. Unknown nonzero codes return the same results, so retain the code for fault reports. Encoder calibration values enc1_error_code / enc2_error_code and the Wuji Hand u32 error bitfield belong to other categories and must not be passed to these lookup functions.

Distinguish Device History from Host Logs

When Wuji Glove connects, the SDK records a summary of faults from the current power-on period, including faults that occurred while the SDK was disconnected. Power loss clears this device-side history. The computer retains records already written to error_codes.log, subject to file-size rotation. For Wuji Hand 2 power-loss records and their limits, see Diagnostics and Logging. Device fault logs and the device log export contain different information. Include both when reporting a fault.

Overview

Hardware

Software

More

Fault Logs and Error Codes

Find Fault Records

Read States and Full Codes

Look Up Error Codes

Lookup Results

Look Up Integer Fault Codes

Distinguish Device History from Host Logs

​Find Fault Records

​Read States and Full Codes

​Look Up Error Codes

​Lookup Results

​Look Up Integer Fault Codes

​Distinguish Device History from Host Logs

Find Fault Records

Read States and Full Codes

Look Up Error Codes

Lookup Results

Look Up Integer Fault Codes

Distinguish Device History from Host Logs