ble2mqtt is a small script that writes data from Bluetooth LE devices to MQTT topics

Usage no npm install needed!

<script type="module">
  import sebbo2002Ble2mqtt from 'https://cdn.skypack.dev/@sebbo2002/ble2mqtt';



License GitHub Workflow Status

🧐 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


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.

LYWSDCGQ Mi Flora Sensor
Values: (without basics) temperature, moisture, illuminance, fertility
Update interval: ~ 1x / min
LYWSDCGQ Xiaomi Thermometer / Hygrometer
Values: (without basics) temperature, humidity, battery
Update interval: ~ 20x / min
LYWSDCGQ SwitchBot Bot
Values: (without basics) switchAddOnUsed, state, battery
Update interval: ?
LYWSDCGQ SwitchBot Meter
Values: (without basics) temperature, humidity, battery
Update interval: ?
LYWSDCGQ SwitchBot Curtain
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.

📚 Credits

👩‍⚖️ Copyright & License

Copyright (c) Sebastian Pekarek under the MIT license.