Add TimeSync support for nodes with TimeSynchronization cluster by markvp · Pull Request #440 · matter-js/matterjs-server

markvp · 2026-03-24T11:12:28Z

Summary

Adds TimeSyncManager that proactively syncs UTC time on nodes with the TimeSynchronization cluster (0x38)
Syncs time on three triggers: node connect/reconnect (immediate), timeFailure event (reactive), and periodic resync every 12 hours
Follows the existing CustomClusterPoller pattern for consistency

Context

Devices like IKEA ALPSTUGA lack battery backup and lose their time after power loss. The controller previously only set time during commissioning, causing timeSynchronization.timeFailure events after reconnection.

The setUtcTime command is sent with MillisecondsGranularity and TimeSource.Admin. TlvEpochUs handles automatic conversion from Unix epoch to Matter epoch (2000-01-01).

Changes

New: packages/ws-controller/src/controller/TimeSyncManager.ts — TimeSyncManager class and hasTimeSyncCluster() utility
New: packages/ws-controller/test/controller/TimeSyncManagerTest.ts — 12 unit tests
New: packages/ws-controller/test/tsconfig.json — enables test compilation for ws-controller
Modified: packages/ws-controller/src/controller/ControllerCommandHandler.ts — integrates TimeSyncManager at all lifecycle points
Modified: packages/ws-controller/tsconfig.json — adds test reference

Test plan

npm run format passes
npm run lint passes (0 warnings, 0 errors)
npm run build passes (including test type validation)
npm test — all 12 ws-controller unit tests pass
Manual test: commission an ALPSTUGA, power-cycle it, verify time sync on reconnect

Closes #245

🤖 Generated with Claude Code

…n cluster Devices like IKEA ALPSTUGA lack battery backup and lose their time after power loss. The controller now proactively syncs time on three triggers: 1. Node connects/reconnects (immediate) 2. timeFailure event from the node (reactive) 3. Periodic resync every 12 hours Closes matter-js#245 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds proactive UTC time synchronization for Matter nodes that implement the TimeSynchronization cluster, ensuring devices that lose time after power loss are resynced on reconnect, on timeFailure, and periodically.

Changes:

Introduce TimeSyncManager with cluster detection and periodic resync scheduling
Integrate TimeSyncManager into controller lifecycle (connect, events, removal, close)
Add ws-controller test compilation config and unit tests for sync triggers

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/ws-controller/tsconfig.json	Adds test project reference so ws-controller tests are typechecked/compiled.
packages/ws-controller/test/tsconfig.json	New tsconfig for ws-controller tests, wiring in shared test settings and references.
packages/ws-controller/test/controller/TimeSyncManagerTest.ts	New unit tests for cluster detection + immediate/reactive sync behavior.
packages/ws-controller/src/controller/TimeSyncManager.ts	Implements the TimeSyncManager (register/unregister, event-driven sync, periodic resync).
packages/ws-controller/src/controller/ControllerCommandHandler.ts	Wires TimeSyncManager into node lifecycle/events and adds setUtcTime command sender.

Copilot · 2026-03-24T11:19:15Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+    handleEvent(nodeId: NodeId, data: DecodedEventReportValue<any>): void {
+        const { path } = data;
+        if (path.clusterId === TIME_SYNC_CLUSTER_ID && path.eventId === TIME_FAILURE_EVENT_ID) {
+            logger.info(`Received timeFailure event from node ${nodeId}, syncing time`);
+            this.#syncNode(nodeId);
+        }
+    }


