alexei.dolgolyov
3d15f481a0
- 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
46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
# 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
|
|
|
|
1. Receives MQTT messages from one or two Zigbee buttons.
|
|
2. Reads `action` from the payload and looks it up in the configured **Action IDs** list.
|
|
3. The matched index is used to pick the corresponding entity from the **Switches** list.
|
|
4. Toggles the matched entity (`light` / `switch` / `input_boolean`).
|
|
5. 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.
|
|
6. 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>)
|