flatline69/pybtble repository overview

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 }

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:

NEW METHOD:
# bluetoothctl
# power on
# agent on
# default-agent
# scan on
<wait for device to show  up>
# pair 11:11:11:11:11:11
<validate pairing>
# scan off
# exit

OLD METHOD:
# 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:

***NOTE***

Newer versions of Home Assistant have deprecated binary_sensor definition of MQTT sensors and
now is placed under the MQTT integration:

mqtt:
  binary_sensor:
    - 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

DEPRECATED USAGE:

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