Bermuda - Bluetooth/BLE Room Presence and tracking [custom integration]

[bernieq (bq)]

Wow, what a thread. I’ve finally caught up with the present after mention of the project in a Whirlpool topic a few days ago - an entertaining read & a teriffic project.

Whilst reading, I had a thought about the multi-floor issue. Perhaps you could designate a floor attribute for each proxy. Usually there are limited paths to move between one floor and the next. Two special ‘level’ proxies, one near the top of the stairs and another at the bottom, could determine that the tracked device is on floor 1 or 2. Then, Bermuda could be restricted to only report proxies from that floor (& both ‘level’ proxies) until the other ‘level’ proxy detects the tracked device.

Bermuda would always know what floor the device is on (not so good if the tracked device falls out of the window … but I guess you have other things to worry about then : )

[agittins (Ashley Gittins)]

Wow, my last post on Whirlpool was around 2013! Fixed that now

@bernieq

Perhaps you could designate a floor attribute for each proxy. Usually there are limited paths to move between one floor and the next. Two special ‘level’ proxies…

Interesting idea! It’d be a fair bit of site-specific logic to embed into the integration, but could be something one could implement with templates, if sufficiently motivated.

[GeorgeCastanza]

Is it possible to exclude certain bluetooth addresses? I have a lot of Hue lights that constantly broadcast, and it’s not possible to turn off bluetooth (in Hue)

[jackjourneyman (Jack)]

There’s always a very long list of available Bluetooth devices (over 1000 on mine - the neighbours must have lots of gadgets), but you select the ones you want to track. Bermuda does a pretty good job of putting them at the top of the list.

[tim.plas]

I’ve got an idea, but don’t have a way to test it: Would it be possible to use 3d printing filament that is conductive (yeah that’s a thing) to create “wave guides” to provide “beam shaping”, to restrict BT/BLE to cover only desired areas of a room?

I first considered that for mmWave presence sensors, to eliminate motion/presence sensing from undesired areas like ceiling fans. But principle should still be the same for BT/BLE, to shield RF in specific directions.

[RN-Say]

I attempted to setup my M5 stack devices as bermuda proxies using minimal configuration. I found it to be a challenge, so I thought I would share in case someone else tries the same thing or has suggestions for improvement.

Here’s what I settled on for my S3 Lites:

packages:
  Bermuda.esp32: github://agittins/bermuda-proxies/packages/bermuda-proxy-esp32-s3-full.yaml
  
esphome:
  name: esp-guest-node-1
  friendly_name: ESP Guest Node 1
  name_add_mac_suffix: "False"

And here is where I ended up for my Atom Echos:

packages:
  Bermuda.esp32: github://agittins/bermuda-proxies/packages/bermuda-proxy-esp32-orig-full.yaml

substitutions:
  name: esp-kitchen-node-2
  friendly_name: ESP Kitchen Node 2
  name_add_mac_suffix: "False"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

[agittins (Ashley Gittins)]

New Release: v0.8.0 Known Unknowns

This is a significant release that fixes a collection of issues introduced in v0.8.0 as well as some significant fixes for recent iOS devices, where devices would appear as Unknown for various periods or on various user actions on the device (this particular issue will be at least “much improved”, if not fully solved).

Huge thanks to all those who assisted in the various “iOS devices going unknown” threads with sharing observations and diagnostic data - an incomplete list being @oneseventhree, @drothenberger, @erkr, @hajar97, @faz17, @kbrohkahn, @rccoleman, @jksmurf, @milandzuris, @iotola, @rickt123, @bill7531 and more, and particularly to @tylerhartwig for some very decisive debug capture!
Thanks also @jackjourneyman for documentation improvements.

Breaking Change

The keys and some value formats in the bermuda.dump_devices service call / action have changed.

I’m not aware of any integrations that use this service, so this will probably only affect you if you have used the service yourself to create template sensors etc.

