BLE Gateway

For ESP32 Bluetooth go here

Bluetooth Low Energy Sensors~

Different vendors offer Bluetooth solutions, mostly as part of the Xiaomi brand, often under the Mijia label. The sensors supported by Tasmota use BLE (Bluetooth Low Energy) to transmit the sensor data, but they differ in their accessibilities quite substantially.

Basically all of them use the so-called "MiBeacons" which are BLE advertisement packets with a certain data structure, which are broadcasted by the devices automatically while the device is not in an active Bluetooth connection.
The frequency of these messages is set by the vendor and ranges from one per 3 seconds to one per hour (e.g., for the battery status of the LYWSD03MMC). Motion sensors and BLE remote controls start to send when an event is triggered.
These packets already contain the sensor data and can be passively received by other devices and will be published regardless if a user decides to read out the sensors via connections or not. Thus the battery life of a BLE sensor is not influenced by reading these advertisements and the big advantage is the power efficiency as no active bi-directional connection has to be established. The other advantage is, that scanning for BLE advertisements can happen nearly parallel (very quickly one after the other), while a direct connection must be established for at least a few seconds and will then block both involved devices for that time.

This is therefore the preferred option, if supported by the sensor.

Supported Devices~

The naming conventions in the product range of Bluetooth sensors in Xiaomi universe can be a bit confusing. The exact same sensor can be advertised under slightly different names depending on the seller (Mijia, Xiaomi, Cleargrass, ...).

MJ_HT_V1	LYWSD02	CGG1	CGD1
temperature, humidity, battery	temperature, humidity, battery	temperature, humidity, battery	temperature, humidity, battery
passive for all entities, reliable battery value	battery only active, thus not on the NRF24L01, set clock and unit, very frequent data sending	passive for all entities, reliable battery value	battery only active, thus not on the NRF24L01, no reliable battery value, no clock functions

MiFlora	LYWSD03MMC / ATC	NLIGHT	MJYD2S
temperature, illuminance, soil humidity, soil fertility, battery, firmware version	temperature, humidity, battery	motion	motion, illuminance, battery, no-motion-time
passive only with newer firmware (>3.0?), battery only active, thus not on the NRF24L01	passive only with decryption or using custom ATC-firmware, no reliable battery value with stock firmware	NRF24L01, ESP32	passive only with decryption, thus only NRF24L01, ESP32

YEE RC	MHO-C401	MHO-C303
button press (single and long)	temperature, humidity, battery	temperature, humidity, battery
passive	equal to the LYWS03MMC, but no custom firmware yet	passive for all entities, set clock and unit, no alarm functions, very frequent data sending

passive means data is received via BLE advertisements while active means data is received via a bidirectional connection to the sensor.

LYWSD03MMC sends encrypted sensor data every 10 minutes. As there are no confirmed reports about correct battery presentation of the sensor (always shows 99%), this function is currently not supported.

MJYD2S sends motion detection events and 2 discrete illuminance levels (1 lux or 100 lux for a dark or bright environment). Additionally battery level and contiguous time without motion in discrete growing steps (no motion time = NMT).

Encryption and bind_key~

Most of the older sensors use unencrypted messages, which can be read by all kinds of BLE devices or even a NRF24L01. With the arrival of newer sensors, such as LYWSD03MMC, MHO-C401 or MJYD2S, came the problem of encrypted data in MiBeacons, which can be decrypted in Tasmota (not yet with the HM-1x).

Some sensor still allow an unencrypted connection the reading of the sensor data using normal subscription methods to GATT-services (currently used on the HM-1x). This is more power hungry than the passive reading of BLE advertisements.

Some other sensors like the MJYD2S are not usable without the "bind_key".

It is recommended to obtain the bind_key if usable by your BLE driver to reduce the battery drain.

Obtain bind_key~

To get the necessary decryption key ("bind_key") use:

• Xiaomi Cloud Tokens Extractor (Windows executable or Python) - works on any device in the Mi Home app
• pvvx Telink Flasher (Webpage) - LYWSD03MMC, MHO-C401 and CGG1 only
• ATC Telink Flasher (Webpage) - LYWSD03MMC only

Telink Flashers allow the generation of a bind_key by faking a pairing with the Xiaomi cloud.

Use bind_key~

Use the bind_key and MAC address of the sensor to use with command NRFkey. Tasmota will receive the sensor data roughly every 10 minutes (in two chunks for humidity and temperature with about a minute in between) and decode the data. This is the most energy efficient way.

The current way of storing these keys on the NRF24L01 is to use NRFkey):

rule1 on System#Boot do backlog NRFkey 00112233445566778899AABBCCDDEEFF112233445566; NRFkey 00112233445566778899AABBCCDDEEFF112233445566; NRFPage 6; NRFUse 0; NRFUse 4 endon

Encryption is not supported on HM-1x (for legacy reasons). The only method is to connect to the sensor from time to time. This circumvents the data encryption but drains the battery fast. Thus it is only recommended as a last resort.

Custom firmware~

pvvx Telink Flasher also allows to flash custom firmware on supported sensors. This will work out of the box with Tasmota. This firmware does send data more frequently and is a bit more power hungry than the stock firmware.

