BTHome discussion topic

BTHome is a Bluetooth Low Energy (BLE) format to send sensor information from a Bluetooth device to a Bluetooth receiver (e.g. Home Assistant). The BTHome format allows you to create your own DIY Bluetooth sensors. More information about the BTHome format can be found on

I’ve opened this topic such that you can discuss everything related to BTHome here.

I will update this topic start in the near future, to show you some cool examples.



hello, I don’t know if this deserves a ticket opening or if it’s just me who doesn’t understand
I just got brand new shelly blu button 1
I have the functional bluetooth integration and I had thought that the addition was done “out of the box” (seeing last change log )

  • [BTHome] added support for button and dimmer events. This means it supports the brand new [Shelly BLU Button1] ! Thanks, [@Ernst79]
    When I click on the button I have the appearance of the device but only 3 entities and none concerning the actions of the button
    did I understand everything? :slight_smile:

Just create an automation (click on the + in the automation section on the left in your print screen) and you should be able to set an action on a certain button event.


In more detail, a button sends bthome_ble_events, it is not a sensor. Based on the event, you can start an action

so I really miss somthing
thank for your quick answer, work fine now

Hi, I created a test automation as above but nothing happens. Do you see any events in the log window of the BLU button device? I don’t see anything there, unlike older Button1 buttons.

Currently, events are not logged in the logbook. This will be added in a future update.
The fact that the older buttons do show something in the logbook is because the shelly integration has implemented logbook functionality, while the BTHome integration hasn’t (yet). I will add that in a future update of HA.

However, regardless of the logbook, automations should work fine. I have a Shelly BLU button too, and the automation works fine. Can you show me your automation configuration?

Hmm, I realized I had to move closer to the HA server. Is it possible that the initial detection works over a longer distance than BThome communication itself?

So my simple automation now works but I noticed that I have to wait 5-10 seconds before it can be repeated. Is it expected behaviour? The automation looks like this:

- id: '1684337094740'
  alias: Test BLU button
  description: ''
  - platform: device
    device_id: 42bc25105e80907f0c082ddf46118754
    domain: bthome
    type: button
    subtype: press
  - service: light.toggle
      entity_id: light.edison
  mode: single

I also tried to change the mode to queued but it didn’t help.

Bluetooth range can be limited when the Bluetooth receiver (HA) is close to a WiFi router, SSD drive and/or USB3 device. If it all works ok, it should respond immediately, not after 5 seconds. Hard to say what is wrong, but I suspect interference of Bluetooth with e.g WiFi.

Yes, my HA server with the Bluetooth USB dongle sits next to the WiFi router, I didn’t know they could interfere. I will try to put it somewhere else. Thanks for help and your work on BThome.

Here I some explanation and some tips how to prevent interference.

1 Like

I tried to move the HA server away from the WiFi router but don’t see much change. The problem with triggering the automation successively still persists: if I wait for 10+ seconds, it will be triggered again virtually every time, but triggering it within one second or so almost never works. @Ari-run, can you trigger the automation with the BLU button repeatedly in a short succession?

I’m having a similar issue to you. Using a es32 with Esphome as by BT proxy. Using it to open a lock on my communal for my flat so not really a big issue at the moment, but weird that it has a cool down period

I’ve just managed to feed a SparkFun NanoBeacon BLE advertisement in to BTHome, but I’m wondering if it is possible to have the integration publish raw data?
The problem is that BTHome expects a data type, but there is none for raw data publication (payload definition Reference – BTHome)

I have a SHT31 sensor connected over i2c on the NanoBeacon and the BLE advertise spews out raw sensor data. BTHome requires a data type for conversion, which I dont want/need.

The SHT31 sensor data should be converted in HA using the well known formula

float cTemp = ((((data[0] * 256.0) + data[1]) * 175) / 65535.0) - 45;
float humidity = ((((data[3] * 256.0) + data[4]) * 100) / 65535.0);