Of particular note is that the scanners sub-key on each device is now called adverts, better reflecting the actual content, and the key is now device-address__scanner-address (a tuple, internally). Advertisement data has also been moved around inside the advert dict, and values are now generally expressed in hex rather than bytes, because python’s bytes format causes my retinas to slowly detach with a scraping noise that is decidedly disconcerting.

Significant Changes

Area and Distance sensors now use the icon defined for the current Area (it’s not the most significant change, but it’s the most easily noticed!)

Bermuda takes a different approach to gathering the advertising data from scanners, and now has visibility of all packets reported by scanners rather than just those collated by the Bluetooth manager. The scanning logic has been cleaned up and refactored.

New scanner handling avoids problems caused by previously storing state / a list of scanners. Scanner discovery is now cleaner and more robust and should respond better to realtime changes in device addition/removal. This also means that the Distance to... (and Unfiltered Distance to...) sensors now get created on-demand as new scanners appear / are removed, which should lead to less surprising behaviour.

Device pruning has been improved and several bugs fixed. This resolves some issues with CPU and memory use increases, as well as IRK or iBeacon devices going unknown prematurely due to over-zealous pruning.

Area detection tweaks continue, with improvements to more stable transitions from an Area to Unknown, without glitching to another area in the interim.

Bermuda now includes an IRK implementation in parallel to Private BLE Device that tracks full history for valid MACs (a resolvable MAC can be used for up to 15 minutes) and allows Bermuda to validate prior MACs after a reload and respond to advertisements that might not be forwarded to the entire Bluetooth stack.

Ignore zombie advertisements reported from BlueZ (local USB or onboard BLE adaptors) for paired but absent devices (rssi -128)

Significant code restructuring, cleanups etc. Fixed some asyncio usage issues.

Sub-millisecond startup time by placing startup io tasks in separate thread

Full changelog: Release Known Unknowns · agittins/bermuda · GitHub
Release Discussion: Known Unknowns · agittins/bermuda · Discussion #578 · GitHub
Upgrade via HACS strongly recommended!

[agittins (Ashley Gittins)]

v0.8.3 Security Release: fix for Download Diagnostics

Version 0.8.2beta3, released May 20 2025 at 02:46 GMT, as well as v0.8.2 contain a bug that exposed IRKs and some temporary MAC addresses in the “Download Diagnostics” without being redacted.

Who is affected

If you posted the results of a “download diagnostics” from Bermuda to a public place, while running v0.8.2beta3 or v0.8.2, your file will have contained the unredacted form of any IRK devices you have configured. These are the devices defined in your “Private BLE Device” integration.

If you have not uploaded a “Download Diagnostics” in the last three days you are not affected, but should update to v0.8.3 as soon as practicable.

Consequences

• The temporary MAC addresses are only in use for 15 minutes from their first creation, so are extremely unlikely to present any privacy risk.
• The IRKs are more permanent, and with access to these another party would be able to identify your device’s bluetooth traffic as belonging to your device. Obviously this risk has a limited physical radius which reduces the exposure risk.

Mitigation

All github issues in the Bermuda repository that contain a diagnostic from the affected versions have been scrubbed already. Only a single instance of this has been found.

If you have uploaded a diagnostics to another public area in the last 3 days please seek to remove that posting if possible.

If mitigation of exposure is not possible, for phones a factory reset and restore may re-set the IRK of the device.

Other changes in this release

