Upgrade your first device's firmware with BB-Eco
A firmware upgrade puts the device into bootloader mode and writes flash memory. Pulling the power, network cable, or killing BB-Eco mid-transfer may brick your Brainboxes device. Set aside ten uninterrupted minutes per device before you start — and if anything does go wrong, Brainboxes support is always at hand.
This guide walks you through a single-device firmware upgrade end-to-end, with the safety checks that prevent the most common ways an upgrade goes wrong.
Before you start
- The device is online in BB-Eco (see Discover your first device).
- Wired Ethernet is preferred. Most upgrades over Wi-Fi finish without trouble, but a flaky wireless link can occasionally stall the BOOTP/TFTP transfer — wired removes that variable.
- You're on the same Layer 2 broadcast domain as the device. BOOTP cannot cross routers.
- You have administrator (or sudo) access on your computer. Firmware upgrades require binding to UDP ports 67 and 69, which are privileged.
- You've reviewed the device's release notes (linked in BB-Eco when an update is available).
Step 1 — Open the device's Firmware tab
- In the BB-Eco dashboard, click the device card to open its detail panel.
- Click the Firmware tab.
- If a newer firmware version is available, BB-Eco displays an Update available banner with the current version, the latest version, and the release notes.
If the banner doesn't appear, click Check for updates. BB-Eco contacts the Brainboxes manifest service (or uses its local cache if you're offline) and reports back within a few seconds.
Step 2 — Read the pre-flight result
Click Upgrade. BB-Eco does not start writing firmware yet — it runs a pre-flight check first:
- Spawns its elevated helper process (you'll see your OS password dialog).
- Verifies the elevated process can bind UDP ports 67 (BOOTP) and 69 (TFTP).
- Runs a short UDP connectivity test to the device to confirm a firewall isn't silently dropping packets.
- Cross-checks the firmware compatibility against the device's reported model and MCU.
The result appears in a dialog with one of three outcomes:
| Verdict | Meaning | What to do |
|---|---|---|
| Compatible (green) | Safe to upgrade | Click Proceed. |
| Compatible (with warnings) (amber) | Upgrade will work, but BB-Eco found something worth flagging — typically a Wi-Fi or VPN interface, or a much-older firmware version | Read every warning. Resolve the ones you can (move to wired Ethernet, disable VPN). Proceed only when you understand each. |
| Incompatible (red) | The firmware doesn't match this device | Click Cancel. Do not override. |
Wi-Fi upgrades usually go fine in our testing. Occasionally a flaky wireless link drops a TFTP packet at the wrong moment and stalls the transfer. If you're on Wi-Fi and the pre-flight flags it, you can proceed; switching to wired Ethernet just removes one variable from the equation.
Step 3 — Watch the upgrade progress
After you proceed, BB-Eco transfers the firmware to the device using BOOTP and TFTP. Progress is reported in real time:
Typical timings:
- ED devices complete in 2–4 minutes (two stages: Bootloader, FirmwareApp).
- ES devices complete in 3–6 minutes (two or three stages: optional Flash, Bootloader, FirmwareApp).
- BB devices — coming soon. BB-Eco will use the on-device Linux package manager once that integration ships.
- SW devices — coming soon. Managed-switch firmware upgrades will run over Secure Shell (SSH) once that integration ships.
You'll see brief gaps between stages — that's the device rebooting into the next stage. This is expected. Don't panic if the progress bar pauses for up to thirty seconds between stages.
When the upgrade completes, the device reboots and BB-Eco re-discovers it on the network with the new firmware version showing on its card.
What to do if something goes wrong
| Symptom | What it usually means | Recovery |
|---|---|---|
| Pre-flight warns "BOOTP/TFTP packets could not reach this application" | Firewall is blocking ports 67/69 | Allow BB-Eco through your firewall; retry pre-flight |
| Progress bar stalls at 0% during BOOTP stage | Device didn't see your BOOTP reply | Check cable, confirm same subnet, retry |
| Progress bar stalls mid-transfer for over 60 seconds | TFTP packet loss or firewall interference | Wait two minutes — TFTP retries are slow. If still stalled, see below |
| BB-Eco reports "Stage timed out" | Final ACK never arrived | Stage may have completed anyway — wait for the device to reboot, then check the firmware version |
| ED device dashboard card shows "Stuck in upgrade" | Device is in bootloader awaiting BOOTP | A dedicated Recover a stuck device how-to is in the works during beta. ED devices broadcast BOOTP indefinitely while stuck and can usually be recovered by re-running the upgrade |
| ES device went silent and doesn't reboot | Older ES firmware versions don't include a recovery bootloader, so an interrupted upgrade can leave the device unrecoverable over the network | Contact support — recent ES firmware adds recovery support, and the support team can advise on what's possible for your specific model and version |
Going further
- Bulk-upgrade firmware across many devices — one workflow, dozens of devices
- Recover an ED device stuck in bootloader — for ED devices that didn't complete an upgrade
- Run BB-Eco without internet access — air-gapped factory floors and Cyber Essentials admin accounts
More resources
- BB-Eco overview
- Discover your first device
- Legacy ED firmware upgrade with Boost.IO Manager — if you're not yet ready to switch to BB-Eco
- Legacy ES firmware upgrade with Boost.LAN — same, for ES gateways