Does anyone knows how to do this?

You could use 4 count sensors of 1 byte (0x09) and use two template sensor to convert the data in HA. But can’t you convert it in the SparkFun NanoBeacon firmware itself? I’m not familiar with this device, but I assume you can program it?

I also thought of that, but as this my first BTHome adventure I thought ask here first :wink:
Don’t believe the beacon itself is programmable. Its based on the Inplay IN100 NanoBeacon and that was designed to publish sensor data over BLE.
What makes things worse is that I’m a HA beginner, so that doesnt help either.
And to top it off, the Beacon is one time programmable, so the advertising data must be good at the first attempt.

Hi @Ernst . I have a Shelly Blu also. HA reads button presses. I can automate as described by you above.

I have used the Shelly app to turn beacon mode on for the blu. Is something supposed to show up in HA as a result of adding beacon mode? Nothing seems to have.

To be honest, I haven’t used beacon mode yet. I don’t know what format is used in beacon mode, I will investigate. I doubt it is BTHome format, more likely something like iBeacon, Eddystone or something similar.

The great thing about the beacon is that you are totally free to do what you want. It supports iBeacon, Eddystone annd custom advertising data in which you can freely define your own data packet. This, on the other hand, makes it difficult for beginners like me. Take a look at the NanoBeacon Config Tool if you like NanoBeacon™ Config Tool — InPlay
There’s also a showcase video based on the SHT40 Ep14. I2C Configuration Explained with Sensirion SHT40 Temperature/Humidity Sensor Example - YouTube

I’ve composed an experimental custom data package and it appears to be working:

0x0201060D16D2FC403D8D6C02<TEMP 2byte 0 0>4A<VCC 2byte 1 0>

This will send out the internal sensor temp and board voltage.

What I want to achieve is, transmit i2c slave data. The sht31 datasheet says that both temperature and humidity consist of 3 byte packages, of which I only need the first 2 (3rd is crc).
As per your suggestion I could chop them up in 1 or 2 byte data packets and assemble them back in HA (need to figure out how). That would lead to the following data package:

0x0201060F16D2FC403D<I2C1R0 2byte 0 0>09<I2C1R2 1byte 0 0>3D<I2C1R3 2byte 0 0>09<I2C1R5 1byte 0 0>

Broken down:

Header: 0x020106

15 byte payload length: 0E

Service data: 16


Device info: 40

i2c measurement:

Bytes 1+2, offset 0: 3D<I2C1R0 2byte 0 0>
Byte 3, offset 2: 09<I2C1R2 1byte 0 0>
Byte 4+5, offset 3: 3D<I2C1R3 2byte 0 0>
Byte 6, offset 5: 09<I2C1R5 1byte 0 0>

This should theoretically work, but I’m hessitant to try because if you want to include i2c data the Beacon has to be programmed permanently. You can freely experiment with other data by running in ram, just not with i2c.
What do you think @Ernst, will this work?

I will also ask InPlay to review the data package, to include BTHome support in the Config Tool and for an API to make interfacing with, and integration in, HA possible. Maybe you can contact InPlay as well to lobby to make this possible? The more BTHome is used, the more manufacturers will support it.

Thanks for your help :+1:

That should work, I guess. You can use a template sensor to do some math with the numbers. However, as you send the two bytes of e.g. temperature in one value, you have to convert it back from an integer, to two bytes and than back to two integers, one for each byte. Can’t you send byte 1 and 2 as different counters? Same for 4+5?

Not sure what the best approach is, especially because I still lack sufficient in-depth HA knowledge, but learning fast :slight_smile:
I’m still convinced that BTHome should have some sort of data type for raw data, maybe a text type with a size of i.e. 24 characters? Then any kind of data can be stored without having to bother about the length or contents. After that the data can be processed in whatever manner necessary.
Is there a procedure for requesting this?
Are you willing to follow-up on my idea about contacting Inplay for the API, BTHome support and HA integration?