Skip to content

Home

Jump to bottom
Ashley Gittins edited this page Apr 12, 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
  • 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 :-)

Clone this wiki locally