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:

┌────────────────────────────┐
│  BB-Eco desktop app        │
│  (Electron + React UI)     │
└──────────────┬─────────────┘
               │ JSON-RPC over stdin/stdout
               │ + WebSocket for streaming events
┌──────────────▼─────────────┐
│  BB-Eco sidecar            │
│  (.NET, native AOT)        │
└──────────────┬─────────────┘
               │ SSDP / mDNS / HTTP / BOOTP / TFTP
┌──────────────▼─────────────┐
│  Your Brainboxes devices   │
└────────────────────────────┘
  • 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 devinfo.xml over TCP 80Identifies 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)Linux package manager over SSHBB-400 runs Linux; firmware ships as .deb packages

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.

Why upgrades ask for your password​

BOOTP and TFTP listen on UDP ports 67 and 69. On every desktop OS those are privileged ports — they need root or administrator rights to bind. Rather than running the whole app as administrator (which would be a security overreach), BB-Eco spawns a second, elevated sidecar on demand:

  1. You click Upgrade.
  2. BB-Eco asks the OS to spawn the sidecar binary with elevated privileges. macOS shows the system password prompt; Windows shows a UAC dialog; Linux uses polkit or sudo-prompt.
  3. The elevated sidecar binds the privileged ports, runs the BOOTP/TFTP transfer, and exits when the upgrade completes.
  4. The unprivileged main sidecar talks to the elevated one over WebSocket — same protocol it uses internally, just locked down with a per-process token and an Origin allowlist.

You see one password prompt per upgrade session, not one per device — the elevated sidecar stays alive across the batch.

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 hundreds of devices with the bulk-apply dialog.

Where things live on disk​

PathContents
macOS ~/Library/Application Support/bb-eco/Config, device cache, firmware cache
macOS ~/Library/Logs/bb-eco/Daily-rotated log files
Linux ~/.config/bb-eco/Config, device cache, firmware cache, logs
Windows %APPDATA%\bb-eco\Config, device cache, firmware cache, logs

The firmware cache is the same path the elevated sidecar reads from but never writes to — that asymmetry prevents root-owned files appearing in your home directory after an upgrade.

More resources​

Tags:
Last updated on