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

# 设备管理

> 扫描设备、探测连通性与指定目标设备

## 扫描设备

`wuji devices` 扫描并列出 USB 和 UDP 总线上的全部设备：

```bash theme={null}
wuji devices          # 表格输出
wuji devices --json   # JSON 输出，便于脚本解析
```

输出列包括 SN、Transport、USB Port、IP 和 Address。设备类型与固件版本用 `wuji ping` 获取。

## 探测连通性

`wuji ping` 对设备执行完整握手，确认设备真正可用，并报告 SN、固件版本和 IP：

```bash theme={null}
wuji ping                 # 逐台探测全部已发现设备
wuji ping --sn <SN>       # 只探测指定设备
wuji ping --json          # 结构化输出
```

任一设备探测失败时，命令返回退出码 1，可直接用于脚本判定。

## 指定目标设备

多数命令支持用以下参数指定设备，三者互斥：

```bash theme={null}
--sn WG1KXXXXXXXXXXX             # 按序列号（推荐，最精确）
--address 192.168.1.100:50000    # 按地址：UDP 为 ip:port，USB 为 /dev/ttyACM0
--handedness left                # 按手性 left/right（双手设备）
```

不指定设备时的行为：

* `ping` 和 `doctor` 处理**全部**已发现设备
* `get`、`set`、`sub` 和 `resources` 在只有一台设备时自动连接，存在多台设备时报错并列出候选 SN，按提示用 `--sn` 指定

## 设备被占用时的行为

设备固件同一时刻只允许一个直连会话。设备已被其它宿主应用直连占用时，CLI 自动回退为只读访问：

* 读操作（`get`、`sub`、`resources`、`doctor` 的采样）正常工作
* 写操作（`set`）会被拒绝，释放直连占用方后重试

## 常见提示与处理

| 提示 | 含义与处理 |
| - | - |
| `found N devices: ...` | 未指定设备且总线上有多台，按提示用 `--sn` 指定 |
| `Session already exists (0x0013)` | 设备被其他进程直连占用，CLI 自动回退为只读模式 |
| `connected to wrong device: requested sn=X, got sn=Y` | 多设备共享同一地址或扫描条目过期，重新运行 `wuji devices` 核对 |


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