> ## 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 upgrade 检查固件更新、批量升级设备、安装指定版本或刷写本地固件文件

设备固件有新版本时，用 `wuji upgrade` 升级。它从官方固件源获取与设备匹配的固件，完成校验后经当前连接方式刷写，并逐台输出结果报告。刷写完成后设备自动重启进入新固件。

## 范围与动作

每次调用由**范围**（升级哪些设备）和**动作**（升到哪个版本）组合而成。

范围：

* 不带范围参数：环境内仅连接一台设备时，可不填写范围参数
* `--all`：全部已发现设备（仅升级到各自最新版本）
* `--type <TYPE>`：某一类型的全部设备，如 `--type wuji_glove`（与 `ping` 的 Device Type 列一致，大小写不敏感）
* `--sn` / `--address` / `--handedness`：指定单台，与其他命令相同

动作：

* 不带动作参数：将范围内设备升级到各自最新版本
* `--to <VERSION>`：安装指定版本固件到范围内设备
* `--file <PATH>`：将官方 ZIP 包或独立 Wuji `.bin` 固件刷写到范围内设备
* `--list`：查看可用固件版本，需指定到某一类型或某一台设备，只读
* `--check`：检查全部已连接设备的固件是否有更新，任意范围可用，只读

版本号只在单一设备类型下才有意义，所以 `--to`、`--file` 和 `--list` 要求单一类型范围：`--type` 或单台设备。`--all` 始终表示「每台升级到各自最新版本」。

## 用法

```bash theme={null}
wuji upgrade --check                        # 哪些设备有固件更新（只读）
wuji upgrade --all                          # 全部设备升到各自最新版本
wuji upgrade --sn <SN>                      # 单台升到最新版本
wuji upgrade --sn <SN> --to 0.11.0          # 单台安装指定版本
wuji upgrade --type wuji_glove --to 0.11.0   # 按设备类型批量安装指定版本
wuji upgrade --sn <SN> --list               # 列出该设备可用的固件版本
wuji upgrade --file fw.zip                  # 刷写本地固件包
wuji upgrade --file firmware.bin            # 刷写独立 Wuji 固件文件
```

未指定设备时，单台动作自动选择唯一在线的设备。总线上有多台时报错并列出候选 SN，按提示用 `--sn` 指定。

## 本地固件文件

`--file` 根据文件内容而非扩展名识别固件格式。它接受以下格式：

* **官方 ZIP 包**：CLI 在刷写前校验包内清单和固件摘要。
* **独立 Wuji `.bin` 固件**：CLI 直接刷写该文件。该文件不含清单，CLI 无法校验其摘要、设备类型或版本。确认提示将该文件标记为 `UNVERIFIED`。

其他文件会在连接设备前触发 `not a firmware file` 错误。若独立 `.bin` 固件与目标设备类型不匹配，刷写仍可能失败。失败报告会提示核对固件是否与目标设备类型匹配。

## 读懂报告

* 每台设备一行：`Status` 为 `ok` / `skipped` / `failed`，`Detail` 列给出失败原因或跳过说明
* **退出码**：没有 `failed` 即为 0（`skipped` 不算失败），可直接用于脚本判定
* `--check` 的退出码与是否存在更新无关，只有查询失败才返回 1。脚本判断是否有更新时，用 `--json` 输出的 `status` 字段

## 示例

`wuji upgrade --check` 输出全部设备的只读更新概览：

```bash theme={null}
$ wuji upgrade --check
1/2 device(s) have updates available
┌──────────────────┬─────────────┬─────────┬────────┬──────────────────┐
│ SN               ┆ Device Type ┆ Current ┆ Latest ┆ Status           │
╞══════════════════╪═════════════╪═════════╪════════╪══════════════════╡
│ WG1KXXXXXXXXX001 ┆ wuji_glove   ┆ 0.11.0  ┆ 0.11.1 ┆ update available │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXX002 ┆ wuji_glove   ┆ 0.11.1  ┆ 0.11.1 ┆ up to date       │
└──────────────────┴─────────────┴─────────┴────────┴──────────────────┘
```

`wuji upgrade --all` 先确认升级计划，再逐台刷写并输出报告：

```bash theme={null}
$ wuji upgrade --all
firmware: 0.11.1 (157.15 KiB, released 2026-06-24)
  - Fixed an incorrect IMU initialization warning.
device(s) to upgrade (2):
  WG1KXXXXXXXXX001 (0.11.0 → 0.11.1)
  WG1KXXXXXXXXX002 (0.11.0 → 0.11.1)
proceed? [y/N] y

2 upgraded (2 device(s))
┌──────────────────┬────────┬────────┬────────┬──────────┐
│ SN               ┆ Status ┆ Before ┆ After  ┆ Duration │
╞══════════════════╪════════╪════════╪════════╪══════════╡
│ WG1KXXXXXXXXX001 ┆ ok     ┆ 0.11.0 ┆ 0.11.1 ┆ 16s      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXX002 ┆ ok     ┆ 0.11.0 ┆ 0.11.1 ┆ 16s      │
└──────────────────┴────────┴────────┴────────┴──────────┘
```

已在目标版本的设备被跳过，`Detail` 列说明原因：

```bash theme={null}
$ wuji upgrade --all --yes
0 upgraded, 2 skipped (2 device(s))
┌──────────────────┬─────────┬────────┬───────┬──────────┬───────────────────┐
│ SN               ┆ Status  ┆ Before ┆ After ┆ Duration ┆ Detail            │
╞══════════════════╪═════════╪════════╪═══════╪══════════╪═══════════════════╡
│ WG1KXXXXXXXXX001 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1 │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXX002 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1 │
└──────────────────┴─────────┴────────┴───────┴──────────┴───────────────────┘
```

`--to` 指定低于当前的版本时，确认交互中显著标注降级：

```bash theme={null}
$ wuji upgrade --sn WG1KXXXXXXXXX001 --to 0.11.0
firmware: 0.11.0 (155.68 KiB, released 2026-06-18)
  - Updated tactile output to the new 24×31 matrix format.
device(s) to upgrade (1):
  WG1KXXXXXXXXX001 (0.11.1 → 0.11.0)  ⚠ DOWNGRADE
proceed? [y/N]
```

## 结构化输出

`--json` 输出与表格相同字段的结构化报告，便于脚本处理。刷写动作在 `--json` / `--jsonl` 下必须同时带 `--yes`：

```bash theme={null}
wuji upgrade --check --json
wuji upgrade --all --yes --json
```


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