TimeSynchronization Cluster

Cluster ID: 0x0038  |  Endpoint: Fixed on Endpoint 0 (Root Endpoint)

TimeSynchronization handles Matter device time management — telling the device "what time is it," "what timezone," and "is there daylight saving time." Many features depend on accurate time: scheduled automations, log timestamps, certificate validity checks, energy statistics, etc. Without time synchronization, these features either won't work or will produce incorrect results.

Commands

TimeSynchronization Cluster has 5 request commands, with SetTimeZone having a corresponding response command. The most basic SetUTCTime is supported by all devices; other commands require the device to enable the corresponding Feature. Click a command ID in the table below to jump to its detailed description.

SetUTCTime — Set UTC Time (0x00)

Directly sets the device's UTC time. This is the most basic time setting method — during commissioning, the Commissioner typically uses this command to inject the current time into the device. Upon receiving it, the device updates both Granularity and TimeSource attributes.

↑ Back to Commands

SetTrustedTimeSource — Set Trusted Time Source (0x01)

Specifies a node within the Fabric as a trusted time source. The device will periodically synchronize time from this node, similar to a local network "time authority." Setting to null clears the trusted time source.

TrustedTimeSource Struct

↑ Back to Commands

SetTimeZone — Set Timezone (0x02)

Sets the device's timezone list. Can contain multiple timezone entries, each with an effective time (validAt), to support historical or future timezone changes. After successful processing, the device returns SetTimeZoneResponse, informing the Commissioner whether DST offset setting is needed next.

TimeZoneStruct Struct

SetTimeZoneResponse Response Fields

↑ Back to Commands

SetDSTOffset — Set DST Offset (0x04)

Sets the daylight saving time (DST) offset list. Each entry defines an additional offset within a time range. The device matches entries based on current time and adds the offset on top of the timezone offset to calculate local time.

DSTOffsetStruct Struct

↑ Back to Commands

SetDefaultNTP — Set Default NTP Server (0x05)

Sets the default NTP server address for device time synchronization. Requires the device to have NTPC (NTP client) feature enabled. Set to null to clear the default NTP server.

↑ Back to Commands

Attributes

TimeSynchronization Cluster has 13 application attributes. Click an attribute ID in the summary table below to jump to its detailed description.

Time Status (0x0000 ~ 0x0002)

Describes the device's current time value and its precision and source.

↑ Back to Attributes

Time Source Configuration (0x0003, 0x0004)

Describes the device's time synchronization source — where precise time is obtained from.

↑ Back to Attributes

Timezone and DST (0x0005 ~ 0x0007)

Manages timezone configuration, DST offsets, and local time calculation. Requires the device to have TZ feature enabled.

↑ Back to Attributes

Capabilities and Limits (0x0008 ~ 0x000C)

Describes the device's capability limits and hardware characteristics for time synchronization. Most of these attributes are read-only, determined by device firmware.

↑ Back to Attributes

Feature Bitmap

TimeSynchronization Cluster declares device time synchronization capabilities through FeatureMap (0xFFFC):

Enum Definitions

GranularityEnum

Describes the device's current time precision level. Higher precision indicates a more reliable time source.

TimeSourceEnum

Identifies the source of the device's current time. Higher values typically indicate a more reliable time source. The NTS suffix indicates Network Time Security authentication was used.

TimeZoneDatabaseEnum

Describes the device's built-in timezone database capability, determining whether the device can calculate DST rules on its own.

Events

TimeSynchronization Cluster defines 5 events to notify the Commissioner or automation systems of time status changes.

Example Data

Attribute Data Example

Below is typical attribute data from a TimeSynchronization Cluster of a smart light (China region) supporting TZ + NTPC:

{
  // --- Time Status ---
  "0x0000": 1695312000000000,    // UTCTime = 2023-09-21T16:00:00Z (microsecond-level epoch)
  "0x0001": 3,                   // Granularity = MillisecondsGranularity
  "0x0002": 7,                   // TimeSource = MatterNTP

  // --- Trusted Time Source ---
  "0x0003": {                    // TrustedTimeSource
    "fabricIndex": 1,
    "nodeID": "0x0000000000000001",
    "endpoint": 0
  },
  "0x0004": "pool.ntp.org",      // DefaultNTP

  // --- Timezone & DST ---
  "0x0005": [{                   // TimeZone
    "offset": 28800,             //   UTC+8 (seconds)
    "validAt": 0,
    "name": "Asia/Shanghai"
  }],
  "0x0006": [{                   // DSTOffset
    "offset": 0,                 //   No DST
    "validStarting": 0,
    "validUntil": null
  }],

  // --- Local Time ---
  "0x0007": 1695340800000000,    // LocalTime (timezone offset applied)

  // --- Capabilities & Limits ---
  "0x0008": 1,                   // TimeZoneDatabase = Full
  "0x0009": false,               // NTPServerAvailable = false
  "0x000A": 2,                   // TimeZoneListMaxSize = 2
  "0x000B": 2,                   // DSTOffsetListMaxSize = 2
  "0x000C": true                 // SupportsDNSResolve = true
}

SetUTCTime Interaction Example

Commissioner sets initial time for the device after commissioning:

// Commissioner → Device: Set UTC time
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0038",
      "commandId": "0x00"            // SetUTCTime
    },
    "commandFields": {
      "UTCTime": 1695312000000000,   // 2023-09-21T16:00:00Z (microseconds)
      "granularity": 3,              // MillisecondsGranularity
      "timeSource": 2                // Admin
    }
  }]
}

SetTimeZone Interaction Example

Setting the China timezone (UTC+8) for the device:

// Commissioner → Device: Set timezone
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0038",
      "commandId": "0x02"            // SetTimeZone
    },
    "commandFields": {
      "timeZone": [{
        "offset": 28800,             // UTC+8 (seconds)
        "validAt": 0,                // Effective immediately
        "name": "Asia/Shanghai"      // IANA timezone name (optional)
      }]
    }
  }]
}

// Device → Commissioner: Confirm timezone setting
{
  "DSTOffsetRequired": true          // Need to follow up with DST offset setting
}

Common Scenarios