wuji-cli-upgrade

wuji upgrade 会从官方目录获取固件，通过已连接的传输方式进行刷写，并打印每台设备的报告。设备会自动重启并运行新固件。

心智模型：范围 × 操作

每次调用都由一个范围（针对哪些设备）和一个操作（要做什么）组成。不带参数运行 wuji upgrade 会打印帮助信息——不会隐式刷写固件。

范围（默认选择唯一已连接的设备）：

• --all — 所有发现的设备（仅刷写最新固件）
• --type <TYPE> — 某一类型的所有设备（匹配 ping 的 Device Type，不区分大小写，例如 --type wuji_glove）
• --sn / --address / --handedness — 一台设备，与其他命令使用相同的选择器

操作：

• --check — 更新概览，只读，适用于任何范围
• （不带操作标记） — 将范围内的设备升级到目录中的最新版本
• --to <VERSION> — 安装指定的目录版本
• --file <PATH> — 刷写本地固件文件
• -l / --list — 浏览固件目录，只读

版本只对一种设备类型有意义，因此 --to、--file 和 --list 需要单一类型范围：--type 或一台设备。--all 始终表示“每种设备都刷写最新版本”。

用法

wuji upgrade --check                        # Which devices have updates (read-only)
wuji upgrade --all                          # Upgrade every device to its latest
wuji upgrade --sn <SN>                      # Upgrade one device to its latest
wuji upgrade --sn <SN> --to 0.11.0          # Install a specific version
wuji upgrade --type wuji_glove --to 0.11.0   # Install a version on every glove
wuji upgrade --sn <SN> --list               # List firmware versions for one device
wuji upgrade --file fw.zip                  # Flash a local package

不指定设备时，单设备操作会自动选择唯一已连接的设备；如果总线上有多台设备，CLI 会报错并列出候选 SN。

安全语义

• 刷写前始终会显示确认提示，其中包含每台设备的固件版本、大小和版本变更情况。使用 -y / --yes 可跳过确认。
• 已是目标版本的设备会被跳过。若设备版本高于目录中的最新版本，使用 --force 可将其降级。
• 通过 --to 或 --file 降级到较旧版本是允许的；确认提示会用 ⚠ DOWNGRADE 标出。
• --file 支持官方 .zip 软件包（自动验证）和原始 .bin 文件（按原样刷写）。

阅读报告

• 每台设备的 Status：ok / skipped / failed；Detail 列包含失败原因或跳过说明，原始 .bin 还会附带未经验证的文件说明
• 退出代码：除非有设备失败，否则为 0（跳过设备不算失败），可直接用于脚本
• 无论是否存在更新，--check 的退出代码均为 0（仅查询失败时退出代码为 1）；应根据 JSON 的 status 字段进行判断

示例

wuji upgrade --check 可只读查看所有设备的概览：

$ wuji upgrade --check
1/2 device(s) have updates available
┌──────────────────┬─────────────┬─────────┬────────┬──────────────────┐
│ SN               ┆ Device Type ┆ Current ┆ Latest ┆ Status           │
╞══════════════════╪═════════════╪═════════╪════════╪══════════════════╡
│ WG1KXXXXXXXXXX01 ┆ wuji_glove   ┆ 0.11.0  ┆ 0.11.1 ┆ update available │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXXX02 ┆ 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):
  WG1KXXXXXXXXXX01 (0.11.0 → 0.11.1)
  WG1KXXXXXXXXXX02 (0.11.0 → 0.11.1)
proceed? [y/N] y

2 upgraded (2 device(s))
┌──────────────────┬────────┬────────┬────────┬──────────┐
│ SN               ┆ Status ┆ Before ┆ After  ┆ Duration │
╞══════════════════╪════════╪════════╪════════╪══════════╡
│ WG1KXXXXXXXXXX01 ┆ ok     ┆ 0.11.0 ┆ 0.11.1 ┆ 16s      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXXX02 ┆ 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              │
╞══════════════════╪═════════╪════════╪═══════╪══════════╪═════════════════════╡
│ WG1KXXXXXXXXXX02 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1   │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXXX01 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1   │
└──────────────────┴─────────┴────────┴───────┴──────────┴─────────────────────┘

安装低于当前版本的版本时，提示中会标出：

$ wuji upgrade --sn WG1KXXXXXXXXXX01 --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):
  WG1KXXXXXXXXXX01 (0.11.1 → 0.11.0)  ⚠ DOWNGRADE
proceed? [y/N]

wuji upgrade --sn <SN> --list 会显示该设备的目录，按版本从新到旧排列：

$ wuji upgrade --sn WG1KXXXXXXXXXX01 --list
WG1KXXXXXXXXXX01 (current: 0.11.1)
┌─────────────────┬────────────┬────────────┬──────────────────────────────────┐
│ Version         ┆ Released   ┆ Size       ┆ Notes                            │
╞═════════════════╪════════════╪════════════╪══════════════════════════════════╡
│ 0.11.1 (latest, ┆ 2026-06-24 ┆ 157.15 KiB ┆ Fixed an incorrect IMU           │
│ current)        ┆            ┆            ┆ initialization warning.          │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 0.11.0          ┆ 2026-06-18 ┆ 155.68 KiB ┆ Updated tactile output to the    │
│                 ┆            ┆            ┆ new 24×31 matrix format.         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 0.10.1          ┆ 2026-04-28 ┆ 152.27 KiB ┆ Fixed some known issues.         │
└─────────────────┴────────────┴────────────┴──────────────────────────────────┘

用于脚本时，添加 --json（刷写操作还需要 --yes）。每台设备对应的行包含 sn、status、 firmware_before、firmware_after、duration_s、note 和 error，以及从目录或软件包清单中 获取目标版本的 firmware_expected。

Before 和 After 均从设备读取；After 在升级完成后读取。升级未运行（已跳过）、未成功（失败）， 或设备未报告版本时，After 会保持为 -（且 firmware_after 保持为 null）。设备报告版本时， After 会显示读取到的值，即使它与 Before 相同：使用 --force 重新刷写相同版本，或只更改从节点的 升级，都会使两者相同，但仍会对设备进行写入。请将 After 视为参考信息，而非判定结果。

回滚固件

wuji upgrade rollback 可一步将设备切换到备份固件。这是一个子命令，而不是标志，并且不接受任何升级操作标志（--check、--to、--file、--list、--force、--all、--type）：

wuji upgrade rollback --sn WH2KXXXXXXXXXX01            # Roll back one device (prompts for confirmation)
wuji upgrade rollback --sn WH2KXXXXXXXXXX01 --yes      # Skip the prompt
wuji upgrade rollback --sn WH2KXXXXXXXXXX01 --yes --json   # Machine-readable report

• 必须指定 --sn；回滚始终只针对一台设备。
• 当前触觉传感器处于在线状态的手部设备无法回滚：请求会在修改设备之前被拒绝，报告的 Status 为 failed（问题解决后可安全重试）。
• 无法选择回滚目标，也无法在操作完成前获知目标版本。确认提示会明确说明这一点。
• 报告的 Status 为 ok、failed 或 unknown。unknown 表示回滚未达到已确认的最终状态（无法确认设备的某个部分、回读未验证切换成功，或无法回读回滚后的版本）——请勿盲目重试（重试成功会切换回原始版本）；请先使用 wuji ping --sn <SN> 验证实际版本。只有报告包含从设备回读的回滚后版本时，状态才会是 ok。