Bermuda BLE Trilateration

• Track bluetooth devices by Area (Room) in Home Assistant, using ESPHome Bluetooth Proxies and Shelly Gen2 or later devices.

• (eventually) Triangulate device positions! Like, on a map. Maybe.

What it does:

Bermuda aims to let you track any bluetooth device, and have Home Assistant tell you where in your house that device is. The only extra hardware you need are esp32 devices running esphome that act as bluetooth proxies. Alternatively, Shelly Plus devices can also perform this function.

• Area-based device location (ie, device-level room prescence) is working reasonably well.
• Creates sensors for Area and Distance for devices you choose
• Supports iBeacon devices, including those with randomised MAC addresses (like Android phones running HA Companion App)
• Supports IRK (resolvable keys) via the Private BLE Device core component. Once your iOS device (or Android!) is set up in Private BLE Device, it will automatically receive Bermuda sensors as well!
• Creates device_tracker entities for chosen devices, which can be linked to "Person"s for Home/Not Home tracking
• Configurable settings for rssi reference level, environmental attenuation, max tracking radius
• Provides a comprehensive json/yaml dump of devices and their distances from each bluetooth receiver, via the bermuda.dump_devices service.

What you need:

• Home Assistant. The current release of Bermuda requires at least

• One or more devices providing bluetooth proxy information to HA using HA's bluetooth backend. These can be:

  • ESPHome devices with the bluetooth_proxy component enabled. I like the D1-Mini32 boards because they're cheap and easy to deploy.
  • Shelly Plus or later devices with Bluetooth proxying enabled in the Shelly integration.
  • USB Bluetooth on your HA host. This is not ideal, since they do not timestamp the advertisement packets and finding a well-supported usb bluetooth adaptor is non-trivial. However they can be used for simple "Home/Not Home" tracking, and basic Area distance support is enabled currently.

• Some bluetooth BLE devices you want to track. Phones, smart watches, beacon tiles, thermometers etc.

• Bermuda! I strongly recommend installing Bermuda via HACS:

Documentation and help

The Wiki is the primary and official source of information for setting up Bermuda.

Discussions contain both official and user-contributed guides, how-tos and general Q&A.

HA Community Thread for Bermuda contains a wealth of information from and for users of Bermuda, and is where many folk first ask for assistance in setting up.

Screenshots

After installing, the integration should be visible in Settings, Devices & Services

Press the CONFIGURE button to see the configuration dialog. At the bottom is a field where you can enter/list any bluetooth devices the system can see. Choosing devices will add them to the configured devices list and creating sensor entities for them. See How Do The Settings Work? for more info.

Choosing the device screen shows the current sensors and other info. Note that there are extra sensors in the "not shown" section that are disabled by default (the screenshot shows several of these enabled already). You can edit the properties of these to enable them for more detailed data on your device locations. This is primarily intended for troubleshooting or development, though.

The sensor information also includes attributes area name and id, relevant MAC addresses etc.

In Settings, People, you can define any Bermuda device to track home/away status for any person/user.

FAQ

See The FAQ in the Wiki!

Hacking tips

Wanna improve this? Awesome! Bear in mind this is my first ever HA integration, and I'm much more greybeard sysadmin than programmer, so ifwhere I'm doing stupid things I really would welcome some improvements!

You can start by using the service bermuda.dump_devices to examine the internal state.

Using bermuda.dump_devices service

Just calling the service bermuda.dump_devices will give you a full dump of the internal data structures that bermuda uses to track and calculate its state. This can be helpful for working out what's going on and troubleshooting, or to use if you have a very custom need that you can solve with template sensors etc.

If called with no parameters, the service will return all data. parameters are available which let you limit or reformat the resulting data to make it easier to work with. In particular the addresses parameter is helpful to only return data relevant for one or more MAC addresses (or iBeacon UUIDs). See the information on parameters in the Services page in Home Assistant, under Developer Tools.

Important: If you decide to use the results of this call for your own templates etc, bear in mind that the format might change in any release, and won't necessarily be considered a "breaking change". This is beacuse the structure is used internally, rather than being a published API. That said, efforts will be made to indicate in the release notes if fields in the structure are renamed or moved, but not for adding new items.

Prior Art

The bluetooth_tracker and ble_tracker integrations are only built to give a "home/not home" determination, and don't do "Area" based location. (nb: "Zones" are places outside the home, while "Areas" are rooms/areas inside the home). I wanted to be free to experiment with this in ways that might not suit core, but hopefully at least some of this could find a home in the core codebase one day.

The "monitor" script uses standalone Pi's to gather bluetooth data and then pumps it into MQTT. It doesn't use the bluetooth_proxy capabilities which I feel are the future of home bluetooth networking (well, it is for my home, anyway!).

ESPresense looks cool, but I don't want to dedicate my nodes to non-esphome use, and again it doesn't leverage the bluetooth proxy features now in HA. I am probably reinventing a fair amount of ESPresense's wheel.

Installation

You can install Bermuda by opening HACS on your Home Assistant instance and searching for "Bermuda". Alternatively you can click the button below to be automatically redirected.

You should now be able to add the Bermuda BLE Trilateration integration. Once you have done that, you need to restart Home Assistant, then in Settings, Devices & Services choose Add Integration and search for Bermuda BLE Trilateration. It's possible that it will autodetect for you just by noticing nearby bluetooth devices.

Once the integration is added, you need to set up your devices by clicking Configure in Devices and Services, Bermuda BLE Trilateration.

In the Configuration dialog, you can choose which bluetooth devices you would like the integration to track.

You can manually install Bermuda by doing the following:

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called bermuda.
4. Download all the files from the custom_components/bermuda/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Bermuda BLE Trilateration"

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines

Credits

This project was generated from @oncleben31's Home Assistant Custom Component Cookiecutter template.

Code template was mainly taken from @Ludeeus's integration_blueprint template Cookiecutter User Guide**

---