Skip to content

Supported devices

Jump to bottom
Ashley Gittins edited this page Oct 4, 2024 · 4 revisions

Supported scanners / proxies

  • esphome with bluetooth_proxy enabled. ESP8266 has no Bluetooth, so only ESP32-based (or other supported, bluetooth-capable platforms. LibreTiny does not yet offer this, but I think the little RasPi boards do)
  • Shelly Gen2 devices, using the built-in HA bluetooth proxy script
  • Local bluetooth adaptors (like USB dongles) via BlueZ on your HA host, but these are only partially supported, and not recommended, because they don't give Bermuda accurate timestamp information.
  • Anything else that registers in HA as a "bluetooth scanner" should work (or might cause problems if it does something weird!).

Supported tracking devices

In broad terms, any device that sends bluetooth advertisements should be trackable by Bermuda. However, devices that regularly change their MAC address need to be supported via a protocol that lets us know which physical device is which, despite the changing address.

One big caveat to be aware of is: Many devices will stop advertising if they have a currently active connection. So my watch, for example, works pretty great as a tracker, but if I let my phone connect to it I no longer get updates in Bermuda. An app on the phone to ensure it always advertises (say, an iBeacon app) would solve this. For my part I just don't let my phone stay connected to it. But keep this in mind if trying to set up headphones, speakers etc.

For any device there might be more than one way we can track it. Perhaps it sends a particular ID in every advertisement. Perhaps it uses encryption to choose a random address - so if we know the key we can know which address belongs to it (IRK). But the simplest of all is to just match a device by its "MAC Address". If the device always uses the same address, that's great. If it doesn't, we'll need one of the previous methods.

When adding devices in the configuration, the better-recognised forms are listed first. As you scroll down the list, eventually you will get to devices listed as "Random MAC". These devices are using addresses that are chosen by the device at random. If the device just chooses a random device once then uses that forever (or maybe until a battery change), then it's fine to use. But if the device changes its address every hour or less, you won't get much joy from selecting that entry, and should look for a better option.

Devices with a static MAC address

  • Almost anything, as long as it transmits advertisements and doesn't change its address.
  • This includes things like:
    • Really cheap bluetooth trackers from Aliexpress
    • ODBII to bluetooth interfaces that plug into cars, including some fitted by insurance companies.
    • Some ebike controllers
    • Simple smart watches
    • All BTHome devices (unless there are some that use changing MACs, but I don't think the protocol supports that)
    • Most thermometers, window sensors, moisture sensors, plant sensors etc etc. Most of these will have a static MAC address, so will work just fine. For example:
      • Xiaomi LYWSD03MMC Temp/Humi sensors (running original firmware or pvvx ATC, regardless of advertising type)
      • Some (cheaper?) bluetooth speakers, headphones etc - providing they aren't "connected" at the time, perhaps.

Devices using IRK / Private Resolvable Addresses

  • iOS devices like iPhone, iPad
  • Android phones
  • Less-simple watches like Apple iWatch, Samsung watches etc

This is the single most reliable way of detecting phones and fancy watches. The IRK is used by the Private BLE Device integration (part of HA core) to resolve the random MAC address being used by the device. The trick here is you need to find the "IRK" or "key" to use.

The known ways to find the IRK are documented at https://github.com/agittins/bermuda/wiki/How-to-get-the-IRK-(Identity-Resolving-Keys)-for-iOS,-Android-etc

Devices acting as iBeacon devices

iBeacon is an Apple protocol, but many devices support it. Examples include:

  • Slightly less-cheap beacons on Aliexpress
  • Some tracking tiles (often via configuring them to operate in iBeacon mode)
  • Phone apps, like the HA Companion app or others (this works regardless of whether you have IRK set up).

Eddystone beacons

  • I am not 100% sure about this. If they use a static MAC, then yes. Otherwise I'll need to add eddystone support specifically, but nobody's asked yet.

Planned Support

Class-based fingerprinting and aggregation of randomised addresses. What a mouthful! This isn't done yet, but eventually I plan to offer a "last-ditch" effort for things that are otherwise un-trackable, so that even if you can't exactly know which device it is (eg, is it my cat's Airtag, your dog's airtag, or someone else's airtag?) but we can at least say "There are three AirTags in the house right now, at these locations". I'm using airtags as an example, but this could include things like headphones, google find-my-device network tags, or things that are otherwise supported but you don't have paired to your system (eg a guest's iPhone). Work on this will be tracked at https://github.com/agittins/bermuda/issues/272

Currently NOT Supported things

See Class-based fingerprinting above for a potential work-around of sorts, which also does not depend on device ownership/control.

In general these things will hopefully have support, but work is not there yet, and no timeline is available.

  • Google Find My Device Network (FMDN) tags. These are recommended to use randomised addresses to aid privacy. It should be possible for these to be supported via IRK or via a specific FMDN integration, but I am not aware of one being worked on yet. The trick for IRK support is to find a way to pair a device and discover its IRK, which should then work if fed to the Private Bluetooth Device integration. For FMDN support, an integration could pair to a device and register its application-id, then it could expose the current known-address to Bermuda. This of course will only work for devices you own/control.

  • AirTags. The protocol is fairly well described, and ultimately we'd need to know they key used to set up the tag, and probably have a separate integration responsible for tracking the current address, which could then expose that to Bermuda, very much like the Private Bluetooth Device integration does. I think the key is stored in the apple user's keychain (since both phone and macbook can resolve it) so it should be possible, I think? This of course will only work for airtags you own/control.

  • Apple AirPods. Possibly similar to the Airtags situation, but might simply be a form of IRK - so perhaps if one can grab the key, maybe it will work in Private Bluetooth Device. I don't own any so can't test.

Clone this wiki locally