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

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.

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-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

Apollon77 · 2026-04-09T11:07:29Z

Sooo, we had a discussion yesterday because we should know if the host is synced time wise:

add a commandline/ENV-var option to enable time sync (because server is considered) synced
Any only ten enable it here
The HA app/addon should check the above mentioned supervisor ntp information and set this cli flag accordingly

markvp · 2026-04-11T09:21:20Z

@Apollon77 do you want me to work on this or do you want to close it. IF you want me to work on it, please let me know what you would like me to do / not do.

Apollon77 · 2026-04-11T12:05:46Z

Give all my comments to your AI and I guess he can work with it. If you like feel free to continue. If now I will take it over somewhen ;-)

codersaur · 2026-05-01T11:00:52Z

Would be great to get this one finally over the line. FWIW, having an ENV var to enable the time sync would work for me.

markvp · 2026-05-03T02:17:14Z

Review addressed

All feedback from @Apollon77 and @copilot-pull-request-reviewer has been incorporated in the latest commit. Summary of changes:

New: --enable-time-sync opt-in flag

Added --enable-time-sync CLI flag and ENABLE_TIME_SYNC env var (default: off). Time sync must only be enabled when the host's NTP is reliable.

New: NodeProcessor abstract base class

Extracted shared timer lifecycle, node registration, and per-node processing loop into NodeProcessor. Both TimeSyncManager and CustomClusterPoller now extend it, eliminating ~80 lines of duplication in each.

TimeSyncManager changes

Resync interval: Hours(24) (was 12 * 60 * 60 * 1000 with _MS naming)
Startup window: Minutes(30) + Math.random() * Minutes(30) (was random 0–60s)
Startup protection: #startupComplete flag blocks immediate syncs until the first periodic cycle fires; only then do reconnects trigger an immediate sync
In-flight dedup: #inFlightSyncs: Map<NodeId, Promise<void>> — syncNode() is a no-op if a sync is already running for that node
Async stop(): cancels delay, stops timer, then await Promise.allSettled(inFlightSyncs) before clearing
handleEvent() removed — caller now calls syncNode() directly

ControllerCommandHandler changes

ObserverGroup per node: all node.events.* subscriptions are registered in a per-node ObserverGroup, closed on decommission and on manager stop
eventTriggered handler filters directly by TIME_SYNC_CLUSTER_ID + TIME_FAILURE_EVENT_ID before calling syncNode()
Note: node.eventsOf(TimeSynchronizationClient) is not used because @matter/node is not a dependency of ws-controller; cluster/event ID filtering achieves the same result
Time.nowMs replaces Date.now()

Tests rewritten

Tests now cover: startup protection, immediate sync after completeStartup(), in-flight deduplication, post-unregister/post-stop guards, error resilience

markvp · 2026-05-06T13:47:50Z

@Apollon77 please can you confirm if my updates address all your concerns or if there are any other changes required? thanks for your patience while I try to get this right :)

Apollon77 · 2026-05-06T13:55:47Z

@markvp Yes I have seen the updates and did not had time so far to review.

markvp · 2026-05-30T22:18:19Z

This has been open for 2 months now. I've addressed all your requests and changes.

What is the issue?

Apollon77 · 2026-05-31T17:10:10Z

My last comment is 3 weeks ago and in that time I had a week vacation and the current priority is to have a stable server baseline for the official release. New features like this I will focus on once everything is stable for the official release. Just be patient please

Apollon77 · 2026-06-11T08:26:07Z

Will continue once the new matter server is released and stable, I want to keep changes low currently to be able to do bugfixes without bigger changes

Apollon77 · 2026-06-24T09:46:16Z

@markvp Ok now we can continue. Could you please rebase on current changes? Thanks a lot

…n cluster Introduces opt-in time synchronization via --enable-time-sync / ENABLE_TIME_SYNC. Adds NodeProcessor abstract base class for timer-driven periodic node processing, and TimeSyncManager which extends it to sync UTC time using PeerAddress (matching the CustomClusterPoller upstream migration). Syncs on reconnect after startup window and periodically every 24 hours. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…rClientByIdFor Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Eliminates duplicated timer/loop boilerplate (~50 lines) by extending the shared NodeProcessor abstraction. Per-node attribute paths stay in the subclass; shouldProcess, processNode, and onCycleComplete implement the polling logic. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Tests cover: registration (startup window guard, connectivity check, cluster detection), syncNode (immediate fire, deduplication, in-flight tracking), unregisterNode, periodic resync via NodeProcessor timer (startup delay, 24h cycle, skip disconnected/in-flight peers), and stop() awaiting in-flight syncs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Math.random() produces a float; @matter/testing's MockTimer requires integer milliseconds and throws on fractional values. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

markvp · 2026-06-25T03:44:28Z

@markvp Ok now we can continue. Could you please rebase on current changes? Thanks a lot

done. tests are being blocked by your "request changes".

Apollon77

makes sense ... I proposed some smaller changes ...

the only detail we need to find out is how we get this parameter set by the integration and how we handle it when fresh-starting the server where the time might not be synced already

