{"id":15163171,"url":"https://github.com/shmuelzon/esp32-ble2mqtt","last_synced_at":"2025-05-15T05:07:51.700Z","repository":{"id":41128680,"uuid":"115448822","full_name":"shmuelzon/esp32-ble2mqtt","owner":"shmuelzon","description":"A BLE to MQTT bridge running on an ESP32","archived":false,"fork":false,"pushed_at":"2025-03-31T17:06:08.000Z","size":256,"stargazers_count":711,"open_issues_count":52,"forks_count":112,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-14T08:12:42.035Z","etag":null,"topics":["ble","bluetooth","esp32","gatt","mqtt"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shmuelzon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["shmuelzon"]}},"created_at":"2017-12-26T19:21:00.000Z","updated_at":"2025-04-04T08:42:04.000Z","dependencies_parsed_at":"2023-11-23T18:24:01.840Z","dependency_job_id":"b01f5e83-8f32-45ef-b33b-6f1759cc04ca","html_url":"https://github.com/shmuelzon/esp32-ble2mqtt","commit_stats":{"total_commits":195,"total_committers":12,"mean_commits":16.25,"dds":"0.10256410256410253","last_synced_commit":"7bd29fe04a83468c12dba14e28335e660a00b03f"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shmuelzon%2Fesp32-ble2mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shmuelzon%2Fesp32-ble2mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shmuelzon%2Fesp32-ble2mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shmuelzon%2Fesp32-ble2mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shmuelzon","download_url":"https://codeload.github.com/shmuelzon/esp32-ble2mqtt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","esp32","gatt","mqtt"],"created_at":"2024-09-27T02:20:22.349Z","updated_at":"2025-05-15T05:07:46.692Z","avatar_url":"https://github.com/shmuelzon.png","language":"C","funding_links":["https://github.com/sponsors/shmuelzon"],"categories":["Interfaces"],"sub_categories":["Makers"],"readme":"# ESP32-BLE2MQTT\n\nThis project is a BLE to MQTT bridge, i.e. it exposes BLE GATT characteristics\nas MQTT topics for bidirectional communication. It's developed for the ESP32 SoC\nand is based on [ESP-IDF](https://github.com/espressif/esp-idf) release v5.2.1.\nNote that using any other ESP-IDF version might not be stable or even compile.\n\nFor example, if a device with a MAC address of `a0:e6:f8:50:72:53` exposes the\n[0000180f-0000-1000-8000-00805f9b34fb service](https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.battery_service.xml)\n(Battery Service) which includes the\n[00002a19-0000-1000-8000-00805f9b34fb characteristic](https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.battery_level.xml)\n(Battery Level), the `a0:e6:f8:50:72:53/BatteryService/BatteryLevel` MQTT topic\nis published with a value representing the battery level.\n\nCharacteristics supporting notifications will automatically be registered on and\nnew values will be published once available. It's also possible to proactively\nissue a read request by publishing any value to the topic using the above format\nsuffixed with '/Get'. Note that values are strings representing the\ncharacteristic values based on their definitions grabbed from\nhttp://bluetooth.org. For example, a battery level of 100% (0x64) will be sent\nas a string '100'.\n\nIn order to set a GATT value, publish a message to a writable characteristic\nusing the above format suffixed with `/Set`. Payload should be of the same\nformat described above and will be converted, when needed, before sending to the\nBLE peripheral.\n\nIn addition to the characteristic values, the BLE2MQTT devices also publish\nadditional topics to help book-keeping:\n* `\u003cPeripheral MAC address\u003e/Connected` - With a payload of `true`/`false`\n  depicting if the peripheral is currently connected or not. Note that this\n  topic is monitored by the BLE2MQTT instance currently connected to the\n  peripheral so that if another instance publishes `false`, the current instance\n  will re-publish `true`\n* `\u003cPeripheral MAC address\u003e/Owner` - The name of the BLE2MQTT instance currently\n  connected to the peripheral, e.g. `BLE2MQTT-XXXX`, where `XXXX` are the last 2\n  octets of the ESP32's WiFi MAC address\n* `BLE2MQTT-XXX/Version` - The BLE2MQTT application version currently running\n* `BLE2MQTT-XXX/ConfigVersion` - The BLE2MQTT configuration version currently\n  loaded (MD5 hash of configuration file)\n* `BLE2MQTT-XXX/Uptime` - The uptime of the ESP32, in seconds, published every\n  minute\n* `BLE2MQTT-XXX/Status` - `Online` when running, `Offline` when powered off\n  (the latter is an LWT message)\n\n## Broadcasters\n\nBroadcasters are non-connectable BLE devices that only send advertisements.\nThis application supports publishing these advertisements over MQTT.\nFor each broadcaster, at-least two topics are published:\n* `BLE2MQTT-XXXX/\u003cBroadcaster MAC address\u003e/Type` - The broadcaster type, e.g.\n  `iBeacon`\n* `BLE2MQTT-XXXX/\u003cBroadcaster MAC address\u003e/RSSI` - The RSSI value of the\n  received advertisement\n\nIn addition, depending on the broadcaster type and payload, additional meta-data\nis published.\n* For iBeacon: `UUID`, `Major`, `Minor` and `Distance`\n* For Eddystone:\n  * `UID` frames: `Namespace`, `Instance` and `Distance`\n  * `URL` frames: `URL` and `Distance`\n  * `TLM` frames: `Voltage`, `Temperature`, `Count` and `Uptime`\n* For Xiaomi Mijia (MiBeacon) sensors: `MACAddress`, `MessageCounter`,\n  `Temperature`, `Humidity`, `Moisture`, `Formaldehyde`, `Illuminance`,\n  `Conductivity`, `Switch`, `Consumable`, `Smoke`, `Light`, `DoorClosed`, `Motion`,\n  `BatteryLevel`\n* For BeeWi Smart Door sensors: `Status` and `Battery`\n* For Xiaomi LYWSD03MMC Temperature Sensors running the ATC1441 firmware:\n  `MACAddress`, `MessageCounter`, `Temperature`, `Humidity`, `BatteryLevel`\n  and `BatteryVolts` (_See https://github.com/atc1441/ATC_MiThermometer_)\n\n**Note:** Broadcaster topics are published without the retained flag regardless\nof what's defined in the configuration file.\n\n## Compiling\n\n1. Install `ESP-IDF`\n\nYou will first need to install the\n[Espressif IoT Development Framework](https://github.com/espressif/esp-idf).\nThe [Installation Instructions](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html)\nhave all of the details. Make sure to follow ALL the steps, up to and including step 4 where you set up the tools and\nthe `get_idf` alias.\n\n2. Download the repository and its dependencies:\n\n```bash\ngit clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt\n```\n\n3. Modify the config.json and flash\n\nModify the [configuration file](#configuration) to fit your environment, build\nand flash (make sure to modify the serial device your ESP32 is connected to):\n\n```bash\nidf.py build flash\n```\n\n## Remote Logging\n\nIf configured, the application can send the logs remotely via UDP to another\nhost to allow receiving logs from remote devices without a serial connection.\nTo receive these logs on your host, execute `idf.py remote-monitor`.\n\n## Configuration\n\nThe configuration file provided in located at\n[data/config.json](data/config.json) in the repository. It contains all of the\ndifferent configuration options.\n\nThe `network` section should contain either a `wifi` section or an `eth`\nsection.  If case there are both, the `eth` section has preference over the\n`wifi` section.\n\nOptionally, the network section can contain a `hostname` which, if set,\nis used in MQTT subscriptions as well. In such case, relace `BLE2MQTT-XXX` in\nthis documentation with the hostname you have set.\n\nThe `wifi` section below includes the following entries:\n```json\n{\n  \"network\": {\n    \"hostname\": \"MY_HOSTNAME\",\n    \"wifi\": {\n      \"ssid\": \"MY_SSID\",\n      \"password\": \"MY_PASSWORD\",\n      \"eap\": {\n        \"method\": null,\n        \"identity\": null,\n        \"client_cert\": null,\n        \"client_key\": null,\n        \"server_cert\": null,\n        \"username\": null,\n        \"password\": null\n      }\n    }\n  }\n}\n```\n* `ssid` - The WiFi SSID the ESP32 should connect to\n* `password` - The security password for the above network\n* `eap` - WPA-Enterprise configuration (for enterprise networks only)\n  * `method` - `TLS`, `PEAP` or `TTLS`\n  * `identity` - The EAP identity\n  * `ca_cert`, `client_cert`, `client_key` - Full path names, including a\n    leading slash (/), of the certificate/key file (in PEM format) stored under\n    the data folder\n  * `username`, `password` - EAP login credentials\n\nThe `eth` section below includes the following entries:\n```json\n{\n  \"network\": {\n    \"eth\": {\n      \"phy\": \"MY_ETH_PHY\",\n      \"phy_power_pin\": -1\n    }\n  }\n}\n```\n* `phy` - The PHY chip connected to ESP32 RMII, one of:\n  * `IP101`\n  * `RTL8201`\n  * `LAN8720`\n  * `DP83848`\n* `phy_power_pin` - Some ESP32 Ethernet modules such as the Olimex ESP32-POE require a GPIO pin to be set high in order to enable the PHY. Omitting this configuration or setting it to -1 will disable this.\n\n_Note: Defining the `eth` section will disable WiFi_\n\nThe `mqtt` section below includes the following entries:\n```json\n{\n  \"mqtt\": {\n    \"server\": {\n      \"host\": \"192.168.1.1\",\n      \"port\": 1883,\n      \"ssl\": false,\n      \"client_cert\": null,\n      \"client_key\": null,\n      \"server_cert\": null,\n      \"username\": null,\n      \"password\": null,\n      \"client_id\": null\n    },\n    \"publish\": {\n      \"qos\": 0,\n      \"retain\": true\n    },\n    \"topics\" :{\n      \"prefix\": \"\",\n      \"get_suffix\": \"/Get\",\n      \"set_suffix\": \"/Set\"\n    }\n  }\n}\n```\n* `server` - MQTT connection parameters\n  * `host` - Host name or IP address of the MQTT broker\n  * `port` - TCP port of the MQTT broker. If not specificed will default to\n    1883 or 8883, depending on SSL configuration\n  * `client_cert`, `client_key`, `server_cert` - Full path names, including a\n    leading slash (/), of the certificate/key file (in PEM format) stored under\n    the data folder. For example, if a certificate file is placed at\n    `data/certs/my_cert.pem`, the value stored in the configuration should be\n    `/certs/my_cert.pem`\n  * `username`, `password` - MQTT login credentials\n  * `client_id` - The MQTT client ID\n* `publish` - Configuration for publishing topics\n* `topics`\n  * `prefix` - Which prefix should be added to all MQTT value topics. OTA\n    related topics are already prefixed and are not affected by this value\n  * `get_suffix` - Which suffix should be added to the MQTT value topic in order\n    to issue a read request from the characteristic\n  * `set_suffix` - Which suffix should be added to the MQTT value topic in order\n    to write a new value to the characteristic\n\nThe `ble` section of the configuration file includes the following default\nconfiguration:\n```json\n{\n  \"ble\": {\n    \"//Optional: 'whitelist' or 'blacklist'\": [],\n    \"services\": {\n      \"definitions\": {},\n      \"//Optional: 'whitelist' or 'blacklist'\": []\n    },\n    \"characteristics\": {\n      \"definitions\": {},\n      \"//Optional: 'whitelist' or 'blacklist'\": []\n    },\n    \"passkeys\": {},\n    \"mikeys\": {}\n  }\n}\n```\n* `whitelist`/`blacklist` - An array of MAC addresses of devices. If `whitelist`\n  is used, only devices with a MAC address matching one of the entries will be\n  connected while if `blacklist` is used, only devices that do not match any\n  entry will be connected. It's possible to use the wildcard character `?` to\n  denote any value for a nibble.\n\n    ```json\n    \"whitelist\": [\n      \"aa:bb:cc:dd:ee:ff\",\n      \"00:11:22:??:??:??\"\n    ]\n    ```\n* `services` - Add additional services or override a existing definitions to the\n  ones grabbed automatically during build from http://www.bluetooth.org. Each\n  service can include a `name` field which will be used in the MQTT topic\n  instead of its UUID. In addition, it's possible to define a white/black list\n  for discovered services. The white/black list UUIDs may contain the wildcard\n  character `?` to denote any value for a nibble. For example:\n\n    ```json\n    \"services\": {\n      \"definitions\": {\n        \"00002f00-0000-1000-8000-00805f9b34fb\": {\n          \"name\": \"Relay Service\"\n        }\n      },\n      \"blacklist\": [\n        \"0000180a-0000-1000-8000-00805f9b34fb\",\n        \"0000ffff-????-????-????-????????????\"\n      ]\n    }\n    ```\n* `characteristics` - Add additional characteristics or override existing\n  definitions to the ones grabbed automatically during build from\n  http://www.bluetooth.org. Each characteristic can include a `name` field which\n  will be used in the MQTT topic instead of its UUID and a `types` array\n  defining how to parse the byte array reflecting the characteristic's value.\n  In addition, it's possible to define a white/black list for discovered\n  characteristics. The white/black list UUIDs may contain the wildcard character\n  `?` to denote any value for a nibble. For example:\n\n    ```json\n    \"characteristics\": {\n      \"definitions\": {\n        \"00002f01-0000-1000-8000-00805f9b34fb\": {\n          \"name\": \"Relay State\",\n          \"types\": [\n            \"boolean\"\n          ]\n        }\n      },\n      \"blacklist\": [\n        \"00002a29-0000-1000-8000-00805f9b34fb\",\n        \"0000ffff-????-????-????-????????????\"\n      ]\n    }\n    ```\n* `passkeys` - An object containing the passkey (number 000000~999999) that\n  should be used for out-of-band authorization. Each entry is the MAC address of\n  the BLE device and the value is the passkey to use. It's possible to use the\n  wildcard character `?` to denote any value for a nibble.\n\n    ```json\n    \"passkeys\": {\n      \"aa:bb:cc:dd:ee:ff\": 0,\n      \"00:11:22:??:??:??\": 123456\n    }\n    ```\n* `mikeys` - An object containing \"bind keys\" for Xiaomi MiBeacon devices.\n  Each entry is the MAC address of the BLE device and the value is the key to use.\n  Keys are only required for some devices and can be obtained using\n  [these methods](https://github.com/custom-components/ble_monitor/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key).\n\n    ```json\n    \"mikeys\": {\n      \"e4:aa:ec:xx:xx:xx\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"a4:c1:38:xx:xx:xx\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n    }\n    ```\n\nThe optional `log` section below includes the following entries:\n```json\n{\n  \"log\": {\n    \"host\": \"224.0.0.200\",\n    \"port\": 5000\n  }\n}\n```\n* `host` - The hostname or IP address to send the logs to. In case of an IP\n  address, this may be a unicast, broadcast or multicast address\n* `port` - The destination UDP port\n\n## OTA\n\nIt is possible to upgrade both firmware and configuration file over-the-air once\nan initial version was flashed via serial interface. To do so, execute:\n`idf.py upload` or `idf.py upload-config` accordingly.\nThe above will upgrade all BLE2MQTT devices connected to the MQTT broker defined\nin the configuration file. It is also possible to upgrade a specific device by\nadding the `OTA_TARGET` variable to the above command set to the host name of\nthe requested device, e.g.:\n```bash\nOTA_TARGET=BLE2MQTT-470C idf.py upload\n```\n\nNote: In order to avoid unneeded upgrades, there is a mechanism in place to\ncompare the new version with the one that resides on the flash. For the firmware\nimage it's based on the git tag and for the configuration file it's an MD5 hash\nof its contents. In order to force an upgrade regardless of the currently\ninstalled version, run `idf.py force-upload` or `idf.py force-upload-config`\nrespectively.\n\n## Board Compatibility\nThe `sdkconfig.defaults` included in this project covers common configurations.\n\n### Olimex ESP32-POE\nA number of minor changes are required to support this board:\n* Set the `eth` section as follows:\n  ```json\n  {\n    \"network\": {\n      \"eth\": {\n        \"phy\": \"LAN8720\",\n        \"phy_power_pin\": 12\n      }\n    }\n  }\n  ```\n* Run `idf.py menuconfig` and modify the Ethernet configuration to:\n  * RMII_CLK_OUTPUT=y\n  * RMII_CLK_OUT_GPIO=17\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshmuelzon%2Fesp32-ble2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshmuelzon%2Fesp32-ble2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshmuelzon%2Fesp32-ble2mqtt/lists"}