-
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.
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_trackerentities 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_devicesservice.
-
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_proxycomponent 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.
- ESPHome devices with the
-
Some bluetooth BLE devices you want to track. Phones, smart watches, beacon tiles, thermometers etc.
-
Bermuda! I strongly recommend installing Bermuda via HACS:
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.
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.
See The FAQ in the Wiki!
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.
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.
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.
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:
- Using the tool of choice open the directory (folder) for your HA configuration (where you find
configuration.yaml). - If you do not have a
custom_componentsdirectory (folder) there, you need to create it. - In the
custom_componentsdirectory (folder) create a new folder calledbermuda. - Download all the files from the
custom_components/bermuda/directory (folder) in this repository. - Place the files you downloaded in the new directory (folder) you created.
- Restart Home Assistant
- In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Bermuda BLE Trilateration"
If you want to contribute to this please read the Contribution guidelines
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**