Files

T

alexei.dolgolyov 3d15f481a0 feat: add debug mode and clarify docs in MQTT Button Control

- Add optional debug notifications for trigger and light-branch decisions
- Document index-based action/entity mapping and two-topic support
- Add configuration reference table and debug-mode section to README

2026-05-27 13:09:59 +03:00

blueprint.yaml

feat: add debug mode and clarify docs in MQTT Button Control

2026-05-27 13:09:59 +03:00

README.md

feat: add debug mode and clarify docs in MQTT Button Control

2026-05-27 13:09:59 +03:00

README.md

MQTT Button Control Blueprint

Controls lights and switches using Zigbee2MQTT button devices with multiple action mappings.

Features

Map multiple action IDs to different lights/switches by index position
Supports light, switch, and input_boolean entities
Visual feedback via blink indication when pressing an already-active light after an idle timeout
Optionally tracks last interacted entity in an input_text helper
Supports two MQTT topics for two physical buttons
Optional debug notifications for troubleshooting

How It Works

Receives MQTT messages from one or two Zigbee buttons.
Reads action from the payload and looks it up in the configured Action IDs list.
The matched index is used to pick the corresponding entity from the Switches list.
Toggles the matched entity (light / switch / input_boolean).
For lights, if the light is already on and has been on for longer than the configured idle timeout, the light is briefly blinked instead of toggled, to indicate it is already active.
If an input_text helper is configured, the matched entity ID is written to it.

Configuration

Input	Description
MQTT Topic	Primary topic (e.g. `zigbee2mqtt/my_button1`).
MQTT Topic 2 (Optional)	Second topic. Leave the placeholder to disable the second trigger.
Action IDs	Ordered list of action strings emitted by the button (e.g. `single`, `double`, `hold`).
Switches	Entities matched to Action IDs by index — index `0` maps to action `0`, and so on.
Last Interacted Entity Text Helper (optional)	`input_text` that receives the last toggled entity ID. Leave empty to skip.
Timeout for indicator blink	Idle seconds after which a press on an already-on light blinks instead of toggling. `0` disables blinking.
Count of blinks	Number of blink cycles. `0` also disables blinking (every press just toggles).
Interval between blinks	Delay between turn off / turn on in milliseconds.
Enable Debug Notifications	When on, posts a persistent notification per trigger and per light-branch decision.

The number of Action IDs should match the number of Switches. Out-of-range or unknown actions are ignored safely.

Debug Mode

Enable Enable Debug Notifications to surface the resolved action, target index, target entity, and (for lights) the elapsed-time / blink decision in Home Assistant's persistent notifications panel. Disable when not troubleshooting to avoid notification noise.

Author

Alexei Dolgolyov (dolgolyov.alexei@gmail.com)