Recover an ED device stuck in bootloader with BB-Eco
This guide recovers a Brainboxes ED (Ethernet Remote I/O) device that's stuck in bootloader after an interrupted firmware upgrade. ED devices broadcast BOOTP indefinitely while stuck, which makes them recoverable without physical access.
The desktop-app recovery dialog described later in this article is not yet wired into the BB-Eco public beta UI. The component exists in the codebase but the entry-point (a Recover button on the stuck device's card) hasn't shipped. For the beta, run recovery from the CLI — sudo bb-eco upgrade --recover listens for the stuck device's BOOTP broadcasts and pushes a fresh image. The CLI path is stable and used by the team for in-house recoveries today; the desktop UI lands ahead of GA.
This guide does not apply to ES (Ethernet-to-Serial) devices. Older ES models have no recovery firmware — an interrupted upgrade may require physical RMA. If your stuck device is an ES, contact Brainboxes support.
How to tell a device is stuck
After an interrupted firmware upgrade, a stuck ED device looks like this in BB-Eco:
- The device card shows an amber Stuck badge instead of the normal green Online indicator.
- The device's IP appears unreachable — pinging it returns no response.
- Opening the device's web UI fails to connect.
You can also confirm via the OS: sudo tcpdump -i <iface> -n udp port 67 will show the device emitting BOOTP requests every few seconds.
Before you start
- The stuck device is powered on and physically connected to the same Layer 2 LAN as your computer. (BOOTP cannot cross routers, so a desk-side switch is fine but a routed network is not.)
- BB-Eco is installed and the dashboard is running. (See Install BB-Eco.)
- You have administrator/sudo access on your computer.
- You have the correct firmware file for this device on hand. The cached firmware in BB-Eco's local cache works if it was last downloaded for the correct model.
The recovery flow does not validate device family/model the way the live upgrade flow does. Picking firmware for a different model writes the wrong image to flash and bricks the device permanently. Double-check the model on the stuck device's casing before selecting firmware.
Step 1 — Run bb-eco upgrade --recover
From a terminal on the same Layer 2 network as the stuck device:
sudo bb-eco upgrade --recover
The CLI binds UDP port 67 (BOOTP) and 69 (TFTP), then waits for the next BOOTP broadcast from a stuck Brainboxes device. Recovery typically picks up within seconds. When a stuck device is heard, bb-eco prompts you to confirm the device's MAC and select firmware:
- Confirm the MAC matches the device on your bench (a sticker on the casing).
- Pick a
.efwfrom your firmware cache, or pass--firmware <path>ahead of time. - The transfer starts on the next broadcast and runs through the same Bootloader → FirmwareApp stages as a normal upgrade.
Recovery typically completes in 2–4 minutes. The device reboots once and reappears in the BB-Eco dashboard with the freshly installed firmware version.
Step 2 — Watch from the BB-Eco dashboard (optional)
Keep BB-Eco open while the CLI does its work. Once recovery completes, the device's Stuck badge flips to Online and its detail panel re-populates from devinfo.xml — confirmation that the device is back to normal.
If recovery fails
| Symptom | Likely cause | Next step |
|---|---|---|
| BB-Eco doesn't see the device's BOOTP requests | Cross-subnet, on a wireless interface, or VPN active | Move to the same wired LAN segment, disable VPN, retry |
| Recovery starts but stalls during BOOTP stage | Firewall blocking ports 67/69 | Allow BB-Eco through your firewall, restart, retry |
| Recovery starts but stalls during TFTP stage | Packet loss on the network | Try a different switch port or a direct cable |
| Recovery completes but device immediately gets stuck again | Wrong firmware image | Confirm model and firmware variant — try a different cached version or download a fresh copy |
If the device repeatedly gets stuck after recovery with the right firmware image, contact support — there may be a hardware fault.
Why ED devices recover but ES devices don't
ED devices ship with a recovery bootloader that broadcasts BOOTP indefinitely when the main firmware is corrupt or absent. As long as the device has power and a network connection, it advertises itself and waits for a BOOTP reply with new firmware. This makes recovery a network operation, not a physical one.
ES devices don't have this safety net — once the bootloader is corrupted, the device goes silent. There's no broadcasted request for BB-Eco to respond to.
More resources
- Upgrade your first device with BB-Eco — the safe upgrade flow that avoids stuck-device situations
- Bulk-upgrade firmware with BB-Eco — for upgrading many devices at once
bb-eco upgradeCLI reference — every flag including--recover- Brainboxes ED Range — Ethernet Remote I/O product overview