Skip to content

Home

Jump to bottom
Ashley Gittins edited this page May 8, 2024 · 3 revisions

Bermuda Logo

This Wiki is the official location of the Bermuda documentation.

TL/DR:

  • Install Bermuda in your Home Assistant.
  • Set up some esp32's with bluetooth_proxy.
  • Assign the proxies to "Areas" in HA.
  • (optionally) set up your phones in Private BLE Device
  • Select which Bluetooth devices to track / create sensors for (in "Settings", "Devices & Services", "Bermuda", "Configure")
  • Enjoy each device's:
    • "Home/Away" device_tracker entity
    • "Area" sensors for which room the device is "in"
    • "Area Distance" estimation sensor
    • Extra (disabled by default) sensors for extra nerd points and sweeeet history graphs
    • Increased database size
  • Wait patiently for full 2D trilateration (ie, location-on-a-map) support.

What is Bermuda?

Bermuda is a custom integration for Home Assistant, which lets you track the presence and location of Bluetooth low-energy devices in and near your home.

It runs on your Home Assistant (HA) server and processes the Bluetooth data that HA gathers from other integrations like the ESPHome integration, the Bluetooth integration or from later Shelly devices.

Bermuda tells you which of your devices is "Home", what "Area" (room) they are in, and how far it is from that "Area".

Ultimately, it is planned that Bermuda will give you a "map" of your house, and advise of the positions on that map of each of your devices. While a lofty goal, the current progress is promising.

What do I need?

  • Software:
    • Home Assistant, at least 2023.8, but tracking the latest release or so is strongly recommended.
    • Bermuda, naturally
    • To track devices using IRK (randomised MAC address adverts) like Android and iOS, the Private BLE Device core component, which comes as a part of Home Assistant.
  • Hardware:
    • A machine running Home Assistant and the Bermuda integration. This could be a raspberry Pi, a laptop, a full server or anything in-between.
    • One or more "proxies" (also referred to as scanners):
      • esp32 devices running esphome with the bluetooth proxy configured. This link will help you install directly onto a device with no coding. Common devices are NodeMCU, D1mini32 etc. Note that esp8266 devices do not have bluetooth so are not suitable.
      • Shelly Plus devices or later are able to act as bluetooth proxies to Home Assistant. I have no direct experience with these but others are using them and report good results.
      • A bluetooth dongle attached directly to your HA server. I do not recommend this as your primary bluetooth scanner, and not much effort will be spent troubleshooting these devices. This is because the current bluetooth backend does not report timestamps for advertisements, so it's impractical to include this data when trying to analyse a very time-sensitive set of data points. For basic home/not-home tracking however it may be all you need.

That's it! The more proxies you have, the more accurate and meaningful the data is likely to be.

What can I track?

  • Any BLE (Bluetooth Low-Energy) device that sends advertisements from a single, static MAC address. Cheap bluetooth tags, fitness bands, some watches, maybe your toothbrush, or a Tesla.
  • Android phones via the Private BLE Device component and/or the iBeacon transmitter in the Home Assistant Companion app.
  • Apple phones and tablets via the Private BLE Device component
  • iBeacons with a static uuid/major/minor, even if they have randomised MAC addresses.

Other devices that send from randomised addresses (some watches, AirTags, probably earbuds) can still be localised by Bermuda, but it has no way to individually "identify" them, so can't present them as a known device. The data about them is still available in the backend though, and can be queried via the bermuda.dump_devices service call, if you feel particularly masochistic.

What doesn't work?

A 2D map of your house is not yet a thing. A 3D map is even less of a thing. There are several good discussions about this in the issue tracker and docs, so feel free to read up on what that situation is if you are keen to contribute. We might not be far off the 2D map goal at this stage.

Devices (other than iOS, Androids and iBeacons) that randomise their MAC address are not generally supported. If they have some identifiable aspect it may be possible, but since randomisation is usually aimed at avoiding that it's unlikely.

While the whole thing works (surprisingly well), it's important to have realistic expectations.

The entire circus relies on estimating distances based on how strong the signals are from each device. This is measured using "RSSI" (received signal strength indication), which reported as an integer in dBm typically ranging from something around -20dBm to -100dBm. Readings closer to zero are "stronger" and readings lower are "weaker" (yes, it is confusing). The scale is logarithmic. The readings sort of kinda mostly are proportionate to distance. They are also massively affected by interference, reflections, hairy sacks of water (humans etc), sunspots and the dark, arcane magicks of RF propagation at 13cm wavelengths.

It's a horribly inaccurate and unreliable method of measuring a distance. But is is cheap, which is nice. So, the fact it works at all should be worth your undying praise and adulation, and complaints about lack of accuracy or reliability will be met with the disdainful scorn of a bored teenager. Practical ideas about ways to improve those things will be met with grateful acceptance, though! But please take a look around the previous discussions etc first as a lot of ground has already been covered :-)

How does it work?

This integration uses the advertisement data gathered by your esphome or Shelly Plus bluetooth-proxy deployments into Homeassistant to track (and ultimately) triangulate (more correctly, trilaterate) the relative positions of any BLE devices observed around your home.

For now that means it can tell you which "Area" a device is closest to. In future it's hoped to have it tell you "where" in your home a device is, in relative co-ordinates (ie, a map).

Note that this is more properly called "Trilateration", as we are not measuring the angles, but instead measuring distances. The bottom line is that triangulation is more likely to hit people's search terms so we'll probably bandy that term about a bit :-)

The integration gathers the advertisement data from the bluetooth integration, and uses it to glean location/area info for all devices.

You can view the internal state of Bermuda by calling the bermuda.dump_devices service.

Currently it munges this into three types of entities for each tracked device:

  • A device_tracker entity, which exposes a "home/not home" state. This entity can be mapped to a person to indicate if they are home (eg, by tracking their smart watch). This integration gives you two forms of presence tracking.

  • An Area sensor. This gives the area name of the nearest bluetooth proxy. If you have a proxy in each room, you can use this to know which room a given device is currently in.

  • A Distance sensor which gives the estimated distance from the nearest bluetooth proxy. This may help give a more relative indication of presence.

  • It also provides a bunch of other fun sensors like "Distance from scanner x" and stuff - these are disabled by default because there are many of them, and enabling lots WILL bog down your system, and cause your recorder database to grow - possibly by a lot.

Ultimately, it is hoped to also provide a mud-map of the home, where relative positions of proxies and devices can be visually expressed. This assumes that we can (with some level of reliability) compute the layout with trilateration. That is, by measuring the distances between devices and scanners it is hoped to approximate a solution for the entire "network" of devices. This won't be lidar-level accurate, but it might mean you'd only need proxies in every second room, say.

Clone this wiki locally