Troubleshooting

Bermuda is quite simple conceptually ("Use signal strength and math to localise bluetooth devices") but for various reasons becomes a fairly complex beast by the time things are implemented. Some things that cause this are:

• Homeassistant has very particular ways that it thinks about and does things, plus supports a legacy of previous ways it thought about and did things
• The developer has half a life time (at most, hopefully) of different ways, and is new to HA and relatively new to python.
• Each layer in the stack (physical bluetooth devices, esphome, linux, blueZ, python, HA, Bermuda) overloads the terminology of just about everything, making it really hard to accurately talk about things without adding clarification. For example, you have a physical bluetooth "device". The Bluetooth spec might call that a "coordinator" or "peripheral" instead. But HA also has things called co-ordinators, and things called devices, and it's neither of those. Internally, Bermuda calls things "device"s, but what it means by that is "a mac address, or an iBeacon UUID+major+minor, or an IRK (Private bluetooth device) key" etc. So it can get really confusing when talking about "devices" or "sensors" when troubleshooting.

So, it can be quite helpful to take a methodical approach to troubleshooting issues so that you have clarity about what aspects or layers you are looking at, and where issues might be hiding.

Information Gathering

Bermuda tries to find as much info for you as it can. The first page of the CONFIGURATION flow will give you some quick diagnostics. Go to "Settings", "Devices and Services", "Bermuda" then "CONFIGURE". You should see something like this:

Actually, hopefully you'll not see any skull-and-crossbones! This page tells you how many bluetooth devices Bermuda can see, and how many "proxies" or "scanners" you have set up in HA. It will also let you know when the last advertisement was received from each scanner, so you can tell if some or all of them are actively reporting data. In the example above we can see that 12 out of 24 devices appear active (this is good - as long as "some" appear active, that's good, and the inactive ones are possibly old addresses no longer being used, or devices that have appeared but since gone out of range, etc. The number of active and present scanner devices should be equal - there's no good reason for a scanner to not be active. The table shows that the Prox-test scanner in this case has not reported any bluetooth advertisements for 41 seconds! This number should be between 0 and 3 seconds. If all scanners have that (and will therefore have check-marks) then your proxy->HA->Bermuda setup looks OK.

The next few steps can be a bit intimidating, so feel free to skip to Device and Scanner counts below - if things look OK there you can be pretty sure your general setup is probably OK, and you'll only need to dig around in the esphome/ha layers if you have specific issues with particular devices.

Sniffing the Air

Mobile phone apps like NRFConnect can be super helpful, because they directly show you what a physical bluetooth device is sending out through the air, well before any of the complexities of a HA bluetooth stack come into play. It is available for both Android and iOS. This is usually about as close to the physical device you can get, short of doing some electronics.

If you can not find your physical device in an app like NRFConnect, then there is no way that HA or Bermuda is going to find it, either.

ESPHome

You can use logging on the esphome device to see what it is seeing, but this is probably not really necessary in most cases, because the link between ESPHome and HA is pretty solid, in that if anything is getting through, you can be pretty sure that everything is getting through. Also, enabling logging on the esphome might actually alter the nature of the problem, since the device is already quite busy just doing bluetooth stuff, and adding logging as well can further stretch the system resources. Just make sure you have the recommended ESPHome settings and you'll typically be OK.

HomeAssistant

• You can "Enable Debug Logging" on the ESPHome integration. This will cause the HA logs to include information about all of the bluetooth advertisements received from esphome bluetooth proxies. When you turn debug logging off, your browser will prompt you to save the generated logs. You could also watch the logs in realtime if you are able to ssh into your HA server (I use docker logs --tail=80 -f homeassistant which works if you are using HAOS or a typical docker setup).

• If you have a local bluetooth adaptor installed, you should see the "Bluetooth" integration in "Settings", "Devices and Services". This integration has a "Download Diagnostics" option which includes a full dump of the received BLE advertisements, which is exactly the source that Bermuda uses for all of its work.

Device and Scanner counts

In versions v0.6.8 and after (and main from July 12, 2024) Bermuda's configuration dialog will display how many scanners it can see, how many bluetooth devices it can see, and how many of those are "active", meaning they have timestamps less than 10 seconds old. This can be helpful to know if your bluetooth backend is working properly.

• Go to "Settings", "Devices and Services", "Bermuda"
• Click CONFIGURE
• Note the text at the top of the dialog
• You can just close the dialog at that point, you don't need to go through the "Submit" steps.

Screenshot:

If the device or scanner counts look off, Bermuda will give some hints as to what you can do about it. Generally, it will boil down to checking your HA bluetooth config, ESPHome Config and Shelly bluetooth proxy settings.

Download Diagnostics