Working principle of Tasmota BLE drivers (>8.5.)~

The idea is to provide drivers with as many automatic functions as possible. Besides the hardware setup, there are zero or very few things to configure.
The sensor namings are based on the original sensor names and shortened if appropriate (Flower care -> Flora). A part of the MAC will be added to the name as a suffix.
All sensors are treated as if they are physically connected to the ESP8266 device. For motion and remote control sensors, MQTT messages will be published in (nearly) real time.

Take note that only the ESP32 and the HM-1x modules are real BLE devices whereas the NRF24L01(+) is only a generic 2.4 GHz transceiver with very limited capabilities that was finagled into reading BLE packets.

using HM-1x~

Otherwise you must compile your build. Add the following to user_config_override.h:

#ifndef USE_HM10
#define USE_HM10          // Add support for HM-10 as a BLE-bridge (+9k3 code)
#endif

Features~

Supported sensors will be connected to at a set interval (default interval equals TelePeriod). A subscription is established for 5 seconds and data (e.g. temperature, humidity and battery) is read and reported to an mqtt topic (Dew point is calculated):

tele/%topic%/SENSOR = {"Time":"2020-03-24T12:47:51","LYWSD03-52680f":{"Temperature":21.1,"Humidity":58.0,"DewPoint":12.5,"Battery":100},"LYWSD02-a2fd09":{"Temperature":21.4,"Humidity":57.0,"DewPoint":12.5,"Battery":2},"MJ_HT_V1-d8799d":{"Temperature":21.4,"Humidity":54.6,"DewPoint":11.9},"TempUnit":"C"}

After a completed discovery scan, the driver will report the number of found sensors. As Tasmota can not know how many sensors are meant to be discovered you have to force a re-scan until the desired number of devices is found.

Rule1 ON HM10#Found<6 DO Add1 1 ENDON ON Var1#State<=3 DO HM10Scan ENDON 

using nRF24L01(+)~

Configuration~

You must compile your build. Change the following in my_user_config.h:

#define USE_SPI                                  // Hardware SPI using GPIO12(MISO), GPIO13(MOSI) and GPIO14(CLK) in addition to two user selectable GPIOs(CS and DC)
#ifdef USE_SPI
  #define USE_NRF24                              // Add SPI support for NRF24L01(+) (+2k6 code)
  #ifdef USE_NRF24
    #define USE_MIBLE                            // BLE-bridge for some Mijia-BLE-sensors (+4k7 code)

Sensors will be discriminated by using the Product ID of the MiBeacon. A human readable short product name will be shown instead of the company-assigned ID of the BLE Public Device Address (the "lower" 24 bits).

A Tele message could like look this:

10:13:38 RSL: stat/tasmota/STATUS8 = {"StatusSNS":{"Time":"2019-12-18T10:13:38","Flora-6ab577":{"Temperature":21.7,"Illuminance":21,"Humidity":0,"Fertility":0},"MJ_HT_V1-3108be":{"Temperature":22.3,"Humidity":56.1},"TempUnit":"C"}}

As the NRF24L01 can only read BLE-advertisements, only the data in these advertisements is accessible. All sensors have an additional GATT-interface with more data in it, but it can not be read with a NRF24L01.

As we can not use a checksum to test data integrity of the packet, only data of sensors whose addresses showed up more than once (default = 3 times) will be published. Internally from time to time "fake" sensors will be created, when there was data corruption in the address bytes. These will be removed automatically.

Commands~

Full list of available Bluetooth commands.

iBeacon~

Otherwise you must compile your build. Add the following to user_config_override.h:

#ifndef USE_IBEACON
#define USE_IBEACON          // Add support for bluetooth LE passive scan of ibeacon devices 
#endif

HM-1x or nRF24L01(+)~

Tasmota uses a BLE 4.x module to scan for iBeacon devices. This driver is working with HM-10 and clones and HM16/HM17 modules and potentially other from the HM-1x series, depending on firmware capabilities.

Features~

For a list of all available commands see Sensor52 command.

This driver reports all beacons found during a scan with its ID (derived from beacon's MAC address) prefixed with IBEACON_ and RSSI value.

Every beacon report is published as an MQTT tele/%topic%/SENSOR in a separate message:

tele/ibeacon/SENSOR = {"Time":"2021-01-02T12:08:40","IBEACON":{"MAC":"A4C1387FC1E1","RSSI":-56,"STATE":"ON"}}

If the beacon can no longer be found during a scan and the timeout interval has passed the beacon's RSSI is set to zero (0) and it is no longer displayed in the webUI

tele/ibeacon/SENSOR = {"Time":"2021-01-02T12:08:40","IBEACON":{"MAC":"A4C1387FC1E1","RSSI":-56,"STATE":"OFF"}}

Additional fields will be present depending upon the beacon, e.g. NAME, UID, MAJOR, MINOR.

Supported Devices~

All Apple compatible iBeacon devices should be discoverable.

Various nRF51822 beacons should be fully Apple compatible, programmable and their battery lasts about a year.

• Amazon.com
• Aliexpress

Cheap "iTag" beacons with a beeper. The battery on these lasts only about a month.

• Aliexpress
• eBay
• Amazon.com