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