What it exposes
| Feature | Property | Values | Control |
|---|---|---|---|
| Battery | battery | % · 0…100 | read only |
| Action (button press) | action | *_single, *_double, *_triple, *_quadruple, *_release, *_hold | read only |
| Switch type (button_1) | switch_type_button_1 | toggle, momentary, multifunction | settable |
| Switch actions (button_1) | switch_actions_button_1 | on, off, toggle | settable |
| Switch type (button_2) | switch_type_button_2 | toggle, momentary, multifunction | settable |
| Switch actions (button_2) | switch_actions_button_2 | on, off, toggle | settable |
| Switch type (button_3) | switch_type_button_3 | toggle, momentary, multifunction | settable |
| Switch actions (button_3) | switch_actions_button_3 | on, off, toggle | settable |
| Switch type (button_4) | switch_type_button_4 | toggle, momentary, multifunction | settable |
| Switch actions (button_4) | switch_actions_button_4 | on, off, toggle | settable |
| Switch type (button_5) | switch_type_button_5 | toggle, momentary, multifunction | settable |
| Switch actions (button_5) | switch_actions_button_5 | on, off, toggle | settable |
| Switch type (button_6) | switch_type_button_6 | toggle, momentary, multifunction | settable |
| Switch actions (button_6) | switch_actions_button_6 | on, off, toggle | settable |
| Switch type (button_7) | switch_type_button_7 | toggle, momentary, multifunction | settable |
| Switch actions (button_7) | switch_actions_button_7 | on, off, toggle | settable |
| Switch type (button_8) | switch_type_button_8 | toggle, momentary, multifunction | settable |
| Switch actions (button_8) | switch_actions_button_8 | on, off, toggle | settable |
| Switch type (button_9) | switch_type_button_9 | toggle, momentary, multifunction | settable |
| Switch actions (button_9) | switch_actions_button_9 | on, off, toggle | settable |
| Switch type (button_10) | switch_type_button_10 | toggle, momentary, multifunction | settable |
| Switch actions (button_10) | switch_actions_button_10 | on, off, toggle | settable |
| Switch type (button_11) | switch_type_button_11 | toggle, momentary, multifunction | settable |
| Switch actions (button_11) | switch_actions_button_11 | on, off, toggle | settable |
| Switch type (button_12) | switch_type_button_12 | toggle, momentary, multifunction | settable |
| Switch actions (button_12) | switch_actions_button_12 | on, off, toggle | settable |
| Switch type (button_13) | switch_type_button_13 | toggle, momentary, multifunction | settable |
| Switch actions (button_13) | switch_actions_button_13 | on, off, toggle | settable |
| Switch type (button_14) | switch_type_button_14 | toggle, momentary, multifunction | settable |
| Switch actions (button_14) | switch_actions_button_14 | on, off, toggle | settable |
| Switch type (button_15) | switch_type_button_15 | toggle, momentary, multifunction | settable |
| Switch actions (button_15) | switch_actions_button_15 | on, off, toggle | settable |
| Switch type (button_16) | switch_type_button_16 | toggle, momentary, multifunction | settable |
| Switch actions (button_16) | switch_actions_button_16 | on, off, toggle | settable |
| Switch type (button_17) | switch_type_button_17 | toggle, momentary, multifunction | settable |
| Switch actions (button_17) | switch_actions_button_17 | on, off, toggle | settable |
| Switch type (button_18) | switch_type_button_18 | toggle, momentary, multifunction | settable |
| Switch actions (button_18) | switch_actions_button_18 | on, off, toggle | settable |
| Switch type (button_19) | switch_type_button_19 | toggle, momentary, multifunction | settable |
| Switch actions (button_19) | switch_actions_button_19 | on, off, toggle | settable |
| Switch type (button_20) | switch_type_button_20 | toggle, momentary, multifunction | settable |
| Switch actions (button_20) | switch_actions_button_20 | on, off, toggle | settable |
MQTT: state and commands
Zigbee2MQTT publishes the device state to zigbee2mqtt/my_device (my_device is the name you give the device). An example message:
{
"battery": 87,
"switch_type_button_1": "toggle",
"switch_actions_button_1": "on",
"switch_type_button_2": "toggle",
"switch_actions_button_2": "on",
"switch_type_button_3": "toggle",
"switch_actions_button_3": "on",
"switch_type_button_4": "toggle",
"switch_actions_button_4": "on",
"switch_type_button_5": "toggle",
"switch_actions_button_5": "on",
"switch_type_button_6": "toggle",
"switch_actions_button_6": "on",
"switch_type_button_7": "toggle",
"linkquality": 120
}
Send commands to zigbee2mqtt/my_device/set:
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"switch_type_button_1":"momentary"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"switch_actions_button_1":"off"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"switch_type_button_2":"momentary"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"switch_actions_button_2":"off"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"switch_type_button_3":"momentary"}'
Watch the topics live from the browser: MQTT client.
Home Assistant automation example
Zigbee2MQTT creates Home Assistant entities from the device name. If it is called my_device, an automation in automations.yaml can look like this:
- alias: "Button"
mode: single
triggers:
- trigger: mqtt
topic: zigbee2mqtt/my_device
value_template: "{{ value_json.action }}"
payload: "*_single"
actions:
- action: light.toggle
target:
entity_id: light.living_room
Check the YAML: YAML checker.
How to pair it
- In Zigbee2MQTT click Permit join.
- Put the device in pairing mode: usually a long press of the reset button (5–10 s) until the LED blinks; bulbs: switch the power off and on 5–6 times.
- Keep the device close to the coordinator or a router while pairing.
- Give it a clear name: MQTT topics and Home Assistant entities are built from it.
Exact procedure and model notes: the device page in the Zigbee2MQTT docs. No coordinator yet: coordinator picker.