ESP32-BLE2MQTT is a bidirectional BLE↔MQTT bridge running on ESP32. It directly maps the GATT characteristics of Bluetooth Low Energy (BLE) devices to MQTT topics, allowing Bluetooth sensor data to be pushed to an MQTT server and enabling remote control of Bluetooth devices via MQTT→BLE. In other words, Bluetooth devices that could only interact through a mobile app can now be directly integrated into platforms like Home Assistant, Node-RED, and ThingsBoard, transforming them into true IoT nodes.
What pain points does it address?
| Pain Point | Traditional Approach | ESP32-BLE2MQTT Solution |
| Bluetooth devices can only be controlled locally | Can only be accessed via mobile or dedicated app, unreachable outside the local network | Publishes data to the cloud via MQTT, accessible anytime, anywhere |
| Managing multiple devices is cumbersome | Each device must be paired individually and coded separately | Automatically discovers and maps characteristics, managed uniformly with topics, clear structure |
| Lack of unified monitoring | Requires self-developed monitoring scripts or UI | Built-in system topics for status, connection, uptime, etc., can be subscribed to directly |
| Firmware upgrades are difficult | Can only be done OTA via app, limited by mobile network | Supports ESP-IDF OTA, uniformly pushes firmware and configuration over MQTT |
| Poor cross-platform compatibility | Different manufacturers have varying Bluetooth protocols | Custom Service/Characteristic definitions allow compatibility with various broadcast protocols like iBeacon, Eddystone, MiBeacon, etc. |
Installation & Usage Made Easy
- 1. Prepare the development environment
- • Install ESP-IDF v5.2.1 as per the official documentation (do not use other versions, as compilation may fail).
- •
<span>git clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt</span>to pull the source code.
- • Open
<span>data/config.json</span>and fill in the Wi-Fi or Ethernet information, MQTT Broker address, topic prefix, etc. - • To filter specific Bluetooth devices, write the MAC addresses in
<span>ble.whitelist</span>/<span>ble.blacklist</span>(supports<span>?</span>wildcard).
idf.py build flash- • During this process,
<span>sdkconfig.defaults</span>will be automatically generated, covering common development boards (e.g., Olimex ESP32-POE).
- • After startup, the ESP32 will publish system topics like
<span><MAC>/Connected</span>,<span><MAC>/Owner</span>,<span>BLE2MQTT-XXX/Uptime</span>on MQTT. - • For example, the battery service:
<span>a0:e6:f8:50:72:53/BatteryService/BatteryLevel</span>will push the battery percentage in real-time. - • To read a value once, simply send any payload to
<span>…/BatteryLevel/Get</span>; to write a value, send the corresponding string to<span>…/RelayState/Set</span>.
- • Configure the UDP address in the
<span>log</span>node, and run<span>idf.py remote-monitor</span>to capture device logs in real-time, eliminating the need for serial debugging.
Advantages & Disadvantages at a Glance
| Advantages | Description |
| Cross-platform compatibility | Supports Wi-Fi, Ethernet, compatible with most ESP32 development boards |
| Automatic characteristic mapping | Directly uses official Bluetooth UUIDs, no need to write parsing code |
| Flexible topic configuration | Customizable prefixes, Get/Set suffixes, perfectly integrates into existing MQTT structures |
| Rich system information | One-click monitoring of connection status, owner, version, uptime, etc. |
| OTA support | Unified firmware and configuration upgrades, saving time and effort |
| Disadvantages | Description |
| Can only run on ESP32 | Due to hardware limitations, other MCUs need to be ported manually |
| Dependent on BLE specifications | Some manufacturers’ custom characteristics may require manual additions in <span>characteristics.definitions</span> |
| Resource consumption | When connecting multiple Bluetooth devices simultaneously, the ESP32’s RAM/CPU may be strained (recommended to keep it between 5-10 devices) |
| Requires ESP-IDF basics | Newcomers need to spend time familiarizing themselves with the ESP-IDF environment |
Conclusion: Why Should You Integrate It into Your IoT Project? If you are already working with MQTT, Home Assistant, or Node-RED but are frustrated that Bluetooth devices can only be controlled locally, then ESP32-BLE2MQTT is the missing “bridge” you need. It brings the Bluetooth world onto the “big stage” of MQTT, unifying device data, control, and monitoring. The entry cost is low, configuration is flexible, and the community is active, making it possible to integrate almost all BLE-compatible sensors, switches, and lights available on the market. By installing it on your gateway, your entire smart home system can instantly upgrade to a truly interconnected home!
Project Address: https://github.com/shmuelzon/esp32-ble2mqtt