Health Diagnostics
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 JSONRead 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.100/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 tactile heatmap in Wuji Studio- 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 IPandHost subnetrun 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 & diagnoseinstead 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 tactile matrix heatmap in Wuji Studio
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 tactile heatmap in Wuji StudioStructured Output
--json prints the same information as the tree report in machine-readable form, for saving and scripting:
wuji doctor --json > doctor-report.jsonThe top-level object splits into two arrays by diagnosis layer, one node per check item, nested via children:
| Field | Contents |
|---|---|
env | Host-environment checks: env_software (CLI / SDK / Studio versions), env_system (system info), and network interfaces |
device | Device-layer results: a Generic entry without sn holding the device-discovery check, followed by one entry per device with label, sn, and its check tree |
An array is omitted only when empty. env is always there online, and device is there whenever a scan ran or a device was targeted.
The example below assumes discovery found a UDP device. With only USB or Zenoh devices, the discovery node and both IP checks use "status": "skip", and the summary states that the IP checks were skipped because no UDP device was found.
Earlier versions printed two flat arrays, system and devices. Scripts reading those field names need to move to env and device.
{
"env": [
{
"id": "env_software",
"label": "Software",
"status": "warn",
"summary": "updates available or unable to verify latest",
"children": [
{ "label": "CLI", "status": "warn", "summary": "2026.8.3 (unable to check latest version)" },
{ "label": "SDK", "status": "skip", "summary": "not installed or version undetectable (skipped)" },
{ "label": "Studio", "status": "pass", "summary": "2026.8.3 (up to date)" }
]
}
],
"device": [
{
"label": "Generic",
"children": [
{
"id": "device_discovery",
"label": "Device discovery",
"status": "pass",
"summary": "1 device(s) found, no issues",
"children": [
{ "label": "Devices found", "status": "pass", "summary": "1 device(s) found" },
{ "label": "Duplicate device IP", "status": "pass" },
{ "label": "Host subnet", "status": "pass" }
]
}
]
},
{
"label": "wuji_glove",
"sn": "WG1KXXXXXXXXXXX",
"children": [
{ "id": "emf_disconnect", "label": "EMF disconnect check", "status": "pass", "summary": "all 5 fingers normal" }
]
}
]
}