github agittins/bermuda v0.8.0-rc1
v0.8.0-rc1 Area Stability, System Stability
on GitHub

latest releases: v0.8.5, v0.8.5-beta3, v0.8.5-beta2...
5 months ago

This release contains a lot of changes, but mostly behind-the-scenes stuff. Some significant items include:

  • Homeassistant minimum version is now 2025.3 due to required APIs.

Area Stability

  • The way that the closest area is established has been revamped and a new set of "rules" applied. The result is that Bermuda is now FAR LESS TWITCHY in general, and particularly in "marginal" areas between proxies.
    • This includes some "hysteresis", meaning that if the area just changed, it will resist switching back again in a short time, even if the distances are close. Bermuda now examines the percentage difference between readings, so longer distances can vary more without triggering an area change, but also helps ensure that distance changes are "significant" before adopting them.
    • Bermuda also examines recent history when considering an area change, and can avoid switching if the current distance is uncharacteristic, say if we usually read close but we have a one-off long reading.

As always, there are trade-offs between being "twitchy" and being "sluggish". Bermuda aims for twitchy, because you can always tame that down by using a smoothing template if you want, but you can't restore responsiveness once it's smoothed out. The exact values used for thresholds in this will be tweaked over the next several releases, and if some are found to be useful as per-site tuneables they will be exposed as settings. I think the changes have left things a bit over-smoothed now, so you might wish to reduce the smoothing samples setting if you want more responsive area changes.

IRK Devices going "Unknown"

This was a bug that I first noticed when my Android phone upgraded to 15, but I suspect it might also be the root cause of the Apple newer iOS devices going "unknown" for long periods as well - but I can't confirm this as I don't have any Apple devices that new. Fingers crossed! The issue was that Bermuda only used the most-recent IRK-based MAC address, but devices may use multiple irk MAC addresses for different services, so the transmissions might be interleaved, or the most recent address might be discarded. Bermuda now keeps looking for packets from previously-known IRK addresses, which has completely resolved the Android Unknown issue in my testing, and I have hopes for the iOS issues. Feedback welcome!

A side-benefit of the changes required also mean that iBeacons that use multiple UUIDs (such as one when stationary and another when moving) now have initial support #236

System Stability - memory use, CPU use

A few issues were found that affect system load, some of which are likely to be the cause of performance issues on various installs, although NUCs seem to be over-represented in this set (maybe simply due to their popularity):

  • Area-based calculations are now only performed for tracked devices (ie, those chosen in Configure Devices), saving some cycles, especially in areas with lots of bluetooth traffic.
  • Some event listeners were not properly cleaned up after a reload, causing some odd behaviour and also extra cpu/memory load
  • Moved to new API version of _discovered_device_timestamps in bluetooth backend
  • Bermuda prunes its list of discovered addresses periodically. Some bugs in this were found, which was causing extra data to be persisted indefinitely. This would present as increased memory usage and cpu time.
  • Avoid re-processing old advertisements and abort a processing run if a previous run is detected as still active

Altogether this should hopefully fix (or greatly improve) issues with increasing memory and cpu use, and issues with crashes in extremely busy BLE environments (such as adjacent high-rise apartment buildings). Testing and reports welcome!

Device names and related changes

A few changes may cause device and entity names to change. This may require your automations, scripts etc to be updated, and also require changes if you are relying on the output of the bermuda.dump_devices action/service. Most of these changes have actually been aimed at making future changes less likely.

  • User-set names should now be honoured more reliably
  • Internally bermuda can now track the sources of names and make better decisions when one changes
  • ESPHome Bluetooth Proxies since 2025.3 now report their BLE MAC address as the scanner source, and the Bluetooth integration creates a new HA device with that address, linked-to-but-separate-from the existing ESPHome device entry. Shelly scanners will also have two HA "devices", one in the Shelly integration and one in the Bluetooth integration. Shelly's and ESPHome prior to 2025.3 will still appear with their WiFi MAC address (or Ethernet MAC if hardwired), but ESPHome devices will switch to their BLE MAC after being flashed with 2025.3+. I know that's a lot of explaining... the result is that: Bermuda now knows this, and takes care to:
    • treat the WiFi MAC (espressif's "base mac") as the primary identifier for scanner identification
    • track the BLE MAC address for linking the HA Bluetooth device and for recognising packets sent from that proxy via BLE
    • accommodate each combination of version and connection method - including Ethernet-connected devices.

It's possible that this might cause some device/ entity renaming, as the MAC address is regularly used as the unique_id for entities. This release should be the stabilising release for that issue, and should guard against this happening again.

  • You can set names and Areas of Bluetooth Proxies in either their native integration's page, or in the Bluetooth page. Bermuda honours user-defined names in the Bluetooth integration first, then falls back to the ESPHome / Shelly integration, so you can choose to maintain your details in either (or both!).

  • Because of the MAC address changes, the Distance to... and Unfiltered Distance To.. sensors might have been duplicated if you have ESPHome devices with 2025.3 and have run one of the v0.8.0-alpha versions of Bermuda. This and future releases of Bermuda should prevent this in future.

  • Proxy names in general no longer have their MAC address suffixed, so will show as Dining Room Proxy instead of Dining Room Proxy [aa:bb:cc:dd:ee:ff:aa:bb]

  • (only relevant for users of the dump_devices service or direct internal access): the device structure internally now keys scanner advertisements with a tuple of (device_mac, scanner_mac) to support multiple active MAC addresses for a single device, such as Android15+

Changes

  • refactor!: fixed naming of devices for consistency @agittins (#465) fixes #426 #405
  • feat: Restore Area Last Seen on HA restart, fix Area not timing out @agittins (#467)
  • fix: handle malformed iBeacon packets fixes #466 @agittins (#468)
  • fix: stale listeners causing oddities. @agittins (#508)
  • fix: IRK devices going Unknown @agittins (#509)
  • Significant Area matching improvements @agittins (#511)
  • fix: GLOBAL sensors now have MEASUREMENT state class, so history will render as a Graph
  • fix: diagnostics crashes due to binary data in bluetooth advert data
  • fix: diagnostics redaction issues, now handles more MAC address formats and separators
  • fix: crash caused by enormous per-scanner calibration offset #497
  • fix: FutureWarning: BaseHaRemoteScanner._discovered_device_timestamps is deprecated
    fixes #503 and #493

📦 Dependencies

Check out latest releases or
releases around agittins/bermuda v0.8.0-rc1

Don't miss a new bermuda release

NewReleases is sending notifications on new releases.

Get notifications