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.

What's in a log entry​

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.

"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​