home-assistant / bthome.io

BTHome is a BLE API to broadcast data for your home.

Home Assistant

Open source home automation that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts. Perfect to run on a Raspberry Pi or a local server.

Check out home-assistant.io for a demo, installation instructions, tutorials and documentation.

This is a project of the Open Home Foundation.

Featured integrations

The system is built using a modular approach so support for other devices or actions can be implemented easily. See also the section on architecture and the section on creating your own components.

If you run into issues while using Home Assistant or during development of a component, check the Home Assistant help section of our website for further help and information.

bthome.io's Issues

BT home misses packages from Shelly BLU devices

I see previous post re. package misses from BT devices.
I run Shelly BLU devices.
In order to monitor the situation:
I have a script running on Shelly 1Mini Gen3 that holds a virtual component = a number variable, and second digit in this is equal to my door/window sensor. Example Open = 910000 Closed = 900000, so second digits is either 1 og 0.
When I display in Home Assistant both:
(1) The original BLU device entities
(2) My virtual component
It is clearly seen that the BLU device entities do not pass into Home Assistant correctly.
Also the log shows that only some packages are read by Home Assistant - whereas the virtual component react on each open/close of the door.
See screenshot.

Please define upper bound for door/garage door/window

All these object id's use uint8 data with 0 defined as Closed. Can we define the Open state? One can assume 1 as Open or 100(percent) as Open or 255 as open. This should not be left to implementers to decide or a chaos will rein :)

bthome and android mac address randomization

I'm trying to create presence detection based on sending packets with presence data from my phone every 60 seconds, that part working fine but android randomizes the mac address every few minutes so when I come home from a walk home assistant detects my phone as new device cause of that mac address change, there is no way how to set static mac address in android,

is there any way how to overcome this?

maybe you could add some new data type like a unique mac address...

v1.1

Use single UUID and add versioning

We want v2 to be able to get certified by the Bluetooth SIG, this requires to use a single UUID. This means moving encryption into the payload. We should also include a version number, just in case.

• Use a single UUID
• First byte should include encryption bit and version bit

Allow to communicate sleep time

Home Assistant currently assumes to receive an update every 5 minutes. If a sensor updates less often, the state of the sensor changes to unavailable.

Sensors might have widely different sleep times. Instead of making assumptions, it would be nice to have an option to communicate the expected sleep time using the BTHome protocol.

Related issue: home-assistant/core#78702

Optimize data payload

All data types have fixed predefined length and known scale factor. This information is definitely known to the clients receiving the data.
This information is redundant from the clients perspective, and should not go over the air and occupy the precious data payload.
Please consider removing it. This will free up to 30% of the usable payload data.
`

Object id	Property	Preferred data type	Factor	Example	Result	Unit	Reduced Example
0x01	battery	uint8 (1 byte)	1	020161	97	%	0161
0x02	temperature	sint16 (2 bytes)	0.01	2302CA09	25.06	°C	02CA09

`
etc.

Typo in `format.html` example

Hi,

There seems to be a typo here:

bthome.io/src/format.html

Line 708 in 9eb9527

<code>0C4A0C</code>

This should read 4A020C, I guess...

HTH,
Flössie

Support buttons

We want to support buttons with BTHome.

Requirements:

• Support multiple buttons (max 4?), so data needs to include an index.
• Support different press types. Initially press, double press, triple press, long press

New BTHome Project

I'm not sure if there's requirements or anything for a mention, but I've written a project using the ESP-IDF tools to send BTHome format packets, which some people may find useful to make their own sensor packages.

https://github.com/stumpylog/bthome-weather-station

Allow types to be specified multiple times

We want to allow a device to be able to report multiple measurements of the same data type. For example, a BBQ thermometer wants to report 4 temperature sensors.

• Allow the payload to support specifying the same data type multiple times
• Receiver will need to append numbers after the name for a type if a payload contains multiple of that type, ie temperature 1, temperature 2
• The data type that is specified multiple times will always need to be grouped together in the same payload and in the same order for the receiver to be able to find it. There is no index field.

sensor update only once

i'm using the pvvx firmware with a xiaomi thermometer 2 and i see the voltage sensor updating only one time after homeassistant startup.

bug or we have a big update interval to wait?!

(temperature or humidity update as expected)

thanks

Characteristic to offer configuration

Some data we want the receiver to know but it never changes. It would be nice if we could offer a read-only characteristic for receivers to fetch this. It could contain:

• Device class
• Interval that data is send (for unavailable tracking)
• Extended name
• Firmware name
• Firmware version
• Model name
• Manufacturer name

The flow would be:

• Receiver sees a BTHome packet
• Receiver makes a connection to fetch the static configuration
• Receiver will from time to time refresh the static configuration

ShellyBLU button 1 empty log

Hey,
I don't know if this is a bug of the bthome integration or something on the HA side,
but the shellyBLU button1 works fine if you use automations,
but the button itself isn't seen as a switch / entity

so no actions show up in the log aswell when pressing the button,
only the battery gets updated etc

Add support for tags

Home Assistant has the notion of tags. A tag is a random string that can be used for automations. It would be great if tag readers could be supported by BTHome to be able to support battery-powered tag readers.

• Add a new data type tag whose data is a string. Tags do not have a fixed length in Home Assistant.

Receiver should process it as a tag if it supports tags. In Home Assistant that will be async_scan_tag if the tag integration is set up.