Update EnOcean PTM 21xZ/ZE - MQTT Trigger

EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md

@@ -441,3 +441,101 @@ Settings → Automations & Scenes → Blueprints
 7. Verify the MQTT base topic.
 8. Configure the desired button actions.
 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