Add EnOcean PTM 21xZ/ZE - MQTT Trigger
332
EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md
Normal file
332
EnOcean PTM 21xZ%2FZE - MQTT Trigger.-.md
Normal file
@@ -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/<controller>/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:
|
||||||
|
|
||||||
|
<base_topic>/<controller>/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
|
||||||
Reference in New Issue
Block a user