Matter Cluster 56 — Time Synchronization Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 56 values in the device shadow use this format:

endpoint_id / 56 / attribute_id

Example:

{
  "0/56/0": 0
}

Cluster 56 Features

The FeatureMap attribute (0/56/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 15 means every feature listed above is enabled.

Data Types

GranularityEnum

StatusCodeEnum

TimeSourceEnum

TimeZoneDatabaseEnum

It indicates what the device knows about the contents of the IANA Time Zone Database. Partial support on a device may be used to omit historical data, less commonly used time zones, and/or time zones not related to the region a product is sold in.

DSTOffsetStruct (struct)

FabricScopedTrustedTimeSourceStruct (struct)

TimeZoneStruct (struct)

TrustedTimeSourceStruct (struct)

Cluster 56 Attributes

Cluster 56 defines 13 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — UTCTime

Path example:

0/56/0

No condensed specification text is available for UTCTime; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/56/0": 0
}

Attribute 1 / 0x0001 — Granularity

Path example:

0/56/1

Indicates granularity of the error that the node is willing to guarantee on the time synchronization. It is of type GranularityEnum. This value is set to NoTimeGranularity if UTCTime is null and must NOT be set to NoTimeGranularity if UTCTime is non-null.

Values (GranularityEnum):

Example:

{
  "0/56/1": 0
}

Attribute 2 / 0x0002 — TimeSource

Path example:

0/56/2

Indicates the node's time source. This attribute indicates what method the node is using to sync, whether the source uses NTS or not and whether the source is internal or external to the Matter network. This attribute may be used by a client to determine its level of trust in the UTCTime. It is of type TimeSourceEnum.

Values (TimeSourceEnum):

Example:

{
  "0/56/2": 0
}

Attribute 3 / 0x0003 — TrustedTimeSource

Path example:

0/56/3

Indicates the Node ID, endpoint, and associated fabric index of a Node that may be used as trusted time source. 17.13, "Time source prioritization". This attribute reflects the last value set by an administrator using the SetTrustedTimeSource command. If the value is null, no trusted time source has yet been set.

Value is a TrustedTimeSourceStruct struct (see Data Types).

Example:

{
  "0/56/3": {
    "fabricIndex": 1,
    "nodeID": 1,
    "endpoint": 1
  }
}

Attribute 4 / 0x0004 — DefaultNTP

Path example:

0/56/4

No condensed specification text is available for DefaultNTP; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/56/4": "example"
}

Attribute 5 / 0x0005 — TimeZone

Path example:

0/56/5

This attribute contains a list of time zone offsets from UTC and when they must take effect. This attribute uses a list of time offset configurations to allow Nodes to handle scheduled regulatory time zone changes. This attribute must NOT be used to indicate daylight savings time changes. The first entry has a ValidAt entry of 0.

Each entry is a TimeZoneStruct (see Data Types).

Example:

{
  "0/56/5": []
}

Attribute 6 / 0x0006 — DSTOffset

Path example:

0/56/6

No condensed specification text is available for DSTOffset; use the type, conformance and constraint below together with the cluster description above.

Each entry is a DSTOffsetStruct (see Data Types).

Example:

{
  "0/56/6": []
}

Attribute 7 / 0x0007 — LocalTime

Path example:

0/56/7

Indicates the computed current local time of the node as a epoch-us (Epoch Time in Microseconds). The value of LocalTime is the sum of the UTCTime, the offset of the currently valid TimeZoneStruct from the TimeZone attribute (converted to microseconds), and the offset of the currently valid DSTOffsetStruct from the DSTOffset attribute (converted to microseconds), if such an entry exists. If the node has not achieved time synchronization, this is null. If the node has an empty DSTOffset, this is null.

Example:

{
  "0/56/7": 0
}

Attribute 8 / 0x0008 — TimeZoneDatabase

Path example:

0/56/8

Indicates whether the node has access to a time zone database. Nodes with a time zone database may update their own DSTOffset attribute to add new entries and may push DSTOffset updates to other Nodes in the same time zone as required.

Values (TimeZoneDatabaseEnum):

Example:

{
  "0/56/8": 0
}

Attribute 9 / 0x0009 — NTPServerAvailable

Path example:

0/56/9

No condensed specification text is available for NTPServerAvailable; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/56/9": true
}

Attribute 10 / 0x000A — TimeZoneListMaxSize

Path example:

0/56/10

Indicates the number of supported list entries in the TimeZone attribute. This attribute may take the value of 1 or 2, where the optional second list entry may be used to handle scheduled regulatory time zone changes.

Example:

{
  "0/56/10": 1
}

Attribute 11 / 0x000B — DSTOffsetListMaxSize

Path example:

0/56/11

No condensed specification text is available for DSTOffsetListMaxSize; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/56/11": 1
}

Attribute 12 / 0x000C — SupportsDNSResolve

Path example:

0/56/12

No condensed specification text is available for SupportsDNSResolve; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/56/12": true
}

Cluster 56 Commands

Cluster 56 has 5 client-to-server commands and 1 response.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 56 / 65529

{
  "0/56/65529": [
    0,
    1,
    2,
    4,
    5
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetUTCTime",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 56, always use "cluster_id": 56. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: SetUTCTime

Purpose

SetUTCTime is a client-to-server command of the Time Synchronization cluster.

Command Identity

Payload Fields

Granularity values (GranularityEnum): 0 = NoTimeGranularity, 1 = MinutesGranularity, 2 = SecondsGranularity, 3 = MillisecondsGranularity, 4 = MicrosecondsGranularity

TimeSource values (TimeSourceEnum): 0 = None, 1 = Unknown, 2 = Admin, 3 = NodeTimeCluster, 4 = NonMatterSNTP, 5 = NonMatterNTP, 6 = MatterSNTP, 7 = MatterNTP, 8 = MixedNTP, 9 = NonMatterSNTPNTS, 10 = NonMatterNTPNTS, 11 = MatterSNTPNTS, 12 = MatterNTPNTS, 13 = MixedNTPNTS, 14 = CloudSource, 15 = PTP, 16 = GNSS

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetUTCTime",
    "payload": {
      "utcTime": 0,
      "granularity": 0
    }
  }
}

Command: SetTrustedTimeSource

Purpose

This command is used to set the TrustedTimeSource attribute. Upon receipt of this command: - If the TrustedTimeSource field in the command is null, the node must set the TrustedTimeSource attribute to null and must generate a MissingTrustedTimeSource event. - Otherwise, the node must set the TrustedTimeSource attribute to a struct which has NodeID and Endpoint fields matching those in the TrustedTimeSource field and has its FabricIndex field set to the command's accessing fabric index.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetTrustedTimeSource",
    "payload": {
      "trustedTimeSource": {
        "nodeID": 1,
        "endpoint": 1
      }
    }
  }
}

Command: SetTimeZone

Purpose

This command is used to set the time zone of the node. If the given list is larger than the TimeZoneListMaxSize, the node must respond with RESOURCE_EXHAUSTED and the TimeZone attribute must NOT be updated. If the given list does not conform to the list requirements in TimeZone attribute the node must respond with a CONSTRAINT_ERROR and the TimeZone attribute must NOT be updated. If there are no errors in the list, the TimeZone field is copied to the TimeZone attribute.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetTimeZone",
    "payload": {
      "timeZone": []
    }
  }
}

The device answers with SetTimeZoneResponse (see below).

Command: SetTimeZoneResponse

Purpose

THis command is used to report the result of a SetTimeZone command. This command is generated in response to a SetTimeZone command.

Command Identity

Response Fields

Command: SetDSTOffset

Purpose

SetDSTOffset is a client-to-server command of the Time Synchronization cluster.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetDSTOffset",
    "payload": {
      "dstOffset": []
    }
  }
}

Command: SetDefaultNTP

Purpose

SetDefaultNTP is a client-to-server command of the Time Synchronization cluster.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 56,
    "command_name": "SetDefaultNTP",
    "payload": {
      "defaultNTP": "example"
    }
  }
}

Cluster 56 Events

Event 0 — DSTTableEmpty

This event has no fields.

Event 1 — DSTStatus

Event 2 — TimeZoneStatus

This event is generated when the node changes its time zone offset or name. It must NOT be sent for DST changes that are not accompanied by a time zone change.

Event 3 — TimeFailure

This event is generated if the node has not generated a TimeFailure event in the last hour, and the node is unable to get a time from any source. This event should NOT be generated more often than once per hour.

This event has no fields.

Event 4 — MissingTrustedTimeSource

This event is generated if the TrustedTimeSource is set to null upon fabric removal or by a SetTrustedTimeSource command. This event must also be generated if the node has not generated a MissingTrustedTimeSource event in the last hour, and the node fails to update its time from the TrustedTimeSource because the TrustedTimeSource is null or the specified peer cannot be reached. MissingTrustedTimeSource events corresponding to a time update should NOT be generated more often than once per hour.

This event has no fields.

SmartphoneKey Notes

• Cluster 56 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/56/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.