Skip to content

FAQ

Jump to bottom
Ashley Gittins edited this page May 25, 2024 · 5 revisions

Features

Can I track my Phone or Watch?

  • Yes! Both Android and iOS devices (iPhone, iPad) are supported. iWatch and Samsung watches are also reported as working. The key is to configure the built-in Private BLE Device core integration. Once you have a device paired with Private BLE it should automatically appear in Bermuda. Apple devices are pretty chatty, so at that point they should be trackable. For Androids you might need to configure the iBeacon transmitter in the HA Companion app.

What about iBeacons?

Yes! iBeacons are natively supported by Bermuda. You do not need to install the core iBeacon integration.

  • Bermuda's iBeacon support is rather simplistic and opinionated, somewhat reflecting the author.
    • To create a sensor for iBeacons, choose them in the Configure dialog where you can pick them from a drop-down, searchable list. iBeacons will appear near the top of the list.
    • You'll probably want to rename the device and sensors to something sensible.
    • Bermuda considers every UUID/Major/Minor version to uniquely identify a given iBeacon. That means the MAC address can change, or you can have multiple beacons transmitting the same uuid/major/minor and they'll all be one single device - but don't do that though, IMO it's silly.
    • If your beacon sends multiple uuid's or changes its major or minor version, they will show up as different "devices" that you can create sensors for. This might be good if you have one device that sends multiple IDs for some reason, or terrible if you have a device that tries to pack information into the major or minor fields. The latter device is, IMO, silly.
    • If there are known beacons (in reasonable numbers) that do something I thought was silly, I will consider adding support for them. I'd rather they don't exist though, and I think the iBeacon integration suffers because of its trying to support those cases.

Isn't mmWave better?

  • mmWave is definitely faster, but it will only tell you "someone" has entered a space, while Bermuda can tell you who (or what) is in a space.

What about PIR / Infrared?

  • PIR is also likely faster than bluetooth, but again it only tells you that someone / something is present, but doesn't tell you who/what.

So how does that help?

  • If the home knows who is in a given room, it can set the thermostat to their personal preferences, or perhaps their lighting settings. This might be particularly useful for testing automations on yourself before unleashing them on to your housemates, so they don't get annoyed while you iron out the bugs :-)

  • If you have BLE tags on your pets you can have automations specifically for them, and/or you can exclude certain automations, for example don't trigger a light from an IR sensor if it knows it's just your cat, say.

How quickly does it react?

  • There are three main factors.
    • How often your beacon transmits advertisements. Most are less than 2 seconds.
    • Bermuda only checks for new advertisements every second. It will update sensors immediately if devices get "closer", but it is more leisurely for devices that appear to be "leaving" an area.
    • The proxies might not catch every advertisement. In my esphome proxies I usually use these settings to ensure we don't miss toooo many: 
      esp32_ble_tracker:
  interval: 1000ms # default 320ms. Time spent per adv channel
  window: 900ms # default 30ms. Time spent listening during interval.
      This makes sure the device is spending the majority of its time listening for bluetooth advertisements. 320/280 also works, but I think that 1000/900 gives a better balance of dedicated listening vs enough time for wifi tasks.^[citation required!]
  • So if your beacon transmits every second, it might take up to two seconds for Bermuda to come up with a new distance measurement, assuming no packets were lost. Which happens a lot.
  • Due to the noise inherent in RSSI measurements, we do a lot of filtering on the values. The upshot of this is that measurements that read "closer" come through a lot faster because they're more reliable / more likely to be accurate, while readings of an increasing distance will be tracked a lot slower because most of them are signals that were weakened by noise, reflections, dog bodies etc. So asserting that something is in an area is authoritative and quick, while asserting that something is leaving or not in an area carries less confidence and higher latency.

What's going on inside?