Cache #peerOf(nodeId) in a local variable at all three call sites where both customClusterPoller and timeSyncManager receive the same peer, avoiding a redundant call. Simplify hasTimeSyncCluster to a direct attribute key lookup on the Granularity attribute (0/56/1) rather than iterating all keys. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ute 0 The hasTimeSyncCluster implementation now checks specifically for the mandatory Granularity attribute (ID 1) on endpoint 0, rather than any attribute from the cluster. Update test fixtures and assertions to match: makeTimeSyncAttrs uses attribute 1, and the 'any attribute index' test is replaced with a test that confirms non-Granularity attributes return false. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

markvp · 2026-06-28T05:14:52Z

Companion add-on PR submitted to wire up the --enable-time-sync flag from the HA side: home-assistant/addons#4685

That PR adds an enable_time_sync option to the add-on config (default: off). When enabled, the startup script checks NTP sync state via the Supervisor API and logs a warning if the host clock isn't yet synchronised before passing the flag to the server.

This way the responsibility for ensuring that the time is actually in sync, or waiting until the time is in sync, lies with the "user" - for HA this is the HA-Addon. If installing this independently, it's the environment in which you install it.

Add an enable_time_sync boolean option (default false). When enabled, the startup script passes --enable-time-sync to the Matter Server so it pushes the current time to commissioned Matter devices. Before passing the flag, the script checks host NTP sync state via the Supervisor API (GET /supervisor/info, field ntp_synchronized) and logs an advisory warning if the host clock is not synchronised. The warning does not gate the feature, since the time sent to devices is only as accurate as the host clock. The --enable-time-sync flag is only passed when the running Matter Server is new enough to support it (>= 1.2.0). The server uses commander, which exits on unknown options, so on older builds the flag is skipped with a warning rather than breaking startup. Companion to the server-side flag in matter-js/matterjs-server#440. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a time_sync option (auto/on/off, default auto) controlling whether the Matter Server pushes the current time to nodes with the TimeSynchronization cluster, via the server's --enable-time-sync flag. - auto (default): enable only when the host clock is NTP synchronised, as reported by the Supervisor API (GET /supervisor/info, ntp_synchronized). - on: always enable, logging a warning if the host clock is not NTP synchronised, since the time sent to devices is only as accurate as the host clock. - off: leave disabled. The --enable-time-sync flag is only passed when the running Matter Server is new enough to support it (>= 1.2.0). The server uses commander, which exits on unknown options, so on older builds the flag is skipped with a warning rather than breaking startup. Companion to the server-side flag in matter-js/matterjs-server#440. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

Closed

21 tasks

Apollon77 requested changes Mar 24, 2026

View reviewed changes

markvp force-pushed the feat/245-time-sync branch from bf8c31b to e72bf8d Compare May 3, 2026 03:14

markvp force-pushed the feat/245-time-sync branch from 04564d7 to 5f36f5b Compare May 16, 2026 06:09

satmandu mentioned this pull request Jun 8, 2026

“entity is no longer being provided by the matter_time_sync integration” error. Loweack/Matter-Time-Sync#56

Closed

markvp and others added 6 commits June 24, 2026 20:34

Fix #syncNodeTime to use invokeCommand instead of non-existent cluste…

3a34673

…rClientByIdFor Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: floor startup delay to integer ms to satisfy MockTimer

19e2120

Math.random() produces a float; @matter/testing's MockTimer requires integer milliseconds and throws on fractional values. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix import ordering in ControllerCommandHandler (oxfmt)

a9f9697

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

markvp force-pushed the feat/245-time-sync branch from 21d497c to a9f9697 Compare June 25, 2026 03:35

Apollon77 reviewed Jun 27, 2026

View reviewed changes

Comment thread packages/ws-controller/src/controller/ControllerCommandHandler.ts Outdated

Comment thread packages/ws-controller/src/controller/ControllerCommandHandler.ts Outdated

Comment thread packages/ws-controller/src/controller/TimeSyncManager.ts Outdated

markvp and others added 2 commits June 27, 2026 07:17

markvp mentioned this pull request Jun 28, 2026

Matter Server: add time_sync option (auto/on/off) home-assistant/addons#4685

Draft

13 tasks

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

piitaya commented Mar 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Apollon77 commented Mar 25, 2026

Uh oh!

agners commented Mar 25, 2026

Uh oh!

Apollon77 commented Apr 4, 2026

Uh oh!

Apollon77 commented Apr 9, 2026

Uh oh!

markvp commented Apr 11, 2026

Uh oh!

Apollon77 commented Apr 11, 2026

Uh oh!

codersaur commented May 1, 2026

Uh oh!

markvp commented May 3, 2026

Review addressed

Uh oh!

markvp commented May 6, 2026

Uh oh!

Apollon77 commented May 6, 2026

Uh oh!

markvp commented May 30, 2026

Uh oh!

Apollon77 commented May 31, 2026

Uh oh!

Apollon77 commented Jun 11, 2026

Uh oh!

Apollon77 commented Jun 24, 2026

Uh oh!

markvp commented Jun 25, 2026

Uh oh!

Apollon77 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

markvp commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

markvp commented Jun 28, 2026 •

edited

Loading