The diagnostics function (added to main July 12, 2024, present in versions >= v0.6.8) gives you a json file containing specifics about how your Bermuda installation is configured and also the current internal state of the integration (list of devices, their properties etc). The information is "redacted", meaning that all the MAC addresses are replaced with non-identifying names to guard your privacy. This is intended to make the file safe to post publicly online, but you are still advised to look through the file in case you have device names or other features that disclose information you would rather protect.

Rather than simply replacing the MAC addresses with xxxx or similar, Bermuda assigns each address an identifier (like CONF_DEV_3) with which it replaces each occurrence of that MAC. Bermuda also retains the first and last octet of the original MAC, so that it is not enough to uniquely identify it globally, but should give enough of a clue that you can match that identifier with a known device in your config.

• Go to "Settings", "Devices and Services", "Bermuda"
• Click the "meatballs" menu (3 dots arranged vertically) next to the CONFIGURE button
• Choose "Download Diagnostics"

Screenshot:

Most of the information in the "Download Diagnostics" file is gathered from Bermuda's dump_devices service. You can access this data directly on your system by browsing to "Developer Tools", "Services" and choosing bermuda.dump_devices from the services list. This allows you to view the data directly without redactions.

Specific Common Issues

Why do my bluetooth devices have only the address and no name?

• You can simply rename your entities if you like.

• You can also tell your bluetooth proxies to send an inquiry in response to advertisements, this might cause names to show up. Consider also though that it means while your proxy is asking a device for its name it can't be listening for BLE traffic to proxy. In esphome, this is done by adding active: true to the esp32_ble_tracker section (this is separate from the active property of the bluetooth_proxy section, which controls outbound client connections).

  The default is True, and the templates at Ready-Made Projects also default to True.

  To be explicit in setting the option, the YAML should contain a section like this (there migth be extra paramaters, that's OK):

  esp32_ble_tracker:
    scan_parameters:
      active: True
  

• Also, when you first restart homeassistant after loading the integration it may take a minute or so for the system to collect the names of the devices it sees.

My device bounces between Areas

Causes

A device flipping, bouncing or wandering between areas is a common issue and can be due to several factors:

• Using rssi to measure distances is simply noisy and inaccurate, so we'll always have this issue to some degree.
• Proxies not reporting advertisements regularly. This will cause more distant proxies to "win" the area between updates. This is the most likely cause if the bouncing is persistent and rapid (2 to 30 seconds, say). Any proxy sending updates more than 5 seconds apart is going to cause substandard performance. You can check the hist_interval data in the "download diagnostics" or the action (aka service) response of bermuda.dump_devices to see if this is the cause for you. A nearby device should show intervals up to perhaps 6 - 10 seconds, but hopefully much shorter.
• If your device is a "wearable" or otherwise attached to a mammal, the signal strength will tend to vary a lot, and receivers in different directions will get differing signals due to the body absorbing signals travelling through it (some signal will usually still arrive, but possibly via reflections instead of directly, and at much reduced strength - which means a longer apparent distance).

Solutions

Solutions / work-arounds (depending on the root causes) include:

• For some automations it might make sense to have them only trigger when an area changes "for" at least a given duration. This can help prevent unwanted triggers into (or out of) areas when you don't need the response to be immediate. For example we typically want lights to react immediately and the "cost" of a false positive is typically "low", but if you want to automate a heater or turning on a HVAC zone, it makes sense to wait a bit before "committing" to it.
• Other automations might benefit from combining Bermuda sensors with other sensors. This is where the real power of Home Assistant really comes to bear, so it's worth exploring your options here.
• Throw more proxies at the problem. Multiple proxies in one area increase the chances of a timely update to "win" that area. You effectively multiply the update rate, and also improve the chances of at least one proxy "hearing" an advert, even if the signal is blocked from the other proxies, or they don't happen to be "listening" at that instant. If you have shelly light switches in the walls, make sure they are all configured to act as proxies, the extra functionality is free! The most affordable proxies I'm aware of are D1mini32 boards from AliExpress.
• Improve your proxy's firmware settings. See the notes in the Configuration pages.
• If you are using Shelly devices, it's possible that you have a non-standard BLE script installed, or perhaps multiple BLE scripts installed on the device. Use the latest firmware, and only install the BLE script that comes bundled with the HA Shelly integration - it will automatically install it for you when you configure either Passive or Active Bluetooth Scanning. You could flash esphome on to your Shelly devices instead - you will get better proxy performance but (presumably?) lose official support.
• Check that your wifi network is performing well and fix any issues. The wifi network is how the advertisements get from your proxy back to Home Assistant.
• Increase distances between proxies. If you have two adjacent rooms, avoid putting the proxies on either side of the common wall. Instead, move one or both so that they have more separation, giving them a better chance to get clearly different signal strength readings.
• Wait for trilateration (but still keep deploying proxies in the meantime!). Trilateration will use the signals from all proxies to decide which Area a device is in. Hopefully this will mean much higher accuracy, since Bermuda can then make better choices about device locations under more challenging signal conditions.