Troubleshooting, Recovery, and Maintenance

Safe Stop and Fault Recovery

Fault severity sets how the device stops, and communication loss, emergency stop, the fault-clearing reset, hazard zones, and the responsibility split for running with a robot arm each follow a fixed convention.

Fault Severity and Stop Behavior

Decode a device error code with WujiHand2.describe_error(code). The result carries a severity level (severity) and a clear policy (clear_policy). Each severity maps to a stop behavior:

Clear policies come in three kinds: AutoClear (clears itself once the cause is removed), ManualClear (needs a clear-fault call), and NonClearable (needs a power cycle, and if it recurs, stop using the device).

Communication Loss Behavior

If communication with the host drops while the hand is enabled, the device stops the motors and reports a fault. It doesn't resume motion on its own once communication returns—call enable() again (firmware v2.1.0 and later).

Emergency Stop

• Software emergency stop: hand.emergency_stop() stops the whole hand immediately and takes no mask
• Hardware emergency stop interface: not available in this version

Torque State After a Fault

A Warning doesn't stop the device, so it keeps running. After a DeferredStop, ImmediateStop, or Fatal fault stops the device, the joints go limp. For the meaning of each level, see Fault Severity and Stop Behavior above. Assess the risk of dropping a held object in your application.

Clear Faults and Reset Safely

1. Subscribe to joint_diagnostics to read the active error codes, then call info = describe_error(code).
2. If code is 0, no fault is active. Keep monitoring the device.
3. If info is None, retain the original error code and contact support to confirm how to handle it. Don't continue with the fault-clearing steps below.
4. Otherwise, read cause and resolution from info, then address the reported cause.
5. Clear the fault: for AutoClear, wait for it to clear itself. For ManualClear, call clear_fault() (optionally with a 20-bit mask to target specific joints).
6. Enable again with enable(), and confirm the status light turns white solid.
7. For NonClearable (Fatal) faults, power-cycle the device. If the fault recurs, stop using the device and contact support.

Hazard Zones

• Pinch points: the gaps between fingers and at the joints. Always run the hand with the soft pad and skin fitted, and keep clear while the hand moves
• Hot zone: the motor area in the palm. Don't touch it directly after a high load
• Cable zone: the flex cables on the finger surface and the cables leaving the wrist. Avoid scratching and pulling

Safety Responsibilities When Running With a Robot Arm

• The hand has no awareness of the arm's motion planning. Arm-side collision detection, speed limits, and workspace isolation are the integrator's responsibility
• The hand side provides its own over-torque, over-temperature, and communication-loss protection, and records impact detection events

Troubleshooting

Device discovery, connection, status light patterns, joint and temperature faults, and firmware upgrades each come with a check order and the action to take, with log export and support contact as the last resort.

The Device Isn't Discovered

1. Check whether the back-of-hand status light is on. If there's no light at all, check the power supply and the XT30 power connector first
2. Check that both ends of the network cable are seated
3. Confirm your computer's network adapter uses a static IP on the same subnet (default subnet 192.168.1.x, see Quick Start)
4. ping the device IP: 192.168.1.110 for the left hand, 192.168.1.111 for the right hand

If your computer has several network adapters, upgrade Wuji SDK to the latest version first, then disable the others and try again. If the device still isn't found, export the logs and contact support (see Export Logs and Contact Support).

Connection Fails or IPs Conflict

Two devices of the same handedness on one subnet share a default IP, which conflicts:

1. Connect only one device first
2. Change the IP of one of them, following SDK Reference
3. Put both devices on the network again, and connect by serial number (sn)

With several devices of the same handedness on the network, connect(handedness=...) raises AmbiguousHandedness. Specify the device with sn instead.

If there's no IP conflict and the connection still fails, check whether another program holds local port 50001, and upgrade Wuji SDK to the latest version.

The Status Light Shows a Warning or Fault

For what each level means, see Product Introduction. Handle each pattern as follows:

