A native Home Assistant custom component to synchronize Time and Timezone on Matter devices that support the Time Synchronization cluster.

This component communicates directly with the Matter Server Add-on (or standalone container) via WebSocket, ensuring your devices always display the correct local time. I originally created this solution out of frustration with the IKEA ALPSTUGA's inability to sync time (via Home Assistant), but it works across various Matter devices with automatic discovery and flexible scheduling options.

🫰🏻 A big thank you to @cnc-lasercraft, @svasek, @Lexorius and @miketth for their help.

• 🔍 Automatic Device Discovery: Discovers all Matter devices and identifies those supporting time synchronization.
• 🔘 Button Entities: Creates sync buttons for each device using your Home Assistant friendly names.
• ⚡ Auto-Sync: Optionally synchronize all devices at regular intervals (15 min to 24 hours).
• 🎯 Device Filtering: Filter which devices get sync buttons by name or specific criteria.
• ⚡ Native Async: Built on aiohttp and standard Platform.BUTTON enums for high performance and stability.
• 🛠️ Zero Dependencies: Does not require the heavy chip SDK or external websocket-client libraries.
• ⚙️ UI & Multi-Instance: Configure everything via the UI with full support for multiple integration instances.
• 🌍 Complete Sync: Synchronizes UTC and Time Zone with automatic Home Assistant timezone detection during setup.
• 🧹 Smart Lifecycle: Automatically cleans up resources for removed devices and prevents duplicate service registrations.
• 🛡️ Robust Messaging: Gracefully logs and skips unexpected Matter Server messages to prevent errors.

⚠️ You have to expose the TCP port 5580. To do this, go to Settings → Add-ons → Matter Server → Configuration → Network and add 5580 to expose the Matter Server WebSocket port.

