Skip to content
Get started

BTHome MiThermometer Sensor

The bthome_mithermometer sensor platform lets you receive measurements from Xiaomi/Mijia thermometers broadcasting in BTHome v2 format — that is, devices flashed with PVVX MiThermometer firmware and set to the “BTHome v2” advertisement type. The component listens passively to the advertisements, so it does not pair with the device and has no impact on its battery life.

Other BTHome v2 thermometers work too, as long as they send temperature and humidity in one of the standard formats the component decodes: temperature in 0.01 °C (object 0x02, PVVX) or 0.1 °C (object 0x45), humidity in 0.01 % (object 0x03, PVVX) or 1 % (object 0x2E). Each object is decoded on its own, so any combination works. The Shelly BLU H&T, for example, sends temperature as 0x45 and humidity as 0x2E.

It requires a BLE tracker, for example the ESP32 BLE Tracker, to receive the advertisements.

For choosing between the firmware options of these thermometers (stock MiBeacon, ATC, PVVX and their advertisement formats) and for flashing/bindkey instructions, see LYWSD03MMC on the Xiaomi BLE page — this page is the option reference for the bthome_mithermometer platform itself.

# Example configuration entry
esp32_ble_tracker:
sensor:
- platform: bthome_mithermometer
mac_address: "XX:XX:XX:XX:XX:XX"
bindkey: "00112233445566778899aabbccddeeff"
temperature:
name: "BTHome Temperature"
humidity:
name: "BTHome Humidity"
battery_level:
name: "BTHome Battery Level"

NOTE

A bindkey is only required for devices configured to encrypt their BTHome advertisements; unencrypted devices work without one. It is the same 32-character (16-byte) hex key you set when enabling encryption on the device (for example in the ATC/PVVX web configurator).

A bindkey makes sure that only the device can create valid advertisements, but a valid advertisement recorded by someone in range can still be sent again later. With replay_protection: true the component uses the counter carried by every encrypted advertisement to ignore:

  • an exact repeat of the last advertisement;
  • an advertisement whose counter is lower than the last accepted one (a warning is logged).

An advertisement with the same counter but new data is accepted, because some firmwares (for example PVVX) send new readings without increasing the counter. If the device restarts its counter, for example after a battery change, its advertisements are accepted again once none has been accepted for 10 minutes, so expect a gap of up to 10 minutes in that case. The last counter is not stored across reboots of the ESP, so the first valid advertisement after a reboot is always accepted.

So the check holds only while the device keeps being heard. After a reboot of the ESP, or after 10 minutes without an accepted advertisement, one recorded advertisement is accepted again and becomes the new baseline, and recorded advertisements with higher counters can then follow it in order. On a firmware that does not increase the counter it only blocks advertisements with a lower counter.

  • mac_address (Required, MAC Address): The MAC address of the device to receive data from.
  • bindkey (Optional, 32-character hex string): The encryption key for devices that broadcast encrypted BTHome advertisements. Omit it for unencrypted devices.
  • replay_protection (Optional, boolean): Ignore repeated or older encrypted advertisements, see Replay protection. Requires bindkey. Defaults to false.
  • temperature (Optional): The temperature, in °C. All options from Sensor.
  • humidity (Optional): The relative humidity, in %. All options from Sensor.
  • battery_level (Optional): The battery level, in %. All options from Sensor.
  • battery_voltage (Optional): The battery voltage, in V. All options from Sensor.
  • signal_strength (Optional): The signal strength (RSSI), in dBm. All options from Sensor.
  • esp32_ble_id (Optional, ID): The ID of the ESP32 BLE Tracker to receive advertisements from. Only needed when more than one tracker is configured.