Skip to main content

Bulk-upgrade firmware across many Brainboxes devices with BB-Eco

Coming after the 1.0 release

The bulk-upgrade dialog described here is not yet available in the BB-Eco public beta. The desktop-app dialog component exists in the codebase but isn't wired into the UI, and the matching sidecar handler hasn't shipped. We're publishing this how-to ahead of time so the workflow is documented when the feature lands. For now, upgrade devices one at a time using the single-device upgrade flow, or script bb-eco upgrade in a Bash loop against a list of IPs.

Avoid interrupting a bulk upgrade

Once it ships, bulk upgrades multiply the risk of an interrupted transfer. Do not put your laptop to sleep, switch networks, kill BB-Eco, or unplug any device mid-transfer. Set aside enough uninterrupted time before you start — typically 3–6 minutes per device, run sequentially.

This guide covers upgrading firmware on many Brainboxes devices in a single workflow with the BB-Eco desktop app. Use it when commissioning a site, refreshing a fleet to a new release, or upgrading every ES device on a production line at once.

Before you start​

  • BB-Eco is installed (see the BB-Eco install guide).
  • All target devices are visible in the BB-Eco dashboard. (See Discover your first device if any are missing.)
  • All target devices are on wired Ethernet, on the same Layer 2 broadcast domain as your computer.
  • You have administrator (or sudo) access on your computer — bulk upgrades need the same elevated privileges as a single upgrade.
  • You've reviewed the firmware release notes for the target version and understand whether it requires a factory reset on any model.

Step 1 — Select the devices​

  1. In the dashboard, switch to list view for easier multi-select on long lists.
  2. Hold ⌘ (macOS) or Ctrl (Windows / Linux) and click each device you want to include. Use Shift+click for ranges.
  3. Confirm the selection count in the dashboard footer.
Filter first, then select

If you're upgrading every ED device but leaving the ES gateways alone, set the family filter to ED before selecting. The selection count then matches what's visible.

Step 2 — Open the bulk upgrade dialog​

With your selection in place, open the Bulk Upgrade dialog from the dashboard toolbar. BB-Eco shows a per-device row listing model, current firmware, and the latest firmware available from the manifest.

Each row also shows a compatibility status — same three verdicts as the single-device pre-flight:

VerdictMeaningWhat to do
CompatibleSafe to upgradeLeave checked
Compatible (with warnings)A warning was flagged — typically Wi-Fi, VPN, or a much-older firmwareRead the per-device warnings; uncheck or fix
IncompatibleFirmware doesn't match this modelBB-Eco unchecks the row automatically

Step 3 — Confirm and watch​

  1. Review the per-device rows. Anything you don't want to upgrade in this batch — uncheck.
  2. Click Start bulk upgrade.
  3. Enter your administrator password when prompted (single prompt for the whole batch — BB-Eco reuses the elevated session).

BB-Eco runs the upgrades sequentially, not in parallel. Each device:

  1. Goes through its own pre-flight check.
  2. Transfers firmware via BOOTP/TFTP.
  3. Reboots into the new firmware.
  4. Reports success or failure to the bulk dialog.

Watch the aggregated progress and the per-device status. Devices that fail one stage do not block the rest of the batch — they're flagged and the queue continues.

After the batch​

When the queue completes, BB-Eco shows a summary: how many succeeded, how many failed, and which ones need attention. Any device showing Stuck or Failed should be triaged before you leave the site:

  • Stuck (ED): see Recover an ED device stuck in bootloader.
  • Failed before transfer: usually a firewall or VPN issue — re-run the upgrade on that device alone after fixing the network.
  • Failed mid-transfer (ES): ES devices have no recovery bootloader. Contact support for physical recovery.

When not to bulk-upgrade​

  • Mixed device families with overlapping but distinct firmware images. Run one batch per family.
  • Devices with active production traffic. Schedule the bulk upgrade for a maintenance window.
  • An air-gapped site that hasn't pre-cached the firmware. See Air-gapped firmware upgrades (coming soon during beta) for the offline workflow.

More resources​