ESP32‑BLE2MQTT 是一个运行在 ESP32 上的 BLE↔MQTT 双向桥。它把蓝牙低功耗（BLE）设备的 GATT 特性直接映射成 MQTT 主题，既能把蓝牙传感器的数据推送到 MQTT 服务器，也能通过 MQTT → BLE 的方式远程控制蓝牙设备。换句话说，原本只能用手机 APP 交互的蓝牙设备，现在可以直接接入 Home Assistant、Node‑RED、ThingsBoard 等平台，变身为真正的物联网节点。
它解决了哪些痛点？
|
痛点 |
传统做法 |
ESP32‑BLE2MQTT 的解决方案 |
| 蓝牙设备只能本地控制 |
只能用手机或专属 APP，局域网外不可达 |
通过 MQTT 把数据发布到云端，随时随地读取 |
| 多设备管理繁琐 |
每个设备都要单独配对、编写代码 |
自动发现并映射特性，统一用主题管理，结构清晰 |
| 缺少统一监控 |
需要自行开发监控脚本或 UI |
内置状态、连接、Uptime 等系统主题，直接订阅即可 |
| 固件升级困难 |
只能 OTA via App，受限于手机网络 |
支持 ESP‑IDF OTA，统一在 MQTT 上推送固件和配置 |
| 跨平台兼容性差 |
不同厂商蓝牙协议各异 |
通过自定义 Service/Characteristic 定义，可兼容 iBeacon、Eddystone、MiBeacon 等多种广播协议 |
安装&使用一步到位
-
1. 准备开发环境
-
• 按官方文档装好 ESP‑IDF v5.2.1（别用别的版本，可能编译不通过）。
-
•
git clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt把源码拉下来。
2. 配置
-
• 打开
data/config.json，填入 Wi‑Fi 或 以太网 信息、MQTT Broker 地址、主题前缀等。 -
• 如需过滤特定蓝牙设备，可在
ble.whitelist/ble.blacklist中写入 MAC（支持?通配符）。
3. 编译刷入
idf.py build flash-
• 期间会自动生成
sdkconfig.defaults，覆盖常见开发板（如 Olimex ESP32‑POE）。
4. 运行 & 监控
-
• ESP32 启动后会在 MQTT 上发布
<MAC>/Connected、<MAC>/Owner、BLE2MQTT-XXX/Uptime等系统主题。 -
• 例如电池服务：
a0:e6:f8:50:72:53/BatteryService/BatteryLevel会实时推送电量百分比。 -
• 想读取一次值，只需向
…/BatteryLevel/Get发送任意负载；想写值，向…/RelayState/Set发送对应的字符串。
5. 远程日志（可选）
-
• 在
log节点配置 UDP 地址，idf.py remote-monitor即可实时抓取设备日志，省去串口调试。
优点 & 缺点一目了然
|
优点 |
说明 |
| 全平台兼容 |
支持 Wi‑Fi、以太网，适配多数 ESP32 开发板 |
| 自动特性映射 |
直接使用蓝牙官方 UUID，无需手写解析代码 |
| 灵活主题配置 |
可自定义前缀、Get/Set 后缀，完美融入现有 MQTT 结构 |
| 丰富系统信息 |
连接状态、所有者、版本、Uptime 等主题一键监控 |
| OTA 支持 |
固件+配置文件统一升级，省时省力 |
|
缺点 |
说明 |
| 只能跑在 ESP32 |
受硬件限制，其他 MCU 需要自行移植 |
| 对 BLE 规范依赖 |
某些厂商自定义特性可能需要手动补充 |
| 资源占用 |
同时连接多个蓝牙设备时，ESP32 的 RAM/CPU 可能紧张（建议控制在 5‑10 台） |
| 需要 ESP‑IDF 基础 |
初次上手的伙伴需要花时间熟悉 ESP‑IDF 环境 |
小结：为什么要把它装进你的 IoT 项目？
如果你已经在玩 MQTT、Home Assistant 或者 Node‑RED，却苦于蓝牙设备只能本地控制，那 ESP32‑BLE2MQTT 就是你缺的那块“桥”。它把蓝牙世界搬上了 MQTT 的“大舞台”，让设备数据统一、控制统一、监控统一。上手成本不高，配置灵活，社区活跃，几乎可以把市面上所有支持 BLE 的传感器、开关、灯具统一收编。把它装到你的网关上，整个智能家居系统瞬间升级为 真正的全屋互联！
项目地址：https://github.com/shmuelzon/esp32-ble2mqtt