This logs syncing time even when the manager is stopped or the node isn’t registered/connected (since #syncNode will early-return). Consider guarding here (e.g., check this.#closed, this.#registeredNodes.has(nodeId), and optionally this.#connector.nodeConnected(nodeId)) before logging, or have #syncNode return a boolean indicating whether a sync was actually attempted so the log reflects reality.

Copilot · 2026-03-24T11:19:16Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+        let syncedNodes = 0;
+        try {
+            const nodes = Array.from(this.#registeredNodes);
+            for (let i = 0; i < nodes.length; i++) {
+                const nodeId = nodes[i];
+                if (!this.#registeredNodes.has(nodeId)) {
+                    continue;
+                }
+                if (!this.#connector.nodeConnected(nodeId)) {
+                    continue;
+                }
+                syncedNodes++;
+                try {
+                    await this.#connector.syncTime(nodeId);
+                    logger.info(`Periodic resync: synced time on node ${nodeId}`);
+                } catch (error) {
+                    logger.warn(`Periodic resync: failed to sync time on node ${nodeId}:`, error);
+                }


syncedNodes is incremented before syncTime succeeds, but later the summary log says synced ${syncedNodes} nodes, which will over-report when there are failures. Track separate counters (e.g., attempted vs succeeded) or increment only after a successful await this.#connector.syncTime(nodeId) to keep the summary accurate.

Copilot · 2026-03-24T11:19:16Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+                }
+                // Small delay between nodes to avoid overwhelming the network
+                if (i < nodes.length - 1) {
+                    this.#currentDelayPromise = Time.sleep("sleep", Millis(2_000)).finally(() => {


The timer/sleep label \"sleep\" is very generic and makes diagnostics harder (and can be ambiguous if the underlying timer system uses names for tracing). Use a more specific name (e.g., \"time-sync-resync-delay\") so logs/traces clearly attribute these delays to TimeSyncManager.

Suggested change

this.#currentDelayPromise = Time.sleep("sleep", Millis(2_000)).finally(() => {

this.#currentDelayPromise = Time.sleep("time-sync-resync-delay", Millis(2_000)).finally(() => {

Copilot · 2026-03-24T11:19:16Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+    async #resyncAllNodes(): Promise<void> {
+        if (this.#isResyncing) {
+            return;
+        }
+
+        const targetInterval = Millis(RESYNC_INTERVAL_MS);
+        if (this.#resyncTimer.interval !== targetInterval) {
+            this.#resyncTimer.interval = targetInterval;
+        }
+
+        this.#isResyncing = true;
+
+        let syncedNodes = 0;
+        try {
+            const nodes = Array.from(this.#registeredNodes);
+            for (let i = 0; i < nodes.length; i++) {
+                const nodeId = nodes[i];
+                if (!this.#registeredNodes.has(nodeId)) {
+                    continue;
+                }
+                if (!this.#connector.nodeConnected(nodeId)) {
+                    continue;
+                }
+                syncedNodes++;
+                try {
+                    await this.#connector.syncTime(nodeId);
+                    logger.info(`Periodic resync: synced time on node ${nodeId}`);
+                } catch (error) {
+                    logger.warn(`Periodic resync: failed to sync time on node ${nodeId}:`, error);
+                }
+                // Small delay between nodes to avoid overwhelming the network
+                if (i < nodes.length - 1) {
+                    this.#currentDelayPromise = Time.sleep("sleep", Millis(2_000)).finally(() => {
+                        this.#currentDelayPromise = undefined;
+                    });
+                    await this.#currentDelayPromise;
+                }
+            }
+        } finally {
+            this.#isResyncing = false;
+            this.#scheduleResync();
+        }
+        if (syncedNodes > 0) {
+            logger.info(
+                `Periodic resync complete: synced ${syncedNodes} nodes. Next resync in ${Duration.format(this.#resyncTimer.interval)}`,
+            );
+        }
+    }


The PR adds significant periodic-resync behavior (interval adjustment, node iteration with inter-node delay, error handling, and rescheduling in finally), but the new unit tests don’t appear to cover this path. Add tests using fake timers to validate: (1) resync timer scheduling is started only when nodes are registered, (2) stop() cancels any in-flight delay and prevents further resync, (3) per-node delay is applied between nodes, and (4) failures don’t prevent remaining nodes from being processed/rescheduled.

piitaya · 2026-03-24T12:13:20Z

How will it work when multiple matter controller wants to sync time. For example, if I connected my IKEA ALPSTUGA to 2 matters server with different time. I know it's an edge case but we have concurrency issue because each control may have different logic to sync time.

Apollon77 · 2026-03-24T11:45:20Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+     */
+    handleEvent(nodeId: NodeId, data: DecodedEventReportValue<any>): void {
+        const { path } = data;
+        if (path.clusterId === TIME_SYNC_CLUSTER_ID && path.eventId === TIME_FAILURE_EVENT_ID) {


The event can also be received because of the update on a reconnect so we need to ensure we do not execute the sync to often in parallel or such

Also see above directly subscribe to the event and not check any triggered event. thats too inefficient

Apollon77 · 2026-03-24T11:47:09Z

packages/ws-controller/src/controller/ControllerCommandHandler.ts

+    /**
+     * Send a setUtcTime command to a node's TimeSynchronization cluster.
+     */
+    async #syncNodeTime(nodeId: NodeId): Promise<void> {


I think thats more needed for it ... check home-assistant/core#166133 which basically implements anything correctly ... and we might also need a trigger on DST changes?

Apollon77 · 2026-03-24T11:50:34Z

packages/ws-controller/src/controller/ControllerCommandHandler.ts

+    async #syncNodeTime(nodeId: NodeId): Promise<void> {
+        const client = this.#nodes.clusterClientByIdFor(nodeId, EndpointNumber(0), TimeSynchronization.Cluster.id);
+        await client.commands.setUtcTime({
+            utcTime: Date.now() * 1000,


we have matter.js Time.nowMs that can be used here

Apollon77 · 2026-03-24T11:52:56Z

packages/ws-controller/src/controller/ControllerCommandHandler.ts

-        node.events.eventTriggered.on(data => this.events.eventChanged.emit(nodeId, data));
+        node.events.eventTriggered.on(data => {
+            this.events.eventChanged.emit(nodeId, data);
+            this.#timeSyncManager.handleEvent(nodeId, data);


if we only care about one event then it is better to subscribe for this one event using node.eventsOf(TimeSynchronizationClient).xxy.on(...) and add this to an ObserverGroup to clean up on close

Apollon77 · 2026-03-24T11:58:09Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+ * Syncs UTC time on three triggers:
+ * 1. Node connects/reconnects (immediate)
+ * 2. timeFailure event from the node (reactive)
+ * 3. Periodic resync every 12 hours


i think 24h is sufficient because it is an intermediate solution anyway

Apollon77 · 2026-03-24T11:59:14Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+const RESYNC_INTERVAL_MS = 12 * 60 * 60 * 1000;
+
+// Maximum initial delay in milliseconds (random 0-60s to stagger startup)
+const MAX_INITIAL_DELAY_MS = 60_000;


Use "Seconds(60)" and also no _MS and better use 30-60mins because we need to ensure to not add additional traffic while the server tries to connect all nodes initially ... we have a bit of time when we do all this normally. We should also prevent initial "hey i connected" triggers from being executed while we startup ...

Apollon77 · 2026-03-24T12:02:30Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+        }
+
+        // Sync time immediately on connect/reconnect
+        this.#syncNode(nodeId);


see above: we need an initial startup protection delay!

Apollon77 · 2026-03-24T12:04:56Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+     */
+    stop(): void {
+        this.#closed = true;
+        this.#currentDelayPromise?.cancel(new Error("Close"));


we should track the current "time sync promise" and await this here if any is in progress and so make this async to have a clean stop

Apollon77 · 2026-03-24T12:08:01Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+            logger.debug(`Node ${nodeId} not connected, skipping time sync`);
+            return;
+        }
+        this.#connector.syncTime(nodeId).then(


as said above. track that promise and cleanup so that we can await it on close and it is not hidden

Apollon77 · 2026-03-24T12:13:51Z

packages/ws-controller/src/controller/TimeSyncManager.ts

+/**
+ * Manages time synchronization for nodes with the TimeSynchronization cluster.
+ */
+export class TimeSyncManager {


the whole class adds a lot of code duplication with the CustomClusterPoller.ts ... because this is done by AI anyway please refactor to use a common "NodeProcessor" class as basis and try to streamline the two use cases as sub classes

Apollon77 · 2026-03-25T11:43:38Z

@piitaya I completely agree :-) Thats why also the real official solution is a bit more effort :-) ... and I need to real all spec on it

agners · 2026-03-25T14:20:42Z

@piitaya I completely agree :-) Thats why also the real official solution is a bit more effort :-) ... and I need to real all spec on it

In Home Assistant the Supervisor exposes if the time go synchronized through NTP (see /supervisor/info endpoint in the Supervisor developer docs). I'd only sync time if that is true, since otherwise a freshly started Raspberry Pi (which has no RTC) may sync a wrong time to devices after power outage 🥶 ).

Currently we don't have an event when synchronization state changes 😢 . So we'd probably have to poll the flag for a while if it is false on startup.

Apollon77 · 2026-04-04T16:26:47Z

Ok, so from what I get ... the interestung question is how to determine IF a host time is synced with any relevant source and so a valid source for it ... and when that happened ... that's maybe a tough one

Copilot AI review requested due to automatic review settings March 24, 2026 11:12

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Apollon77 mentioned this pull request Mar 24, 2026

Add time sync button to Matter integration home-assistant/core#166133

Open

21 tasks

Apollon77 requested changes Mar 24, 2026

View reviewed changes

	this.#currentDelayPromise = Time.sleep("sleep", Millis(2_000)).finally(() => {
	this.#currentDelayPromise = Time.sleep("time-sync-resync-delay", Millis(2_000)).finally(() => {

Conversation

markvp commented Mar 24, 2026

Summary

Context

Changes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

piitaya commented Mar 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Apollon77 commented Mar 25, 2026

Uh oh!

agners commented Mar 25, 2026

Uh oh!

Apollon77 commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants