Add Legrand devices: Connected Outlet, Micromodule Switch, Shutter Switch, Remote Shutter Switch, Switch and Dimmer (#4271)

* Add custom clusters for Legrand devices

* Extend the main `LegrandCluster` to support a generic `device_mode` enum attribute that can be used in various modes. The enum values are actually taken from the Z2M project for consistency (even if following commits utilize only the `Dimmer_On` and `Dimmer_Off` values)
* Add a custom Identify cluster, to support the custom identification method for Legrand devices, which consists in sending a `trigger_effect` command before the `identify` command in order to work properly
* Add a custom Shutter cluster, that adds a `calibration_mode` attribute used by shutter switches

Note: All information has been derived from the official Legrand documentation, which can be found at https://developer.legrand.com/local-interoperability/#Products%20cluster%20list

* Add support for Legrand connected outlets

Additional notes:
* The BinaryInput cluster entity is removed as it is non functional
* The OnOff cluster opening entity is removed as it is non functional
* Additional options for controlling the device LED have been added

* Add support for Legrand micromodule switches

Additional notes:
* The BinaryInput cluster entity is removed as it is non functional
* The OnOff cluster opening entity is removed as it is non functional
* Additional options for controlling the device LED have been added

* Add support for Legrand shutter switches

Additional notes:
* The "calibration mode" attribute has been added from the custom Shutter cluster
* The BinaryInput cluster entity is removed as it is non functional
* The OnOff cluster opening entity is removed as it is non functional
* Additional options for controlling the device LED have been added

* Add support for Legrand remote shutter switch

Additional notes:
* The BinaryInput cluster entity is removed as it is non functional
* NO Additional options for controlling the device LED have been added as they are not used in battery powered devices

* Convert Legrand switch quirk to V2

Additional notes:
* The BinaryInput cluster entity is removed as it is non functional
* The OnOff cluster opening entity is removed as it is non functional
* Additional options for controlling the device LED have been added

* Convert Legrand dimmer quirk to V2

Additional notes:
* Add a "dimmer mode" toggle entity to enable or disable dimmer functionality
* The BinaryInput cluster entity is removed as it is non functional
* The OnOff cluster opening entity is removed as it is non functional
* Additional options for controlling the device LED have been added

* Remove obsolete signature test for Legrand switch

* Better handling of command arguments in the LegrandIdentify clusters

* Add a test for the custom Legrand identify command

* Clean up test syntax for the custom Legrand identify command

Author: rapgenic

tests/test_legrand.py

@@ -32,35 +32,6 @@ async def test_legrand_battery(zigpy_device_from_quirk, voltage, bpr):
     assert power_cluster["battery_percentage_remaining"] == bpr
 
 
-def test_light_switch_with_neutral_signature(assert_signature_matches_quirk):
-    """Test signature."""
-    signature = {
-        "node_descriptor": "NodeDescriptor(logical_type=<LogicalType.Router: 1>, complex_descriptor_available=0, user_descriptor_available=1, reserved=0, aps_flags=0, frequency_band=<FrequencyBand.Freq2400MHz: 8>, mac_capability_flags=<MACCapabilityFlags.AllocateAddress|RxOnWhenIdle|MainsPowered|FullFunctionDevice: 142>, manufacturer_code=4129, maximum_buffer_size=89, maximum_incoming_transfer_size=63, server_mask=10752, maximum_outgoing_transfer_size=63, descriptor_capability_field=<DescriptorCapability.NONE: 0>, *allocate_address=True, *is_alternate_pan_coordinator=False, *is_coordinator=False, *is_end_device=False, *is_full_function_device=True, *is_mains_powered=True, *is_receiver_on_when_idle=True, *is_router=True, *is_security_capable=False)",
-        "endpoints": {
-            "1": {
-                "profile_id": 260,
-                "device_type": "0x0100",
-                "in_clusters": [
-                    "0x0000",
-                    "0x0003",
-                    "0x0004",
-                    "0x0005",
-                    "0x0006",
-                    "0x000f",
-                    "0xfc01",
-                ],
-                "out_clusters": ["0x0000", "0x0019", "0xfc01"],
-            }
-        },
-        "manufacturer": " Legrand",
-        "model": " Light switch with neutral",
-        "class": "zigpy.device.Device",
-    }
-    assert_signature_matches_quirk(
-        zhaquirks.legrand.switch.LightSwitchWithNeutral, signature
-    )
-
-
 async def test_legrand_wire_pilot_cluster_write_attrs(zigpy_device_from_v2_quirk):
     """Test Legrand cable outlet pilot_wire_mode attr writing."""
 
@@ -82,3 +53,36 @@ async def test_legrand_wire_pilot_cluster_write_attrs(zigpy_device_from_v2_quirk
         [],
         manufacturer=0xFC40,
     )
+
+
+async def test_legrand_identify_command(zigpy_device_from_v2_quirk):
+    """Test Legrand Identify cluster command handling."""
+
+    device = zigpy_device_from_v2_quirk(f" {LEGRAND}", " Light switch with neutral")
+    identify_cluster = device.endpoints[1].identify
+
+    with mock.patch("zigpy.zcl.Cluster.request") as request:
+        # Expected values for the mocked function calls
+        IDENTIFY_TIME = 1234
+        IDENTIFY_COMMAND = 0x00
+        TRIGGER_EFFECT_COMMAND = 0x40
+        EFFECT_ID = 0x00
+        EFFECT_VARIANT = 0x00
+
+        # Test the identify command
+        await identify_cluster.identify(identify_time=IDENTIFY_TIME)
+
+        # The identify command should produce two requests
+        assert request.call_count == 2
+
+        # The first call is for the trigger effect command
+        assert request.call_args_list[0].args[1] == TRIGGER_EFFECT_COMMAND
+        assert request.call_args_list[0].kwargs["effect_id"] == EFFECT_ID
+        assert request.call_args_list[0].kwargs["effect_variant"] == EFFECT_VARIANT
+        assert "identify_time" not in request.call_args_list[0].kwargs
+
+        # The second call is for the identify command
+        assert request.call_args_list[1].args[1] == IDENTIFY_COMMAND
+        assert request.call_args_list[1].kwargs["identify_time"] == IDENTIFY_TIME
+        assert "effect_id" not in request.call_args_list[1].kwargs
+        assert "effect_variant" not in request.call_args_list[1].kwargs

zhaquirks/legrand/__init__.py

@@ -1,15 +1,38 @@
 """Module for Legrand devices."""
 
+from typing import Any
+
 from zigpy.quirks import CustomCluster
 import zigpy.types as t
-from zigpy.zcl.foundation import BaseAttributeDefs, ZCLAttributeDef
+from zigpy.zcl.clusters.closures import WindowCovering
+from zigpy.zcl.clusters.general import EffectIdentifier, EffectVariant, Identify
+from zigpy.zcl.foundation import (
+    BaseAttributeDefs,
+    DataTypeId,
+    GeneralCommand,
+    ZCLAttributeDef,
+)
 
 from zhaquirks import PowerConfigurationCluster
 
 LEGRAND = "Legrand"
 MANUFACTURER_SPECIFIC_CLUSTER_ID = 0xFC01  # decimal = 64513
 
 
+class DeviceMode(t.enum16):
+    """Device modes for some Legrand devices. To be used in custom cluster.
+
+    Note: some values are taken from the Z2M code.
+    """
+
+    Pilot_Off = 0x0001
+    Pilot_On = 0x0002
+    Switch = 0x0003
+    Auto = 0x0004
+    Dimmer_Off = 0x0100
+    Dimmer_On = 0x0101
+
+
 class LegrandCluster(CustomCluster):
     """LegrandCluster."""
 
@@ -20,15 +43,74 @@ class LegrandCluster(CustomCluster):
     class AttributeDefs(BaseAttributeDefs):
         """Cluster attributes."""
 
-        dimmer = ZCLAttributeDef(
-            id=0x0000, type=t.data16, is_manufacturer_specific=True
+        device_mode = ZCLAttributeDef(
+            id=0x0000,
+            type=DeviceMode,
+            zcl_type=DataTypeId.data16,
+            is_manufacturer_specific=True,
         )
         led_dark = ZCLAttributeDef(
             id=0x0001, type=t.Bool, is_manufacturer_specific=True
         )
         led_on = ZCLAttributeDef(id=0x0002, type=t.Bool, is_manufacturer_specific=True)
 
 
+class LegrandIdentify(CustomCluster, Identify):
+    """Custom Identify cluster for Legrand devices. Replaces the identify command."""
+
+    async def command(
+        self,
+        command_id: GeneralCommand | int | t.uint8_t,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Override the command method to customize the identify command."""
+
+        if command_id == Identify.ServerCommandDefs.identify.id:
+            # Remove identify command specific arguments
+            identify_time = kwargs.pop("identify_time", None)
+
+            await super().command(
+                command_id=Identify.ServerCommandDefs.trigger_effect.id,
+                effect_id=EffectIdentifier.Blink,
+                effect_variant=EffectVariant.Default,
+                **kwargs,
+            )
+
+            # Restore identify command specific arguments
+            if identify_time is not None:
+                kwargs["identify_time"] = identify_time
+
+        return await super().command(
+            command_id,
+            *args,
+            **kwargs,
+        )
+
+
+class ShutterCalibrationMode(t.enum8):
+    """Shutter calibration modes for Legrand devices."""
+
+    Classic = 0x00
+    Specific = 0x01
+    Up_Down_Stop = 0x02
+    Temporal = 0x03
+    Venetian = 0x04
+
+
+class LegrandShutterCluster(CustomCluster, WindowCovering):
+    """Custom Shutter cluster for Legrand devices. Adds calibration mode."""
+
+    class AttributeDefs(WindowCovering.AttributeDefs):
+        """Cluster attributes."""
+
+        calibration_mode = ZCLAttributeDef(
+            id=0xF002,
+            type=ShutterCalibrationMode,
+            is_manufacturer_specific=True,
+        )
+
+
 class LegrandPowerConfigurationCluster(PowerConfigurationCluster):
     """PowerConfiguration conversor 'V --> %' for Legrand devices."""
 

zhaquirks/legrand/connected_outled.py

@@ -0,0 +1,31 @@
+"""Module for Legrand switches (without dimming functionality)."""
+
+from zigpy.quirks.v2 import QuirkBuilder
+from zigpy.zcl.clusters.general import BinaryInput, OnOff
+
+from zhaquirks.legrand import LEGRAND, LegrandCluster, LegrandIdentify
+
+(
+    QuirkBuilder(f" {LEGRAND}", " Connected outlet")
+    .replaces(LegrandCluster)
+    .replaces(LegrandIdentify)
+    .prevent_default_entity_creation(endpoint_id=1, cluster_id=BinaryInput.cluster_id)
+    .prevent_default_entity_creation(
+        endpoint_id=1,
+        cluster_id=OnOff.cluster_id,
+        function=lambda entity: entity.device_class == "opening",
+    )
+    .switch(
+        attribute_name=LegrandCluster.AttributeDefs.led_dark.name,
+        cluster_id=LegrandCluster.cluster_id,
+        translation_key="turn_on_led_when_off",
+        fallback_name="Turn on LED when off",
+    )
+    .switch(
+        attribute_name=LegrandCluster.AttributeDefs.led_on.name,
+        cluster_id=LegrandCluster.cluster_id,
+        translation_key="turn_on_led_when_on",
+        fallback_name="Turn on LED when on",
+    )
+    .add_to_registry()
+)

zhaquirks/legrand/dimmer.py

@@ -2,6 +2,7 @@
 
 from zigpy.profiles import zgp, zha
 from zigpy.quirks import CustomDevice
+from zigpy.quirks.v2 import QuirkBuilder
 from zigpy.zcl.clusters.general import (
     Basic,
     BinaryInput,
@@ -28,7 +29,9 @@
 from zhaquirks.legrand import (
     LEGRAND,
     MANUFACTURER_SPECIFIC_CLUSTER_ID,
+    DeviceMode,
     LegrandCluster,
+    LegrandIdentify,
     LegrandPowerConfigurationCluster,
 )
 
@@ -278,108 +281,38 @@ class DimmerWithoutNeutralAndBallast(CustomDevice):
     }
 
 
-class DimmerWithNeutral(DimmerWithoutNeutral):
-    """Dimmer switch with neutral."""
-
-    signature = {
-        #  <SimpleDescriptor endpoint=1 profile=260 device_type=256
-        # device_version=1
-        # input_clusters=[0, 3, 4, 8, 6, 5, 15, 64513]
-        # output_clusters=[0, 25, 64513]>
-        MODELS_INFO: [(f" {LEGRAND}", " Dimmer switch with neutral")],
-        ENDPOINTS: {
-            1: {
-                PROFILE_ID: zha.PROFILE_ID,
-                DEVICE_TYPE: zha.DeviceType.ON_OFF_LIGHT,
-                INPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    Identify.cluster_id,
-                    Groups.cluster_id,
-                    OnOff.cluster_id,
-                    LevelControl.cluster_id,
-                    Scenes.cluster_id,
-                    BinaryInput.cluster_id,
-                    MANUFACTURER_SPECIFIC_CLUSTER_ID,
-                ],
-                OUTPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    MANUFACTURER_SPECIFIC_CLUSTER_ID,
-                    Ota.cluster_id,
-                ],
-            },
-            242: {
-                PROFILE_ID: zgp.PROFILE_ID,
-                DEVICE_TYPE: zgp.DeviceType.COMBO_BASIC,
-                INPUT_CLUSTERS: [GreenPowerProxy.cluster_id],
-                OUTPUT_CLUSTERS: [GreenPowerProxy.cluster_id],
-            },
-        },
-    }
-
-
-class DimmerWithNeutral2(CustomDevice):
-    """Dimmer switch with neutral."""
-
-    signature = {
-        #  <SimpleDescriptor endpoint=1 profile=260 device_type=256
-        # device_version=1
-        # input_clusters=[0, 3, 4, 8, 6, 5, 15, 64513]
-        # output_clusters=[0, 64513, 5, 25]>
-        MODELS_INFO: [(f" {LEGRAND}", " Dimmer switch with neutral")],
-        ENDPOINTS: {
-            1: {
-                PROFILE_ID: zha.PROFILE_ID,
-                DEVICE_TYPE: zha.DeviceType.ON_OFF_LIGHT,
-                INPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    Identify.cluster_id,
-                    Groups.cluster_id,
-                    OnOff.cluster_id,
-                    LevelControl.cluster_id,
-                    Scenes.cluster_id,
-                    BinaryInput.cluster_id,
-                    MANUFACTURER_SPECIFIC_CLUSTER_ID,
-                ],
-                OUTPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    MANUFACTURER_SPECIFIC_CLUSTER_ID,
-                    Scenes.cluster_id,
-                    Ota.cluster_id,
-                ],
-            },
-            242: {
-                PROFILE_ID: zgp.PROFILE_ID,
-                DEVICE_TYPE: zgp.DeviceType.COMBO_BASIC,
-                INPUT_CLUSTERS: [GreenPowerProxy.cluster_id],
-                OUTPUT_CLUSTERS: [GreenPowerProxy.cluster_id],
-            },
-        },
-    }
-
-    replacement = {
-        ENDPOINTS: {
-            1: {
-                PROFILE_ID: zha.PROFILE_ID,
-                DEVICE_TYPE: zha.DeviceType.ON_OFF_LIGHT,
-                INPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    Identify.cluster_id,
-                    Groups.cluster_id,
-                    OnOff.cluster_id,
-                    LevelControl.cluster_id,
-                    Scenes.cluster_id,
-                    BinaryInput.cluster_id,
-                    LegrandCluster,
-                ],
-                OUTPUT_CLUSTERS: [
-                    Basic.cluster_id,
-                    LegrandCluster,
-                    Scenes.cluster_id,
-                    Ota.cluster_id,
-                ],
-            }
-        }
-    }
+(
+    QuirkBuilder(f" {LEGRAND}", " Dimmer switch with neutral")
+    .replaces(LegrandCluster)
+    .replaces(LegrandIdentify)
+    .prevent_default_entity_creation(endpoint_id=1, cluster_id=BinaryInput.cluster_id)
+    .prevent_default_entity_creation(
+        endpoint_id=1,
+        cluster_id=OnOff.cluster_id,
+        function=lambda entity: entity.device_class == "opening",
+    )
+    .switch(
+        attribute_name=LegrandCluster.AttributeDefs.device_mode.name,
+        cluster_id=LegrandCluster.cluster_id,
+        on_value=DeviceMode.Dimmer_On,
+        off_value=DeviceMode.Dimmer_Off,
+        translation_key="dimmer_mode",
+        fallback_name="Dimmer mode",
+    )
+    .switch(
+        attribute_name=LegrandCluster.AttributeDefs.led_dark.name,
+        cluster_id=LegrandCluster.cluster_id,
+        translation_key="turn_on_led_when_off",
+        fallback_name="Turn on LED when off",
+    )
+    .switch(
+        attribute_name=LegrandCluster.AttributeDefs.led_on.name,
+        cluster_id=LegrandCluster.cluster_id,
+        translation_key="turn_on_led_when_on",
+        fallback_name="Turn on LED when on",
+    )
+    .add_to_registry()
+)
 
 
 class RemoteDimmer(CustomDevice):