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

# Device Management

> Scan devices, probe connectivity, and target a specific device

## Scan Devices

`wuji devices` scans and lists all devices on the USB and UDP buses:

```bash theme={null}
wuji devices          # table output
wuji devices --json   # JSON output for scripting
```

Output columns include SN, Transport, USB Port, IP, and Address. Use `wuji ping` to get the device type and firmware version.

## Probe Connectivity

`wuji ping` performs a full handshake with the device to confirm it's actually reachable, reporting SN, firmware version, and IP:

```bash theme={null}
wuji ping                 # probe all discovered devices one by one
wuji ping --sn <SN>       # probe a specific device only
wuji ping --json          # structured output
```

If any device fails the probe, the command returns exit code 1 — ready for script assertions.

## Target a Specific Device

Most commands accept one of the following mutually exclusive flags to select a device:

```bash theme={null}
--sn WG1KXXXXXXXXXXX             # by serial number (recommended, most precise)
--address 192.168.1.100:50000    # by address: ip:port for UDP, /dev/ttyACM0 for USB
--handedness left                # by handedness left/right (two-handed devices)
```

Behavior when no device is specified:

* `ping` and `doctor` process **all** discovered devices
* `get`, `set`, `sub`, and `resources` connect automatically when exactly one device is present. With multiple devices, they report an error listing candidate SNs — pick one with `--sn`

## Behavior When the Device Is Occupied

Device firmware allows only one direct session at a time. When another host application already occupies the device, the CLI falls back to read-only access:

* Read operations (`get`, `sub`, `resources`, and `doctor` sampling) keep working
* Write operations (`set`) are rejected — release the occupying direct connection and retry

## Common Messages

| Message | Meaning and Handling |
| - | - |
| `found N devices: ...` | No device specified and multiple devices are on the bus — pick one with `--sn` |
| `Session already exists (0x0013)` | The device is occupied by another direct connection — the CLI falls back to read-only access automatically |
| `connected to wrong device: requested sn=X, got sn=Y` | Multiple devices share the same address, or the scan entry is stale — rerun `wuji devices` to verify |


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