# Bermuda: how BLE proxy RSSI translates into room presence in Home Assistant > Bermuda is a MIT-licensed Home Assistant custom integration that assigns BLE devices to rooms by comparing signal strength from ESPHome or Shelly bluetooth proxies. Room-level area tracking works in v0.8.7; map-based triangulation is listed as a future goal and is not yet implemented. **agittins/bermuda** — Bermuda Bluetooth/BLE Triangulation / Trilateration for HomeAssistant - Repository: https://github.com/agittins/bermuda - Stars: 2,082 · Forks: 81 - Language: Python - License: MIT - Published: 2026-10-09 · Updated: 2026-10-09 · Language: en - Canonical page: https://hysenlabs.com/projects/agittins-bermuda ## Room presence rather than home/away is Bermuda's actual target Home Assistant ships with presence detection that tells you whether a device is home or away. That binary answer covers locking doors and turning off lights when the last person leaves. What it cannot tell you is which room the person is in, which is the trigger point for a different class of automations: adjusting the thermostat only in the room someone entered, starting music only where someone is sitting. Bermuda takes the problem one level further by assigning each BLE device to the area of the nearest bluetooth receiver. The project qualifies this with "working reasonably well" rather than claiming precision, which is the honest way to describe probabilistic radio-based positioning. Anyone building automations on top of Bermuda's area sensors should factor in the occasional misread, particularly near walls between two rooms where signals from two proxies are nearly equal. The intended user is an existing Home Assistant owner who wants indoor location without deploying a dedicated tracking infrastructure. The only extra hardware required is bluetooth proxy devices, either ESP32 boards flashed with ESPHome or Shelly Plus units with bluetooth proxying enabled. ## RSSI readings from multiple bluetooth proxies determine which room wins The core mechanism is signal strength comparison. Each BLE-capable device periodically broadcasts an advertisement packet. Every bluetooth receiver within range hears that advertisement and measures how strong the signal was when it arrived. This strength reading is the RSSI (received signal strength indication), and it drops as distance increases. Bermuda collects RSSI readings from all of your bluetooth proxies for each tracked device. It then applies an attenuation model: you configure an rssi reference level (the expected RSSI at a known distance) and an environmental attenuation factor (how quickly signal drops in your specific building materials). A max tracking radius setting caps how far Bermuda considers a proxy to still be relevant. With those three values tuned, Bermuda converts each proxy's RSSI into a distance estimate and assigns the device to the area of the proxy with the smallest estimate. This is trilateration, not triangulation. Triangulation requires angle measurements. Trilateration requires only distance estimates from at least two or three points. With a single proxy per room, Bermuda degrades to a simpler comparison: whichever receiver hears the device loudest is declared the nearest one. Adding more proxies per room improves the geometry and reduces misclassification when walls attenuate signals unevenly. ## HACS is the install path; no package manager or clone is needed Bermuda installs through the Home Assistant Community Store, known as HACS. The README presents a HACS badge link that opens the repository screen directly inside a running Home Assistant instance. There is no pip install, no git clone, and no shell command involved in the install step. The underlying requirements.txt file pins homeassistant to 2025.3.0 as a minimum, and the pyproject.toml targets Python 3.12 (py312), so both the platform and runtime floors are spelled out. Once the HACS install completes, the integration appears under Settings, Devices & Services. Pressing CONFIGURE opens a field where you enter bluetooth device addresses or names. Two entity types then appear for each chosen device: a sensor showing the current area and a sensor showing the estimated distance. A device_tracker entity is also created, which is the entity type Home Assistant uses for person-level home/away tracking, letting you wire the room-level data into person automations alongside the presence system. For proxy hardware, the README identifies ESPHome devices with the bluetooth_proxy component enabled as the primary path, and Shelly Plus or later with bluetooth proxying turned on as an alternative. Both paths timestamp advertisement packets, which is the technical requirement for multi-proxy distance comparison to work accurately. ## iBeacon UUIDs and IRK let Bermuda follow phones that rotate their MAC address Tracking a modern phone with BLE is complicated by MAC address randomization. Both Android and iOS rotate the hardware address a phone advertises, so a naive BLE scanner sees what appears to be a new device every few minutes and loses the thread of any individual phone's movements. Bermuda handles this through two separate mechanisms. The first covers iBeacon-compatible devices: Bermuda reads the UUID embedded in the iBeacon advertisement, which stays fixed even as the MAC address rotates. Android phones running the Home Assistant Companion App broadcast in iBeacon format, so that path covers Android tracking without additional setup. The second mechanism covers IRK, the Identity Resolving Key. A phone that has been registered in the Private BLE Device core component shares a key that lets the bluetooth driver verify the device's identity from any MAC address it currently uses. Once that registration is done in Private BLE Device, Bermuda picks up the device automatically and creates sensors for it. For iOS, which rotates MAC address aggressively, this IRK path is the more reliable route for continuous tracking. ## The bermuda.dump_devices service exposes internal state, but its format is not stable Bermuda registers a Home Assistant service named bermuda.dump_devices. Calling it with no parameters returns a full JSON and YAML dump of the integration's internal tracking state: all known bluetooth receivers, all tracked devices, and the distance reading Bermuda computed from each receiver for each device. The README suggests using this service to "work out what's going on" when device placement looks wrong. Two filter parameters narrow the output. The addresses parameter accepts one or more MAC addresses or iBeacon UUIDs and limits the dump to just those devices. The documentation points to Home Assistant's Developer Tools, Services page for the full parameter list. The important caveat is in the README: "bear in mind that the format might change in any release, and won't necessarily be considered a 'breaking change'." Anyone who writes Home Assistant template sensors that read fields from this dump should expect to audit their templates after every Bermuda update. Bermuda exposes the dump as a debugging and introspection tool; it is not positioned as a stable API surface. Using it for production automations is possible, but the maintenance cost belongs to whoever writes those templates. ## USB Bluetooth misses advertisement timestamps, degrading area estimation ESPHome proxies and Shelly Plus devices timestamp each BLE advertisement packet before forwarding it to Home Assistant's Bluetooth backend. That timestamp is what allows Bermuda to correlate readings across multiple proxies: an advertisement heard at the same millisecond by three different receivers produces three simultaneous RSSI samples that Bermuda can compare directly. When timestamps differ or are absent, pairing samples across receivers becomes ambiguous. USB Bluetooth adapters plugged into the Home Assistant host machine do not add those timestamps to advertisement data. The README describes this as "not ideal" and explains that USB adapters do not timestamp the packets. The consequence is that simple home/away tracking still works with USB Bluetooth, and Bermuda enables basic Area distance support for USB, but the README is clear that USB is not the recommended path for room-level detection. If your hardware is currently a single USB Bluetooth dongle, Bermuda will function in a limited way but will not deliver the room presence accuracy it achieves with dedicated ESPHome proxies. The practical recommendation from the README is to use ESPHome proxies, with the D1-Mini32 boards mentioned as a cheap option. ## Triangulation on a map is a stated goal in v0.8.7, not a shipped feature The repository is named bermuda and its description says "Bluetooth/BLE Triangulation / Trilateration for HomeAssistant." The README itself says: "(eventually) Triangulate device positions! Like, on a map. Maybe." That parenthetical tone is the honest description of where the feature sits. At v0.8.7, released on 2026-07-11, the integration tracks devices by area, not by coordinates. Placing a device at a map position requires knowing the physical coordinates of each bluetooth proxy and applying math that maps RSSI samples to XY or latitude/longitude. Neither the proxy location input nor the coordinate output is present in the current documentation. The distinction matters when evaluating Bermuda against competing integrations. If your use case is "which room is the phone in," Bermuda delivers that today. If your use case is "show a floor plan with a dot moving between rooms," that is not a current feature. The wiki and community threads are where progress on triangulation would be announced, since the README is not where detailed roadmap discussion lives. ## MIT licence, Python 3.12 target, and last push on 2026-10-05 The repository carries an MIT licence. The LICENSE file at the top level is the authoritative text. MIT is a permissive licence, so using Bermuda in a home or commercial Home Assistant setup carries no licence restrictions beyond attribution. The pyproject.toml sets target-version to py312, which means the code is written and tested against Python 3.12. Home Assistant 2025.3.0 or newer is the floor from requirements.txt. Trying to run Bermuda against an older Home Assistant installation will fail the import check. The last push to the repository was on 2026-10-05. The latest stable release is v0.8.7, tagged on 2026-07-11. The repository is not archived. The README links to GitHub Sponsors, BuyMeCoffee and Patreon for funding, which signals this is a solo maintainer project rather than a team effort. The project has its own Discord server, a Home Assistant community thread described as containing a wealth of user-contributed information, and a wiki that the README identifies as the primary and official documentation source. ## Conclusion Use Bermuda if you run Home Assistant with ESPHome bluetooth proxies or Shelly Plus devices and want room-level device placement. Its iBeacon and IRK support lets it follow Android and iOS phones that rotate MAC addresses. Skip it if your only Bluetooth receiver is a USB adapter, since that path lacks packet timestamps and area detection quality degrades. Skip it also if you expect map-level coordinates: triangulation appears in the project name but is not present at v0.8.7. Before adopting, confirm Home Assistant is at 2025.3.0 or newer, then call bermuda.dump_devices to check that distance readings appear for your actual devices. ## FAQ ### How do I install Bermuda in Home Assistant? The README directs users to install via HACS, the Home Assistant Community Store, using a badge link that opens the repository screen inside a running Home Assistant instance. There is no pip install or command-line step involved. ### What hardware does Bermuda need to track rooms? Bermuda requires one or more bluetooth proxies: ESPHome devices with the bluetooth_proxy component enabled, or Shelly Plus or later devices with Bluetooth proxying enabled in the Shelly integration. A USB Bluetooth adapter on the HA host is also accepted but is described as not ideal because it does not timestamp advertisement packets. ### Can Bermuda track iPhones and Android phones? The README states that Bermuda supports iBeacon devices including those with randomised MAC addresses such as Android phones running the HA Companion App, and supports IRK via the Private BLE Device core component for iOS devices. Once a device is set up in Private BLE Device, Bermuda sensors are added automatically. ### What is the bermuda.dump_devices service? It is a Home Assistant service that returns a full dump of Bermuda's internal tracking state, including all known receivers and the distance readings for each tracked device. The README warns that the format may change in any release without being treated as a breaking change. ### Does Bermuda support triangulation to show device position on a map? Not at v0.8.7. The README lists map-based triangulation as a future goal with the phrase "(eventually) Triangulate device positions! Like, on a map. Maybe." The current release tracks which area or room a device is in, not its X/Y coordinates. ## Sources - [agittins/bermuda on GitHub](https://github.com/agittins/bermuda) - [Issues](https://github.com/agittins/bermuda/issues) - [License: MIT](https://github.com/agittins/bermuda/blob/main/LICENSE) - [README](https://github.com/agittins/bermuda/blob/main/README.md) - [Releases](https://github.com/agittins/bermuda/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agittins-bermuda