Skip to main content

BB-Eco finds no Brainboxes devices on my network — troubleshooting checklist

If BB-Eco's dashboard stays empty after launch and you know there are Brainboxes devices on your network, work through this checklist in order. The first three items account for the vast majority of cases.

BB-Eco's empty-dashboard state. Centre of the screen shows the Brainboxes logo, a 'No devices found' headline, a small spinner with the message 'Searching for devices on your network…', and a row of network-interface chips below — Wired (loopback, en0, bridge100, bridge101), WiFi (en0), and two VPN tunnels detected (utun2, ppp0). A purple 'VPN detected' banner offers two CIDR scan suggestions to find Brainboxes devices on those VPN subnets, followed by a checklist (firewall on UDP 1900, same-subnet check, manual IP entry) and an Add Device button.

The empty-state panel itself is informative — it shows every network interface BB-Eco can see, calls out any VPN tunnels (with one-click CIDR-scan suggestions for those subnets), and reminds you of the three most common causes. If a VPN suggestion is showing, that's almost certainly the issue — see Step 3 below.

1. Confirm the device is powered and connected​

  • The device's power LED is on.
  • The Ethernet activity LEDs flicker periodically.
  • A direct ping from your computer to the device's IP succeeds.

If the device is unresponsive at the network level, the rest of this guide doesn't apply — start with the device's own quick start guide.

2. Confirm you're on the same Layer 2 broadcast domain​

BB-Eco's auto-discovery uses SSDP (UPnP) for ED, ES, and managed SW devices, which relies on UDP multicast (239.255.255.250:1900). For BB-400 Industrial Edge Controllers it additionally listens on mDNS (224.0.0.251:5353), which sometimes survives where SSDP doesn't. Either way, multicast does not cross routers without explicit configuration, so BB-Eco only sees devices on the same broadcast domain — the same VLAN, the same physical switch.

SetupDiscovery works?
Laptop and device on the same desk-side switchYes
Laptop and device on the same office VLANYes
Laptop on Wi-Fi, device on wired Ethernet through different switchMaybe — depends on the wireless access point bridging
Laptop on a different subnet (cross-VLAN)No — use manual entry
tip
Verify with tcpdump

On macOS or Linux, sudo tcpdump -n -i <iface> 'udp port 1900' should show SSDP traffic from your devices. No traffic on the wire means the broadcasts aren't reaching you — a switch or router config issue, not a BB-Eco issue.

3. Disable any VPN client​

VPN clients commonly block LAN broadcasts when active, even when configured for "split tunnel" mode. Quick test: disconnect from the VPN, restart BB-Eco, and check whether devices appear.

If they do, you have two options for production work:

  • Toggle the VPN off while using BB-Eco on the local network.
  • Add devices manually by IP — manual entry uses unicast HTTP, which the VPN typically allows.

4. Allow BB-Eco through your firewall​

Windows Defender Firewall​

  1. Open Windows Security → Firewall & network protection → Allow an app through firewall.
  2. Find BB-Eco in the list. If it isn't there, click Allow another app and add the executable.
  3. Tick both Private and Public networks.
  4. Restart BB-Eco.

macOS Application Firewall​

  1. System Settings → Network → Firewall → Options.
  2. Confirm BB-Eco is listed and set to Allow incoming connections.
  3. Restart BB-Eco.

Linux (ufw, firewalld, or equivalent)​

Allow inbound UDP on port 1900 (SSDP) and port 5353 (mDNS, for BB-400 discovery). For ufw:

sudo ufw allow 1900/udp
sudo ufw allow 5353/udp

Most desktop Linux distributions don't run a host firewall by default — only worry about this if you've enabled one explicitly.

5. Confirm multicast isn't disabled at the switch​

In some industrial networks, multicast snooping is disabled or aggressively pruned. Check with your network administrator if every other check passes and discovery still doesn't work.

A network test for the brave:

# Listen for SSDP broadcasts on the wire
sudo tcpdump -n -i <iface> 'udp port 1900' -c 5

# In another terminal, force a manual M-SEARCH
echo -e 'M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nMAN: "ssdp:discover"\r\nMX: 1\r\nST: ssdp:all\r\n\r\n' | nc -u -w 2 239.255.255.250 1900

Brainboxes devices respond to ST: BrainboxesED:1 and ST: BrainboxesES:1. If you see no responses on the tcpdump, the broadcasts aren't reaching your laptop.

6. Check the BB-Eco sidecar status​

The status indicator at the bottom-left of the dashboard should show Sidecar running within a few seconds of launch. If it shows Sidecar not running:

  1. Settings → Logs — look for sidecar startup errors. Filter for category Comms or Discovery.
  2. Toggle Verbose on to see more detail.
  3. Restart BB-Eco. If the sidecar still won't start, restart your computer to clear any stuck child processes.

7. Send diagnostics to support​

If none of the above works, generate a diagnostics bundle:

  1. Settings → Logs → Export diagnostics, or
  2. From a terminal: bb-eco diagnostics --output diagnostics.json --discover

Attach diagnostics.json to a support ticket along with a description of your network topology (single switch / multiple switches / cross-VLAN / VPN active).

More resources​