Firmware Upgrade

When new device firmware is available, upgrade with wuji upgrade. It fetches firmware matched to each device from the official catalog, verifies it, flashes it over the current transport, and prints a per-device report. The device reboots into the new firmware automatically.

Scope and Action

Every invocation combines a scope (which devices) with an action (which version).

Scope:

No scope flag: when only one device is connected, the scope flag is optional
--all: every discovered device (latest firmware only)
--type <TYPE>: every device of one type, such as --type WujiGlove (matches ping's Device Type column, case-insensitive)
--sn / --address / --handedness: one device, same selectors as other commands

Action:

No action flag: upgrade the scoped devices to their latest versions
--to <VERSION>: install a specific version on the scoped devices
--file <PATH>: flash a local firmware package onto the scoped devices
--list: browse available firmware versions, requires one device type or one device, read-only
--check: check all connected devices for firmware updates, works with any scope, read-only

A version number 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 firmware 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 on one device
wuji upgrade --type WujiGlove --to 0.11.0   # install a specific version on every device of one type
wuji upgrade --sn <SN> --list               # list firmware versions available for one device
wuji upgrade --file fw.zip                  # flash a local firmware package

Without a device selector, single-device actions auto-pick the only connected device. With several devices on the bus, the CLI errors out listing candidate SNs — pick one with --sn.

Read the Report

One row per device: Status is ok / skipped / failed, and the Detail column carries the failure reason or skip note
Exit code: 0 unless a device failed (skipped doesn't count as failure) — ready for script assertions
--check exits 0 whether or not updates exist, and returns 1 only when the query itself fails. To gate scripts on update availability, use the status field in --json output

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           │
╞══════════════════╪═════════════╪═════════╪════════╪══════════════════╡
│ WG1KXXXXXXXXX001 ┆ WujiGlove   ┆ 0.11.0  ┆ 0.11.1 ┆ update available │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXX002 ┆ WujiGlove   ┆ 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):
  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      │
└──────────────────┴────────┴────────┴────────┴──────────┘

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            │
╞══════════════════╪═════════╪════════╪═══════╪══════════╪═══════════════════╡
│ WG1KXXXXXXXXX001 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1 │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ WG1KXXXXXXXXX002 ┆ skipped ┆ 0.11.1 ┆ -     ┆ -        ┆ already on 0.11.1 │
└──────────────────┴─────────┴────────┴───────┴──────────┴───────────────────┘

Installing a version below the current one is flagged in the prompt:

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

Structured Output

--json prints a structured report with the same fields as the tables, for scripting. Flashing actions require --yes together with --json / --jsonl:

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

Scope and Action

Usage

Read the Report

Examples

Structured Output

On this page