Add Matter support for White series switches

This is currently untested.

Author: wbyoung

README.md

@@ -26,8 +26,6 @@ What it can do:
 - **Even more**  
   There are some more goodies in to docs below. Enjoy!
 
-_Note: currently this is limited to Blue switches using ZHA or Zigbee2MQTT and Red switches using Z-Wave JS, but other Inovelli switches will be added in the future._
-
 **Configure notifications** for multiple switches easily:
 
 <img width="300" alt="Image" src="https://github.com/user-attachments/assets/02f4888b-836c-4114-8a1d-bff66738087e" />
@@ -285,6 +283,17 @@ Unlike the Blue series switches under ZHA, there is no way to receive events for
 
 This integration therefore handles notification expiration itself for switches configured with Z-Wave. This may change unexpectedly in the future—if and when it is possible, Lampie will change to sending durations to the firmware.
 
+##### Matter
+
+White series switches only have a single LED and do not support effects. Lampie will do the following for these switches:
+
+- All will simply indicate to enable the notification (besides `CLEAR`)
+- If [individual LEDs](#full-led-configuration) are configured, the first LED settings will be used
+
+Unlike the Blue series switches under ZHA, there is no way to receive events for when a notification expires (it only supports, for instance, when the config button is dobule pressed via a state change on `event.<switch_id>_config` with `event_type="multi_press_2"`). This may be supported in the firmware and not yet available for end user consumption.
+
+This integration therefore handles notification expiration itself for switches configured with Matter. This may change unexpectedly in the future—if and when it is possible, Lampie will change to sending durations to the firmware.
+
 ## More Screenshots
 
 Once configured, the integration links the various entities to logical devices:

custom_components/lampie/const.py

@@ -35,6 +35,8 @@
     "LZW30-SN",  # red on/off switch
     "LZW31-SN",  # red dimmer
     "LZW36",  # red fan/light combo
+    "VTM31-SN",  # white dimmer (2-in-1 switch/dimmer)
+    "VTM35-SN",  # white fan
     "VZM30-SN",  # blue switch
     "VZM31-SN",  # blue 2-in-1 switch/dimmer
     "VZM35-SN",  # blue fan switch

custom_components/lampie/orchestrator.py

@@ -13,6 +13,7 @@
 from typing import TYPE_CHECKING, Any, Final, NamedTuple, Protocol, Unpack
 
 from homeassistant.components import mqtt
+from homeassistant.components.light import DOMAIN as LIGHT_DOMAIN
 from homeassistant.components.mqtt import DOMAIN as MQTT_DOMAIN
 from homeassistant.components.mqtt.models import MqttData
 from homeassistant.components.script import DOMAIN as SCRIPT_DOMAIN
@@ -52,6 +53,7 @@
     LEDConfig,
     LEDConfigSource,
     LEDConfigSourceType,
+    MatterSwitchInfo,
     Slug,
     SwitchId,
     Z2MSwitchInfo,
@@ -64,6 +66,7 @@
 
 type ZHAEventData = dict[str, Any]
 type ZWaveEventData = dict[str, Any]
+type MatterEventData = dict[str, Any]
 type MQTTDeviceName = str
 
 _LOGGER = logging.getLogger(__name__)
@@ -75,13 +78,15 @@
     model: {Effect[effect_key].value: value for effect_key, value in mapping.items()}
     for model, mapping in _ZWAVE_EFFECT_MAPPING.items()
 }
+MATTER_DOMAIN: Final = "matter"
 
 ALREADY_EXPIRED: Final = 0
 
 SWITCH_INTEGRATIONS = {
     ZHA_DOMAIN: Integration.ZHA,
     MQTT_DOMAIN: Integration.Z2M,
     ZWAVE_DOMAIN: Integration.ZWAVE,
+    MATTER_DOMAIN: Integration.MATTER,
 }
 
 FIRMWARE_SECONDS_MAX = dt.timedelta(seconds=60).total_seconds()
@@ -127,6 +132,8 @@
     ("003", "KeyPressed2x"): "button_3_double",
 }
 
+MATTER_COMMAND_MAP = {("config", "multi_press_2"): "button_3_double"}
+
 
 class _LEDMode(IntEnum):
     ALL = 1
@@ -198,6 +205,11 @@ def __init__(self, hass: HomeAssistant) -> None:
                 self._handle_zwave_event,
                 self._filter_zwave_events,
             ),
+            hass.bus.async_listen(  # matter listener is for any state change event
+                "state_changed",
+                self._handle_matter_event,
+                self._filter_matter_events,
+            ),
         ]
 
     async def add_coordinator(self, coordinator: LampieUpdateCoordinator) -> None:
@@ -288,6 +300,7 @@ async def _ensure_switch_setup_completed(self, switch_id: SwitchId) -> None:
             Integration.ZHA: self._zha_switch_setup,
             Integration.Z2M: self._z2m_switch_setup,
             Integration.ZWAVE: self._zwave_switch_setup,
+            Integration.MATTER: self._matter_switch_setup,
         }[integration](switch_id, device, entity_entries)
 
         self._switch_ids[_SwitchKey(_SwitchKeyType.DEVICE_ID, device_id)] = switch_id
@@ -410,6 +423,32 @@ async def _zwave_switch_setup(  # noqa: PLR6301
     ) -> ZWaveSwitchInfo:
         return ZWaveSwitchInfo()
 
+    async def _matter_switch_setup(  # noqa: PLR6301
+        self,
+        switch_id: SwitchId,  # noqa: ARG002
+        device: dr.DeviceEntry,  # noqa: ARG002
+        entity_entries: list[er.RegistryEntry],
+    ) -> MatterSwitchInfo:
+        effect_id = None
+
+        def is_matter_platform(entry: er.RegistryEntry) -> bool:
+            return bool(entry.platform == MATTER_DOMAIN)
+
+        for entity_entry in filter(is_matter_platform, entity_entries):
+            if (
+                entity_entry.domain == LIGHT_DOMAIN
+                and entity_entry.translation_key == "effect"
+            ):
+                effect_id = entity_entry.entity_id
+                _LOGGER.debug(
+                    "found Matter effect entity: %s",
+                    effect_id,
+                )
+
+        return MatterSwitchInfo(
+            effect_id=effect_id,
+        )
+
     def has_notification(self, slug: Slug) -> bool:
         return slug in self._coordinators
 
@@ -930,6 +969,7 @@ async def _dispatch_service_command(
             Integration.ZHA: self._zha_service_command,
             Integration.Z2M: self._z2m_service_command,
             Integration.ZWAVE: self._zwave_service_command,
+            Integration.MATTER: self._matter_service_command,
         }[switch_info.integration]
 
         await service_command(
@@ -1084,6 +1124,48 @@ async def _zwave_service_command(
             },
         )
 
+    async def _matter_service_command(
+        self,
+        *,
+        switch_id: SwitchId,
+        device: dr.DeviceEntry,
+        led_mode: _LEDMode,
+        params: dict[str, Any],
+    ) -> None:
+        if (
+            led_mode == _LEDMode.INDIVIDUAL
+            and (led_number := params["led_number"]) != 0
+        ):
+            _LOGGER.warning(
+                "skipping setting LED_%s (idx %s) on for model %s: "
+                "individual LEDs unsupported",
+                led_number + 1,
+                led_number,
+                device.model,
+            )
+            return
+
+        switch_info = self.switch_info(switch_id)
+
+        service_call_action = "turn_on"
+        service_call_data = {
+            "brightness_pct": params["led_level"],
+            "hs_color": [round(((params["led_color"] / 255) * 360), 1), 100],
+        }
+
+        if params["led_effect"] == Effect.CLEAR.value:
+            service_call_action = "turn_off"
+            service_call_data = {}
+
+        await self._hass.services.async_call(
+            LIGHT_DOMAIN,
+            service_call_action,
+            {
+                "entity_id": switch_info.integration_info.effect_id,
+                **service_call_data,
+            },
+        )
+
     def _switch_command_led_params(
         self, led: LEDConfig, switch_id: SwitchId
     ) -> dict[str, Any]:
@@ -1127,10 +1209,14 @@ def _z2m() -> bool:
         def _zwave() -> bool:
             return False  # unsupported for now
 
+        def _matter() -> bool:
+            return False  # unsupported for now
+
         return {
             Integration.ZHA: _zha,
             Integration.Z2M: _z2m,
             Integration.ZWAVE: _zwave,
+            Integration.MATTER: _matter,
         }[integration]()
 
     def _double_tap_clear_notifications_disabled(self, switch_id: SwitchId) -> bool:
@@ -1156,10 +1242,14 @@ def _z2m() -> bool:
         def _zwave() -> bool:
             return False  # unsupported for now
 
+        def _matter() -> bool:
+            return False  # unsupported for now
+
         return {
             Integration.ZHA: _zha,
             Integration.Z2M: _z2m,
             Integration.ZWAVE: _zwave,
+            Integration.MATTER: _matter,
         }[integration]()
 
     def _any_has_expiration_messaging(self, switches: Sequence[SwitchId]) -> bool:
@@ -1173,6 +1263,7 @@ def _any_has_expiration_messaging(self, switches: Sequence[SwitchId]) -> bool:
             Z2M: Processes these and turns them into
                 `{"notificationComplete": "{ALL|LED_1-7}"}` messages.
             ZWAVE: May or may not create these messages.
+            MATTER: May or may not create these messages.
 
         Returns:
             A boolean indicating if any of the switches are part of such an
@@ -1326,6 +1417,51 @@ async def _handle_zwave_event(self, event: Event[ZWaveEventData]) -> None:
             integration=Integration.ZWAVE,
         )
 
+    @callback
+    def _filter_matter_events(
+        self,
+        event_data: MatterEventData,
+    ) -> bool:
+        entity_id = event_data["entity_id"]
+
+        if (
+            not entity_id.startswith("event.")
+            or not (entity_registry := er.async_get(self._hass))
+            or not (event_entity := entity_registry.async_get(entity_id))
+            or not (
+                switch_key := _SwitchKey(
+                    _SwitchKeyType.DEVICE_ID, event_entity.device_id
+                )
+            )
+        ):
+            return False
+
+        state = event_data["new_state"]
+        attributes = state["attributes"]
+        command = MATTER_COMMAND_MAP.get(
+            (event_entity.translation_key, attributes.get("event_type"))
+        )
+        return switch_key in self._switch_ids and command in DISMISSAL_COMMANDS
+
+    @callback
+    async def _handle_matter_event(self, event: Event[MatterEventData]) -> None:
+        entity_id = event.data["entity_id"]
+        entity_registry = er.async_get(self._hass)
+        event_entity = entity_registry.async_get(entity_id)
+        device_id = event_entity.device_id
+        switch_key = _SwitchKey(_SwitchKeyType.DEVICE_ID, device_id)
+        switch_id = self._switch_ids[switch_key]
+        state = event.data["new_state"]
+        attributes = state["attributes"]
+        command = MATTER_COMMAND_MAP[
+            event_entity.translation_key, attributes["event_type"]
+        ]
+        await self._handle_generic_event(
+            command=command,
+            switch_id=switch_id,
+            integration=Integration.MATTER,
+        )
+
     async def _handle_generic_event(
         self,
         *,

custom_components/lampie/types.py

@@ -227,6 +227,7 @@ class Integration(StrEnum):
     ZHA = auto()
     Z2M = auto()
     ZWAVE = auto()
+    MATTER = auto()
 
 
 @dataclass(frozen=True)
@@ -277,6 +278,13 @@ class ZWaveSwitchInfo:
     """ZWave switch info data class."""
 
 
+@dataclass(frozen=True)
+class MatterSwitchInfo:
+    """Matter switch info data class."""
+
+    effect_id: EntityId | None = None
+
+
 @dataclass(frozen=True)
 class LampieSwitchInfo:
     """Lampie switch data class."""

tests/__init__.py

@@ -86,6 +86,7 @@ def add_mock_switch(
         Integration.ZHA: "zha",
         Integration.Z2M: "mqtt",
         Integration.ZWAVE: "zwave_js",
+        Integration.MATTER: "matter",
     }[integration]
 
     identifiers = {
@@ -95,13 +96,15 @@ def add_mock_switch(
             "zwave_js",
             f"mock-zwave-driver-controller-id_mock-node-{object_id}",
         ),
+        Integration.MATTER: ("matter", f"mock:deviceid_{object_id}-nodeid"),
     }[integration]
 
     model_key = "model_id" if integration == Integration.Z2M else "model"
     model = {
         Integration.ZHA: "VZM31-SN",
         Integration.Z2M: "VZM31-SN",
         Integration.ZWAVE: "VZW31-SN",
+        Integration.MATTER: "VTM31-SN",
     }[integration]
 
     device_registry = dr.async_get(hass)
@@ -177,6 +180,24 @@ def add_mock_switch(
             "discovery_payload"
         ]["state_topic"] = f"home/z2m/{mock_config_entry.title}"
 
+    if integration == Integration.MATTER:
+        entity_registry.async_get_or_create(
+            "event",
+            integration_domain,
+            f"{object_id}-config",
+            suggested_object_id=f"{object_id}_config",
+            translation_key="config",
+            device_id=device_entry.id,
+        )
+        entity_registry.async_get_or_create(
+            "light",
+            integration_domain,
+            f"{object_id}-effect",
+            suggested_object_id=f"{object_id}_effect",
+            translation_key="effect",
+            device_id=device_entry.id,
+        )
+
     return switch