> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Diagnostics

> 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

<Warning>
  For the tactile check, place the glove statically. Don't wear or press it, or the check may report false positives.
</Warning>

## Usage

```bash theme={null}
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

```bash theme={null}
$ 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`](/en/docs/wuji-cli/visualization#wuji-glove)

## 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:

```bash theme={null}
$ 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:

```bash theme={null}
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.

<Warning>
  Earlier versions printed two flat arrays, `system` and `devices`. Scripts reading those field names need to move to `env` and `device`.
</Warning>

```json theme={null}
{
  "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" }
      ]
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.