What is ESP32-BLE2MQTT?
In simple terms, it is a small ESP32 (the commonly known Wi-Fi + Bluetooth dual-mode chip) running firmware specifically designed to map BLE GATT characteristics to MQTT topics.
- • As long as your BLE device broadcasts data such as battery level, power, and temperature, BLE2MQTT can help you push this data directly to the MQTT server.
- • At the same time, you can send messages to the corresponding MQTT topics to read (/Get) or write (/Set) the characteristic values of the BLE device, achieving bidirectional control.
Imagine this: smartwatches, temperature and humidity sensors, lights, door sensors… these devices, which could only be controlled via mobile apps, can now all run on platforms like Home Assistant, Node-RED, and ThingsBoard, saving time and effort.
What Pain Points Does It Solve?
| Traditional Approach | Advantages of BLE2MQTT |
| Each BLE device requires a separate SDK program, leading to code redundancy and high maintenance costs. | A single firmware handles all devices, managed uniformly through MQTT topics. |
| Data can only be viewed on local apps, making cross-platform access difficult. | MQTT is inherently cross-platform; any system that supports MQTT can consume it. |
| Device communication relies on Bluetooth broadcasting, which is limited in range and not friendly for concurrent connections. | ESP32 pushes data to the cloud via Wi-Fi, expanding the range and supporting a large number of concurrent connections. |
| Manual pairing and PIN entry are cumbersome. | Supports whitelist/blacklist, automatic pairing, and passkey, eliminating manual pairing. |
| OTA upgrades are troublesome and require reflashing firmware. | Built-in OTA allows for remote upgrades of both firmware and configuration files. |
In short, it paves the way for “Bluetooth → MQTT”, guiding you step by step to integrate various BLE sensors and controllers into a complete IoT ecosystem.
Installation & Usage Guide (One-Step Process)
⚡ Prerequisites: Have the ESP-IDF (v5.2.1) environment set up and prepare an ESP32 development board (recommended: Olimex ESP32-POE with Ethernet).
- 1. Clone the code
git clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt cd esp32-ble2mqtt - 2. Edit
<span>data/config.json</span>
- • Network: Enter Wi-Fi SSID/PWD or Ethernet configuration.
- • MQTT: Enter broker address, port, username, and password (if any).
- • BLE: Optionally restrict devices with
<span>whitelist</span>/<span>blacklist</span>; you can also customize service/characteristic names.
idf.py build flashAfter flashing, the ESP32 will automatically connect to Wi-Fi, connect to MQTT, and start scanning for BLE devices.
- • Enter the MQTT client (e.g.,
<span>mosquitto_sub -t "#" -v</span>), and you will see something like:a0:e6:f8:50:72:53/BatteryService/BatteryLevel 78 a0:e6:f8:50:72:53/Connected true - • Want to control a light switch? Send
<span>1</span>to<span>xx:xx:xx:xx:xx:xx/RelayService/RelayState/Set</span>.
<span>config.json</span><code><span> log section, and execute </span><code><span>idf.py remote-monitor</span> to view logs in real-time.idf.py upload # Upgrade firmware
idf.py upload-config # Upgrade configuration filePros and Cons Quick Review
| Pros | Cons |
| ✅ One-click bridging: BLE → MQTT bidirectional, almost no coding required. | ❌ Can only run on ESP32, hardware resources are limited (e.g., connecting too many BLE devices at once may cause lag). |
| ✅ Standardization: Based on BLE GATT and MQTT protocols, good compatibility. | ❌ For custom non-standard characteristics, parsing rules need to be manually added in <span>config.json</span><span>.</span> |
| ✅ Flexible configuration: Whitelist/blacklist, service/characteristic customization, passkey. | ❌ Initial configuration of JSON structure can be a bit cumbersome; beginners need to refer to documentation. |
| ✅ OTA: Both firmware and configuration can be upgraded remotely. | ❌ OTA requires the MQTT broker to be continuously online; upgrades may fail if the network is unstable. |
| ✅ Broadcast parsing: Various broadcasts like iBeacon, Eddystone, MiBeacon can be directly converted to MQTT. | ❌ Broadcast topics are not retained (non-retained); after disconnection, you need to resubscribe to get the latest data. |
Conclusion
If you are already using Home Assistant, Node-RED, or want to unify various Bluetooth sensors in your home onto one platform, ESP32-BLE2MQTT is almost a ready-made bridge. It transforms originally scattered and hard-to-unify BLE devices into standard MQTT topics, allowing backend systems to handle them as easily as ordinary sensors. The only thing to note is the concurrent capability of the ESP32: connecting too many BLE devices at once may cause response delays; in this case, consider scanning in batches or using more powerful hardware (like ESP32-S3). Overall, its ease of use + scalability makes it stand out in DIY IoT projects.
Project address: https://github.com/shmuelzon/esp32-ble2mqtt