How is the distance calculated?

  • Currently, we use the relatively simple equation: distance = 10 ** ((ref_power - rssi) / (10 * attenuation))

    • ref_power is the rssi value you get when the device is 1 metre from the receiver. Currently you can configure this as a global setting in the options.
    • rssi is the "received signal strength indicator", being a measurement of RF power expressed in dBm. RSSI will usually range from -30 or so "down" to -100 or more. Numbers closer to zero are "stronger" or closer.
    • attenuation is a "constant" for the losses in the environment (humidity, air pressure(!), mammals etc). It's a bit of a "fudge factor". This is also set in the options. Typical values are between 1 and 3 but can vary. Finding this value is part of the calibration/setup process.
    • distance is the resulting distance in metres.

  • The default values won't be suitable for all use-cases. Apart from the environmental factors we can't calculate (like walls, reflective surfaces etc), each device might transmit a different power level, and every transmitter and receiver might have antennae that perform differently. Because of this it is planned to allow separate calibration of scanners and devices to account for the variances.

  • See How do I choose values for Attenuation and Ref_power for instructions on calibration.

Configuration

How do the settings work?

See Settings for the explanation of each setting in detail.

Why do my bluetooth devices have only the address and no name?

  • You can simply rename your entities if you like.

  • You can also tell your bluetooth proxies to send an inquiry in response to advertisements, this might cause names to show up. Consider also though that it means while your proxy is asking a device for its name it can't be listening for BLE traffic to proxy. In esphome, this is done by adding active: true to the esp32_ble_tracker section (this is separate from the active property of the bluetooth_proxy section, which controls outbound client connections).

    The default is True, and the templates at Ready-Made Projects also default to True.

    To be explicit in setting the option, the YAML should contain a section like this (there migth be extra paramaters, that's OK):

    esp32_ble_tracker:
  scan_parameters:
    active: True

  • Also, when you first restart homeassistant after loading the integration it may take a minute or so for the system to collect the names of the devices it sees.

How do I choose values for Attenuation and Ref_Power?

  • Soon you'll be able to set this per-device to account for variations in circuits, antennas and cases, but currently there are only the global defaults to fiddle with. Check out the Calibration guide for instructions.

Troubleshooting

My device switches between Areas every few seconds

  • If your device is a "wearable" or otherwise attached to a mammal, the signal strength will tend to vary a lot, and receivers in different directions will get differing signals due to the body absorbing signals travelling through it (some signal will usually still arrive, but possibly via reflections instead of directly). This makes it difficult/impossible to tell which receiver is physically closer to the device on signal strength alone. There are a few workarounds you can try:
    • More distance between proxies. If you have two adjacent rooms, avoid putting the proxies on either side of the common wall. Instead, move one or both so that they have more separation, giving them a better chance to distinguish the signal strength.
    • Add a second (or third!) proxy in the same area. When one proxy is blocked by a body, the other one might get a stronger signal. Obviously this is not ideal financially, but it can make a significant difference.
    • Wait for trilateration (but still keep deploying proxies in the meantime!). Trilateration will use the signals from all proxies to decide which Area a device is in. Hopefully this will mean much higher accuracy, since Bermuda can then make better choices about device locations under more challenging signal conditions.

My device switches between Areas occasionally, despite not moving

Measuring distance using RSSI is inherently noisy, so it's important to have reasonable expectations. However we typically find that Bermuda can do a reasonable job in most cases, and the simplistic area matching we have currently (prior to having trilateration support) should be fairly stable.

That said, it's possible that your proxy is rebooting, crashing or dropping off the network:

  • If you are using esphome proxies, you might have your window and interval timings set too close to each other, or they might be too long or too short.
  • If you are using Shelly devices, it's possible that you have a non-standard BLE script installed, or perhaps multiple BLE scripts installed on the device. Use the latest firmware, and only install the BLE script that comes bundled with the HA Shelly integration - it will automatically install it for you when you configure either Passive or Active Bluetooth Scanning.
Clone this wiki locally