固件升级

设备固件有新版本时，用 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 始终表示「每台升级到各自最新版本」。

用法

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 输出全部设备的只读更新概览：

$ 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 先确认升级计划，再逐台刷写并输出报告：

$ 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 列说明原因：

$ 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 指定低于当前的版本时，确认交互中显著标注降级：

$ 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：

wuji upgrade --check --json
wuji upgrade --all --yes --json

概览

硬件

软件

更多

范围与动作

用法

本地固件文件

读懂报告

示例

结构化输出

​范围与动作

​用法

​本地固件文件

​读懂报告

​示例

​结构化输出

范围与动作

用法

本地固件文件

读懂报告

示例

结构化输出