Bluetooth Low Energy

Integration Key: bluetoothLowEnergy

The Bluetooth Low Energy (BLE) integration scans for advertisement packets that other devices, like iBeacon or Bluetooth tags, emit. You can use any of the many different BLE tags or smart armbands out there, as long as they send out a constant ID. An example would be the RadBeacon Chipopen in new window or the iB001Wopen in new window. You can use Google or your favorite tech hardware store to find many other products like them that would also work.

The integration calculates an estimated distance in meters for all advertisements it receives and uses that to update the current location of the device. Since there are many factors at play these estimations are not exact measurements, especially once there are obstructions between the BLE device and room-assistant instance. The best accuracy can be achieved with properly configured iBeacons. The distance value is smoothed using a Kalman filteropen in new window to limit the impact of measurement noise.

Requirements

TIP

Using this together with Bluetooth Classic on the same adapter works, but will slightly degrade the performance. If you encounter issues you can try to run to run the integrations from different HCI devices.

This integration requires a BLE capable Bluetooth adapter. Most modern boards like the Raspberry Pi Zero W have an integrated adapter that is suitable. Any Bluetooth USB stick with BLE and Linux support should also work.

Running with NodeJS

Apart from that you are also required to have a few more system packages installed:

sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
sudo npm i --global --unsafe-perm room-assistant
1
2

If you want to run room-assistant without root privileges (as it is recommended) you also need to give NodeJS the correct permissions:

sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
sudo setcap cap_net_admin+eip $(eval readlink -f `which hciconfig`)
1
2

Running with Docker

This integration requires you to run room-assistant in the host network.

Determining the IDs

In order to not clutter your home automation software with the many BLE devices broadcasting their status nearby, room-assistant requires you to set up a allowlist or denylist before it will pass on any information. For regular BLE devices this is the lowercase MAC address without :, for example 7750fb4dab70 for a peripheral with the MAC address 77:50:FB:4D:AB:70. When using iBeacons the ID will be in the format of uuid-major-minor, for example 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2.

If you are unsure what ID your device has you can start room-assistant with the BLE integration enabled, but no allowlist. Devices that are seen for the first time after starting will be logged with their ID to the console.

Tracking iOS Devices

TIP

To use all features that the app offers you should be running room-assistant v2.17.0 or higher.

You can track iOS devices (iPhones, iPads) with this integration using our companion app. You will need to install the app, open it, grant the requested permissions and then follow the on-screen instructions.

Download on the App Storeopen in new window

It is recommended to raise the timeout setting to at least 60 when using the companion app, as the signal may not always be constant.

You can turn on auto-toggling of this feature in the companion app, which will automatically turn off the trackable information when you are not in reach of any room-assistant instance. This feature requires "always" location permissions to work. It uses beacon advertisements emitted by room-assistant and does not grab your geo-location.

Example Config
bluetoothLowEnergy:
  timeout: 60
  allowlist:
  - 'UUID-LIKE-IN-THE-APP'
1
2
3
4

Settings

NameTypeDefaultDescription
allowlistArrayA list of BLE tag IDs that should be tracked.
allowlistRegexBooleanfalseWhether the allowlist should be evaluated as a list of regular expressionsopen in new window or not.
denylistArrayA list of BLE tag IDs that should not be tracked. If an ID matches both allowlist and denylist it will not be tracked.
denylistRegexBooleanfalseWhether the denylist should be evaluated as a list of regular expressionsopen in new window or not.
processIBeaconBooleantrueWhether additional data from iBeacon devices should be taken into account or not. Affects tag IDs and distance estimation.
onlyIBeaconBooleanfalseWhether only iBeacons should be considered when scanning for devices ot not.
timeoutNumber60The time after which a recorded distance is considered outdated. This value should be higher than the advertisement frequency of your peripheral.
updateFrequencyNumber0Minimum amount of seconds that should be waited between distance updates for each tag. The default value disables the throttling.
maxDistanceNumberLimits the distance at which a received BLE advertisement is still reported if configured. Value is in meters.
rssiFactorNumber1Multiplier for the measured RSSI values. Allows you to fine-tune measurements if you use different Bluetooth adapters across your cluster.
majorMaskNumber0xffffFilter out bits of the major ID to make dynamic tag IDs with encoded information consistent for filtering.
minorMaskNumber0xffffFilter out bits of the minor ID to make dynamic tag IDs with encoded information consistent for filtering.
batteryMaskNumber0x00000000If non-zero, extract the beacon's battery level from the major/minor fields. The mask operates on a 32bit value with major as the high two bytes and minor as the low two bytes.
tagOverridesTag OverridesAllows you to override some properties of the tracked devices.
hciDeviceIdNumber0ID of the Bluetooth device to use for the inquiries, e.g. 0 to use hci0.
instanceBeaconEnabledBooleantrueWhether this instance should emit iBeacon advertisements via BLE, which can be used by the room-assistant companion app to auto-toggle advertising.
instanceBeaconMajorNumber1The major of the advertised iBeacon.
instanceBeaconMinorNumberRandomThe minor of the advertised iBeacon.
minDiscoveryLogRssiNumber-999Only log newly discovered beacons if raw RSSI values are greater than this (useful to reduce log spam if on a busy street).

Tag Overrides

The tag overrides object can be considered as a map with the BLE tag ID as key and an object with some of the following settings as value.

NameTypeDefaultDescription
idStringChanges the ID of the device within room-assistant, which is used for entity ID generation. Useful to hide peripheral addresses from publicly shared home automation configurations.
nameStringSets a friendly name for the device, which is sent to the home automation software for easier identification.
measuredPowerNumberOverrides the measured poweropen in new window of a BLE tag, which is used for distance calculation. Should be the expected RSSI when the beacon is exactly 1 meter away from the room-assistant instance.
batteryMaskNumber0x00000000If non-zero, extract the beacon's battery level from the major/minor fields. The mask operates on a 32bit value with major as the high two bytes and minor as the low two bytes.
Example Config
global:
  integrations:
    - bluetoothLowEnergy
bluetoothLowEnergy:
  allowlist:
    - 7750fb4dab70
    - 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2
  maxDistance: 7
  tagOverrides:
    7750fb4dab70:
      name: Cool BLE Tag
      measuredPower: -61
      batteryMask: 0x0000FF00
1
2
3
4
5
6
7
8
9
10
11
12
13
Multiple Bluetooth Integrations Example Config

hciDeviceId can be used to choose a different Bluetooth adapter than the default one. Use hciconfig from the command line to see all available Bluetooth adapters. This may be useful when using Bluetooth Classic and Bluetooth Low Energy at the same time, as you could then have BLE passive scanning enabled at all times instead of just when no Bluetooth Classic inquiry is running.

global:
  integrations:
    - bluetoothClassic
    - bluetoothLowEnergy
bluetoothClassic:
  hciDeviceId: 0
  addresses:
    - '08:05:90:ed:3b:60'
    - '77:50:fb:4d:ab:70'
bluetoothLowEnergy:
  hciDeviceId: 1
  allowlist:
    - 7750fb4dab70
    - 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2
1
2
3
4
5
6
7
8
9
10
11
12
13
14