README

ble2mqtt

🧐 What's this?

ble2mqtt is a small script that writes data from Bluetooth-LE devices to MQTT Topics. Unlike many other implementations it only listens to the broadcasts of the devices, there is no active polling. This has the advantage that it is more stable, the sensors consumes less energy and mostly the range is higher. The disadvantage is that, depending on the device, individual values may be missing if they are not transmitted by broadcast. If these values are required, they would still have to be retrieved by polling. However, the most important data is usually transmitted via broadcasts, so that less important data (e.g. the battery status of the device) can also be requested less frequently.

💾 Installation

This module is based on noble. Therefore the same requirements are necessary here as well.

for macOS: install Xcode
for Ubuntu/Debian/Raspbian: run sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
for Fedora / Other-RPM based: run sudo yum install bluez bluez-libs bluez-libs-devel
for Windows and other systems have a look at the noble project, they may already have some instructions for you

After you have met the requirements for noble, you can install bte2mqtt:

npm install -g @sebbo2002/ble2mqtt

If you want to run ble2mqtt without root privileges, you have to give the node binary the right cap_net_raw under Linux, otherwise no Bluetooth advertisements can be received. How to do this is described here quite well.

🔧 Configuration

Environment Variable	Default Value	Description
`BROKER_URL`	`mqtt://localhost`	MQTT-Broker URI
`TOPIC_PREFIX`	`ble2mqtt`	Prefix used to generate MQTT topics
`CACHE_TTL`	`5000`	Cache TTL in ms, set to `0` to disable cache and publish every single message it gets
`RETAIN_FLAG`	`0`	Set the retain flag for MQTT messages? Default is no, set to `1` to enable.
`WHITELIST`	-	Comma seperated list of device UUIDs or addresses. If set, all other devices are ignored.
`MONITORING_ID`	-	Added to monitoring topics like `pid` or `uptime` to distinguish multiple agents
`WATCHDOG_SUICIDE`	`0`	Setting this to `1` allows the internal Watchdog to kill ble2mqtt if something goes wrong

⌨️ Usage

If you have ble2mqtt installed, you can start the tool. The best thing to do is to set --debug first, so you can see what happens. When the script reports Connections established it will start. If not make sure that no other programs access your Bluetooth adapter. This can cause problems.

ble2mqtt screenshot

ble2mqtt now collects data from devices that send it out via Bluetooth LE. This data is parsed and forwarded in MQTT topics. Besides the general attributes there are also devices that reveal more about themselves. These are mostly sensors. If they are implemented in ble2mqtt, these values are forwarded as well. A list with all supported devices can be found below.

General attributes

Event if there's no implementation for your device you can use this module to get some basic information. You can still use other implementations to poll values in parallel. These general attributes are:

name
address
uuid
lastSeen
rssi

Monitoring

ble2mqtt supports several topics that can be used to monitor the process. They are updated every times the script starts.

pid
version
uptime
watchdogTimeout

Internal Cache

To avoid flooding the MQTT-Broker with a huge amount of messages, there is a limit of one update per topic per 5 seconds. The limit can be changed or deactivated with the environment variable CACHE_TTL.

📡 Supported Devices

Here's a list of devices which are supported. Other devices as listed here will most likely only support the basic attributes.

	Mi Flora Sensor HHCCJCY01
Values: (without basics)	temperature, moisture, illuminance, fertility
Update interval:	~ 1x / min

	Xiaomi Thermometer / Hygrometer LYWSDCGQ
Values: (without basics)	temperature, humidity, battery
Update interval:	~ 20x / min

	SwitchBot Bot WoHand
Values: (without basics)	switchAddOnUsed, state, battery
Update interval:	?

	SwitchBot Meter WoSensorTH
Values: (without basics)	temperature, humidity, battery
Update interval:	?

	SwitchBot Curtain WoCurtain
Values: (without basics)	calibrated, battery, position, lightLevel
Update interval:	?

🤷 Frequently asked questions

How do I determine which Bluetooth adapter the script should use?

hcitool dev
NOBLE_HCI_DEVICE_ID=1 (hci1 used)

Something doesn't work. How can I get more information about what's going on inside the script?

ble2mqtt --debug

After some time ble2mqtt does not work anymore, what can be the reason?

The problem is known, but unfortunately I do not know yet what the exact reason is. On some hosts I have the problem, on others not. A restart will reliably solve the problem. If ble2mqtt was started in such a way that it is automatically restarted when it terminates (e.g. via forever), WATCHDOG_SUICIDE can be used to allow the watchdog to terminate ble2mqtt when no more data is received. This works very reliably for me.

I have a large area to cover. How do I scale ble2mqtt with multiple agents?

You can run the script on multiple hosts and run it in parallel. If you set the same topic, it makes no difference which instance received the beacons from the device. Set MONITORING_ID if you want to distinguish the monitoring topics.

@sebbo2002/ble2mqtt

Usage no npm install needed!