• Yellow slow flash (warning): subscribe to joint_diagnostics, check the active error codes, and decode them with WujiHand2.describe_error(code). Warnings are mostly early alerts—remove the cause (cooling, wiring, load), and keep working.
• Red slow flash (fault): work through Clear Faults and Reset Safely above—decode the error code, remove the cause, clear the fault, then enable again. If it keeps coming back, contact support.
• Red solid (critical): power-cycle the device. If it recurs, stop using the device, contact support, and follow their repair instructions.

Communication Drops After Enabling and the Device Stops

1. Check both ends of the network cable and the network gear, and confirm the link to the host is back
2. Subscribe to joint_diagnostics, read the active error codes, and decode them with WujiHand2.describe_error(code), then remove the reported cause.
3. Call enable() again, and confirm the status light turns white solid

The device doesn't resume motion on its own once communication returns. For the full stop-and-recovery behavior, see Communication Loss Behavior above. If the link keeps dropping, follow Export Logs and Contact Support below.

A Joint Is Offline (Fewer Than 20 Online)

1. Confirm the online joint count with hand.online_joints_count().get()
2. Subscribe to the joint_diagnostics stream and locate the offline joint by its nid
3. Power down, then check the flex cable and connector of that finger for looseness
4. Reseat the connector and power up for a self-check

A single failed finger doesn't stop the other joints from working, and the device keeps warning. If reseating doesn't help, the cause is usually hardware, and the fix is a whole-finger replacement. For what you can service yourself, see What You Can Service below. Spare parts and replacement steps aren't available yet, so contact support to get them.

Enabling Fails

1. Subscribe to the joint_diagnostics stream, check the active error codes, and decode them with WujiHand2.describe_error(code)
2. Act on the clear_policy returned:

• AutoClear: remove the cause and wait for the fault to clear itself
• ManualClear: remove the cause, call clear_fault(), then enable again
• NonClearable: power-cycle the device. If the fault recurs, stop using the device and contact support

3. Call enable() again, and confirm the status light turns white solid

Over-Temperature or Over-Current Faults

• Over-temperature: wait for the device to cool down and recover automatically. Improve cooling, and lower the load or duty cycle
• Over-current: check the load and wiring, clear the fault, and retry. If it keeps coming back, check the motor and load. If it still recurs, contact support

Encoder Warnings

1. Subscribe to joint_diagnostics to confirm which joint raised the warning and its error code.
2. Power down, then check the wiring and signal quality around that joint, and confirm the joint area is away from magnetic objects
3. Clear the fault and enable again to verify
4. A warning that keeps coming back is a hardware problem. Contact support

Firmware Upgrade Fails

1. Follow the error message from the upgrade tool (firmware v2.1.0 and later report detailed errors, while earlier versions give only a summary)
2. Losing power during an upgrade can corrupt the firmware data. Clear the fault and upgrade again
3. If the upgrade keeps failing, contact support

For the upgrade flow, see Wuji Studio firmware upgrade.

Export Logs and Contact Support

import asyncio

result = asyncio.run(hand.dump_hand_logs(bank="current"))
print(result["session_dir"]) # the log session directory, with joint{0..19}.log and sboard.log

Logs export to ~/.wuji/hand_logs by default. For usage details, see SDK Reference. The device keeps at least one week of full logs on board, so anything older needs to be reproduced before you export.

When you contact support@wuji.tech, include:

• The log bundle
• The error code and status light pattern
• The firmware and SDK versions
• Steps to reproduce

Maintenance and Consumables

The skin, soft pad, and whole fingers are user-replaceable, while board-level parts are not. Daily checks, storage, transport, and warranty each carry their own requirements.

What You Can Service

Daily Checks and Maintenance Intervals

Check before each day's use:

• No visible damage, with the skin properly fitted
• No cable damage and no loose connectors
• The power-on self-check passes (the status light reaches white breathing)

Storage and Transport

• Storage: power down and store in a dry environment, with the fingers extended flat in the box
• Transport: use the original packaging, which is designed for high-temperature, high-humidity, drop, stacking, and vibration conditions

Warranty and Support

The warranty scope and repair process aren't available yet and will be added later. If a prototype is damaged, contact your point of contact or support@wuji.tech immediately.