时间同步 Cluster（TimeSynchronization）

Cluster ID: 0x0038  |  所在 Endpoint: 固定在 Endpoint 0（Root Endpoint）

TimeSynchronization 负责 Matter 设备的时间管理 —— 让设备知道「现在几点」「在哪个时区」「有没有夏令时」。 很多功能依赖准确的时间：定时自动化、日志时间戳、证书有效期校验、能源统计等。 没有时间同步，这些功能要么无法工作，要么会给出错误的结果。

命令（Commands）

TimeSynchronization Cluster 共有 5 个请求命令，其中 SetTimeZone 有对应的响应命令。 最基础的 SetUTCTime 所有设备都支持，其余命令需要设备启用对应的 Feature。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

SetUTCTime —— 设置 UTC 时间（0x00）

直接设置设备的 UTC 时间。这是最基础的时间设置方式 —— 在配网阶段，Commissioner 通常通过此命令为设备注入当前时间。 设备收到后会同时更新 Granularity 和 TimeSource 属性。

↑ 返回命令列表

SetTrustedTimeSource —— 设置可信时间源（0x01）

指定一个 Fabric 内的节点作为可信时间源。设备会周期性地从这个节点同步时间， 类似于局域网内部的「时间权威」。设置为 null 可清除可信时间源。

TrustedTimeSource 结构体

↑ 返回命令列表

SetTimeZone —— 设置时区（0x02）

设置设备的时区列表。可以包含多个时区条目，每个条目有生效时间（validAt）， 用于支持历史或未来的时区变更。设备处理成功后返回 SetTimeZoneResponse， 告知 Commissioner 是否需要继续设置夏令时偏移。

TimeZoneStruct 结构体

SetTimeZoneResponse 响应字段

↑ 返回命令列表

SetDSTOffset —— 设置夏令时偏移（0x04）

设置夏令时（DST）偏移列表。每个条目定义一段时间范围内的额外偏移量。 设备根据当前时间匹配对应的条目，将偏移量叠加到时区偏移上，得出本地时间。

DSTOffsetStruct 结构体

↑ 返回命令列表

SetDefaultNTP —— 设置默认 NTP 服务器（0x05）

设置设备用于时间同步的默认 NTP 服务器地址。需要设备启用 NTPC（NTP 客户端）特性。 设为 null 可清除默认 NTP 服务器。

↑ 返回命令列表

属性详解

TimeSynchronization Cluster 共有 13 个应用属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

时间状态（0x0000 ~ 0x0002）

描述设备当前的时间值以及时间的精度和来源。

↑ 返回属性列表

时间源配置（0x0003, 0x0004）

描述设备的时间同步源 —— 从哪里获取精确时间。

↑ 返回属性列表

时区与夏令时（0x0005 ~ 0x0007）

管理时区配置、夏令时偏移和本地时间计算。需要设备启用 TZ 特性。

↑ 返回属性列表

能力与限制（0x0008 ~ 0x000C）

描述设备在时间同步方面的能力上限和硬件特性。这些属性大部分是只读的，由设备固件决定。

↑ 返回属性列表

Feature 位图

TimeSynchronization Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些时间同步能力：

枚举定义

GranularityEnum

描述设备当前时间的精度等级。精度越高，表示设备的时间源越可靠。

TimeSourceEnum

标识设备当前时间的获取来源。数值越高通常意味着更可靠的时间源。NTS 后缀表示使用了网络时间安全（Network Time Security）认证。

TimeZoneDatabaseEnum

描述设备内置的时区数据库能力，决定设备能否自行推算夏令时规则。

事件（Events）

TimeSynchronization Cluster 定义了 5 个事件，用于通知 Commissioner 或自动化系统时间状态的变化。

示例数据

属性数据示例

以下是一个支持 TZ + NTPC 的智能灯（中国地区）的 TimeSynchronization Cluster 典型属性数据：

{
  // --- 时间状态 ---
  "0x0000": 1695312000000000,    // UTCTime = 2023-09-21T16:00:00Z（微秒级 epoch）
  "0x0001": 3,                   // Granularity = MillisecondsGranularity
  "0x0002": 7,                   // TimeSource = MatterNTP

  // --- 信任时间源 ---
  "0x0003": {                    // TrustedTimeSource
    "fabricIndex": 1,
    "nodeID": "0x0000000000000001",
    "endpoint": 0
  },
  "0x0004": "pool.ntp.org",      // DefaultNTP

  // --- 时区与夏令时 ---
  "0x0005": [{                   // TimeZone
    "offset": 28800,             //   UTC+8（秒）
    "validAt": 0,
    "name": "Asia/Shanghai"
  }],
  "0x0006": [{                   // DSTOffset
    "offset": 0,                 //   无夏令时
    "validStarting": 0,
    "validUntil": null
  }],

  // --- 本地时间 ---
  "0x0007": 1695340800000000,    // LocalTime（已加时区偏移）

  // --- 能力与限制 ---
  "0x0008": 1,                   // TimeZoneDatabase = Full
  "0x0009": false,               // NTPServerAvailable = false
  "0x000A": 2,                   // TimeZoneListMaxSize = 2
  "0x000B": 2,                   // DSTOffsetListMaxSize = 2
  "0x000C": true                 // SupportsDNSResolve = true
}

SetUTCTime 交互示例

Commissioner 在配网完成后为设备设置初始时间：

// Commissioner → Device：设置 UTC 时间
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0038",
      "commandId": "0x00"            // SetUTCTime
    },
    "commandFields": {
      "UTCTime": 1695312000000000,   // 2023-09-21T16:00:00Z（微秒）
      "granularity": 3,              // MillisecondsGranularity
      "timeSource": 2                // Admin
    }
  }]
}

SetTimeZone 交互示例

为设备设置中国时区（UTC+8）：

// Commissioner → Device：设置时区
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0038",
      "commandId": "0x02"            // SetTimeZone
    },
    "commandFields": {
      "timeZone": [{
        "offset": 28800,             // UTC+8（秒）
        "validAt": 0,                // 立即生效
        "name": "Asia/Shanghai"      // IANA 时区名（可选）
      }]
    }
  }]
}

// Device → Commissioner：确认时区设置
{
  "DSTOffsetRequired": true          // 需要跟进设置夏令时偏移
}

常见场景