BTHome logo

BTHome is an open standard for broadcasting sensor data over Bluetooth LE

BTHome is an energy effective but flexible BLE format for devices to broadcast their sensor data. Devices can run over a year on a single battery. It allows data encryption and is supported by popular home automation platforms, like Home Assistant, out of the box.

Picture showing a Bluetooth temperature sensor broadcasting it's data to Home Assistant, showing it formatted to the user.

BTHome is part of the Open Home and aims to create smart homes that offer privacy, choice and durability. Learn more about the Open Home.

Projects using BTHome

Home Assistant

Open source home automation with a focus on local control and privacy. Automatically discovers BTHome devices and allows users to add them to their home with a single click.

Website

ATC MiThermometer

Custom firmware for several Bluetooth thermometer & hygrometer devices that can broadcast temperature and humidity via BTHome.

Use their TelinkMiFlasher.html tool to upgrade your device directly from your browser. Once installed, change the advertising type to "BTHome" and click "Send Config".

Website

b-parasite

b-parasite is an open source soil moisture and ambient temperature/humidity/light sensor that supports BTHome.

Website

ESP32_BTHome

ESP32_BTHome is an example of using an ESP32 to send BLE advertisement packets in the BTHome format in such way that you have a very lightweight, energy efficient sensor. Between the broadcasting of BLE advertisements, the ESP32 will in a sleeping state, making it more suitable for battery powered sensors.

Website

Example Data

The format can best be explained with an example. A BLE advertisement is a long message with bytes (bytestring).

043E2702010000A5808FE648541B 0201060B094449592D73656E736F720B161C182302C4090303BF13 CC

This message is split up in three parts, the header, the advertising payload and an RSSI value

The first part 043E2702010000A5808FE648541B is the header of the message and contains, amongst others

Advertising payload

The second part 020106 0B094449592D73656E736F72 0B161C182302C4090303BF13 contains the advertising payload, and can consist of one or more Advertising Data (AD) elements. Each element contains the following:

The advertising payload should contain the following three AD elements:

In the example, we have:

BTHome Data format

The BTHome data can contain multiple measurements. We continue with the example from above.

BTHome data = 0x1C18 2302C409 0303BF13

Lets explain how the last two data packets work. The temperature packet is used as example. The first byte 0x23 (in bits 00100 011) is giving information about:

Type Bit 5-7 Format Data Type
0 000 uint unsingned integer
1 001 int signed integer
2 010 float float
3 011 string string
4 100 MAC MAC address (reversed)

Supported data

Full example payloads for each data type.

Sensor data

Object id Property Preferred data type Factor Example Result Unit
0x01 battery uint8 (1 byte) 1 020161 97 %
0x02 temperature sint16 (2 bytes) 0.01 2302CA09 25.06 °C
0x03 humidity uint16 (2 bytes) 0.01 0303BF13 50.55 %
0x04 pressure uint24 (3 bytes) 0.01 0404138A01 1008.83 hPa
0x05 illuminance uint24 (3 bytes) 0.01 0405138A14 13460.67 lux
0x06 mass (kg) uint16 (2 byte) 0.01 03065E1F 80.3 kg
0x07 mass (lb) uint16 (2 byte) 0.01 03073E1D 74.86 lb
0x08 dewpoint sint16 (2 bytes) 0.01 2308CA06 17.38 °C
0x09 count uint 1 020960 96
0X0A energy uint24 (3 bytes) 0.001 040A138A14 1346.067 kWh
0x0B power uint24 (3 bytes) 0.01 040B021B00 69.14 W
0x0C voltage uint16 (2 bytes) 0.001 030C020C 3.074 V
0x0D pm2.5 uint16 (2 bytes) 1 030D120C 3090 ug/m3
0x0E pm10 uint16 (2 bytes) 1 030E021C 7170 ug/m3
0x12 co2 uint16 (2 bytes) 1 0312E204 1250 ppm
0x13 tvoc uint16 (2 bytes) 1 03133301 307 ug/m3
0x14 moisture uint16 (2 bytes) 0.01 0314020C 30.74 %

