Skip to content

Runbook: Bermuda BLE presence + proxy watchdog

Bermuda (stacks/ha/homeassistant/config/custom_components/bermuda, v0.8.7) estimates room-level presence from BLE advertisements heard by scanners (Bluetooth proxies). Deployed 2026-07-20.

Scanners

Scanner Type Notes
hci0 (local) host BlueZ adapter MediaTek radio; shared with matter-server (--bluetooth-adapter 0)
ESPHome bluetooth_proxy nodes remote one per area; each must have an Area assigned

Good trilateration wants ≥3 scanners hearing a device at once, and Bermuda raises a repair for any scanner without a Home Assistant Area.

"Device not advertising" is usually a dead SCANNER, not the device

A healthy scanner shows a sub-second "last advertisement"; minutes/hours means that proxy has stopped delivering, so devices near it read as "not advertising". Check per-scanner freshness (Bermuda config-flow table, or query it — HA_TOKEN is in stacks/ha/.env):

curl -s -XPOST -H "Authorization: Bearer $HA_TOKEN" \
  "http://localhost:8123/api/services/bermuda/dump_devices?return_response"

Each scanner's last_seen (monotonic) compared to time.monotonic() = seconds since its last advert. sensor.bermuda_active_proxy_count vs ..._total_proxy_count is the quick health signal.

ESPHome proxy reliability (learned the hard way)

  • wifi: power_save_mode: none on every proxy node — LIGHT sleep dropped the API connection and staled the advert subscription.
  • Don't run bluetooth_proxy on overloaded nodes. The bedroom m5stick-c wedged for 17 h (bleak_esphome … "stale advertisement subscriber") while still API-connected; it was stripped to a proxy-only config.
  • The wedge is HA-side. Rebooting/reflashing the node does not restore delivery — the fix is reloading the node's ESPHome config entry in HA: 
    curl -s -XPOST -H "Authorization: Bearer $HA_TOKEN" \
  http://localhost:8123/api/config/config_entries/entry/<ENTRY_ID>/reload
    If a node stays dead after the reload, reboot it after the reload — or it's a genuinely fragile proxy host (the Apollo MTR-1's mmWave + BT is one).

Watchdog

binary_sensor.bermuda_proxies_degraded (on when active < total proxies, delay_on 10 min) drives the FMM Problem Watchdog blueprint → phone alert. See packages/house/bermuda_watchdog.yaml and blueprints/automation/fmm/problem_watchdog.yaml. Note: it catches a proxy that has fully dropped, not one that is "registered but silent".

Open items

  • Living Room has no BLE coverage. The Apollo MTR-1 is an ESP32-C3 (single core; WiFi + BLE share one radio) and can't sustain bluetooth_proxy alongside its mmWave workload — it delivered zero adverts and watchdog-rebooted under load (device info: proxy flags 255 yet 0 log lines in 30 s). bluetooth_proxy was removed from it (2026-07-20, reflash to apply). Add a dedicated wall-powered ESP32/S3 proxy in the room for coverage.
  • Own phones/watches rotate their BLE MAC (RPA); register them via IRK / private_ble_device so they stop appearing as "not advertising".