ESP32-BLE2MQTT

This project aims to be a BLE to MQTT bridge, i.e. expose BLE GATT characteristics as MQTT topics for bidirectional communication. It's developed for the ESP32 SoC and is based on ESP-IDF release 3.0.

Important: Please note that recent versions of ESP-IDF have proven to be very unstable for be with regards to both WiFi and BLE performance. To that end, I suggest using commit 139d49894c473bd34ab6e9515e85d3f6871a30c7 of the ESP-IDF and compile this project with it.

For example, if a device with a MAC address of a0:e6:f8:50:72:53 exposes the 0000180f-0000-1000-8000-00805f9b34fb service (Battery Service) which includes the 00002a19-0000-1000-8000-00805f9b34fb characteristic (Battery Level), the a0:e6:f8:50:72:53/BatteryService/BatteryLevel MQTT topic is published with a value representing the battery level.

Characteristics supporting notifications will automatically be registered on and new values will be published once available. It's also possible to proactively issue a read request by publishing any value to the topic using the above format suffixed with '/Get'. Note that values are strings representing the characteristic values based on their definitions grabbed from http://bluetooth.org. For example, a battery level of 100% (0x64) will be sent as a string '100'.

In order to set a GATT value, publish a message to a writable characteristic using the above format suffixed with /Set. Payload should be of the same format described above and will be converted, when needed, before sending to the BLE peripheral.

Compiling

Download the repository and its dependencies:

git clone --recursive https://github.com/shmuelzon/esp32-ble2mqtt

Modify the configuration file to fit your environment, build and flash (make sure to modify the serial device your ESP32 is connected to):

make flash

Configuration

The configuration file provided in located at data/config.json in the repository. It contains all of the different configuration options.

The wifi section below includes the following entries:

{
  "wifi": {
    "ssid": "MY_SSID",
    "password": "MY_PASSWORD"
  }
}

• ssid - The WiFi SSID the ESP32 should connect to
• password - The security password for the above network

The mqtt section below includes the following entries:

{
  "mqtt": {
    "server": {
      "host": "192.168.1.1",
      "port": 1883,
      "username": null,
      "password": null,
      "client_id": null
    },
    "publish": {
      "qos": 0,
      "retain": true
    },
    "topics" :{
      "get_suffix": "/Get",
      "set_suffix": "/Set"
    }
  }
}

• server - MQTT connection parameters
• publish - Configuration for publishing topics
• topics
  • get_suffix - Which suffix should be added to the MQTT value topic in order to issue a read request from the characteristic
  • set_suffix - Which suffix should be added to the MQTT value topic in order to write a new value to the characteristic

The ble section of the configuration file includes the following default configuration:

{
  "ble": {
    "//Optional: 'whitelist' or 'blacklist'": [],
    "services": {
      "definitions": {},
      "//Optional: 'whitelist' or 'blacklist'": []
    },
    "characteristics": {
      "definitions": {},
      "//Optional: 'whitelist' or 'blacklist'": []
    },
    "passkeys": {}
  }
}

• whitelist/blacklist - An array of MAC addresses of devices. If whitelist is used, only devices with a MAC address matching one of the entries will be connected while if blacklist is used, only devices that do not match any entry will be connected

  "whitelist": [
    "aa:bb:cc:dd:ee:ff"
  ]

• services - Add additional services or override a existing definitions to the ones grabbed automatically during build from http://www.bluetooth.org. Each service can include a name field which will be used in the MQTT topic instead of its UUID. In addition, it's possible to define a white/black list for discovered services. For example:

  "services": {
    "definitions": {
      "00002f00-0000-1000-8000-00805f9b34fb": {
        "name": "Relay Service"
      }
    },
    "blacklist": [
      "0000180a-0000-1000-8000-00805f9b34fb"
    ]
  }

• characteristics - Add additional characteristics or override existing definitions to the ones grabbed automatically during build from http://www.bluetooth.org. Each characteristic can include a name field which will be used in the MQTT topic instead of its UUID and a types array defining how to parse the byte array reflecting the characteristic's value. In addition, it's possible to define a white/black list for discovered characteristics. For example:

  "characteristics": {
    "definitions": {
      "00002f01-0000-1000-8000-00805f9b34fb": {
        "name": "Relay State",
        "types": [
          "boolean"
        ]
      }
    },
    "blacklist": [
      "00002a29-0000-1000-8000-00805f9b34fb"
    ]
  }

• passkeys - An object containing the passkey (number 000000~999999) that should be used for out-of-band authorization. Each entry is the MAC address of the BLE device and the value is the passkey to use.

  "passkeys": {
    "aa:bb:cc:dd:ee:ff": 000000
  }

OTA

It is possible to upgrade both firmware and configuration file over-the-air once an initial version was flashed via serial interface. To do so, execute: make upload or make upload-config accordingly. The above will upgrade all BLE2MQTT devices connected to the MQTT broker defined in the configuration file. It is also possible to upgrade a specific device by adding the OTA_TARGET variable to the above command set to the host name of the requested device, e.g.:

make upload OTA_TARGET=BLE2MQTT-470C

Note: In order to avoid unneeded upgrades, there is a mechanism in place to compare the new version with the one that resides on the flash. For the firmware image it's based on the git tag and for the configuration file it's an MD5 hash of its contents. In order to force an upgrade regardless of the currently installed version, run make force-upload or make force-upload-config respectively.