From a11aa668cc97d14207209221d6c7ceaaecaff563 Mon Sep 17 00:00:00 2001 From: Kasper Date: Thu, 20 Aug 2026 17:10:04 +0200 Subject: [PATCH] Add EnOcean PTM 21xZ/ZE - MQTT Trigger --- EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md | 332 ++++++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md diff --git a/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md b/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md new file mode 100644 index 0000000..9282393 --- /dev/null +++ b/EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md @@ -0,0 +1,332 @@ +# EnOcean PTM 21xZ/ZE - MQTT Trigger + +## Overview + +This Home Assistant Blueprint provides a flexible way to control automations using **EnOcean PTM 21xZ/ZE** wireless switches through MQTT. + +The blueprint is designed to work with EnOcean switches integrated through **Zigbee2MQTT (Z2M)** and allows separate actions to be configured for: + +- Button press +- Button hold +- Button release +- Button combinations +- Two-finger button combinations + +The blueprint uses MQTT action events from the switch and converts them into configurable Home Assistant actions. + +## Features + +- 🔘 Supports EnOcean PTM 21xZ/ZE switches +- 📡 Uses MQTT triggers +- ⚡ Separate actions for press, hold and release +- 🎛️ Supports up to four individual buttons +- 🔀 Supports button combinations +- 👆 Supports two-finger combinations +- ⏱️ Configurable hold detection delay +- 🔧 Configurable MQTT base topic +- 📝 Optional Text Helper for PTM216Z +- 💡 Each button action can execute any Home Assistant action +- ⚙️ Fully configurable through the Home Assistant Blueprint UI + +## Supported Switches + +The blueprint is intended for EnOcean PTM 21xZ/ZE switches. + +Supported configurations include: + +- PTM215ZE +- PTM216Z +- Other compatible PTM 21xZ/ZE devices using the same MQTT action format + +The blueprint specifically contains additional handling for the **PTM216Z**. + +## How it Works + +The blueprint listens for MQTT action messages generated by the switch. + +The expected MQTT topic structure is: + + zigbee2mqtt//action + +For example: + + zigbee2mqtt/Livingroom_Switch/action + +The action payload identifies which button event occurred. + +Examples include: + + press_1 + release_1 + + press_2 + release_2 + + press_1_and_3 + release_1_and_3 + +The blueprint then determines whether the event should trigger a **Pressed**, **Held**, or **Released** action. + +## Button Actions + +Each button can have three independent actions: + +| Event | Description | +|---|---| +| Pressed | Executed when the button is pressed and released before the hold delay | +| Held | Executed when the button remains pressed longer than the configured hold delay | +| Released | Executed when the button is released after a long press | + +This makes it possible to use a single physical button for multiple functions. + +### Example + + Short press + │ + ▼ + Button 1 Pressed + │ + ▼ + Turn light ON + + Long press + │ + ▼ + Button 1 Held + │ + ▼ + Dim light + + Release after long press + │ + ▼ + Button 1 Released + │ + ▼ + Stop dimming + +## Hold Detection + +The **Hold delay** determines how long a button must be held before the blueprint considers it a long press. + +The default value is: + + 500 ms + +The allowed range is: + + 100 ms → 1000 ms + +Example: + + Hold delay: 500 ms + +A press shorter than 500 ms is treated as a normal press. + +A press longer than 500 ms is treated as a hold. + + Button pressed + │ + ▼ + Wait 500 ms + │ │ + Released Still held + │ │ + ▼ ▼ + PRESSED HELD + +## Release Handling + +The blueprint distinguishes between a normal release and a release after a long press. + +For example: + +### Short press + + press_1 + │ + ▼ + release_1 + │ + ▼ + Button 1 Pressed + +### Long press + + press_1 + │ + ▼ + Hold delay exceeded + │ + ▼ + Button 1 Held + │ + ▼ + release_1 + │ + ▼ + Button 1 Released + +This makes it possible to use the release event to stop an action such as dimming. + +## Supported Individual Buttons + +The blueprint supports four individual buttons. + +### Button 1 + +- Button 1 Pressed +- Button 1 Held +- Button 1 Released + +### Button 2 + +- Button 2 Pressed +- Button 2 Held +- Button 2 Released + +### Button 3 + +- Button 3 Pressed +- Button 3 Held +- Button 3 Released + +### Button 4 + +- Button 4 Pressed +- Button 4 Held +- Button 4 Released + +Each action is independently configurable. + +## Button Combinations + +The blueprint also supports combinations of buttons. + +The following combinations are available: + +### Buttons 1 + 3 + +- Pressed +- Held +- Released + +### Buttons 2 + 4 + +- Pressed +- Held +- Released + +These combinations can be used for additional functions without requiring extra physical buttons. + +## Two-Finger Actions + +For PTM215ZE / PTM216Z devices, the blueprint also provides dedicated two-finger actions. + +Supported combinations are: + +### Buttons 1 + 4 + +- Pressed +- Held +- Released + +### Buttons 2 + 3 + +- Pressed +- Held +- Released + +These are useful for functions such as: + +- Scene control +- All lights ON/OFF +- Heating control +- Alarm control +- Special Home Assistant actions + +## Controller Configuration + +The **Controller Name** must match the controller name configured in Zigbee2MQTT. + +Example: + + Livingroom_Switch + +Multiple controllers can be entered if required. + +The blueprint checks the MQTT topic to determine whether the received event belongs to one of the configured controllers. + +## MQTT Base Topic + +The default MQTT base topic is: + + zigbee2mqtt + +This must match the MQTT base topic configured in Zigbee2MQTT. + +The blueprint constructs the MQTT topic as: + + //action + +For example: + + zigbee2mqtt/Livingroom_Switch/action + +If your Zigbee2MQTT base topic is different, change the **Base topic (MQTT)** setting. + +## PTM216Z Special Configuration + +The PTM216Z requires additional handling for correctly distinguishing button hold events. + +When using a **PTM216Z**, enable: + + PTM216Z: ON + +You must also manually create an **Input Text Helper** in Home Assistant. + +The helper stores the last received controller event and is used by the blueprint to correctly process PTM216Z button hold and release events. + +## PTM216Z Text Helper + +Create a Home Assistant Text Helper: + + Settings + → Devices & services + → Helpers + → Create Helper + → Text + +The helper can have any suitable name, for example: + + PTM216Z Last Controller Event + +Select this helper in: + + PTM216Z - Last Controller Event + +The blueprint stores the last received controller event in this helper. + +## Blueprint Inputs + +| Input | Description | Default | +|---|---|---| +| Controller Name | Controller name as defined in Zigbee2MQTT | — | +| Base topic (MQTT) | MQTT base topic configured in Z2M | `zigbee2mqtt` | +| Hold delay | Time before a press becomes a hold | 500 ms | +| PTM216Z | Enable PTM216Z-specific handling | Off | +| PTM216Z - Last Controller Event | Input Text Helper used for PTM216Z | — | + +## Action Configuration + +Every supported button event has an **Action** selector. + +This means that virtually any Home Assistant action can be executed. + +Examples include: + +```yaml +action: + - service: light.turn_on + target: + entity_id: light.living_room \ No newline at end of file