bb-eco upgrade
Upgrade firmware on a Brainboxes device
Usage
bb-eco upgrade [<device> [<firmware-file>]] [command] [options]
Arguments
| Name | Description |
|---|---|
<device> | IP address, MAC address, or device name |
<firmware-file> | Path to the .efw firmware file |
Options
| Option | Description |
|---|---|
--check | Check for updates without applying |
--csv | Output in CSV format |
--download | Download firmware to local cache (no sudo required) |
--download-all | Download ALL firmware from manifest for air-gapped prep |
--force | Skip confirmation prompt |
--json | Output in JSON format |
--latest | Upgrade to the latest cached firmware (requires sudo on Linux) |
--preserve-config | Preserve device config during upgrade |
--probe | With --recover: answer BOOTP and report what the stuck device asks for, WITHOUT sending firmware |
--recover | Enter recovery mode for stuck devices; pass the .efw path to skip the prompt |
--timeout <timeout> | Override default timeout in milliseconds |
--vendor-identity <vendor-identity> | With --recover: identity string (e.g. F0001V08.33ED588T) offered to an ED device whose BOOTP request has a blank vendor area (identity block erased). Overrides the .efw-derived fallback; never overrides an identity the device reports itself |
--verbose | Enable verbose/debug output |
-?, -h, --help | Show help and usage information |
Subcommands
| Command | Description |
|---|---|
all | Update every discovered ED/ES device to its latest cached firmware, one device at a time. |
Examples
Check whether a newer firmware exists for a device (no changes are made):
bb-eco upgrade 192.168.0.63 --check
Device is up to date (v8.25).
Upgrade a device to the latest published firmware for its model. The transfer uses BOOTP/TFTP on UDP ports 67/69; on Linux those ports are privileged, so prefix the command with sudo there. Windows and macOS need no elevation:
bb-eco upgrade 192.168.0.63 --latest
Upgrade from a specific firmware file instead of the online manifest:
bb-eco upgrade 192.168.0.63 ED-549_V8.25.efw
Pre-download firmware for every known model into the local cache — useful before visiting an air-gapped site:
bb-eco upgrade --download-all
Updating every device at once
upgrade all finds every ED/ES device on the network, shows a plan (which devices will be updated, which are skipped and why), asks you to type CONFIRM, then flashes them one at a time - the upgrade ports (UDP 67/69) allow only one transfer per machine. Devices that are already current, have no cached image, need a factory reset, or are in use by another host are skipped and listed in the final report. As with a single upgrade, prefix with sudo on Linux only:
bb-eco upgrade all
3 device(s) to update, 2 skipped.
Model IP MAC Current Target Action
ED-588 192.168.0.63 00:0A:4F:05:F7:CA 8.25 8.33 Update
ED-549 192.168.0.64 00:0A:4F:06:4A:EE 8.25 8.33 Update
ES-522 192.168.0.70 00:0A:4F:05:28:DB 4.69 7.02 Update
ED-560 192.168.0.65 00:0A:4F:05:B1:10 8.33 - Skip: AlreadyLatest - already on 8.33
ED-004 192.168.0.66 00:0A:4F:05:E0:FF 8.30 - Skip: ThirdPartyConnections - 192.168.0.9:9500, 0, 00:12:40, Modbus
Type CONFIRM to update 3 device(s): CONFIRM
[1/3] ED-588 00:0A:4F:05:F7:CA: starting (about 5 min left)
[1/3] ED-588 00:0A:4F:05:F7:CA: BootloaderUpgrade 12%
...
When a device fails, the batch pauses and asks whether to continue with the remaining devices; --on-failure continue or --on-failure stop decides in advance (a redirected stdin or --json always stops). Exit code 0 means every device was updated or skipped; 1 means at least one device failed or was not reached.
Rehearse the whole flow without touching a device, or script a failure to see how the report looks:
bb-eco upgrade all --dry-run --force
bb-eco upgrade all --dry-run --force --dry-run-fail 00:0A:4F:05:F7:CA=committed
Use --devices bench.json (the test-devices.json schema) to name the devices instead of discovering them, --allow-factory-reset to include images that reset the device to factory settings, and --json for a machine-readable report. Every option is listed on the bb-eco upgrade all page.
Recovering a stuck device
If an upgrade was interrupted, the device sits in its bootloader broadcasting BOOTP requests. Ask a stuck device what it wants without sending anything (again, sudo on Linux only):
bb-eco upgrade --recover --probe
Then re-flash it (the firmware file must match the model and MCU class):
bb-eco upgrade --recover ED-549_V8.25.efw
See the device recovery guide for the full walkthrough, including the --vendor-identity option for ED devices whose identity block was erased.
Never interrupt a running upgrade — power loss or a killed transfer leaves the device in its bootloader until it is recovered.
This page is auto-generated from the live CLI help text. Do not edit by hand - re-run node scripts/gen-cli-reference.mjs after changes. Example sections are maintained in docs/cli-examples/ in the bb-eco repo.