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 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 the same information as the tree report in machine-readable form, for saving and scripting:

wuji doctor --json > doctor-report.json

The 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" }
      ]
    }
  ]
}

Overview

Hardware

Software

More

What It Checks

Usage

Read the Report

Expand All Checks

Structured Output

​What It Checks

​Usage

​Read the Report

​Expand All Checks

​Structured Output

What It Checks

Usage

Read the Report

Expand All Checks

Structured Output