Health Diagnostics

User Guide

Check device health with wuji doctor to locate EMF disconnections and tactile dead pixels

When a device won’t connect or its data looks wrong, run wuji doctor first. It checks the host environment, then scans for devices and samples real-time data (about 100 frames, done in seconds), printing a tree-shaped report that helps narrow down the fault.

What It Checks

Checks run in three layers: host environment, device discovery, and per device.

Environment

Software versions: CLI, Wuji SDK, and Wuji Studio versions, and whether updates are available
System info: whether the operating system and its version are supported
Network interfaces: the online interfaces and their addresses, flagging routing risks when several are present

Generic

Produced whenever a scan runs, even when no device turns up: how many devices were found, whether any device IPs collide, and whether the devices share a subnet with the host.

Per device

wuji_glove
- EMF disconnection check: locates the affected finger and distinguishes RX (receiver) from TX (transmitter) faults
- Tactile sensor dead-pixel, bad-row, and bad-column check

For the tactile check, place the glove statically. Don’t wear or press it, or the check may report false positives.

Usage

wuji doctor                # diagnose all devices
wuji doctor --sn <SN>      # diagnose a specific device only
wuji doctor -v             # show all checks (passing ones are hidden by default)
wuji doctor --json         # the same information as the tree report, as structured JSON

Read the Report

$ wuji doctor

══════ Environment ══════
~ Software: version info incomplete
├─ ✔ CLI: 2026.8.3 (up to date)
├─ ~ SDK: not installed or version undetectable (skipped)
└─ ✔ Studio: 2026.8.3 (up to date)

✔ System: supported
└─ ✔ OS: Ubuntu 26.04 (supported)

! Network interfaces: 2 interfaces, see interface count
├─ ✔ eth0 (192.168.1.50/24, fe80::abcd:.../64)
└─ ! Interface count: 2 interfaces — multiple interfaces may cause routing issues

══════ Generic ══════
✔ Device discovery: 2 device(s) found, no issues
├─ ✔ Devices found: 2 device(s) found
├─ ✔ Duplicate device IP
└─ ✔ Host subnet

══════ wuji_glove: WG1KXXXXXXXXXXX ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
└─ ! tactile dead-pixel check: 0 dead pixels, 2 bad rows, 2 bad cols
   ├─ ! Bad rows: 2 bad row(s)
   └─ ! Bad cols: 2 bad col(s)
   Tip: Tactile check result is for reference only. Verify via the tactile matrix in wuji viz

Status marks: ✔ pass, ! warn (advisory anomaly), ✘ fail (confirmed fault), and ~ skip (the check didn’t apply or couldn’t run)
Tip: lines are fix suggestions
Exit code: 0 means no failures (warnings don’t count as failures), and 1 means a failure exists or the diagnosis couldn’t complete — ready for script assertions. No device attached is not an error: the environment and discovery checks still run and set the exit code
Checks without a target: Duplicate device IP and Host subnet run only when discovery finds a UDP device. If every device uses USB or Zenoh, both checks show ~ not attempted: no UDP devices. A device without a diagnostic recipe also shows ~ connect & diagnose instead of a fault. These skipped checks don’t make the exit code 1. Connection and data-collection failures still show ✘ and return 1
Tactile check results are advisory (capped at warn) — verify with the raw tactile matrix shown by wuji viz

Expand All Checks

By default only anomalies show. Use -v to expand every check, including passing ones, to see exactly what was checked. Only the device section appears below — real output still prints the Environment and Generic sections ahead of the devices:

$ wuji doctor -v

══════ wuji_glove: WG1KXXXXXXXXXXX ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
│  ├─ ✔ Thumb
│  ├─ ✔ Index
│  ├─ ✔ Middle
│  ├─ ✔ Ring
│  └─ ✔ Pinky
└─ ! tactile dead-pixel check: 0 dead pixels, 0 bad rows, 1 bad cols
   ├─ ✔ Thumb
   ├─ ✔ Index
   ├─ ✔ Middle
   ├─ ✔ Ring
   ├─ ✔ Pinky
   ├─ ✔ Palm
   └─ ! Bad cols: 1 bad col(s)
   Tip: Tactile check result is for reference only. Verify via the tactile matrix in wuji viz

Structured Output

--json prints formatted JSON, and --jsonl prints compact JSON on one line for saving and scripting:

wuji doctor --json > doctor-report.json

All check results are in the top-level checks array. Environment checks appear as array nodes. Device discovery and per-device checks contain subtrees in children.

Field	Contents
`checks`	Check results, always present and empty when there are no results
`checks[].status`	Check status: `pass`, `warn`, `fail`, or `skip`
`checks[].children`	Nested checks with the same structure, omitted when there are no children
`device`	A device-scope string, `"all"` for `wuji doctor`, containing no check results
`verdict`	Overall diagnostic verdict

Scripts that read check results from the env or device arrays must now traverse checks and its children. device is now a string, not a check-result array.

The following excerpt shows the fields related to check results:

{
  "device": "all",
  "verdict": "pass",
  "checks": [
    {
      "id": "env_system",
      "label": "System",
      "status": "pass",
      "summary": "supported"
    },
    {
      "id": "device_wg1kxxxxxxxxxxx",
      "label": "wuji_glove: WG1KXXXXXXXXXXX",
      "status": "pass",
      "children": [
        {
          "id": "emf_disconnect",
          "label": "EMF disconnect check",
          "status": "pass",
          "summary": "all 5 fingers normal"
        }
      ]
    }
  ]
}

The doctor_diagnosis.json file in a wuji logs export support bundle uses the same structure and contains the diagnosis generated during export.