Binary Sensor data

Binary sensor data should always be an uint8 of a single byte. It's value should be 1 for on, and 0 for off. Note: Binary sensors will be supported in Home Assistant 2022.10.

Object id Property Data type Example Result
0x0F generic boolean uint8 (1 byte) 020F01 1 (True = On)
0x10 power uint8 (1 byte) 021001 1 (True = On)
0x11 opening uint8 (1 byte) 021100 0 (False = Closed)
0x15 battery uint8 (1 byte) 021500 0 (False = Low)
0x16 battery charging uint8 (1 byte) 021601 1 (True = Charging)
0x17 carbon monoxide uint8 (1 byte) 021700 0 (False = Not detected)
0x18 cold uint8 (1 byte) 021801 1 (True = Cold)
0x19 connectivity uint8 (1 byte) 021900 0 (False = Disconnected)
0x1A door uint8 (1 byte) 021A00 0 (False = Closed)
0x1B garage door uint8 (1 byte) 021B01 1 (True = Open)
0x1C gas uint8 (1 byte) 021C01 1 (True = Detected)
0x1D heat uint8 (1 byte) 021D00 0 (False = Normal)
0x1E light uint8 (1 byte) 021E01 1 (True = Light detected)
0x1F lock uint8 (1 byte) 021F01 1 (True = Unlocked)
0x20 moisture uint8 (1 byte) 022001 1 (True = Wet)
0x21 motion uint8 (1 byte) 022100 0 (False = Clear)
0x22 moving uint8 (1 byte) 022201 1 (True = Moving)
0x23 occupancy uint8 (1 byte) 022301 1 (True = Detected)
0x24 plug uint8 (1 byte) 022400 0 (False = Unplugged)
0x25 pressence uint8 (1 byte) 022500 0 (False = Away)
0x26 problem uint8 (1 byte) 022601 1 (True = Problem)
0x27 running uint8 (1 byte) 022701 1 (True = Running)
0x28 safety uint8 (1 byte) 022800 0 (False = Unsafe)
0x29 smoke uint8 (1 byte) 022901 1 (True = Detected)
0x2A sound uint8 (1 byte) 022A00 0 (False = Clear)
0x2B tamper uint8 (1 byte) 022B00 0 (False = Off)
0x2C vibration uint8 (1 byte) 022C01 1 (True = Detected)
0x2D window uint8 (1 byte) 022D01 1 (True = Closed)

Misc data

Object id Property Data Type Example Result
0x00 packet id uint8 (1 byte) 020009 9
mac 6 bytes (reversed) 86A6808FE64854 5448E68F80A6
Packet id

The packet id is optional and can be used to filter duplicate data. This allows you to send multiple advertisements that are exactly the same, to improve the chance that the advertisement arrives. BTHome receivers should only process the advertisement if the packet id is different compared to the previous one. The packet id is a value between 0 (0x00) and 255 (0xFF), and should be increased on every change in data.

MAC address

You don’t have to specify the mac address in the advertising payload, as it is already included in the header. However, you can overwrite the mac by specifying it in the advertising payload. To do this, set the first byte to 0x86 (meaning: object type = 4 (mac) and object length = 6), followed by the MAC in reversed order. No Object id is needed. Note that the use of alternative mac addresses is not supported in Home Assistant.

Encryption

Unencrypted BLE advertisements can be read by anyone nearby listening for Bluetooth packets. BTHome supports AES encryption (CCM mode) which works with a pre-shared key. When encrypted, the data can only be read by knowing the encryption key. The encryption key should be a 16 bytes long key (32 characters).

More information on how to encrypt your messages is demonstrated in this script.

Scope & Constraints

The goal of the BTHome standard is to share sensor data efficiently via Bluetooth LE discovery packets. It is not the goal to offer a way for devices to share control.