What is it exactly?
ESP32-BLE2MQTT is essentially a BLE↔MQTT bridge that directly maps the GATT characteristics of Bluetooth Low Energy (BLE) devices to MQTT topics.
- • BLE Side: Various sensors, remote controls, lights, door locks… as long as they can broadcast or provide GATT, they can be captured by it.
- • MQTT Side: Home Assistant, Node-RED, cloud platforms… each topic corresponds to a characteristic, enabling seamless two-way communication.
Imagine pushing the “Battery Level 85%” you see on your phone directly to your Home Assistant dashboard, and even being able to remotely write (like turning on a light), all thanks to this bridge.
What pain points does it solve?
| Traditional Approach | Pain Points | ESP32-BLE2MQTT Breakthrough |
| Manually writing Bluetooth protocol + MQTT client | Code is cumbersome, poor compatibility | One-click mapping, automatic parsing of UUID → readable names |
| Writing firmware for each device individually | High maintenance costs, difficult upgrades | Unified firmware, OTA upgrades, configuration files can also be updated remotely |
| Only one-way reading | Business needs are variable, cannot control | Two-way: <span>/Get</span> for reading, <span>/Set</span> for writing, real-time synchronization |
| Requires dedicated gateway hardware | Cost, size, power consumption | Just one ESP32 (even POE version), plug and play |
| BLE broadcasts can only be listened to locally | Remote monitoring is difficult | Broadcast data (iBeacon, Eddystone, MiBeacon) can be pushed directly to MQTT, viewable in the cloud |
In short, it breaks the limitation of “Bluetooth can only be used locally” and connects it directly to “the cloud/local area network anytime, anywhere”.
Installation & Usage Process (Beginner Friendly)
1️⃣ Prepare the Development Environment
- • Install ESP-IDF (v5.2.1), follow the official documentation step by step, and remember to execute
<span>install.sh</span>for complete configuration. - •
<span>git clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt</span>to pull down the source code.
2️⃣ Modify Configuration
- • The directory
<span>data/config.json</span>is crucial. Mainly modify three sections: - • network: Wi-Fi SSID/password (or Ethernet PHY).
- • mqtt: Broker IP, port, optional username and password.
- • ble: You can whitelist/blacklist devices or customize service/characteristic names.
- • Configuration example (in table format):
| Configuration Item | Example Value | Description |
<span>network.wifi.ssid</span> |
<span>"MyHome"</span> |
SSID of home router |
<span>network.wifi.password</span> |
<span>"12345678"</span> |
Wi-Fi password |
<span>mqtt.server.host</span> |
<span>"192.168.0.10"</span> |
Local MQTT Broker |
<span>mqtt.server.port</span> |
<span>1883</span> |
Default unencrypted port |
<span>ble.whitelist</span> |
<span>["aa:bb:cc:dd:ee:ff"]</span> |
Only connect to this Bluetooth device |
<span>topics.prefix</span> |
<span>"home/ble"</span> |
All topics will automatically have this prefix |
3️⃣ Compile & Flash
idf.py set-target esp32
idf.py build
idf.py -p /dev/ttyUSB0 flashAfter completion, the ESP32 will automatically connect to Wi-Fi, connect to MQTT, and then start scanning for BLE.
4️⃣ Verification
- • Use an MQTT client (like MQTT Explorer) to subscribe to
<span>home/ble/+/BatteryService/BatteryLevel</span>, and if you see a value like<span>"85"</span>, it means the bridge is working. - • Want to control a light? Publish
<span>"1"</span>to<span>home/ble/<MAC>/LightService/Power/Set</span>, and the light will turn on.
5️⃣ Advanced Features
- • Broadcast: iBeacon, Eddystone, MiBeacon, etc. can be pushed directly to
<span>BLE2MQTT-XXXX/<MAC>/...</span>. - • Remote Logging: Fill in the UDP address in the
<span>log</span>configuration, and even if the device crashes, it can send logs to the server. - • OTA:
<span>idf.py upload</span>directly upgrades all online devices, or<span>OTA_TARGET=BLE2MQTT-1234 idf.py upload</span>upgrades only the specified node.
Pros and Cons Overview
| Advantages | Disadvantages |
| Unified Bridging: One firmware handles all BLE devices | Dependency on ESP-IDF: May not compile with other SDKs |
| Two-way Communication: Supports reading/writing | BLE Compatibility: Some features (like long authorization) need to be extended manually |
| OTA Support: Firmware + configuration synchronized upgrades | Resource Consumption: ESP32 may experience CPU/memory pressure in high concurrency BLE scenarios |
| Full Broadcast Coverage: iBeacon, Eddystone, MiBeacon can all be pushed | Configuration Complexity: <span>config.json</span><code><span> has many items, beginners need time to understand</span> |
| Flexible Topics: Custom prefixes, suffixes, compatible with existing MQTT structure | Security: Default MQTT is plaintext, SSL/TLS is recommended in production environments |
Conclusion – Why is it Worth Installing?
- • Low Cost: One ESP32 (even POE powered) can bring all Bluetooth devices into the IoT.
- • High Flexibility: Customizable topics, whitelist filtering, broadcast parsing, can meet almost any scenario.
- • Maintenance Savings: Unified OTA, firmware and configuration updates in one go, all nodes upgrade simultaneously.
If you are struggling with “Bluetooth can only be used locally, but the IoT lacks data”, consider getting an ESP32-BLE2MQTT to immediately bring Bluetooth devices into your Home Assistant, Node-RED, or cloud platform, and experience true “Bluetooth as a Service”.
Project Address: https://github.com/shmuelzon/esp32-ble2mqtt