# Bluetooth Low Energy
Using this together with Bluetooth Classic requires multiple Bluetooth adapters.
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 Chip or the iB001W. 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 filter to limit the impact of measurement noise.
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
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`)
# Running with Docker
This integration requires you to run room-assistant in the
# 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 whitelist or blacklist 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
If you are unsure what ID your device has you can start room-assistant with the BLE integration enabled, but no whitelist. Devices that are seen for the first time after starting will be logged with their ID to the console.
| ||Array||A list of BLE tag IDs that should be tracked.|
| ||Boolean|| ||Whether the whitelist should be evaluated as a list of regular expressions or not.|
| ||Array||A list of BLE tag IDs that should not be tracked. If an ID matches both whitelist and blacklist it will not be tracked.|
| ||Boolean|| ||Whether the blacklist should be evaluated as a list of regular expressions or not.|
| ||Boolean|| ||Whether additional data from iBeacon devices should be taken into account or not. Affects tag IDs and distance estimation.|
| ||Boolean|| ||Whether only iBeacons should be considered when scanning for devices ot not.|
| ||Number|| ||The time after which a recorded distance is considered outdated. This value should be higher than the advertisement frequency of your peripheral.|
| ||Number|| ||Minimum amount of seconds that should be waited between distance updates for each tag. The default value disables the throttling.|
| ||Number||Limits the distance at which a received BLE advertisement is still reported if configured. Value is in meters.|
| ||Number|| ||Filter out bits of the major ID to make dynamic tag IDs with encoded information consistent for filtering.|
| ||Number|| ||Filter out bits of the minor ID to make dynamic tag IDs with encoded information consistent for filtering.|
| ||Tag Overrides||Allows you to override some properties of the tracked devices.|
| ||Number|| ||ID of the Bluetooth device to use for the inquiries, e.g. |
# 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.
| ||String||Sets a friendly name for the device, which is sent to the home automation software for easier identification.|
| ||Number||Overrides the measured power 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.|
global: integrations: - bluetoothLowEnergy bluetoothLowEnergy: whitelist: - 7750fb4dab70 - 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2 maxDistance: 7 tagOverrides: 7750fb4dab70: name: Cool BLE Tag measuredPower: -61
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. When using Bluetooth Classic and Bluetooth Low Energy at the same time you need to specify different IDs for these integrations.
global: integrations: - bluetoothClassic - bluetoothLowEnergy bluetoothClassic: hciDeviceId: 0 addresses: - '08:05:90:ed:3b:60' - '77:50:fb:4d:ab:70' bluetoothLowEnergy: hciDeviceId: 1 whitelist: - 7750fb4dab70 - 2f234454cf6d4a0fadf2f4911ba9ffa6-1-2