Skip to main content

General troubleshooting with BB-Eco — logs, filters, and contacting support

When something doesn't work in BB-Eco — a device that won't appear, a config that won't apply, an upgrade that stalls — the first stop is the Logs panel under Settings. This guide covers what's in there and how to get the right detail to Brainboxes support quickly when you need help.

BB-Eco Settings → Logs panel showing structured log entries with timestamp, level, category, and message — discovery, comms, XML parsing, and a warning about a device timeout — with the verbose toggle enabled

Open the Logs panel​

  1. Click the Settings (≡) icon in the left sidebar.
  2. The Logs tab is selected by default.

The panel streams live — new entries from the sidecar appear as soon as they're emitted, no manual refresh needed.

The toolbar above the log stream is where you narrow the firehose:

Logs panel toolbar close-up: Streaming indicator, an All levels dropdown, an All categories dropdown, a search input, a Verbose checkbox, then Clear, Export Logs, and Email Brainboxes Support buttons

What's in a log entry​

Two example entries — one informational, one warning:

Two log entries close-up. First: '15:42:01.845 DEBUG Xml — Parsed devinfo.xml: 1 model, 12 IO lines, fwApp 2.0.1' showing a successful parse. Second: '15:42:02.410 INFO Catalogue — Firmware update available for ED-549: 2.0.1 → 2.1.0' showing an informational catalogue update.

Each row has four fields:

FieldExample
Timestamp2026-05-05T15:42:01.823Z (UTC, ISO 8601)
LevelDebug, Information, Warning, Error, Critical
CategoryDiscovery, Comms, Xml, Cgi, Auth, Upgrade, RealTimeIO, Catalogue
MessageHuman-readable description with relevant IPs, ports, and paths

Categories are stable identifiers — Discovery always means SSDP / mDNS / WS-Discovery activity, Comms is HTTP traffic to devices, Upgrade is anything related to firmware transfer.

Toggle verbose mode​

By default, the panel shows Information and above. Toggle Verbose at the top of the panel to include Debug entries — needed for diagnosing tricky issues like SSDP packet flow or per-block TFTP progress.

Verbose mode is non-persistent — it doesn't survive a restart, and toggling it on doesn't slow the app down (the logs were already being written; the UI just shows more of them).

Filtering: the four controls​

The toolbar has four filters that compose:

  1. Level filter — drop-down: All, Debug, Information, Warning, Error. Picking Warning shows warnings and above.
  2. Category filter — drop-down listing every category that's appeared in this session. Useful for narrowing to one subsystem.
  3. Search box — substring match across the entire entry (timestamp, level, category, and message). Case-insensitive. Useful for tracking a specific IP or MAC across many categories.
  4. Verbose toggle — described above.

Filters apply live; the entry list updates as you type.

Copy individual log lines​

Click any log row to copy that single entry to the clipboard, formatted as:

[2026-05-05T15:42:01.823Z] [Information] [Discovery] Discovered ED-549 at 192.168.1.101 (00:0A:4F:06:4A:EE)

Useful when you're chatting with a colleague or pasting one specific line into a ticket. No need to copy-paste the whole window.

Export the full log​

The Export logs button at the bottom of the panel writes all visible entries (after filters) to a .log file. The file picker defaults to your desktop — pick a location and BB-Eco saves the formatted text.

Export uses the filtered list, so if you've narrowed to Category: Upgrade and Level: Warning+, the export contains only those entries. Clear filters first if you want everything.

Email Brainboxes support directly​

The Email Brainboxes Support button next to Export is a one-click escalation:

  1. Click Email Brainboxes Support.
  2. BB-Eco exports the current logs to a file.
  3. BB-Eco opens your default email client with:
    • To: [email protected]
    • Subject: Technical support issue with BB Eco
    • Body: A pre-filled template prompting you to describe what you tried, what you expected, and what happened
  4. Attach the exported log file to the email before sending — BB-Eco can't attach it for you (browsers and OSes don't expose that capability), so the email body reminds you.
  5. Send.

Including the logs in your first email saves a round-trip — the support team can diagnose most issues from the log file plus your description without needing follow-up requests for diagnostic detail.

Where the log files live on disk​

Even without exporting, BB-Eco writes daily-rotated log files to disk. Useful when something happened earlier and you've since restarted the app:

OSPath
macOS~/Library/Logs/bb-eco/
Linux~/.config/bb-eco/logs/
Windows%APPDATA%\bb-eco\logs\

The Open Log Folder button in the panel opens the directory in your file manager. Tooltip on the path label offers to copy it to the clipboard.

You'll see two files per day:

  • bb-eco-YYYY-MM-DD.log — the unprivileged sidecar (discovery, configuration, monitoring)
  • bb-eco-upgrade-YYYY-MM-DD.log — the elevated sidecar (firmware upgrades, owned by root on macOS / Linux)

The elevated log is owned by root because the elevated sidecar runs as root to bind UDP 67 / 69. To read it on macOS / Linux: sudo less ~/Library/Logs/bb-eco/bb-eco-upgrade-2026-05-05.log.

What's stripped before logging​

BB-Eco's logger redacts the most common forms of sensitive data before writing:

  • Passwords in CGI requests are replaced with ***
  • Authentication headers are stripped
  • Configuration values that contain credentials (admin passwords, MAC filters with personal info) are masked

This means logs are safe to share with support without redacting them yourself. Double-check before sharing if the device you're diagnosing has sensitive data in custom fields like device name or location — those aren't automatically redacted.

Common workflows​

"My device isn't appearing"​

  1. Filter Category: Discovery, set verbose on.
  2. Look for SSDP M-SEARCH sent on... — that confirms BB-Eco is broadcasting.
  3. Look for NOTIFY received from... or SSDP response from... — that confirms the device is replying.
  4. If you see only the M-SEARCH and no responses, it's a network issue — see BB-Eco finds no devices on my network.

"An upgrade failed"​

  1. Filter Category: Upgrade, set verbose on.
  2. Find the stage at which it failed (BootloaderUpgrade, FirmwareAppUpgrade, etc).
  3. Look for the surrounding Comms entries — TFTP block ACK timing, BOOTP reply confirmations.
  4. Use Email Brainboxes Support to send the file with a description of which device, which firmware version, and what stage failed.

From the CLI​

The CLI carries the same diagnostics it bundles for the desktop app:

# Single-shot system + network snapshot for a support ticket
bb-eco diagnostics --output diagnostics.json

# Same, plus a fresh discovery sweep so support sees what's
# currently visible on the LAN
bb-eco diagnostics --output diagnostics.json --discover

The output is the same shape the desktop's Email Brainboxes Support button attaches — sidecar version, OS version, network interfaces, recent log slice, optional discovery results. Pass it to support unedited; the same redaction rules apply as for the desktop logger (passwords + auth headers are masked before write).

Combine with --verbose on any command to get a higher log level temporarily:

bb-eco discover --verbose 2> discover.log

stderr carries the verbose log; stdout is the discovery output. The pattern works for every command — separate the diagnostic stream from whatever you're actually scripting against.

See the bb-eco diagnostics CLI reference for every flag.

"Configuration apply silently doesn't change anything"​

  1. Filter Category: Cgi, set verbose on.
  2. Each setting change shows the CGI request and the device's HTTP response code.
  3. A 200 response means the device acknowledged the change. A 401 means an auth issue. A 4xx other than 401 usually means the device rejected the value.

More resources​