11-09-2022: Container documentation updated for newer versions of Home Assistant (2022.11.1 as of this update.)
Contains Bluez command line tools and Python. Scans for Bluetooth devices and publishes to MQTT with json payload. Does not support encrypted MQTT and requires functional MQTT endpoint. I use this for Home Assistant but included Bluez tools for troubleshooting. Requires functional Bluetooth in the host operating system. Currently only amd64 builds available.
Based on the Python script written by @Bit-River on Home Assistant Community forums.
Image based on HilscherAutomation/netPI-bluetooth
Base image is bitnami/minideb:buster
Python 3.7.3 (debian package)
PahoMQTT 1.5.1 (pip package)
PyBluez 0.41 (pip package)
Bluepy 1.3.0 (pip package)
gattlib 0.20201113 (pip package)
Bluez 5.54 (compiled from source)
Script will scan for:
- all visible BLE devices and publish to MQTT with as MQTT_CLIENTID/MAC { addrType, location, rssi }
- known Bluetooth devices and publish to MQTT as MQTT_CLIENTID/MAC { name, location }
addrType can be āpublicā or ārandomā
name is device-provided
Location is always āhomeā
Docker Requirements
Requires --cap-add=SYS_ADMIN, --cap-add=NET_ADMIN and --net=host
There is a shell in this image as /bin/sh and Bluez command line tools located in /usr/bin
For troubleshooting or pairing bluetooth devices, access shell within container: docker exec -it pybtble /bin/sh
Entrypoint is Python script /root/pybtble.py
Environment
MQTT_SERVER: IP/FQDN of MQTT broker
MQTT_PORT: port of MQTT broker above
MQTT_USER: username for MQTT broker
MQTT_PASS: password for username above
MQTT_CLIENTID: MQTT client ID or autogenerated pybtble-[5chars] (ie: pybtble-6bd6b)
BT_KNOWN_MACS: Quoted, comma-separated list of Bluetooth MAC addresses.
BLE_PUB_RANDOM: Publish randomized BLE addresses to MQTT. True/False. If not set, defaults to True.
MQTT_SERVER, MQTT_PORT, MQTT_USER and MQTT_PASS are mandatory values.
Configuring Bluetooth (non-BLE) devices
Bluetooth devices only can be scanned when in pairing mode which is not useful. This container has the required tools to execute the pairing process below. Do not use this for BLE devices which are passively scanned. Once paired with your BT dongle/controller, a direct name lookup to the device will succeed when the device is in range.
Put your BT device into pairing mode and then pair it to your BT dongle/controller by executing the following within the container:
hcitool cc 11:11:11:11:11:11
hcitool auth 11:11:11:11:11:11
hcitool dc 11:11:11:11:11:11
Where 11:11:11:11:11:11 is the MAC address of the Bluetooth device. On Android devices youāll need to be in Bluetooth Settings to see the pair request. On Apple devices, a dialog should pop up regardless of which screen youāre in. Accept the pair request and you can then scan for the device using this container. Device names are encoded/decoded as ASCII to overcome the apparent Unicode strings presented by Apple devices.
The Bluetooth devices configured here should then be added to the BT_KNOWN_MACS docker environment variable.
Home Assistant
While you can use the MQTT data for device_tracker in Home Assistant, in my config, I use it as a binary_sensor instead:
binary_sensor:
- platform: mqtt
name: Bluetooth Device
state_topic: "pybtble/11:11:11:11:11:11"
payload_on: "home"
value_template: '{{ value_json.location }}'
off_delay: 180
qos: 0
Docker Compose
services:
pybtble:
container_name: pybtble
image: flatline69/pybtble:latest
environment:
MQTT_SERVER: "172.20.10.100"
MQTT_PORT: "1883"
MQTT_USER: "username"
MQTT_PASS: "password"
MQTT_CLIENTID: "pybtble"
BT_KNOWN_MACS: "11:11:11:11:11:11,22:22:22:22:22:22,33:33:33:33:33:33"
BLE_PUB_RANDOM: "false"
restart: unless-stopped
network_mode: host
cap_add:
- SYS_ADMIN
- NET_ADMIN
Logging Output
Found BLE device: a4:c1:38:55:d5:c0
Found BLE device: a4:c1:38:b4:20:2c
Scanning for BT devices...
Found known BT device: 11:11:11:11:11:11
Found known BT device: 22:22:22:22:22:22
Found known BT device: 33:33:33:33:33:33
Found BLE device: 54:bd:79:0e:90:9b
Found randomized BLE device: 7f:be:af:b3:de:e3 - not published
Found BLE device: d0:03:df:ed:ce:1f
Found BLE device: 68:72:c3:03:9c:6b
Found randomized BLE device: 53:d5:b3:03:a7:d1 - not published
Found BLE device: 9c:20:7b:e6:8b:14
āORIGINAL POSTā
Hello Community!
Iāve been using Home Assistant for a few years now, posted a few times here and there on the community and helped where I could. This time I present something I feel might be really useful for folks (as it was for me.) If you check my post history around this topic, itāll probably make more sense (see here: MQTT parsing help - #4 by chrisw)
Like most of you, I have BLE and BT devices that I ingest into Home Assistant and then act upon. For example, I have BLE Tiles, BT on my familyās phones, etc. Problem was (for me) that getting BT/BLE working in Home Assistant wasnāt too problematic but it took a lot of doing most of the time. Iāve seen posts from folks having issues getting it working in order to track their devices as well.
Some time ago, @Bit-River posted a python script which I originally used to track my Tiles (and various other devices) which I later extended to use MQTT. This worked great and I used it for a good deal of time but it too was problematic and would randomly crash as I had to run it on my host machine and package updates, etc could end up clobbering the scripts execution.
So what Iāve done is created a small docker container that scans for known BT MACs and all visible BLE devices. It also includes command-line tools for troubleshooting. It then logs what it sees to MQTT which can then be ingested into Home Assistant as you wish.
Iām hoping this will help someone out there, it made my life easier moving it to a container and I ended up learning quite a bit about docker in the process. Iāve tried to document as much as possible to ensure successful run of the container.
You can find it here:
