Skip to content

Commit 8cb3a07

Browse files
eakoroleveakorolev
committed
Document long-press companion endpoints
1 parent 2cb0108 commit 8cb3a07

2 files changed

Lines changed: 53 additions & 9 deletions

File tree

‎docs/changelog_fw.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,15 @@ Please describe what you are working on, under ## Upcoming
1212

1313
### Features
1414

15+
- **Long-press companion endpoints** — new endpoints `2N+1`..`3N` paired with
16+
the existing switch endpoints `1..N`.
17+
- One button can now drive two independent Zigbee bindings: short-press on
18+
`1..N`, long-press on `2N+1`..`3N`.
19+
- LevelControl emit on long-press is configurable: `Move` vs `MoveWithOnOff`,
20+
direction `Up`/`Down`/`Alternate`.
21+
- Safe defaults — nothing happens on long-press until you opt in. A mutex
22+
protects against conflicting configurations between paired endpoints.
23+
- See [endpoints.md](usage/endpoints.md#long-press-as-a-second-binding-target).
1524
- **Cover cluster** (window covering) for controlling the motor of curtains, blinds, and shutters.
1625
Supports open, close, and stop commands with motor safety delays.
1726
- **Cover switch cluster** for handling user input from window covering switches.
@@ -29,6 +38,11 @@ Please describe what you are working on, under ## Upcoming
2938

3039
### Changes
3140

41+
- **Deprecate `binded_mode=LONG` and `relay_mode=LONG` on switch endpoints** —
42+
use the new long-press companion endpoint instead. Legacy configurations keep
43+
working unchanged; while a switch endpoint is in either deprecated long mode,
44+
its paired long-press endpoint is muted to prevent double-toggles and
45+
conflicting emissions.
3246
- Add `D<N>` config option to customize button debounce delay in milliseconds
3347
- **Bi-stable (latching) relays** have been reworked
3448
- They now use proper pulses instead of continuously driving the coil

‎docs/usage/endpoints.md‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,21 @@
44
55
As the firmware supports multi-channel (multi-gang) devices, it uses Zigbee endpoints to handle command routing. Zigbee endpoints are numbered, starting from one. For each endpoint, only one instance of a specific function can exist. For example, there can only be a single relay (`OnOffCluster`) attached to endpoint 1. This document explains how the firmware assigns and uses endpoints.
66

7-
If the device is an N-gang switch module, the firmware will use `2 × N` endpoints. The first N endpoints are used for "client" (output) OnOff clusters, which can control other Zigbee devices via direct bindings. The next N endpoints (endpoints N+1 to 2×N) are used for "server" (input) OnOff clusters, which are directly linked to physical relays.
7+
If the device is an N-gang switch module, the firmware will use `3 × N` endpoints. The first N endpoints are used for "client" (output) OnOff clusters, which can control other Zigbee devices via direct bindings. The next N endpoints (endpoints N+1 to 2×N) are used for "server" (input) OnOff clusters, which are directly linked to physical relays. The last N endpoints are long-press companion "client" (output) OnOff + LevelControl clusters that fire on long-press.
88

99
Here is an example table:
1010

11-
| Endpoint | Clusters | Description |
12-
|----------|--------------|----------------------------------------------------------------------------------------------|
13-
| 1 | OnOff client | Binding to control other Zigbee devices |
14-
| ... | OnOff client | ... |
15-
| N | OnOff client | Binding to control other Zigbee devices |
16-
| N+1 | OnOff server | Controls Relay 1 state. Add to a group or bind it with another device to control the relay. |
17-
| ... | OnOff server | ... |
18-
| 2N | OnOff server | Controls Relay N state. Add to a group or bind it with another device to control the relay. |
11+
| Endpoint | Clusters | Description |
12+
|----------|--------------------------------|------------------------------------------------------------------------------------------------------------------------------|
13+
| 1 | OnOff client | Binding to control other Zigbee devices on short press |
14+
| ... | OnOff client | ... |
15+
| N | OnOff client | Binding to control other Zigbee devices |
16+
| N+1 | OnOff server | Controls Relay 1 state. Add to a group or bind it with another device to control the relay. |
17+
| ... | OnOff server | ... |
18+
| 2N | OnOff server | Controls Relay N state. Add to a group or bind it with another device to control the relay. |
19+
| 2N+1 | OnOff client + Level client | Long-press companion for switch 1. Bind it to send a `Toggle` (OnOff) and a `Move`/`Stop` (LevelControl) on long-press only. |
20+
| ... | OnOff client + Level client | ... |
21+
| 3N | OnOff client + Level client | Long-press companion for switch N. |
1922

2023
## Usage Examples
2124

@@ -32,3 +35,30 @@ Bind endpoint 2 of your device to endpoint 1 of the bulb, and bind the `OnOff` c
3235
If you have two 2-gang devices and want to group the first relay of both devices, you should add endpoint 3 of both devices to the same group, as shown in the screenshot:
3336

3437
![add to group](/docs/.images/add_to_group.png)
38+
39+
### Long-press as a second binding target
40+
41+
If you want short-press of button 1 to control the local relay and long-press to toggle a different Zigbee device:
42+
43+
1. Leave endpoint 1 (short-press) bound to the local relay as usual.
44+
2. Bind the `OnOff` cluster of endpoint `2N+1` (the long-press companion of button 1) to the target device.
45+
46+
After the bind is created, every long-press of button 1 sends a `Toggle` command to the target — independently of any Home Assistant / Zigbee2MQTT automation.
47+
48+
### Dimming a light by holding a button
49+
50+
1. Bind the `LevelControl` cluster of endpoint `2N+1` to a dimmable Zigbee light.
51+
2. Hold the button — the light dims continuously while held; release stops the dim.
52+
53+
Direction (`Up`/`Down`/`Alternate`), rate, and the underlying command (`Move` vs `MoveWithOnOff`) are configurable through the cluster attributes on the long-press endpoint.
54+
55+
## Migration from legacy long-press configuration
56+
57+
Earlier firmware versions reused the short-press endpoint for long-press behavior via `binded_mode=LONG` (emit OnOff on long-press) and `relay_mode=LONG` (toggle local relay on long-press). These modes are now **deprecated** in favor of the dedicated long-press companion endpoints (`2N+1`..`3N`) introduced above, which support both `OnOff` and `LevelControl` bindings and keep short-press and long-press behavior on separate endpoints.
58+
59+
**Backward compatibility.** Existing configurations continue to work without changes. To keep behavior identical for devices that haven't migrated yet, whenever a switch endpoint has `binded_mode=LONG` or `relay_mode=LONG`, the paired long-press companion endpoint is **fully muted** — no relay toggle, no OnOff emission, no LevelControl emission — to prevent double-toggles and conflicting commands.
60+
61+
**Migrating a button:**
62+
63+
1. On the long-press companion endpoint `2N+1`, configure the bindings and/or `relay_mode` that match the existing long-press behavior.
64+
2. Reset the switch endpoint back to the default (`binded_mode=SHORT`, `relay_mode=SHORT`). The mutex is released and the long-press companion endpoint becomes active.

0 commit comments

Comments
 (0)