• fix: redactions in irk_manager diagnostics @agittins (#582)
• improved performance of redact_data, to reduce instances of system lockup during download diagnostics
• logic improvements to redact_data which may have caused corner-case lockups of download diagnostics
• removed logging for “no ads for metadevice…”
• reduced logging for “scanner stamps for … should not go backwards” to debug, as it seems they often have significant jitter (fixes #580 )

[c-mholm (Carl-Mikael Holm)]

Hello

How do I know which one of these is my iphone, so I could start testing? The mac addresses make no sense.

[gregrs (Greg)]

iPhone MAC addresses are randomised for security, so you need to use the Private BLE Device integration to add to Bermuda. See How to get the IRK (Identity Resolving Keys) for iOS, Android etc · agittins/bermuda Wiki · GitHub

[jackjourneyman (Jack)]

There’s also a post here:

Getting the IRK for your phone

Devices that use Bluetooth randomised mac address security and an IRK (Identity Resolving Key) - which is to say all smartphones - can be tracked by installing the Private BLE Device integration which is part of HA core. You will need to tell the integration the IRK for each of your devices. This is how to find the IRK for your phone - it works for Android and Apple devices. Summary: Install Arduino IDE (Integrated Development Environment) on a desktop or laptop - Windows, Linux or Mac; it…

[c-mholm (Carl-Mikael Holm)]

Thanks for your reply and help. I managed to add my own iphone and apple watch to the Private BLE Device integration. With the help of my MacBook i managed to get the IRK for the two devices.

[c-mholm (Carl-Mikael Holm)]

Thanks for this tutorial Jack. Seems like I should be able to add my wife’s iphone and kids android devices with this well written arduino totorial. Will test it out later today.

[david1 (David)]

I just installed esp home on a few devices, however the latest one I configured it does not seem to work… I can see it in ESPHome builder, but I am sitting right next to it yet its reporting to the other one that’s 50’ away…

im sitting in my office, the esp device is less then 2’ from me…

[qJake]

This is an interesting project!

I’ve been running ESPresence for about a year but haven’t done anything with it - because the location tracking indoors is wildly unreliable.

For example, I’ll be sitting still at my desk in my office, with my ESP32 radio within arm’s reach, and my location will bounce to nearby rooms randomly.

This is obviously completely unreliable for automations. And you might say, “Just apply a smoothing/average function to it!” Yes, but then there is an increased delay between when I enter a new room, and that room reporting as my “location” in Home Assistant.

I think this is partly due to the complex and outdated configuration page for the ESPresence devices.

I’ve even resorted to listening to the raw MQTT distance messages from all of my radios and attempted to create a template entity which attempts to guess the room I’m in based on those sensors and some sample data I took, but that didn’t really significantly improve the problem.

Does Bermuda make any significant improvements in these areas?

[NathanCu (Nathan Curtis)]

It’s better than espresence for me Jake. But you will still need smoothing. I was able to get it to lock pretty reliably to my most used sensors now im working on extending to true trilat by overlaying BPS and bayeseans like Jack recommended

[agittins (Ashley Gittins)]

Hi Jake, if you have a proxy quite close, and the distance ratio to the next proxy is large, and your proxies use my recommended settings, and the device you are tracking transmits reliably, I’d expect tracking to be pretty solid.

And if it isn’t, you can upload a diagnostics to a GitHub issue and i can analyse what’s not working.

The distance ratio is important though, if your proxy is one metre away, and the one in the next room is only 2m away you might find it pretty glitchy.

I can’t advise on how it compares to espresense as such, a number of folk have found it better, but I’m sure there are those who’ve gone back, as well

[agittins (Ashley Gittins)]

Hi David! If you do a “download diagnostics” and send me the results (you can create an issue on the github or email me [email protected]) I can take a look and see what’s going on

Oh, you could also try the latest beta version, it has some fixes for when Bermuda stops tracking a given scanners’ adverts.

[GeorgeCastanza]

Is it possible to disable a specific bluetooth scanner device from Bermuda? I have 7 around the house, but recently installed the Switchbot integration, and it’s having difficulties sending commands (I suspect), due to reading all my Hue devices. I’d like to have 1 bluetooth device reserved for other stuff apart from Bermuda. TIA.

[mhoogenbosch (Martijn Hoogenbosch)]

From what I have read you can only disable the ble device from the Bluetooth integration, but then it won’t send ble commands to Switchbot either I guess.

How do you know for sure this is the problem? In my experience Switchbot I just slow.