Support buttons about bthome.io

[kzyapkov]

My 2 cents:

Switches should be treated as objects with state and be part of the "Binary Sensor data" section. (or "discrete sensor data", since switches with more than 2 states may exist, like rotary switches or some such)

Buttons should be able to emit press, double press, triple press, long press, etc. events.

"turn_on", "turn_off" sound more like commands, not events. I think the actions associated with button events or switch state changes should be generated elsewhere.

[Ernst79]

@balloob, @bdraco, I'm afraid I will need some guidance to get this done step by step. I think we need to modify things in the following order.

• sensor-state-data
• bthome-ble
• HA BTHome integration

So, first things first, sensor-state-data gives me the following output after a "normal" binary sensor (opening) and sensor (signal strength) update.

    SensorUpdate(
        title="TEST DEVICE 18B2",
        devices={
            None: SensorDeviceInfo(
                name="TEST DEVICE 18B2",
                manufacturer=None,
                model="BTHome sensor",
                sw_version="BTHome BLE",
                hw_version=None,
            )
        },
        entity_descriptions={
            KEY_SIGNAL_STRENGTH: SensorDescription(
                device_key=KEY_SIGNAL_STRENGTH,
                device_class=SensorDeviceClass.SIGNAL_STRENGTH,
                native_unit_of_measurement=Units.SIGNAL_STRENGTH_DECIBELS_MILLIWATT,
            ),
        },
        entity_values={
            KEY_SIGNAL_STRENGTH: SensorValue(
                device_key=KEY_SIGNAL_STRENGTH, name="Signal Strength", native_value=-60
            ),
        },
        binary_entity_descriptions={
            KEY_BINARY_OPENING: BinarySensorDescription(
                device_key=KEY_BINARY_OPENING,
                device_class=BinarySensorDeviceClass.OPENING,
            ),
        },
        binary_entity_values={
            KEY_BINARY_OPENING: BinarySensorValue(
                device_key=KEY_BINARY_OPENING, name="Opening", native_value=False
            ),
        },
    )

So, I think it would make sense to expand this (for a button device) with something like

        device_trigger_event={
            KEY_BUTTON: DeviceTriggerEvent(
                event_key=KEY_BUTTON,
                name="Button",
                type="turn_on",
                subtype=None,
            ),
        },

Is this all the info we need for events? I don't think we need something similar as binary_entity_descriptions, is it? As all the device info in in the devices part already. BTW, I added subtype, as I know Xiaomi makes combinations, like dimmers, type="turn left", subtype="3 steps"

[bdraco]

That seems reasonable to me, but we probably need to know which device_id triggered the event

[bdraco]

ex
DeviceKey(key="button_1", device_id=None),
DeviceKey(key="button_1", device_id="controller"),
DeviceKey(key="button_1", device_id="remote1"),

[Ernst79]

Yes, in this example above, KEY_BUTTON = DeviceKey(key="button", device_id=None), so it can contain a device_id

KEY_BUTTON = DeviceKey(key="button", device_id=None)

...

        device_trigger_events={
            KEY_BUTTON: DeviceTriggerEvent(
                device_key=KEY_BUTTON,
                name="Button",
                event_type="turn_on",
                event_subtype=None,
            ),
        },

[Ernst79]

PR for sensor-state-data is ready to review. It adds support for events for dimmers, switches and buttons.

Bluetooth-Devices/sensor-state-data#38

[Ernst79]

PR for bthome-ble is ready to review.

Bluetooth-Devices/bthome-ble#12

[mgsb]

Is it implied that a "0" for event id means "no change"? So if the same adv packet is sent every time, a 0 would be used for buttons/switches that have not had an event?

[Ernst79]

No it isn’t. But why would you want to send “no change”?

[balloob]

Buttons are events and not a state, so there is no binary sensor representation of a button to be on and off. It's just events.

[mgsb]

I am looking at composite devices. For example, a device with a button
and temperature/humidity sensors. Does this device always advertise
all three values? If yes, what does it use when reporting
temperature/humidity and the button has not generated an event? If no,
when does the user discover the button entity when the device is
added? Is the general model that composite devices advertise subsets
of values?

[Ernst79]

There is no need to send all three values at the same time.

there won’t be a button entity, there will be a device in HA with a temperature and humidity entity, and the device will send an “button turn_on” event e.g.

