bt-mqtt-gateway

A simple Python script which provides a Bluetooth to MQTT gateway, easily extensible via custom workers.
See Wiki for more information.

Features

• Highly extensible via custom workers
• Data publication via MQTT
• Configurable topic and payload
• MQTT authentication support
• Systemd service
• Reliable and intuitive
• Tested on Raspberry Pi Zero W

Supported devices

• EQ3 Bluetooth smart thermostat via python-eq3bt
• Xiaomi Mi Scale
• Xiaomi Mi Scale v2 (Body Composition Scale)
• Linak Desk via linak_bt_desk
• MySensors
• Xiaomi Mi Flora plant sensor via miflora
• Xiaomi Aqara thermometer via mithermometer
• Bluetooth Low Power devices (BLE)
• Oral-B connected toothbrushes
• Switchbot
• Sensirion SmartGadget via python-smartgadget
• RuuviTag via ruuvitag-sensor
• Xiaomi Mijia 2nd gen, aka LYWSD02

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Requirements

• Python 3 installed
• Working bluetooth adapter ( might be built in like in raspberry pi )
• Working mqtt server, to which you can connect

Testing mqtt: Use mosquitto_sub to print all messages. Change localhost to your mqtt server address.

# also helpful for testing MQTT messages
mosquitto_sub -h localhost -d -t '#'

# if user/password are defined on your mosquitto server, use
mosquitto_sub -h localhost -d -t '#' -u user -P password

# for more info, see mosquitto_sub --help

Installation

Docker

There are prebuilt docker images at https://hub.docker.com/r/zewelor/bt-mqtt-gateway/tags. Thanks @hobbypunk90 and @krasnoukhov for docker work.

Mount config.yaml as /application/config.yaml volume

Example exec

docker run -d --name bt-mqtt-gateway --network=host --cap-add=NET_ADMIN --cap-add=NET_RAW -v $PWD/config.yaml:/application/config.yaml zewelor/bt-mqtt-gateway

Docker-compose

See docker-compose.yml file in repo. To run:

docker-compose run bt-mqtt-gateway

Virtualenv

On a modern Linux system, just a few steps are needed to get the gateway working. The following example shows the installation under Debian/Raspbian:

sudo apt-get install git python3 python3-pip python3-wheel bluetooth bluez libglib2.0-dev
sudo pip3 install virtualenv
git clone https://github.com/zewelor/bt-mqtt-gateway.git
cd bt-mqtt-gateway
virtualenv -p python3 .venv
source .venv/bin/activate
pip3 install -r requirements.txt

All needed python libs, per each worker, should be auto installed on run. If not you can install them manually:

pip3 install `./gateway.py -r configured`

Configuration

All worker configuration is done in the file config.yaml. Be sure to change all options for your needs. This file needs to be created first:

cp config.yaml.example config.yaml
nano config.yaml
source .venv/bin/activate
sudo ./gateway.py

Attention: You need to add at least one worker to your configuration. Scan for available Bluetooth devices in your proximity with the command:

sudo hcitool lescan

Execution

A test run is as easy as:

source .venv/bin/activate
sudo ./gateway.py

Debug output can be displayed using the -d argument:

sudo ./gateway.py -d

Deployment

Continuous background execution can be done using the example Systemd service unit provided.

sudo cp bt-mqtt-gateway.service /etc/systemd/system/
sudo nano /etc/systemd/system/bt-mqtt-gateway.service (modify path of bt-mqtt-gateway)
sudo systemctl daemon-reload
sudo systemctl start bt-mqtt-gateway
sudo systemctl status bt-mqtt-gateway
sudo systemctl enable bt-mqtt-gateway

Attention: You need to define the absolute path of service.sh in bt-mqtt-gateway.service.

Dynamically Changing the Update Interval To dynamically change the update_interval of a worker, publish a message containing the new interval in seconds at the update_interval topic. Note that the update_interval will revert back to the value in config.yaml when the gateway is restarted. I.E:

# Set a new update interval of 3 minutes
mosquitto_pub -h localhost -t 'miflora/update_interval' -m '150'
# Set a new update interval of 30 seconds
mosquitto_pub -h localhost -t 'mithermometer/update_interval' -m '30'

Custom worker development

Create custom worker in workers directory.

Example simple worker

from mqtt import MqttMessage
from workers.base import BaseWorker

REQUIREMENTS = ['pip_packages']

class TimeWorker(BaseWorker):
  def _setup(self):
    self._some = 'variable'

  def status_update(self):
    from datetime import datetime
    
    return [MqttMessage(topic=self.format_topic('time'), payload=datetime.now())]

REQUIREMENTS add required pip packages, they will be installed on first run. Remember to import them in method, not on top of the file, because on initialization, that package won't exists. Unless installed outside of the gateway. Check status_update method

_setup method - add / declare needed variables.

status_update method - It will be called using specified update_interval

Example config entry

Add config to the example config:

    timeworker:
      args:
        topic_prefix: cool_time_worker
      update_interval: 1800

Variables set in args section will be set as object attributes in BaseWorker.init

topic_prefix, if specified, will be added to each mqtt message. Alongside with global_prefix set for gateway

Troubleshooting

See the Troubleshooting Wiki

Built With

• Python - The high-level programming language for general-purpose programming

Authors

• zewelor - Initial work
• bbbenji - Minor contributions
• elviosebastianelli - BLEscanmulti
• jumping2000 - BLEscan
• AS137430 - Switchbot

License

This project is licensed under the MIT License - see the LICENSE.md file for details