Add time sync button to Matter integration

homeassistant/components/matter/button.py

@@ -4,9 +4,11 @@
 
 from collections.abc import Callable
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
 from chip.clusters import Objects as clusters
+from chip.clusters.Types import NullValue
 
 from homeassistant.components.button import (
     ButtonDeviceClass,
@@ -17,6 +19,7 @@
 from homeassistant.const import EntityCategory, Platform
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
+from homeassistant.util import dt as dt_util
 
 from .entity import MatterEntity, MatterEntityDescription
 from .helpers import get_matter
@@ -52,6 +55,67 @@ async def async_press(self) -> None:
         await self.send_device_command(self.entity_description.command())
 
 
+# CHIP epoch: 2000-01-01 00:00:00 UTC
+CHIP_EPOCH = datetime(2000, 1, 1, tzinfo=UTC)
+
+
+class MatterTimeSyncButton(MatterEntity, ButtonEntity):
+    """Button to synchronize time to a Matter device."""
+
+    entity_description: MatterButtonEntityDescription
+
+    async def async_press(self) -> None:
+        """Sync Home Assistant time to the Matter device."""
+        now = dt_util.utcnow()
+        tz = dt_util.get_default_time_zone()
+        delta = now - CHIP_EPOCH
+        utc_us = (
+            (delta.days * 86400 * 1_000_000)
+            + (delta.seconds * 1_000_000)
+            + delta.microseconds
+        )
+
+        # Compute timezone and DST offsets
+        local_now = now.astimezone(tz)
+        utc_offset_delta = local_now.utcoffset()
+        utc_offset = int(utc_offset_delta.total_seconds()) if utc_offset_delta else 0
+        dst_offset_delta = local_now.dst()
+        dst_offset = int(dst_offset_delta.total_seconds()) if dst_offset_delta else 0
+        standard_offset = utc_offset - dst_offset
+
+        # 1. Set timezone
+        await self.send_device_command(
+            clusters.TimeSynchronization.Commands.SetTimeZone(
+                timeZone=[
+                    clusters.TimeSynchronization.Structs.TimeZoneStruct(
+                        offset=standard_offset, validAt=0, name=str(tz)
+                    )
+                ]
+            )
+        )
+
+        # 2. Set DST offset
+        await self.send_device_command(
+            clusters.TimeSynchronization.Commands.SetDSTOffset(
+                DSTOffset=[
+                    clusters.TimeSynchronization.Structs.DSTOffsetStruct(
+                        offset=dst_offset,
+                        validStarting=0,
+                        validUntil=NullValue,
+                    )
+                ]
+            )
+        )
+
+        # 3. Set UTC time
+        await self.send_device_command(
+            clusters.TimeSynchronization.Commands.SetUTCTime(
+                UTCTime=utc_us,
+                granularity=clusters.TimeSynchronization.Enums.GranularityEnum.kMicrosecondsGranularity,
+            )
+        )
+
+
 # Discovery schema(s) to map Matter Attributes to HA entities
 DISCOVERY_SCHEMAS = [
     MatterDiscoverySchema(
@@ -169,4 +233,16 @@ async def async_press(self) -> None:
         value_contains=clusters.WaterHeaterManagement.Commands.CancelBoost.command_id,
         allow_multi=True,  # Also used in water_heater
     ),
+    MatterDiscoverySchema(
+        platform=Platform.BUTTON,
+        entity_description=MatterButtonEntityDescription(
+            key="TimeSynchronizationSyncTimeButton",
+            translation_key="sync_time",
+            entity_category=EntityCategory.CONFIG,
+        ),
+        entity_class=MatterTimeSyncButton,
+        required_attributes=(clusters.TimeSynchronization.Attributes.UTCTime,),
+        allow_multi=True,
+        allow_none_value=True,
+    ),
 ]

homeassistant/components/matter/icons.json

@@ -20,6 +20,9 @@
       },
       "stop": {
         "default": "mdi:stop"
+      },
+      "sync_time": {
+        "default": "mdi:clock-check-outline"
       }
     },
     "fan": {

homeassistant/components/matter/strings.json

@@ -141,6 +141,9 @@
       },
       "stop": {
         "name": "[%key:common::action::stop%]"
+      },
+      "sync_time": {
+        "name": "Sync time"
       }
     },
     "climate": {