1. Open HACS in Home Assistant.
2. Go to the Integrations section.
3. Click the menu (three dots) in the top right corner and select Custom repositories.
4. Paste the URL of this GitHub repository (https://github.com/Loweack/Matter-Time-Sync).
5. Select Integration as the category and click Add.
6. Click Download on the new "Matter Time Sync" card.
7. Restart Home Assistant.

1. Download the latest release from this repository.
2. Copy the custom_components/matter_time_sync folder into your Home Assistant's homeassistant/custom_components/ directory.
3. Restart Home Assistant.

1. Navigate to Settings > Devices & Services.
2. Click + Add Integration.
3. Search for Matter Time Sync.
4. Enter your configuration details:

5. Click Submit.

The device filter matches device names (case-insensitive, partial match):

• alpstuga - Only devices containing "alpstuga" in their name
• alpstuga, ikea - Devices containing "alpstuga" OR "ikea"
• (empty) - All devices

All settings can be changed later via Settings > Devices & Services > Matter Time Sync > Configure.

Each compatible Matter device gets a button entity named [Device Name] Sync Time. Press the button to synchronize that device's time immediately.

Example entity IDs:

• button.alpstuga_air_quality_monitor_sync_time
• button.vindstyrka_sync_time

Synchronizes time on a specific Matter device by node ID.

Parameters:

• node_id (Required): The Matter Node ID of the device (integer).
• endpoint (Optional): The endpoint ID (default: 0).

Example:

service: matter_time_sync.sync_time
data:
  node_id: 7
  endpoint: 0

Synchronize time on all filtered Matter devices at once.

service: matter_time_sync.sync_all

Search for new Matter devices and create buttons for them (useful after adding new devices).

service: matter_time_sync.refresh_devices

Synchronizes time every Sunday at 03:15 AM and when the device comes online:

alias: "[TIME] Sync IKEA ALPSTUGA"
description: >-
  Synchronizes the time on the IKEA ALPSTUGA on Sundays at 03:15 AM and whenever
  the device becomes available after being unavailable.
triggers:
  - at: "03:15:00"
    trigger: time
    weekday:
      - sun
  - entity_id:
      - switch.alpstuga_air_quality_monitor
    from:
      - unavailable
    to: null
    trigger: state
actions:
  - delay:
      hours: 0
      minutes: 0
      seconds: 5
      milliseconds: 0
  - action: matter_time_sync.sync_time
    data:
      node_id: 7
      endpoint: 0
mode: restart

alias: "Sync Matter Time at Midnight"
trigger:
  - platform: time
    at: "00:00:00"
action:
  - service: matter_time_sync.sync_all

alias: "Sync Matter Time on Startup"
trigger:
  - platform: homeassistant
    event: start
action:
  - delay: "00:01:00"  # Wait for Matter Server to be ready
  - service: matter_time_sync.sync_all

The integration automatically detects which devices support the Time Synchronization cluster (0x0038). Devices that are known to support it include:

• IKEA ALPSTUGA air quality monitor
• IKEA VINDSTYRKA air quality sensor
• Other Matter devices with Time Sync cluster support

Devices without Time Sync support (like simple sensors, buttons, or plugs) will be skipped unless you disable the "Only devices with Time Sync support" option.

• Check that the Matter Server is running and accessible
• Verify the WebSocket URL is correct (default: ws://core-matter-server:5580/ws)
• Check Home Assistant logs for connection errors

• The device may not expose product information
• Check if the device has a user-defined name in Home Assistant
• The name will update after the device is properly commissioned

• The device does not support the Time Synchronization cluster
• Enable "Only devices with Time Sync support" to filter these out automatically

• The device is offline or not responding
• Check the device's battery or power connection
• Try re-commissioning the device in the Matter integration

Enable debug logging for detailed information:

logger:
  default: info
  logs:
    custom_components.matter_time_sync: debug

🐛 Bug Fixes

• Fixed crash when device registry identifiers are not 2-tuples.

✨ New Features

• Added last_synced attribute to button entities (shows UTC timestamp of the last successful time sync)
• Added last_sync_result attribute to button entities (shows success or failed after each sync)
• Auto-sync now updates button entity attributes in real time (no need to press the button manually to see the latest sync status)
• Attributes are visible in Developer Tools → States, entity "More info" panel, and usable in templates/automations

🐛 Bug Fixes

• Fixed session/socket resource leak when WebSocket reconnects (old aiohttp.ClientSession and WebSocket were not properly closed before creating new ones in async_connect)
• Fixed unnecessary WebSocket round-trip on every sync (diagnostics async_get_time_sync_cluster_info call is now gated behind _LOGGER.isEnabledFor(logging.DEBUG) — only runs when debug logging is explicitly enabled)

🛠️ Improvements

• Reduced log noise: per-node detail logs moved from INFO to DEBUG level (summaries remain at INFO, full details available when debug logging is enabled)
• Reduced log noise: skipped device lists moved from INFO to DEBUG level
• Added entity_map in hass.data for efficient node-to-entity lookup during auto-sync
• Added _update_entity_sync_status helper in coordinator for safe, exception-protected entity updates
• Button entities now call async_write_ha_state() immediately after sync to update the HA UI in real time

✨ New Features

• Buttons now attach to existing Matter devices (Sync Time buttons appear under your existing Matter devices instead of creating standalone devices)
• Added “Filter target” option (match device filter against Any, Display name, HA name only, or Matter product/label)
• Added translation support for the filter target option (English, French, German, Czech)

🐛 Bug Fixes

• Fixed orphaned entities when changing/removing device filters (button entities are properly removed on reload)

🛠️ Improvements

• Centralized and shared filter logic in coordinator.py (used by both button.py entity creation and auto-sync bulk process)
• Improved Matter device lookup (uses standard deviceid_--MatterNodeDevice identifier, with hex matching and regex fallback)

✨ New Features

• Added automatic timezone detection from Home Assistant
• Added friendly name support for buttons

🐛 Bug Fixes

• Fixed connection stability during concurrent auto-syncs
• Fixed command retry and reconnection logic
• Fixed internal locking issues during concurrent syncs
• Fixed detection and validation for endpoint 0
• Fixed device filtering for spaces and uppercase letters
• Fixed service reliability after disconnections
• Fixed node ID matching for similar IDs
• Fixed Python compatibility for versions 3.9+
• Fixed deprecated asyncio API usage
• Fixed timeout handling during setup

🛠️ Improvements

• Added automatic resource cleanup for removed devices
• Improved handling of unexpected server messages
• Fixed duplicate service registration on reload
• Added multi-instance support for service calls
• Improved code efficiency and cleanliness
• Improved compatibility with standard platform enums

• Fixed autosync
• Improved time sync

• Added support for the new Matter Server payload format (camelCase) while maintaining backward compatibility
• Added a cooldown/debounce (with concurrency lock) to prevent repeated time-sync requests from rapid clicks

• Fixed DST Offset

• Added automatic device discovery during auto-sync
• Added Time Sync cluster detection
• Added device filter option
• Added "Only Time Sync devices" option
• Added button entities for each device
• Added refresh_devices service
• Added sync_all service
• Added timezone selection dropdown
• Added configurable auto-sync intervals (15 min to 24 hours)
• Added complete German and English translations
• Fixed device naming (unique entity names)
• Fixed attribute parsing for Matter Server

• Initial stable release
• Basic time synchronization via service calls
• WebSocket communication with Matter Server
• UI configuration support