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

Start by getting the dashboard into a view that makes the candidate devices easy to identify. The orange Update pill on the device card is the cue that a newer firmware is available for that model:

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

When the dialog ships, every device row shows the same pre-flight verdict shape as a single-device upgrade — model, target firmware, compatibility result:

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:

Verdict	Meaning	What to do
Compatible	Safe to upgrade	Leave checked
Compatible (with warnings)	A warning was flagged — typically Wi-Fi, VPN, or a much-older firmware	Read the per-device warnings; uncheck or fix
Incompatible	Firmware doesn't match this model	BB-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.

Bulk upgrade from the CLI (available now)

While the desktop dialog is gated to post-1.0, the CLI handles the same workflow today. Loop bb-eco upgrade over an IP list:

#!/usr/bin/env bash
set -uo pipefail   # NOT -e — we want to keep going if one device fails

# 1. Pre-cache every firmware once, so the loop body has no network dependency
bb-eco upgrade --download-all

# 2. Build the IP list from a live discovery, filtered to ED devices only
mapfile -t IPS < <(bb-eco discover --json | jq -r '.[] | select(.family=="ED") | .ipAddress')

echo "Upgrading ${#IPS[@]} ED devices sequentially..."

ok=0; fail=0
for ip in "${IPS[@]}"; do
  echo ""
  echo "=== $ip ==="
  if sudo -n bb-eco upgrade "$ip" --latest; then
    ok=$((ok+1))
  else
    fail=$((fail+1))
    echo "FAILED: $ip — leaving it for manual review"
  fi
done

echo ""
echo "Summary: $ok OK / $fail failed (of ${#IPS[@]} total)"

Notes:

• sudo -n uses a cached sudo token. Run sudo -v once at the start of the script so the loop doesn't pause on each device for a password prompt.
• --download-all once, before the loop. This populates the firmware cache from update.brainboxes.com so each bb-eco upgrade call is a pure LAN operation. Especially valuable on slow uplinks or air-gapped runs.
• Sequential, never parallel. Each upgrade binds UDP ports 67/69 — running two at once collides on the listening socket. Always serialise.
• Don't kill the script mid-transfer. Same brick-risk rule as the single-device flow. If you absolutely must stop, let the current device complete first (Ctrl+C interrupts after the current loop iteration).

For a richer report, swap the success/fail counts for a CSV that records per-device duration + final firmware version — bb-eco firmware status --json after each upgrade gives you what landed.

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

• Upgrade your first device with BB-Eco — the single-device walkthrough this guide builds on
• Recover an ED device stuck in bootloader — for devices that fail mid-batch
• Legacy ED firmware upgrade with Boost.IO Manager — if you're not yet on BB-Eco
• Legacy ES firmware upgrade with Boost.LAN — same, for ES gateways