Implement Matter Time Synchronization support for the Nano Matter

Author: silabs-bozont

boards.txt

@@ -0,0 +1,124 @@
+/*
+   Matter Time Synchronization example
+
+   The example shows how to receive UTC time (and timezone / DST offsets) from a
+   Matter controller and read them as Unix timestamps using the Arduino Matter
+   API.
+
+   The Time Synchronization cluster is enabled on the root endpoint. After the
+   device is commissioned, a Matter hub that supports time sync (or chip-tool
+   SetUTCTime / SetTimeZone / SetDSTOffset) can set the device clock. The sketch
+   waits until time is available, then prints UTC and local timestamps.
+
+   Compatible boards:
+   - Arduino Nano Matter
+
+   Author: Tamas Jozsi (Silicon Labs)
+ */
+#include <Matter.h>
+#include <MatterTemperature.h>
+#include <MatterTimeSynchronization.h>
+
+MatterTemperature matter_temp_sensor;
+MatterTimeSynchronization matter_time;
+
+void print_date_time(const char* label, uint32_t unix_time);
+
+void on_time_updated()
+{
+  Serial.println("Matter time updated");
+}
+
+void on_timezone_updated()
+{
+  Serial.println("Matter timezone updated");
+}
+
+void setup()
+{
+  Serial.begin(115200);
+  Matter.begin();
+  matter_temp_sensor.begin();
+  matter_time.begin();
+  matter_time.set_time_update_callback(on_time_updated);
+  matter_time.set_timezone_update_callback(on_timezone_updated);
+
+  Serial.println("Matter Time Synchronization");
+
+  if (!Matter.isDeviceCommissioned()) {
+    Serial.println("Matter device is not commissioned");
+    Serial.println("Commission it to your Matter hub with the manual pairing code or QR code");
+    Serial.printf("Manual pairing code: %s\n", Matter.getManualPairingCode().c_str());
+    Serial.printf("QR code URL: %s\n", Matter.getOnboardingQRCodeUrl().c_str());
+  }
+  while (!Matter.isDeviceCommissioned()) {
+    delay(200);
+  }
+
+  Serial.println("Waiting for Thread network...");
+  while (!Matter.isDeviceThreadConnected()) {
+    delay(200);
+  }
+  Serial.println("Connected to Thread network");
+
+  Serial.println("Waiting for Matter device discovery...");
+  while (!matter_temp_sensor.is_online()) {
+    delay(200);
+  }
+  Serial.println("Matter device is now online");
+
+  matter_time.request_time();
+  Serial.println("Waiting for Matter controller time synchronization...");
+  uint32_t time_request_cnt = 0u;
+  while (!matter_time.has_time()) {
+    delay(1000);
+    time_request_cnt++;
+    if (time_request_cnt % 60 == 0) {
+      Serial.println("Re-requesting time from controller...");
+      matter_time.request_time();
+    }
+  }
+  Serial.printf("Time synchronized - Unix UTC: %lu\n", matter_time.get_unix_time());
+  print_date_time("UTC time", matter_time.get_unix_time());
+  if (matter_time.has_timezone()) {
+    Serial.printf("Local offset: %ld s\n", matter_time.get_local_offset_seconds());
+    print_date_time("Local time", matter_time.get_local_unix_time());
+  }
+  Serial.println("-----");
+}
+
+void loop()
+{
+  float current_cpu_temp = getCPUTemp();
+  matter_temp_sensor.set_measured_value_celsius(current_cpu_temp);
+
+  if (!matter_time.has_time()) {
+    delay(1000);
+    return;
+  }
+
+  if (matter_time.has_timezone()) {
+    Serial.printf("Local Unix time: %lu | CPU temp: %.02f C\n", matter_time.get_local_unix_time(), current_cpu_temp);
+    print_date_time("Local time", matter_time.get_local_unix_time());
+  } else {
+    Serial.printf("UTC Unix time: %lu | CPU temp: %.02f C\n", matter_time.get_unix_time(), current_cpu_temp);
+    print_date_time("UTC time", matter_time.get_unix_time());
+  }
+  Serial.println("-----");
+  delay(1000);
+}
+
+void print_date_time(const char* label, uint32_t unix_time)
+{
+  time_t timestamp = static_cast<time_t>(unix_time);
+  tm* time_info = gmtime(&timestamp);
+  char formatted_time[32];
+
+  if (time_info == nullptr || strftime(formatted_time, sizeof(formatted_time), "%Y-%m-%d %H:%M:%S", time_info) == 0) {
+    return;
+  }
+
+  Serial.print(label);
+  Serial.print(": ");
+  Serial.println(formatted_time);
+}

libraries/Matter/examples/matter_time_sync/matter_time_sync.ino

@@ -482,6 +482,105 @@ Class for creating and controlling a Matter Power Source appliance with battery
 
 ```void set_system_mode(thermostat_mode_t system_mode);```
 
