Table of contents
BLE monitor has created support for your own DIY sensors, by introducing our own BLE format that can be read by BLE monitor, called
HA BLE. This format tries to provide an energy efective, but still flexible BLE format that can be customized to your own needs. A proof of concept is the latest ATC firmware, which is supporting our new HA BLE format (firmware version 3.7 and up).
The data format has changed from earlier versions, starting with BLE monitor version 8.1.0 HA BLE is using a new, more efficient, format. Note that The old format will be deprecated soon.
HA BLE format can best be explained with an example. A BLE advertisement is a long message with bytes (bytestring).
This message is split up in three parts, the header, the advertising payload and an RSSI value
- Adverting payload
- RSSI value
The first part
043E1B02010000A5808FE648540F is the header of the message and contains, amongst others
- the length of the message in the 3rd byte (
0x1Bin hex is 27 in decimals, meaning 27 bytes after the third byte = 30 bytes in total)
- the MAC address in reversed order in byte 8-13 (
A5808FE64854, in reversed order, this corresponds to a MAC address
- the length of the advertising payload in byte 14 (
The second part
0201060B161C182302C4090303BF13 contains the advertising payload, and can consist of one or more Advertising Data (AD) elements. Each element contains the following:
- 1st byte: length of the element (excluding the length byte itself)
- 2nd byte: AD type – specifies what data is included in the element
- AD data – one or more bytes - the meaning is defined by the AD type
HA BLE format, the advertsing payload should contain the following two AD elements:
- Flags (
- UUID16 (
In the example, we have:
- First AD element:
0x02= length (2 bytes)
0x06= in bits, this is
00000110. Bit 1 and bit 2 are 1, meaning: Bit 1: “LE General Discoverable Mode” Bit 2: “BR/EDR Not Supported”
- This part always has to be added, and is always the same (
- Second AD element:
0B161C182302C4090303BF13(HA BLE data)
0x0B= length (11 bytes)
0x16= Service Data - 16-bit UUID
0x1C182302C4090303BF13= HA BLE data
The HA BLE data is the part that contains the data. The data can contain multiple measurements. We continue with the example from above.
- HA BLE data =
0x1C18= The first two byte are the UUID16, which are assigned numbers that can be found in [this official document]https://btprodspecificationrefs.blob.core.windows.net/assigned-values/16-bit%20UUID%20Numbers%20Document.pdf by the Bluetooth organization. For HA BLE we use the so called
0x1C18) for non-encrypted messages. For encrypted messages, we use
0x1E18). More information about encryption can be found further down this page. This part should always be
0x1E18(encrypted), as it is used to recognize a HA BLE message.
0x2302C409= Temperature packet
0x0303BF13= Humidity packet
Lets explain how the last two data packets work. The temperature packet is used as example.
- The first byte
00100011) is giving information about:
- The object length (bit 0-4):
00011= 3 bytes (excluding the length byte itself)
- The object format (bit 5-7)
001= 1 = Signed Integer (see table below)
- The object length (bit 0-4):
|type||bit 5-7||format||Data type|
| || ||uint||unsingned integer|
| || ||int||signed integer|
| || ||float||float|
| || ||string||string|
| || ||MAC||MAC address (reversed)|
- The second byte
0x02is defining the type of measurement (temperature, see table below)
- The remaining bytes
0xC409is the object value (little endian), which will be multiplied with the factor in the table below to get a sufficient number of digits.
- The object length is telling us that the value is 2 bytes long (object length = 3 bytes minus the second byte) and the object format is telling us that the value is an Signed Integer (possitive or negative integer).
0xC409as unsigned integer in little endian is equal to 2500.
- The factor for a temperature measurement is 0.01, resulting in a temperature of 25.00°C
At the moment, the following sensors are supported. A preferred data type is given for your convienience, which should give you a short data message and at the same time a sufficient number of digits to display your data with high accuracy in Home Assistant. But you are free to use a different data type. If you want another sensor, let us know by creating a new issue on Github.
|Object id||Property||Preferred data type||Factor||example||result||Unit in HA||Notes|
| ||packet id||uint8 (1 byte)||1|| ||9|||
| ||battery||uint8 (1 byte)||1|| ||97|| |
| ||temperature||sint16 (2 bytes)||0.01|| ||25.06|| |
| ||humidity||uint16 (2 bytes)||0.01|| ||50.55|| |
| ||pressure||uint24 (3 bytes)||0.01|| ||1008.83|| |
| ||illuminance||uint24 (3 bytes)||0.01|| ||13460.67|| |
| ||weight||uint16 (2 byte)||0.01|| ||80.3|| |||
| ||weight unit||string (2 bytes)||None|| ||“kg”|||
| ||dewpoint||sint16 (2 bytes)||0.01|| ||17.386|| |
| ||count||uint||1|| ||96|
| ||energy||uint24 (3 bytes)||0.001|| ||1346.067|| |
| ||power||uint24 (3 bytes)||0.01|| ||69.14|| |
| ||voltage||uint16 (2 bytes)||0.001|| ||3.074|| |
| ||pm2.5||uint16 (2 bytes)||1|| ||3090|| |
| ||pm10||uint16 (2 bytes)||1|| ||7170|| |
| ||boolean||uint8 (1 byte)||1|| ||1 (True)|| |
| ||switch||uint8 (1 byte)||1|| ||1 (True)|| |
| ||opening||uint8 (1 byte)||1|| ||0 (false)|| |
| ||co2||uint16 (2 bytes)||1|| ||1250|| |
| ||tvoc||uint16 (2 bytes)||1|| ||307|| |
|mac||6 bytes (reversed)|| ||5448E68F80A6|||
Full example payloads are given in the test_ha_ble.py file.
1. packet id
packet id is optional and is 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. BLE monitor will 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.
2. weight (unit)
weight unit is in
kg by default, but can be set with the weight unit property. Examples of
weight unit packets are:
- kg (
- lbs (
- jin (
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.
Restore state with restart
Currently, the state of a sensor is not restored when restarting HA, even when this is enabled in the BLE monitor settings. This will be fixed in a future update.
You can also choose to send the data in an encrypted way, which gives you extra security. Unencrypted BLE advertisements can be read by everyone, even your neighbour with Home Assistant and BLE Monitor should in theory be able to receive your BLE data. However, when you use encryption, it will be useless for anyone else, as long as he or she doesn’t have 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. HA BLE monitor is using an AES encryption (CCM mode). Don’t forget to set the encryption key in your BLE monitor device settings.