Skip to main content

How BB-Eco works

This page covers what's happening under the hood when BB-Eco discovers a device, edits its configuration, or applies a firmware upgrade. You don't need any of this to use BB-Eco — but it's useful background when troubleshooting, integrating, or convincing your security team that the app does what it says.

Two processes, one app​

BB-Eco is split into two cooperating pieces:

  • The desktop app (or the bb-eco CLI binary) is the surface you interact with — dashboard, dialogs, log viewer.
  • The sidecar is a separate native process that speaks all the on-the-wire protocols. The desktop app launches the sidecar at startup and talks to it over JSON-RPC. The sidecar runs unprivileged so a stray bug can't compromise the rest of the system.

Splitting the network code into a sidecar makes the same engine reusable from the CLI, makes elevation safe (see below), and means a future mobile or web front end can talk to the same sidecar without rewriting the protocol stack.

What's on the wire​

OperationProtocolWhy
Auto-discovery (ED, ES, managed SW)SSDP / UPnP — UDP multicast on 239.255.255.250:1900Brainboxes devices announce themselves the same way printers and Smart TVs do
Auto-discovery (BB-400)mDNS — UDP multicast on 224.0.0.251:5353BB-400 publishes via mDNS in addition to SSDP
Manual add by IPHTTP GET of description.xml, then devinfo.xmlIdentifies the model and capabilities without relying on broadcasts
ConfigureHTTP CGI over TCP 80 (ED, ES, SW) or 5001 (BB)Same endpoints the device's web UI uses — BB-Eco just calls them programmatically
Reboot, locate, factory-resetHTTP CGIOne CGI command per action
Firmware upgrade (ED, ES)BOOTP (UDP 67) + TFTP (UDP 69)Devices enter bootloader mode and listen for a BOOTP reply naming the firmware file
Firmware upgrade (BB-400, SW)—Not yet available; see the compatibility matrix below

Nothing here is new on the wire — Brainboxes devices have spoken these protocols for years. BB-Eco's contribution is wrapping them in a single cross-platform front end with safety checks and bulk operations.

Discovery, end to end​

Discovery is broadcast → response → confirm-with-HTTP. One upnp:rootdevice search reaches every Brainboxes family — ED, ES, BB, and managed SW all answer the standard UPnP search target, and BB-Eco identifies its own hardware from the response. The sidecar also listens passively on the SSDP multicast group, so a device that powers up and announces itself (ssdp:alive) appears without waiting for the next search — and a device that says goodbye (ssdp:byebye) flips to Offline immediately. The HTTP fetch of description.xml and devinfo.xml is what populates the model number, firmware version, and capability list on the device card — without it BB-Eco would only know that something announced itself.

Exactly what BB-Eco can do for each device class — which families support upgrade, recovery, drift detection, templating — is published in the app itself (Settings → About → Feature compatibility) and from the CLI as bb-eco features, straight from the same capability matrix the code enforces.

Why Linux asks for your password (and Windows and macOS don't)​

Firmware transfers run in a second sidecar process dedicated to BOOTP and TFTP, kept apart from the sidecar that does discovery and configuration. The two talk over WebSocket — the same protocol the app uses internally, locked down with a per-process token and an Origin allowlist.

BOOTP and TFTP listen on UDP ports 67 and 69. Whether binding them needs elevated rights depends on the operating system:

  • Windows and macOS — no elevation needed. The transfer sidecar starts unprivileged when the app opens, which is also what lets BB-Eco hear a device stuck in its bootloader from the moment the app is running. On Windows, inbound traffic is admitted by the firewall rule the installer adds once; on macOS by the application firewall's per-app consent.
  • Linux — ports below 1024 are privileged, so BB-Eco spawns the transfer sidecar with elevated rights only when you start an upgrade or recovery, via the system's password prompt. You see one prompt per upgrade session, not one per device — the elevated sidecar stays alive across a batch and exits when it's done.

In every case the rest of BB-Eco keeps running unprivileged; nothing about discovery, configuration or the desktop app itself ever needs administrator rights.

Configuration as code​

BB-Eco can capture a device's full configuration as a JSON template:

  • Export writes the live config to a file you can check into version control.
  • Apply pushes a template to a device, with a dry-run mode to preview changes.
  • Diff compares a live device against a template and reports drift — useful for fleet audits.

Templates are plain JSON. Edit them in your editor of choice, store them with the rest of your infrastructure, review them in pull requests, and apply them across a fleet by looping bb-eco template apply over your device list.

Where things live on disk​

OSConfig and settingsFirmware and template cachesLogs
macOS~/Library/Application Support/bb-eco/~/Library/Caches/bb-eco/firmware/ and .../templates/~/Library/Logs/bb-eco/
Linux~/.config/bb-eco/~/.cache/bb-eco/firmware/ and .../templates/~/.config/bb-eco/logs/
Windows%APPDATA%\bb-eco\%LOCALAPPDATA%\bb-eco\firmware\ and ...\templates\%APPDATA%\bb-eco\logs\

The desktop app and the CLI share all of these, so a firmware image cached by bb-eco upgrade --download-all is the one the app installs. On Linux the elevated transfer sidecar reads the firmware cache but never writes to it — that asymmetry prevents root-owned files appearing in your home directory after an upgrade.

More resources​

Tags:
Last updated on