wuji-cli-upgrade

wuji upgradeは、公式カタログからファームウェアを取得し、接続中のトランスポート経由で書き込み、デバイスごとのレポートを表示します。デバイスは自動的に再起動し、新しいファームウェアで起動します。

考え方：スコープ × アクション

呼び出しはすべて、対象デバイスを指定するスコープと、実行内容を指定するアクションの組み合わせです。引数なしでwuji upgradeを実行するとヘルプが表示されます。暗黙的に書き込みが行われることはありません。

スコープ（デバイスが1台だけ接続されている場合はそのデバイスがデフォルト）：

• --all — 検出されたすべてのデバイス（最新ファームウェアのみ）
• --type <TYPE> — 指定した種類のすべてのデバイス（pingのDevice Typeと一致、大文字と小文字は区別されません。例：--type wuji_glove）
• --sn / --address / --handedness — 1台のデバイス。他のコマンドと同じセレクターです

アクション：

• --check — 更新の概要を表示します。読み取り専用で、任意のスコープで使用できます
• （アクションフラグなし）— スコープ内のデバイスを最新のカタログバージョンにアップグレードします
• --to <VERSION> — 指定したカタログバージョンをインストールします
• --file <PATH> — ローカルのファームウェアファイルを書き込みます
• -l / --list — ファームウェアカタログを表示します。読み取り専用です

バージョンを指定できるのは1種類のデバイスのみなので、--to、--file、--listには単一種類のスコープが必要です。--typeまたは1台のデバイスを指定してください。--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

デバイスセレクターを指定しない場合、単一デバイスを対象とするアクションでは、接続されているデバイスが1台だけなら自動的に選択されます。バス上に複数のデバイスがある場合、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のままです）。デバイスがバージョンを報告する場合は、Beforeと同じ値であっても、読み取った値がAfterに表示されます。--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 は必須です。ロールバックの対象は常に 1 台のデバイスです。
• 触覚センサーが現在オンラインのハンドはロールバックできません。デバイスを変更する前にリクエストが拒否され、レポートの Status は failed になります（問題を解決した後であれば、安全に再試行できます）。
• ロールバック先は選択できず、そのバージョンは操作が完了するまでわかりません。確認プロンプトには、その旨が明記されます。
• レポートの Status は ok、failed、または unknown です。unknown は、ロールバックが確定した終了状態に至らなかったことを意味します（デバイスの一部を確認できなかった、読み戻しで切り替えを検証できなかった、またはロールバック後のバージョンを読み戻せなかったなど）。やみくもに再試行しないでください（再試行に成功すると、元のバージョンに戻ってしまいます）。まず wuji ping --sn <SN> で実際のバージョンを確認してください。レポートのステータスが ok になるのは、デバイスから読み戻したロールバック後のバージョンが記載されている場合に限ります。