Please note that support for events has not been added yet in Home Assistant. It’s a bit more complicated (for me at least) than I hoped, so I have decided to first do some work on BTHome V2.

[kzyapkov]

In the context of the current description of "Events" on "bthome.io", what is the difference between a button and a switch? I find the events being supported by those two objects somewhat misaligned.

Buttons: users can push (press), and release. HID input devices usually generate "button down", "button up", and the higher level "button press", "button hold", for sequences of presses "double press", "triple press" etc. BTHome should probably only deal with the higher-level, "processed" events. But the ones currently enumerated are "turn_on", "turn_off" and "toggle". Those seem to be events for a different type of an input device?

Same for switches: those have two stable states, and users can operate the switch changing between the two. Essentially, only two events can be emitted: "on" and "off", and switches actually have state which can be read. But BTHome defines a number of other events, most of which are something that would come out of a button, not a bi-stable swtich?

So I'm wondering where does this definition come from, what is the rationale?

Also, the current format doesn't allow for a device with multiple buttons. This can probably be circumvented if ble devices use a different MAC for each button, but that's somewhat involved. It's always a tradeoff, but sparing a few bits for "button id" may be worth it.

Gen1 shellies support something we internally call "piano mode" -- any sequence of short and long button presses can be recorded by the device and sent as an event notification. It'd be neat if BTHome supported something like this -- 2 bits per event and a variable element length (4 button actions will fit in a byte) can encode most sensible combinations users may want to employ.

[Jc2k]

Not an answer just some rambling from my experience working with homekit and xiaomi devices in home assistant:

Some of the devices i work with have state, and either you can poll that state or they broadcast that state. We can generate transition events when the state is detected to change. We could not generate events if the state changes and changes back when we weren't looking. But if we restart we can find the current state.

Some devices only generate events, they never broadcast their state. You can synthesise their state but if you miss an event you can't later find out the current state with confidence.

Homekit calls this last concept "stateless programmable switches" and I think they went back and added stateful switches later.

In my experience buttons (like doorbells) often only generate stateless events and don't have a way to get their state. Light switches typically have state.

[Ernst79]

The idea I had when adding "turn on" as an event for buttons was that it should be as flexible as possible. So if one wants to create a button that sends "turn on ", he (or she) can. But after a second thought after your comment it might be better remove that.

Most of the events I have defined now are based on Xiaomi (worked too long on BLE monitor, and xiaomi sensors). Xiaomi is indeed sometimes using the same data type as an event, and sometimes as a state. For Xiaomi, it is therefore needed to know the device type. I remember that Xiaomi, or one of its rebranded brands, has wall switches that do not only send "toggle", but also send "long press", "triple press", etc. These are wall switches that always return to the same position (so, not an on/off switch, but more a "toggle" switch. This is more like a button behavior, I guess.

We have to make a decision about what a switch will send. Will it send events (switch sends turn off), or do we also allow to send states (light is off). I thought states should be represented by a (binary) sensor, like light (which is already possible with 0x1E. You can of course use both.

I will try to make a proposal for a list of possible events, for buttons and one for switches, later this week, such that you can shoot on it.

[kzyapkov]

Homekit calls this last concept "stateless programmable switches" and I think they went back and added stateful switches later.

HAP's "Stateless Programmable Switch" service exposes a "Programmable Switch Event" characteristic which can emit

• 0 ”Single Press”
• 1 ”Double Press”
• 2 ”Long Press”

Basically, a button.

[Jc2k]

Exactly.

I think #5 (comment) is how i would do this for sure.

[Ernst79]

I'm going to try to summarize it below as a first proposal (will update while you give comments).

Devices can send both stateful data (sensor/binary sensors) and stateless data (events). If you want both, just use two object_id's.

Statefull
Power (binary sensor) --> states: on/off
Dimmer (sensor) --> states: brightness 0-255

Stateless
Button --> events (press, double press, triple press, long press, double long press, triple long press)
Dimmer --> events (rotate right x steps, rotate left, x steps)

I'm not so sure about the Switch binary sensor. In HA terms, a switch is something you can control, also from HA, so you can turn it on or off. However, at this moment, we don't use BTHome to control devices. In HA terms, a switch binary sensor is more a Power binary sensor, which can have a state "On" or "Off". I called it Power binary sensor for now.

Please shoot at the above list, what you want to have/change

[Ernst79]

V2 has been released with the above changes. If we need more changes, please create a new issue.