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:
action:
- service: light.turn_on
target:
entity_id: light.living_room
Or:
action:
- service: light.turn_off
target:
entity_id: light.living_room
You can also use the actions for:
- Scripts
- Scenes
- Switches
- Covers
- Media players
- Notifications
- Home Assistant services
- Other automations
Example: Light Switch
A typical four-button switch could be configured like this:
| Button | Press | Hold | Release |
|---|---|---|---|
| Button 1 | Lights ON | Brightness up | Stop |
| Button 2 | Lights OFF | Brightness down | Stop |
| Button 3 | Scene ON | Dim | Stop |
| Button 4 | Scene OFF | Dim | Stop |
This allows a single EnOcean switch to provide a large number of functions.
Example: MQTT Flow
For a button press, Zigbee2MQTT might publish:
Topic:
zigbee2mqtt/Livingroom_Switch/action
Payload:
press_1
The blueprint receives the MQTT message and identifies:
Controller:
Livingroom_Switch
Command:
press_1
The blueprint then waits for the configured hold delay to determine whether the event is a short press or a hold.
Event Processing
The general processing logic is:
MQTT Event
│
▼
Check controller
│
▼
Check command
│
┌─────────┴─────────┐
│ │
PRESS RELEASE
│ │
▼ ▼
Wait hold delay Check previous event
│ │
┌─────┴─────┐ ▼
│ │ RELEASE action
Released Timeout
│ │
▼ ▼
PRESSED action HELD action
Requirements
- Home Assistant 2024.10.0 or newer
- Zigbee2MQTT
- MQTT integration in Home Assistant
- Compatible EnOcean PTM 21xZ/ZE switch
- MQTT action events from the switch
The blueprint specifies a minimum Home Assistant version of:
2024.10.0
Installation
The easiest way to install this Blueprint is to use the Import Blueprint button below.
Automatic Installation
- Click Import Blueprint below.
- Home Assistant will open the Blueprint import page.
- Select Import Blueprint.
- Once imported, the Blueprint will be available under:
Settings → Automations & Scenes → Blueprints - Create a new automation from the Blueprint.
- Enter the Controller Name exactly as it appears in Zigbee2MQTT.
- Verify the MQTT Base Topic. The default is:
zigbee2mqtt - Configure the desired button actions.
- Configure the Hold Delay if required.
- If you are using a PTM216Z, enable the PTM216Z option and select the required Text Helper.
- Save the automation.
Manual Installation
If the automatic import does not work, the Blueprint can also be installed manually.
- Open the Blueprint YAML file in the repository.
- Copy the complete YAML content.
- In Home Assistant, go to:
Settings → Automations & Scenes → Blueprints - Select Import Blueprint.
- Paste the URL of the raw YAML file.
- Confirm the import.
- Create a new automation from the Blueprint.
- Configure the controller, MQTT settings and button actions.
Troubleshooting
Button does not trigger anything
Check that the configured controller name matches the Zigbee2MQTT device name.
For example:
Zigbee2MQTT:
Livingroom_Switch
must be entered as:
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:
500 ms
Try lowering the value if the switch does not reliably detect long presses.
For PTM216Z devices, make sure:
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:
press_1 → release_1
will trigger:
Button 1 Pressed
A long press:
press_1
↓
Hold delay exceeded
↓
Button 1 Held
↓
release_1
will trigger:
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:
<base_topic>/<controller>/action
The default base topic is:
zigbee2mqtt
Version
Current blueprint version:
2025.12.13
Minimum Home Assistant version:
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