scenario_button

Last updated on April 13, 2025

A scenario button is a device that can run smart home scenarios. The scenario button is physically equipped with one or more buttons, each of them can respond to different types of clicks: single, double, long. For each type of click, the user can assign a script or a command to control smart home devices.

Available device functions

The device can have all the functions listed below or some of them. E.g. if a scenario button is equipped only one physical button, the functions button_1_event, button_2_event, etc. do not need to be specified.

For a scenario button, the online function must be described, as well as at least one function of pressing the button.

Function	Mandatory?	Description
battery_low_power		Battery low or not
battery_percentage		Batter charge level
button_event		Pressing the button
button_1_event		Pressing the first button
button_2_event		Pressing the second button
button_3_event		Pressing the third button
button_4_event		Pressing the fourth button
button_5_event		Pressing the fifth button
button_6_event		Pressing the sixth button
button_7_event		Pressing the seventh button
button_8_event		Pressing the eighth button
button_9_event		Pressing the ninth button
button_10_event		Pressing the tenth button
button_bottom_left_event		Pressing the lower left button
button_bottom_right_event		Pressing the lower right button
button_left_event		Pressing the left button
button_right_event		Pressing the right button
button_top_left_event		Pressing the upper left button
button_top_right_event		Pressing the upper right button
online	✔︎	Device availability: offline or online
signal_strength		Signal strength

Scenario button model description example

The model shall be described in accordance with the model structure. The example describes a scenario button with two physical buttons on the case. Also, the scenario button is able to report the signal strength and battery charge.

Besides, allowed values for the button_1_event function of the model are changed: the first button of this model does not support long-pressing long_press, it is deleted.

{
   "id": "QWERTY124",
   "manufacturer": "Xiaqara",
   "model": "SM1123456789",
   "hw_version": "3.1",
   "sw_version": "5.6",
   "description": "Scenario button Xiaqara",
   "category": "scenario_button",
   "features": [
      "online",
      "signal_strength",
      "battery_percentag",
      "button_1_event",
      "button_2_event"
   ],
   "allowed_values": {
      "button_1_event": {
         "type": "ENUM",
         "enum_values": {
            "values": [
               "click",
               "double_click"
            ]
         }
      }
   }
}

User's scenario button description example

The device shall be describe in accordance with the device structure. The example contains no scenario button description as we believe that models are described independently and the model ID will be enough (in this case, QWERTY124).

{
    "id": "ABCD_004",
    "name": "My button",
    "default_name": "Scenario button",
    "nicknames": ["Smart button", "Scripts button"],
    "home": "My home",
    "room": "Living room",
    "groups": [],
    "model_id": "QWERTY124",
    "hw_version": "3.1",
    "sw_version": "5.6",
    "partner_meta": {
        "internal-id": 1234,
        "specificity": "microchip 2A"
    },
}