wuji upgrade fetches firmware from the official catalog, flashes it over the connected transport, and prints a per-device report. The device reboots into the new firmware automatically.
Mental Model: Scope × Action
Every invocation is a scope (which devices) combined with an action (what to do). Running wuji upgrade with no arguments prints help — flashing never happens implicitly.
Scope (defaults to the only connected device):
--all— every discovered device (latest firmware only)--type <TYPE>— every device of one type (matchesping's Device Type, case-insensitive, e.g.--type wuji_glove)--sn/--address/--handedness— one device, same selectors as other commands
Actions:
--check— update overview, read-only, works with any scope- (no action flag) — upgrade the scoped devices to their latest catalog version
--to <VERSION>— install a specific catalog version--file <PATH>— flash a local firmware file-l/--list— browse the firmware catalog, read-only
A version only makes sense for one device type, so --to, --file, and --list require a single-type scope: --type or one device. --all always means "latest for each device".
Usage
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
Without a device selector, single-device actions auto-pick the only connected device; if several are on the bus, the CLI errors out listing candidate SNs.
Safety Semantics
- Flashing always shows a confirmation prompt with firmware version, size, and the version transition for each device.
-y/--yesskips it. - A device already on the target version is skipped. Use
--forceto downgrade a device ahead of the latest catalog version. - Downgrading to an older version via
--toor--fileis allowed; the confirmation prompt flags it with⚠ DOWNGRADE. --filesupports official.zippackages (verified automatically) and raw.binfiles (flashed as-is).
Reading the Report
- Per-device
Status:ok/skipped/failed; theDetailcolumn carries the failure reason or the skip note, plus the unverified-file note for a raw.bin - Exit code: 0 unless a device failed (skipped devices don't fail), directly usable in scripts
--checkexits 0 whether or not updates exist (only a query failure exits 1); gate on the JSONstatusfield instead
Examples
wuji upgrade --check gives a read-only overview of all devices:
$ 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 confirms the plan, then flashes each device in turn and prints a report:
$ 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 │
└──────────────────┴────────┴────────┴────────┴──────────┘
Devices already on the target version are skipped, and the Detail column says why:
$ 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 │
└──────────────────┴─────────┴────────┴───────┴──────────┴─────────────────────┘
Installing a version below the current one is flagged in the prompt:
$ 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 shows the catalog for that device, newest first:
$ 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. │
└─────────────────┴────────────┴────────────┴──────────────────────────────────┘
For scripting, add --json (flashing also needs --yes). Each device row carries sn, status,
firmware_before, firmware_after, duration_s, note and error, plus firmware_expected holding
the target version taken from the catalog or the package manifest.
Before and After are both read from the device, After after the upgrade completed. After stays
- (and firmware_after stays null) when the upgrade did not run (skipped), did not succeed (failed),
or when the device does not report a version. When the device does report one, After shows the value
read, even if it equals Before: re-flashing the same version with --force, or an upgrade that only
changes slave nodes, leaves the two equal while still writing the device. Treat After as supporting
information rather than a verdict.
Rolling Back Firmware
wuji upgrade rollback switches the device to its backup firmware in one step. It is a subcommand, not a flag, and does not take any upgrade action flags (--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
--snis required; rollback always targets a single device.- Hands whose tactile sensors are currently online cannot be rolled back: the request is rejected before the device is modified, and the report's
Statusisfailed(safe to retry once resolved). - The rollback target is not selectable, and its version is not known before the operation completes. The confirmation prompt says so explicitly.
- The report's
Statusisok,failed, orunknown.unknownmeans the rollback did not reach a confirmed end state (part of the device could not be confirmed, the read-back did not verify the switch, or the post-rollback version could not be read back) — do not retry blindly (a successful retry would switch back to the original version); verify the actual version first withwuji ping --sn <SN>. A report is onlyokwhen it carries the post-rollback version that was read back from the device.