+## class MatterTimeSynchronization
+
+Receives UTC time (and optional timezone / DST offsets) from a Matter controller via the Time Synchronization cluster on the root endpoint (not a bridged appliance). Currently enabled for Arduino Nano Matter.
+
+The device does not pull time by itself. A Matter controller that supports time sync must push `SetUTCTime` (and, when the TimeZone feature is advertised, `SetTimeZone` / `SetDSTOffset`). Use `request_time()` to emit a `TimeFailure` event so a supporting controller can push time again.
+
+### Enabling time sync in Home Assistant
+
+Requires Matter Server **1.2.0+** (Home Assistant Matter Server app **9.1.0+**).
+
+#### Home Assistant OS / Supervised (Matter Server add-on)
+
+1. Open **Settings → Add-ons → Matter Server → Configuration**.
+2. Set **`time_sync`** to one of:
+   - `auto` (default) — enable only when the host clock is NTP synchronized
+   - `on` — always enable (use this if sync never starts under `auto`)
+   - `off` — disable time sync
+3. Ensure Home Assistant’s timezone is set correctly under **Settings → System → General** (the add-on uses the host timezone for `SetTimeZone` / DST).
+4. Save and **restart** the Matter Server add-on.
+
+#### Standalone Docker / Docker Compose (`ghcr.io/matter-js/matterjs-server`)
+
+Time sync is **off by default** in the container image. Enable it with environment variables:
+
+```yaml
+services:
+  matterjs-server:
+    image: ghcr.io/matter-js/matterjs-server:stable
+    network_mode: host
+    restart: unless-stopped
+    volumes:
+      - "${HOME}/.matterjs-server:/data"
+    environment:
+      ENABLE_TIME_SYNC: "true"
+      TZ: "Europe/Budapest"   # IANA zone; required for correct local offsets
+```
+
+Or with `docker run`:
+
+```bash
+docker run -d \
+  --name matterjs-server \
+  --restart=unless-stopped \
+  --network=host \
+  -v ${HOME}/.matterjs-server:/data \
+  -e ENABLE_TIME_SYNC=true \
+  -e TZ=Europe/Budapest \
+  ghcr.io/matter-js/matterjs-server:stable
+```
+
+After changing `TZ` / `ENABLE_TIME_SYNC`, recreate the container so the environment is applied (`docker compose up -d --force-recreate`). Verify inside the container:
+
+```bash
+docker exec matterjs-server sh -c 'echo TZ=$TZ; date; node -e "console.log(Intl.DateTimeFormat().resolvedOptions().timeZone)"'
+```
+
+`TZ` must be non-empty and resolve to your IANA zone (not `UTC`), or timezone/DST offsets pushed to the device will be zero.
+
+#### Notes
+
+- After a device reflash/reboot, some Matter Server versions may skip re-sync for up to 24 hours (cooldown). Restarting the Matter Server clears that state. See [matter-js/matterjs-server#938](https://github.com/matter-js/matterjs-server/issues/938).
+- In Matter Server logs, a successful push looks like `timeSynchronization.setUtcTime` (and `setTimeZone` / `setDstOffset` when timezone is supported) with `status: Success`.
+
+```bool request_time();```
+Emits a `TimeFailure` event on the root endpoint so a supporting controller can push time again. Rate-limited to once per 60 seconds. Returns `false` if skipped by the rate limit or if logging fails. Controllers may still ignore the event during their own cooldown windows.
+
+```bool has_time();```
+Returns whether a valid wall-clock time is available.
+
+```uint32_t get_unix_time();```
+Returns seconds since 1970-01-01 UTC, or 0 if time is not available.
+
+```uint64_t get_unix_time_millis();```
+Returns milliseconds since 1970-01-01 UTC, or 0 if time is not available.
+
+```bool has_timezone();```
+Returns whether the controller has set a timezone via `SetTimeZone`.
+
+```int32_t get_timezone_offset_seconds();```
+Returns the active timezone base offset in seconds east of UTC (excluding DST), or 0 if unavailable.
+
+```int32_t get_dst_offset_seconds();```
+Returns the currently applicable DST offset in seconds, or 0 if unavailable / not in DST.
+
+```int32_t get_local_offset_seconds();```
+Returns timezone + DST offset in seconds east of UTC.
+
+```uint32_t get_local_unix_time();```
+Returns local Unix time in seconds (UTC + offsets). If timezone is not set yet, returns UTC.
+
+```uint64_t get_local_unix_time_millis();```
+Returns local Unix time in milliseconds (UTC + offsets). If timezone is not set yet, returns UTC.
+
+```void set_time_update_callback(void (*cb)(void));```
+Sets a callback invoked when UTC time becomes available or is updated by the controller.
+
+```void set_timezone_update_callback(void (*cb)(void));```
+Sets a callback invoked when the timezone list is updated by the controller.
+
 ## class MatterTVOC
 
 ```void set_measured_value(float value);```