Merge pull request romasku#443 from eakorolev/long-press-endpoint

Long-press companion endpoints

# Conflicts:
#	src/zigbee/switch_cluster.c

Author: eakorolev

docs/changelog_fw.md

@@ -12,6 +12,15 @@ Please describe what you are working on, under ## Upcoming
 
 ### Features
 
+- **Long-press companion endpoints** — new endpoints `2N+1`..`3N` paired with
+  the existing switch endpoints `1..N`.
+  - One button can now drive two independent Zigbee bindings: short-press on
+    `1..N`, long-press on `2N+1`..`3N`.
+  - LevelControl emit on long-press is configurable: `Move` vs `MoveWithOnOff`,
+    direction `Up`/`Down`/`Alternate`.
+  - Safe defaults — nothing happens on long-press until you opt in. A mutex
+    protects against conflicting configurations between paired endpoints.
+  - See [endpoints.md](usage/endpoints.md#long-press-as-a-second-binding-target).
 - **Cover cluster** (window covering) for controlling the motor of curtains, blinds, and shutters.
   Supports open, close, and stop commands with motor safety delays.
 - **Cover switch cluster** for handling user input from window covering switches.
@@ -29,6 +38,11 @@ Please describe what you are working on, under ## Upcoming
 
 ### Changes
 
+- **Deprecate `binded_mode=LONG` and `relay_mode=LONG` on switch endpoints** —
+  use the new long-press companion endpoint instead. Legacy configurations keep
+  working unchanged; while a switch endpoint is in either deprecated long mode,
+  its paired long-press endpoint is muted to prevent double-toggles and
+  conflicting emissions.
 - Add `D<N>` config option to customize button debounce delay in milliseconds
 - **Bi-stable (latching) relays** have been reworked
   - They now use proper pulses instead of continuously driving the coil

docs/usage/endpoints.md

@@ -4,18 +4,21 @@
 
 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.
 
-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.
+If the device is an N-gang switch module, the firmware uses up to `3 × N` endpoints. The first N endpoints are "client" (output) OnOff clusters for direct bindings. If the device has physical relays, endpoints `N+1`..`2N` are "server" (input) OnOff clusters linked to those relays — on relay-less devices these endpoints are absent. Endpoints `2N+1`..`3N` are long-press companion "client" (output) OnOff + LevelControl clusters that fire on long-press.
 
 Here is an example table:
 
-| Endpoint | Clusters     | Description                                                                                  |
-|----------|--------------|----------------------------------------------------------------------------------------------|
-| 1        | OnOff client | Binding to control other Zigbee devices                                                      |
-| ...      | OnOff client | ...                                                                                          |
-| N        | OnOff client | Binding to control other Zigbee devices                                                      |
-| N+1      | OnOff server | Controls Relay 1 state. Add to a group or bind it with another device to control the relay.  |
-| ...      | OnOff server | ...                                                                                          |
-| 2N       | OnOff server | Controls Relay N state. Add to a group or bind it with another device to control the relay.  |
+| Endpoint | Clusters                       | Description |
+|----------|--------------------------------|-------------|
+| 1        | OnOff client                   | Binding to control other Zigbee devices on short press |
+| ...      | OnOff client                   | ... |
+| N        | OnOff client                   | Binding to control other Zigbee devices |
+| N+1      | OnOff server                   | Controls Relay 1 state. Add to a group or bind it with another device to control the relay. |
+| ...      | OnOff server                   | ... |
+| 2N       | OnOff server                   | Controls Relay N state. Add to a group or bind it with another device to control the relay. |
+| 2N+1     | OnOff client + Level client    | Long-press companion for switch 1 |
+| ...      | OnOff client + Level client    | ... |
+| 3N       | OnOff client + Level client    | Long-press companion for switch N |
 
 ## Usage Examples
 
@@ -32,3 +35,19 @@ Bind endpoint 2 of your device to endpoint 1 of the bulb, and bind the `OnOff` c
 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:
 
 ![add to group](/docs/.images/add_to_group.png)
+
+### Long-press as a second binding target
+
+Bind the `OnOff` cluster of endpoint `2N+1` (long-press companion of button 1) to a Zigbee target. Each long-press sends `Toggle` to that target — independently of any Home Assistant / Zigbee2MQTT automation.
+
+## Migration from legacy long-press configuration
+
+Earlier firmware reused the short-press endpoint for long-press via `binded_mode=LongPress` / `relay_mode=LongPress`. These are deprecated in favor of the dedicated long-press companion endpoints (`2N+1..3N`).
+
+Existing configurations keep working: while a switch endpoint has either of those deprecated modes, its paired long-press companion is muted to prevent double-toggles.
+
+**To migrate a button**:
+
+1. Move any OnOff and LevelControl bindings from the switch endpoint (`1..N`) onto its long-press companion (`2N+1..3N`).
+2. If `relay_mode=LongPress` was used on the switch endpoint, set `relay_mode=LongPress` on the companion (and configure `relay_index` if needed).
+3. Set the switch endpoint's `binded_mode` and `relay_mode` to anything except `LongPress` — that releases the mute on the companion.

helper_scripts/make_homed_extension.py

@@ -160,6 +160,30 @@
                 "endpointId": switch_endpoints
             })
 
+            long_press_endpoints = list(range(switch_cnt + relay_cnt + cover_cnt + 1,
+                                              switch_cnt + relay_cnt + cover_cnt + 1 + switch_cnt))
+            data[zb_manufacturer].append({
+                "modelNames": model_names,
+                "exposes": ["switchAction", "longRelayMode", "relayIndex", "moveCommand", "levelMoveDirection", "levelMoveRate"],
+                "options": {
+                    "customAttributes": {
+                        "switchAction": {"type": "enum", "clusterId": 0x0007, "attributeId": 0x0010, "dataType": 0x30, "action": True},
+                        "longRelayMode": {"type": "enum", "clusterId": 0x0007, "attributeId": 0xff01, "dataType": 0x30, "action": True},
+                        "relayIndex": {"type": "enum", "clusterId": 0x0007, "attributeId": 0xff02, "dataType": 0x20, "action": True},
+                        "levelMoveRate": {"type": "value", "clusterId": 0x0007, "attributeId": 0xff04, "dataType": 0x20, "action": True},
+                        "levelMoveDirection": {"type": "enum", "clusterId": 0x0007, "attributeId": 0xff08, "dataType": 0x30, "action": True},
+                        "moveCommand": {"type": "enum", "clusterId": 0x0007, "attributeId": 0xff09, "dataType": 0x30, "action": True},
+                    },
+                    "switchAction": {"type": "select", "enum": ["on_off", "off_on", "toggle_simple", "toggle_smart_sync", "toggle_smart_opposite"]},
+                    "longRelayMode": {"type": "select", "enum": {"0": "detached", "2": "long_press"}},
+                    "relayIndex": {"type": "select", "enum": {str(i + 1): f"relay_{i + 1}" for i in range(relay_cnt)}} if relay_cnt else {"type": "value"},
+                    "levelMoveRate": {"type": "number", "min": 1, "max": 255},
+                    "levelMoveDirection": {"type": "select", "enum": {"0": "up", "1": "down", "255": "alternate"}},
+                    "moveCommand": {"type": "select", "enum": {"1": "move", "5": "move_with_on_off"}},
+                },
+                "endpointId": long_press_endpoints
+            })
+
         if indicators_cnt:
             relay_indicator_endpoints = list(range(switch_cnt + 1, switch_cnt + 1 + indicators_cnt))
             data[zb_manufacturer].append({

helper_scripts/templates/switch_custom.js.jinja

@@ -107,6 +107,36 @@ const romasku = {
             valueMax: 255,
             entityCategory: "config",
         }),
+    longRelayMode: (name, endpointName) =>
+        enumLookup({
+            name,
+            endpointName,
+            lookup: { detached: 0, long_press: 2 },
+            cluster: "genOnOffSwitchCfg",
+            attribute: { ID: 0xff01, type: 0x30 }, // Enum8
+            description: "When to toggle the local relay on this long-press endpoint",
+            entityCategory: "config",
+        }),
+    moveCommand: (name, endpointName) =>
+        enumLookup({
+            name,
+            endpointName,
+            lookup: { move: 1, move_with_on_off: 5 },
+            cluster: "genOnOffSwitchCfg",
+            attribute: { ID: 0xff09, type: 0x30 }, // Enum8
+            description: "Which LevelControl command to emit while held: Move (0x01) or MoveWithOnOff (0x05)",
+            entityCategory: "config",
+        }),
+    levelMoveDirection: (name, endpointName) =>
+        enumLookup({
+            name,
+            endpointName,
+            lookup: { up: 0, down: 1, alternate: 0xff },
+            cluster: "genOnOffSwitchCfg",
+            attribute: { ID: 0xff08, type: 0x30 }, // Enum8
+            description: "Level move direction while held: up, down, or alternate (flips per long-press)",
+            entityCategory: "config",
+        }),
     pressAction: (name, endpointName) =>
         enumLookup({
             name,
@@ -415,6 +445,10 @@ const definitions = [
                 {%- for coverName in device.coverNames -%}
                     "{{coverName}}": {{loop.index + (device.switchNames | length) + (device.relayNames | length) + (device.coverSwitchNames | length)}},{{" "}}
                 {%- endfor -%}
+                {# Long-press companion endpoints, appended after everything to keep existing endpoint IDs stable. #}
+                {%- for switchName in device.switchNames -%}
+                    "{{switchName}}_long_press": {{loop.index + (device.switchNames | length) + (device.relayNames | length) + (device.coverSwitchNames | length) + (device.coverNames | length)}},{{" "}}
+                {%- endfor -%}
             } }),
             {% set first_endpoint = device.switchNames[0] if device.switchNames else (device.relayNames[0] if device.relayNames else (device.coverSwitchNames[0] if device.coverSwitchNames else device.coverNames[0])) %}
             romasku.deviceConfig("device_config", "{{first_endpoint}}"),
@@ -436,6 +470,14 @@ const definitions = [
             romasku.bindedMode("{{switchName}}_binded_mode", "{{switchName}}"),
             romasku.longPressDuration("{{switchName}}_long_press_duration", "{{switchName}}"),
             romasku.levelMoveRate("{{switchName}}_level_move_rate", "{{switchName}}"),
+            romasku.switchAction("{{switchName}}_long_press_action_mode", "{{switchName}}_long_press"),
+            romasku.longRelayMode("{{switchName}}_long_press_relay_mode", "{{switchName}}_long_press"),
+            {% if device.relayNames %}
+            romasku.relayIndex("{{switchName}}_long_press_relay_index", "{{switchName}}_long_press", {{device.relayNames | length}}),
+            {% endif %}
+            romasku.moveCommand("{{switchName}}_long_press_move_command", "{{switchName}}_long_press"),
+            romasku.levelMoveDirection("{{switchName}}_long_press_level_move_direction", "{{switchName}}_long_press"),
+            romasku.levelMoveRate("{{switchName}}_long_press_level_move_rate", "{{switchName}}_long_press"),
             {% endfor %}
             {% for relayName in device.relayIndicatorNames %}
             romasku.relayIndicatorMode("{{relayName}}_indicator_mode", "{{relayName}}"),

helper_scripts/templates/zha_quirk.py.jinja

@@ -14,6 +14,11 @@ class RelayMode(t.enum8):
     LongPress = 0x02
     ShortPress = 0x03
 
+
+class LongPressRelayMode(t.enum8):
+    Detached = 0x00
+    LongPress = 0x02
+
 class BindedMode(t.enum8):
     PressStart = 0x01
     LongPress = 0x02
@@ -45,6 +50,17 @@ class CoverSwitchMode(t.enum8):
     Hybrid = 0x03
 
 
+class LevelMoveCommand(t.enum8):
+    Move = 0x01
+    MoveWithOnOff = 0x05
+
+
+class LevelMoveDirection(t.enum8):
+    Up = 0x00
+    Down = 0x01
+    Alternate = 0xff
+
+
 class CustomOnOffConfigurationCluster(CustomCluster, OnOffConfiguration):
 
     class AttributeDefs(OnOffConfiguration.AttributeDefs):
@@ -92,6 +108,20 @@ class CustomOnOffConfigurationCluster(CustomCluster, OnOffConfiguration):
             is_manufacturer_specific=False,
         )
 
+        level_move_direction = ZCLAttributeDef(
+            id=0xff08,
+            type=LevelMoveDirection,
+            access="rw",
+            is_manufacturer_specific=False,
+        )
+
+        move_command = ZCLAttributeDef(
+            id=0xff09,
+            type=LevelMoveCommand,
+            access="rw",
+            is_manufacturer_specific=False,
+        )
+
 
 class CustomMultistateInputCluster(CustomCluster, MultistateInput):
 
@@ -502,4 +532,81 @@ for config in CONFIGS:
             )
         )
 
-    builder.add_to_registry()
+    long_press_start = switch_cnt + relay_cnt + cover_switch_cnt + cover_cnt + 1
+
+    if switch_cnt > 0:
+        legacy_builder = builder.clone(omit_man_model_data=False)
+        legacy_builder.filter(
+            lambda d, ep=long_press_start: ep not in d.endpoints
+        )
+        legacy_builder.add_to_registry()
+
+        for endpoint_id in range(long_press_start, long_press_start + switch_cnt):
+            builder = (
+                builder
+                .removes(OnOffConfiguration.cluster_id, cluster_type=ClusterType.Client, endpoint_id=endpoint_id)
+                .adds(CustomOnOffConfigurationCluster, endpoint_id=endpoint_id)
+                .enum(
+                    CustomOnOffConfigurationCluster.AttributeDefs.switch_actions.name,
+                    SwitchActions,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_switch_actions_"+str(endpoint_id),
+                    fallback_name="Long press switch actions "+str(endpoint_id),
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+                .enum(
+                    CustomOnOffConfigurationCluster.AttributeDefs.relay_mode.name,
+                    LongPressRelayMode,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_relay_mode_"+str(endpoint_id),
+                    fallback_name="Long press relay mode "+str(endpoint_id),
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+                .number(
+                    CustomOnOffConfigurationCluster.AttributeDefs.relay_index.name,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_relay_index_"+str(endpoint_id),
+                    fallback_name="Long press relay index "+str(endpoint_id),
+                    min_value=1,
+                    max_value=relay_cnt,
+                    step=1,
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+                .enum(
+                    CustomOnOffConfigurationCluster.AttributeDefs.move_command.name,
+                    LevelMoveCommand,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_move_command_"+str(endpoint_id),
+                    fallback_name="Long press move command "+str(endpoint_id),
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+                .enum(
+                    CustomOnOffConfigurationCluster.AttributeDefs.level_move_direction.name,
+                    LevelMoveDirection,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_level_move_direction_"+str(endpoint_id),
+                    fallback_name="Long press level move direction "+str(endpoint_id),
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+                .number(
+                    CustomOnOffConfigurationCluster.AttributeDefs.level_move_rate.name,
+                    CustomOnOffConfigurationCluster.cluster_id,
+                    translation_key="long_press_level_move_rate_"+str(endpoint_id),
+                    fallback_name="Long press level move rate "+str(endpoint_id),
+                    min_value=1,
+                    max_value=255,
+                    step=1,
+                    endpoint_id=endpoint_id,
+                    entity_type=EntityType.CONFIG,
+                )
+            )
+
+        builder.filter(lambda d, ep=long_press_start: ep in d.endpoints)
+        builder.add_to_registry()
+    else:
+        builder.add_to_registry()