From ca1709855907077e71e4f818a6c340a26d3a3167 Mon Sep 17 00:00:00 2001
From: Kasper <KasperSkovmose@gmail.com>
Date: Thu, 20 Aug 2026 17:30:14 +0200
Subject: [PATCH] Update EnOcean PTM 21xZ/ZE - MQTT Trigger

---
 EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md | 100 +++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md b/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md
index b8a71af..0400959 100644
--- a/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md	
+++ b/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md	
@@ -440,4 +440,102 @@ Settings → Automations & Scenes → Blueprints
 6. Enter the controller name exactly as it appears in Zigbee2MQTT.
 7. Verify the MQTT base topic.
 8. Configure the desired button actions.
-9. If using a PTM216Z, create and select the required Text Helper.
\ No newline at end of file
+9. If using a PTM216Z, create and select the required Text Helper.
+
+## Troubleshooting
+### Button does not trigger anything
+
+Check that the configured controller name matches the Zigbee2MQTT device name.
+
+For example:
+```text
+Zigbee2MQTT:
+Livingroom_Switch
+```
+must be entered as:
+```text
+Livingroom_Switch
+```
+Also verify that the MQTT base topic is correct.
+
+### Press works but Hold does not
+
+Check the Hold delay setting.
+
+The default is:
+```text
+500 ms
+```
+Try lowering the value if the switch does not reliably detect long presses.
+
+For PTM216Z devices, make sure:
+```text
+PTM216Z: ON
+```
+and that the required Text Helper has been selected.
+
+### Release action does not work
+
+The release action is specifically used for a release after a long press.
+
+For example, a short press:
+```text
+press_1 → release_1
+```
+will trigger:
+```text
+Button 1 Pressed
+```
+A long press:
+```text
+press_1
+    ↓
+Hold delay exceeded
+    ↓
+Button 1 Held
+    ↓
+release_1
+```
+will trigger:
+```text
+Button 1 Released
+```
+
+## Notes
+
+The blueprint uses MQTT topics generated by Zigbee2MQTT and filters events based on the configured controller name.
+
+The MQTT topic structure is:
+```text
+<base_topic>/<controller>/action
+```
+The default base topic is:
+```text
+zigbee2mqtt
+```
+
+## Version
+
+Current blueprint version:
+```text
+2025.12.13
+```
+Minimum Home Assistant version:
+```text
+2024.10.0
+```
+## Changelog
+**v2025.12.13**
+
+- Initial documented version
+- EnOcean PTM 21xZ/ZE MQTT support
+- Press actions
+- Hold actions
+- Release actions
+- Four individual buttons
+- Button combinations
+- Two-finger actions
+- Configurable hold delay
+- PTM216Z-specific event handling
+- Optional Input Text Helper for PTM216Z
+- Multiple controller support
\ No newline at end of file