/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ /*** THIS FILE IS GENERATED, DO NOT EDIT ***/ import type { ClusterType, ClusterTyping } from "../cluster/ClusterType.js"; import type { ClusterId } from "../datatype/ClusterId.js"; import type { ClusterModel } from "@matter/model"; import type { MaybePromise } from "@matter/general"; import type { FabricIndex } from "../datatype/FabricIndex.js"; import type { NodeId } from "../datatype/NodeId.js"; import type { EndpointNumber } from "../datatype/EndpointNumber.js"; import type { StatusResponseError } from "../common/StatusResponseError.js"; import type { Status } from "../globals/Status.js"; /** * Definitions for the TimeSynchronization cluster. * * Accurate time is required for a number of reasons, including scheduling, display and validating security materials. * * This section describes a mechanism for Nodes to achieve and maintain time synchronization. The Time Synchronization * cluster provides attributes for reading a Node's current time. It also allows Administrators to set current time, * time zone and daylight savings time (DST) settings. * * The Time Synchronization cluster may be present on the root node endpoint, and shall NOT be present on any other * Endpoint of any Node. * * @see {@link MatterSpecification.v151.Core} § 11.17 */ export declare namespace TimeSynchronization { /** * The Matter protocol cluster identifier. */ export const id: ClusterId & 0x0038; /** * Textual cluster identifier. */ export const name: "TimeSynchronization"; /** * The cluster revision assigned by {@link MatterSpecification.v151.Cluster}. */ export const revision: 2; /** * Canonical metadata for the TimeSynchronization cluster. * * This is the exhaustive runtime metadata source that matter.js considers canonical. */ export const schema: ClusterModel; /** * {@link TimeSynchronization} always supports these elements. */ export interface BaseAttributes { /** * If the node has achieved time synchronization, this attribute shall indicate the current time as a UTC * epoch-us (Epoch Time in Microseconds). * * If the node has not achieved time synchronization, this attribute shall be null. This attribute may be set * when a SetUTCTime is received. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.1 */ utcTime: number | bigint | null; /** * Indicates granularity of the error that the node is willing to guarantee on the time synchronization. It is * of type GranularityEnum. * * This value shall be set to NoTimeGranularity if UTCTime is null and shall NOT be set to NoTimeGranularity if * UTCTime is non-null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.2 */ granularity: Granularity; /** * 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. * * If a node is unsure if the selected NTP server is within the Matter network, it SHOULD select one of the * NonMatter* values. * * This value shall be set to None if UTCTime is null and shall NOT be set to None if UTCTime is non-null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.3 */ timeSource?: TimeSource; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeSyncClient". */ export interface TimeSyncClientAttributes { /** * Indicates the Node ID, endpoint, and associated fabric index of a Node that may be used as trusted time * source. See Section 11.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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.4 */ trustedTimeSource: TrustedTimeSource | null; } /** * {@link TimeSynchronization} supports these elements if it supports feature "NtpClient". */ export interface NtpClientAttributes { /** * Indicates the default NTP server that this Node may use if other time sources are unavailable. This attribute * is settable by an Administrator using the SetDefaultNTP command. It SHOULD be set by the Commissioner during * commissioning. If no default NTP server is available, the Commissioner may set this value to null. The * default IANA assigned NTP port of 123 shall be used to access the NTP server. * * If set, the format of this attribute shall be a domain name or a static IPv6 address with no port, in text * format, as specified in RFC 5952. The address format shall follow the recommendations in Section 4 and shall * NOT contain a port number. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.5 */ defaultNtp: string | null; /** * Indicates if the node supports resolving a domain name. DefaultNTP Address values for these nodes may include * domain names. If this is False, the Address for a DefaultNTP shall be an IPv6 address. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.13 */ supportsDnsResolve: boolean; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeZone". */ export interface TimeZoneAttributes { /** * This attribute shall contain a list of time zone offsets from UTC and when they shall take effect. This * attribute uses a list of time offset configurations to allow Nodes to handle scheduled regulatory time zone * changes. This attribute shall NOT be used to indicate daylight savings time changes (see Section 11.17.8.7, * "DSTOffset Attribute" for daylight savings time). * * The first entry shall have a ValidAt entry of 0. If there is a second entry, it shall have a non-zero ValidAt * time. * * If a node supports a TimeZoneDatabase, and it has data for the given time zone Name and the given Offset * matches, the node may update its own DSTOffset attribute to add new DST change times as required, based on * the Name fields of the TimeZoneStruct. Administrators may add additional entries to the DSTOffset of other * Nodes with the same time zone, if required. * * If a node does not support a TimeZoneDatabase, the Name field of the TimeZoneStruct is only applicable for * client-side localization. In particular: * * - If the node does not support a TimeZoneDatabase, the Name field shall NOT be used to calculate the local * time. * * - If the node does not support a TimeZoneDatabase, the Name field shall NOT be used to calculate DST start * or end dates. * * When time passes, the node SHOULD remove any entries which are no longer active and change the ValidAt time * for the currently used TimeZoneStruct list item to zero. * * This attribute shall have at least one entry. If the node does not have a default time zone and no time zone * has been set, it may set this value to a list containing a single TimeZoneStruct with an offset of 0 (UTC) * and a ValidAt time of 0. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.6 */ timeZone: TimeZone[]; /** * This attribute shall contain a list of offsets to apply for daylight savings time, and their validity period. * * List entries shall be sorted by ValidStarting time. * * A list entry shall NOT have a ValidStarting time that is smaller than the ValidUntil time of the previous * entry. There shall be at most one list entry with a null ValidUntil time and, if such an entry is present, it * shall appear last in the list. * * Over time, the node SHOULD remove any entries which are no longer active from the list. * * Over time, if the node supports a TimeZoneDatabase and it has information available for the given time zone * name, it may update its own list to add additional entries. * * If a time zone does not use DST, this shall be indicated by a single entry with a 0 offset and a null * ValidUntil field. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.7 */ dstOffset: DstOffset[]; /** * Indicates the computed current local time of the node as a epoch-us (Epoch Time in Microseconds). The value * of LocalTime shall be 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 shall be null. If the node has an empty DSTOffset, * this shall be null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.8 */ localTime: number | bigint | null; /** * 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.9 */ timeZoneDatabase: TimeZoneDatabase; /** * 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.11 */ timeZoneListMaxSize: number; /** * Indicates the number of supported list entries in DSTOffset attribute. This value must be at least 1. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.12 */ dstOffsetListMaxSize: number; } /** * {@link TimeSynchronization} supports these elements if it supports feature "NtpServer". */ export interface NtpServerAttributes { /** * Indicates if the node is running an RFC 5905 NTPv4 compliant server on port 123, this value shall be True. * * If the node is not currently running an NTP server, this value shall be False. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.10 */ ntpServerAvailable: boolean; } /** * Attributes that may appear in {@link TimeSynchronization}. * * Some properties may be optional if device support is not mandatory. Device support may also be affected by a * device's supported {@link Features}. */ export interface Attributes { /** * If the node has achieved time synchronization, this attribute shall indicate the current time as a UTC * epoch-us (Epoch Time in Microseconds). * * If the node has not achieved time synchronization, this attribute shall be null. This attribute may be set * when a SetUTCTime is received. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.1 */ utcTime: number | bigint | null; /** * Indicates granularity of the error that the node is willing to guarantee on the time synchronization. It is * of type GranularityEnum. * * This value shall be set to NoTimeGranularity if UTCTime is null and shall NOT be set to NoTimeGranularity if * UTCTime is non-null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.2 */ granularity: Granularity; /** * 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. * * If a node is unsure if the selected NTP server is within the Matter network, it SHOULD select one of the * NonMatter* values. * * This value shall be set to None if UTCTime is null and shall NOT be set to None if UTCTime is non-null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.3 */ timeSource: TimeSource; /** * Indicates the Node ID, endpoint, and associated fabric index of a Node that may be used as trusted time * source. See Section 11.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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.4 */ trustedTimeSource: TrustedTimeSource | null; /** * Indicates the default NTP server that this Node may use if other time sources are unavailable. This attribute * is settable by an Administrator using the SetDefaultNTP command. It SHOULD be set by the Commissioner during * commissioning. If no default NTP server is available, the Commissioner may set this value to null. The * default IANA assigned NTP port of 123 shall be used to access the NTP server. * * If set, the format of this attribute shall be a domain name or a static IPv6 address with no port, in text * format, as specified in RFC 5952. The address format shall follow the recommendations in Section 4 and shall * NOT contain a port number. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.5 */ defaultNtp: string | null; /** * Indicates if the node supports resolving a domain name. DefaultNTP Address values for these nodes may include * domain names. If this is False, the Address for a DefaultNTP shall be an IPv6 address. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.13 */ supportsDnsResolve: boolean; /** * This attribute shall contain a list of time zone offsets from UTC and when they shall take effect. This * attribute uses a list of time offset configurations to allow Nodes to handle scheduled regulatory time zone * changes. This attribute shall NOT be used to indicate daylight savings time changes (see Section 11.17.8.7, * "DSTOffset Attribute" for daylight savings time). * * The first entry shall have a ValidAt entry of 0. If there is a second entry, it shall have a non-zero ValidAt * time. * * If a node supports a TimeZoneDatabase, and it has data for the given time zone Name and the given Offset * matches, the node may update its own DSTOffset attribute to add new DST change times as required, based on * the Name fields of the TimeZoneStruct. Administrators may add additional entries to the DSTOffset of other * Nodes with the same time zone, if required. * * If a node does not support a TimeZoneDatabase, the Name field of the TimeZoneStruct is only applicable for * client-side localization. In particular: * * - If the node does not support a TimeZoneDatabase, the Name field shall NOT be used to calculate the local * time. * * - If the node does not support a TimeZoneDatabase, the Name field shall NOT be used to calculate DST start * or end dates. * * When time passes, the node SHOULD remove any entries which are no longer active and change the ValidAt time * for the currently used TimeZoneStruct list item to zero. * * This attribute shall have at least one entry. If the node does not have a default time zone and no time zone * has been set, it may set this value to a list containing a single TimeZoneStruct with an offset of 0 (UTC) * and a ValidAt time of 0. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.6 */ timeZone: TimeZone[]; /** * This attribute shall contain a list of offsets to apply for daylight savings time, and their validity period. * * List entries shall be sorted by ValidStarting time. * * A list entry shall NOT have a ValidStarting time that is smaller than the ValidUntil time of the previous * entry. There shall be at most one list entry with a null ValidUntil time and, if such an entry is present, it * shall appear last in the list. * * Over time, the node SHOULD remove any entries which are no longer active from the list. * * Over time, if the node supports a TimeZoneDatabase and it has information available for the given time zone * name, it may update its own list to add additional entries. * * If a time zone does not use DST, this shall be indicated by a single entry with a 0 offset and a null * ValidUntil field. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.7 */ dstOffset: DstOffset[]; /** * Indicates the computed current local time of the node as a epoch-us (Epoch Time in Microseconds). The value * of LocalTime shall be 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 shall be null. If the node has an empty DSTOffset, * this shall be null. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.8 */ localTime: number | bigint | null; /** * 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.9 */ timeZoneDatabase: TimeZoneDatabase; /** * 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.11 */ timeZoneListMaxSize: number; /** * Indicates the number of supported list entries in DSTOffset attribute. This value must be at least 1. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.12 */ dstOffsetListMaxSize: number; /** * Indicates if the node is running an RFC 5905 NTPv4 compliant server on port 123, this value shall be True. * * If the node is not currently running an NTP server, this value shall be False. * * @see {@link MatterSpecification.v151.Core} § 11.17.8.10 */ ntpServerAvailable: boolean; } /** * {@link TimeSynchronization} always supports these elements. */ export interface BaseCommands { /** * This command is used to set the UTC time of the node. * * This command may be issued by Administrator to set the time. If the Commissioner does not have a valid time * source, it may send a Granularity of NoTimeGranularity. * * Upon receipt of this command, the node may update its UTCTime attribute to match the time specified in the * command, if the stated Granularity and TimeSource are acceptable. The node shall update its UTCTime attribute * if its current Granularity is NoTimeGranularity. * * If the time is updated, the node shall also update its Granularity attribute based on the granularity * specified in the command and the expected clock drift of the node. This SHOULD normally be one level lower * than the stated command Granularity. It shall also update its TimeSource attribute to Admin. It shall also * update its Last Known Good UTC Time as defined in Section 3.5.6.1, "Last Known Good UTC Time". * * If the node updates its UTCTime attribute, it shall accept the command with a status code of SUCCESS. If it * opts to not update its time, it shall fail the command with a cluster specific Status Code of * TimeNotAccepted. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.1 */ setUtcTime(request: SetUtcTimeRequest): MaybePromise; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeSyncClient". */ export interface TimeSyncClientCommands { /** * 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 shall set the TrustedTimeSource attribute * to null and shall generate a MissingTrustedTimeSource event. * * - Otherwise, the node shall 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.2 */ setTrustedTimeSource(request: SetTrustedTimeSourceRequest): MaybePromise; } /** * {@link TimeSynchronization} supports these elements if it supports feature "NtpClient". */ export interface NtpClientCommands { /** * This command is used to set the DefaultNTP attribute. * * If the DefaultNTP Address field does not conform to the requirements in the DefaultNTP attribute description, * the command shall fail with a status code of INVALID_COMMAND. If the node does not support DNS resolution (as * specified in SupportsDNSResolve) and the provided Address is a domain name, the command shall fail with a * status code of INVALID_COMMAND. Otherwise, the node shall set the DefaultNTP attribute to match the * DefaultNTP provided in this command. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.6 */ setDefaultNtp(request: SetDefaultNtpRequest): MaybePromise; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeZone". */ export interface TimeZoneCommands { /** * This command is used to set the time zone of the node. * * If the given list is larger than the TimeZoneListMaxSize, the node shall respond with RESOURCE_EXHAUSTED and * the TimeZone attribute shall NOT be updated. * * If the given list does not conform to the list requirements in TimeZone attribute the node shall respond with * a CONSTRAINT_ERROR and the TimeZone attribute shall NOT be updated. * * If there are no errors in the list, the TimeZone field shall be copied to the TimeZone attribute. A * TimeZoneStatus event shall be generated with the new time zone information. * * If the node supports a time zone database and it has information available for the time zone that will be * applied, it may set its DSTOffset attribute, otherwise the DSTOffset attribute shall be set to an empty list. * A DSTTableEmpty event shall be generated if the DSTOffset attribute is empty. A DSTStatus event shall be * generated if the node was previously applying a DST offset. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.3 */ setTimeZone(request: SetTimeZoneRequest): MaybePromise; /** * This command is used to set the DST offsets for a node. * * - If the length of DSTOffset is larger than DSTOffsetListMaxSize, the node shall respond with * RESOURCE_EXHAUSTED. * * - Else if the list entries do not conform to the list requirements for DSTOffset attribute, the node shall * respond with CONSTRAINT_ERROR. * * If there are no errors in the list, the DSTOffset field shall be copied to the DSTOffset attribute. * * If the DSTOffset attribute change causes a corresponding change to the DST state, a DSTStatus event shall be * generated. If the list is empty, the node shall generate a DSTTableEmpty event. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.5 */ setDstOffset(request: SetDstOffsetRequest): MaybePromise; } /** * Commands that may appear in {@link TimeSynchronization}. */ export interface Commands extends BaseCommands, TimeSyncClientCommands, NtpClientCommands, TimeZoneCommands {} /** * {@link TimeSynchronization} always supports these elements. */ export interface BaseEvents { /** * This event shall be 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.4 */ timeFailure: void; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeSyncClient". */ export interface TimeSyncClientEvents { /** * This event shall be generated if the TrustedTimeSource is set to null upon fabric removal or by a * SetTrustedTimeSource command. * * This event shall 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.5 */ missingTrustedTimeSource: void; } /** * {@link TimeSynchronization} supports these elements if it supports feature "TimeZone". */ export interface TimeZoneEvents { /** * This event shall be generated when the node stops applying the current DSTOffset and there are no entries in * the list with a larger ValidStarting time, indicating the need to possibly get new DST data. This event shall * also be generated if the DSTOffset list is cleared either by a SetTimeZone command, or by a SetDSTOffset * command with an empty list. * * The node shall generate this event if the node has not generated a DSTTableEmpty event in the last hour, and * the DSTOffset list is empty when the node attempts to update its time. DSTTableEmpty events corresponding to * a time update SHOULD NOT be generated more often than once per hour. * * There is no data for this event. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.1 */ dstTableEmpty: void; /** * This event shall be generated when the node starts or stops applying a DST offset. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.2 */ dstStatus: DstStatusEvent; /** * This event shall be generated when the node changes its time zone offset or name. It shall NOT be sent for * DST changes that are not accompanied by a time zone change. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.3 */ timeZoneStatus: TimeZoneStatusEvent; } /** * Events that may appear in {@link TimeSynchronization}. * * Some properties may be optional if device support is not mandatory. Device support may also be affected by a * device's supported {@link Features}. */ export interface Events { /** * This event shall be 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.4 */ timeFailure: void; /** * This event shall be generated if the TrustedTimeSource is set to null upon fabric removal or by a * SetTrustedTimeSource command. * * This event shall 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.5 */ missingTrustedTimeSource: void; /** * This event shall be generated when the node stops applying the current DSTOffset and there are no entries in * the list with a larger ValidStarting time, indicating the need to possibly get new DST data. This event shall * also be generated if the DSTOffset list is cleared either by a SetTimeZone command, or by a SetDSTOffset * command with an empty list. * * The node shall generate this event if the node has not generated a DSTTableEmpty event in the last hour, and * the DSTOffset list is empty when the node attempts to update its time. DSTTableEmpty events corresponding to * a time update SHOULD NOT be generated more often than once per hour. * * There is no data for this event. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.1 */ dstTableEmpty: void; /** * This event shall be generated when the node starts or stops applying a DST offset. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.2 */ dstStatus: DstStatusEvent; /** * This event shall be generated when the node changes its time zone offset or name. It shall NOT be sent for * DST changes that are not accompanied by a time zone change. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.3 */ timeZoneStatus: TimeZoneStatusEvent; } export type Components = [ { flags: {}, attributes: BaseAttributes, commands: BaseCommands, events: BaseEvents }, { flags: { timeSyncClient: true }, attributes: TimeSyncClientAttributes, commands: TimeSyncClientCommands, events: TimeSyncClientEvents }, { flags: { ntpClient: true }, attributes: NtpClientAttributes, commands: NtpClientCommands }, { flags: { timeZone: true }, attributes: TimeZoneAttributes, commands: TimeZoneCommands, events: TimeZoneEvents }, { flags: { ntpServer: true }, attributes: NtpServerAttributes } ]; export type Features = "TimeZone" | "NtpClient" | "NtpServer" | "TimeSyncClient"; /** * These are optional features supported by TimeSynchronizationCluster. * * @see {@link MatterSpecification.v151.Core} § 11.17.5 */ export enum Feature { /** * TimeZone (TZ) * * Allows a server to translate a UTC time to a local time using the time zone and daylight savings time (DST) * offsets. If a server supports the TimeZone feature, it shall support the SetTimeZone and SetDSTOffset * commands, and TimeZone and DSTOffset attributes, and shall expose the local time through the LocalTime * attribute. * * @see {@link MatterSpecification.v151.Core} § 11.17.5.1 */ TimeZone = "TimeZone", /** * NtpClient (NTPC) * * Allows a node to use NTP/SNTP for time synchronization. * * @see {@link MatterSpecification.v151.Core} § 11.17.5.2 */ NtpClient = "NtpClient", /** * NtpServer (NTPS) * * Allows a Node to host an NTP server for the network so that other Nodes can achieve a high accuracy time * synchronization within the network. See Section 11.17.15, "Acting as an NTP Server". * * @see {@link MatterSpecification.v151.Core} § 11.17.5.3 */ NtpServer = "NtpServer", /** * TimeSyncClient (TSC) * * This node also supports a time synchronization client and can connect to and read time from other nodes. * * @see {@link MatterSpecification.v151.Core} § 11.17.5.4 */ TimeSyncClient = "TimeSyncClient" } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.1 */ export enum Granularity { /** * This indicates that the node is not currently synchronized with a UTC Time source and its clock is based on * the Last Known Good UTC Time only. */ NoTimeGranularity = 0, /** * This indicates the node was synchronized to an upstream source in the past, but sufficient clock drift has * occurred such that the clock error is now > 5 seconds. */ MinutesGranularity = 1, /** * This indicates the node is synchronized to an upstream source using a low resolution protocol. UTC Time is * accurate to ± 5 seconds. */ SecondsGranularity = 2, /** * This indicates the node is synchronized to an upstream source using high resolution time-synchronization * protocol such as NTP, or has built-in GNSS with some amount of jitter applying its GNSS timestamp. UTC Time * is accurate to ± 50 ms. */ MillisecondsGranularity = 3, /** * This indicates the node is synchronized to an upstream source using a highly precise time-synchronization * protocol such as PTP, or has built-in GNSS. UTC time is accurate to ± 10 μs. */ MicrosecondsGranularity = 4 } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.2 */ export enum TimeSource { /** * Node is not currently synchronized with a UTC Time source. */ None = 0, /** * Node uses an unlisted time source. */ Unknown = 1, /** * Node received time from a client using the SetUTCTime Command. */ Admin = 2, /** * Synchronized time by querying the Time Synchronization cluster of another Node. */ NodeTimeCluster = 3, /** * SNTP from a server not in the Matter network. NTS is not used. */ NonMatterSntp = 4, /** * NTP from servers not in the Matter network. None of the servers used NTS. */ NonMatterNtp = 5, /** * SNTP from a server within the Matter network. NTS is not used. */ MatterSntp = 6, /** * NTP from servers within the Matter network. None of the servers used NTS. */ MatterNtp = 7, /** * NTP from multiple servers in the Matter network and external. None of the servers used NTS. */ MixedNtp = 8, /** * SNTP from a server not in the Matter network. NTS is used. */ NonMatterSntpnts = 9, /** * NTP from servers not in the Matter network. NTS is used on at least one server. */ NonMatterNtpnts = 10, /** * SNTP from a server within the Matter network. NTS is used. */ MatterSntpnts = 11, /** * NTP from a server within the Matter network. NTS is used on at least one server. */ MatterNtpnts = 12, /** * NTP from multiple servers in the Matter network and external. NTS is used on at least one server. */ MixedNtpnts = 13, /** * Time synchronization comes from a vendor cloud-based source (e.g. "Date" header in authenticated HTTPS * connection). */ CloudSource = 14, /** * Time synchronization comes from PTP. */ Ptp = 15, /** * Time synchronization comes from a GNSS source. */ Gnss = 16 } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.4 */ export class TrustedTimeSource { constructor(values?: Partial); /** * The Fabric Index associated with the Fabric of the client which last set the value of the trusted time source * node. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.4.1 */ fabricIndex: FabricIndex; /** * Node ID of the trusted time source node on the Fabric associated with the entry. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.4.2 */ nodeId: NodeId; /** * Endpoint on the trusted time source node that contains the Time Synchronization cluster server. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.4.3 */ endpoint: EndpointNumber; } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.6 */ export class TimeZone { constructor(values?: Partial); /** * The time zone offset from UTC in seconds. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.6.1 */ offset: number; /** * The UTC time when the offset shall be applied. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.6.2 */ validAt: number | bigint; /** * The time zone name SHOULD provide a human-readable time zone name and it SHOULD use the country/city format * specified by the IANA Time Zone Database. The Name field may be used for display. If the node supports a * TimeZoneDatabase it may use the Name field to set its own DST offsets if it has database information for the * supplied time zone Name and the given Offset matches. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.6.3 */ name?: string; } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.7 */ export class DstOffset { constructor(values?: Partial); /** * The DST offset in seconds. Normally this is in the range of 0 to 3600 seconds (1 hour), but this field will * accept any values in the int32 range to accommodate potential future legislation that does not fit with these * assumptions. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.7.1 */ offset: number; /** * The UTC time when the offset shall be applied. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.7.2 */ validStarting: number | bigint; /** * The UTC time when the offset shall stop being applied. Providing a null value here indicates a permanent DST * change. If this value is non-null the value shall be larger than the ValidStarting time. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.7.3 */ validUntil: number | bigint | null; } /** * 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.3 */ export enum TimeZoneDatabase { /** * Node has a full list of the available time zones */ Full = 0, /** * Node has a partial list of the available time zones */ Partial = 1, /** * Node does not have a time zone database */ None = 2 } /** * This command is used to set the UTC time of the node. * * This command may be issued by Administrator to set the time. If the Commissioner does not have a valid time * source, it may send a Granularity of NoTimeGranularity. * * Upon receipt of this command, the node may update its UTCTime attribute to match the time specified in the * command, if the stated Granularity and TimeSource are acceptable. The node shall update its UTCTime attribute if * its current Granularity is NoTimeGranularity. * * If the time is updated, the node shall also update its Granularity attribute based on the granularity specified * in the command and the expected clock drift of the node. This SHOULD normally be one level lower than the stated * command Granularity. It shall also update its TimeSource attribute to Admin. It shall also update its Last Known * Good UTC Time as defined in Section 3.5.6.1, "Last Known Good UTC Time". * * If the node updates its UTCTime attribute, it shall accept the command with a status code of SUCCESS. If it opts * to not update its time, it shall fail the command with a cluster specific Status Code of TimeNotAccepted. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.1 */ export class SetUtcTimeRequest { constructor(values?: Partial); /** * This field shall give the Client's UTC Time. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.1.1 */ utcTime: number | bigint; /** * This field shall give the Client's Granularity, as described in Granularity. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.1.2 */ granularity: Granularity; /** * This field shall give the Client's TimeSource, as described in TimeSource. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.1.3 */ timeSource?: TimeSource; } /** * 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 shall set the TrustedTimeSource attribute to * null and shall generate a MissingTrustedTimeSource event. * * - Otherwise, the node shall 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. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.2 */ export class SetTrustedTimeSourceRequest { constructor(values?: Partial); /** * This field contains the Node ID and endpoint of a trusted time source on the accessing fabric. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.2.1 */ trustedTimeSource: FabricScopedTrustedTimeSource | null; fabricIndex: FabricIndex; } /** * This command is used to set the DefaultNTP attribute. * * If the DefaultNTP Address field does not conform to the requirements in the DefaultNTP attribute description, the * command shall fail with a status code of INVALID_COMMAND. If the node does not support DNS resolution (as * specified in SupportsDNSResolve) and the provided Address is a domain name, the command shall fail with a status * code of INVALID_COMMAND. Otherwise, the node shall set the DefaultNTP attribute to match the DefaultNTP provided * in this command. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.6 */ export class SetDefaultNtpRequest { constructor(values?: Partial); /** * This field contains the address of an NTP server than can be used as a fallback for time synchronization. The * format of this field shall follow the requirements in the DefaultNTP attribute description. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.6.1 */ defaultNtp: string | null; } /** * This command is used to set the time zone of the node. * * If the given list is larger than the TimeZoneListMaxSize, the node shall respond with RESOURCE_EXHAUSTED and the * TimeZone attribute shall NOT be updated. * * If the given list does not conform to the list requirements in TimeZone attribute the node shall respond with a * CONSTRAINT_ERROR and the TimeZone attribute shall NOT be updated. * * If there are no errors in the list, the TimeZone field shall be copied to the TimeZone attribute. A * TimeZoneStatus event shall be generated with the new time zone information. * * If the node supports a time zone database and it has information available for the time zone that will be * applied, it may set its DSTOffset attribute, otherwise the DSTOffset attribute shall be set to an empty list. A * DSTTableEmpty event shall be generated if the DSTOffset attribute is empty. A DSTStatus event shall be generated * if the node was previously applying a DST offset. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.3 */ export class SetTimeZoneRequest { constructor(values?: Partial); timeZone: TimeZone[]; } /** * THis command is used to report the result of a SetTimeZone command. This command shall be generated in response * to a SetTimeZone command. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.4 */ export class SetTimeZoneResponse { constructor(values?: Partial); /** * If the node supports a time zone database with information for the time zone that will be applied, it may use * this information to set the DSTOffset attribute. If the node is setting its own DSTOffset attribute, the * DSTOffsetRequired field shall be set to false, otherwise it shall be set to true. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.4.1 */ dstOffsetRequired: boolean; } /** * This command is used to set the DST offsets for a node. * * - If the length of DSTOffset is larger than DSTOffsetListMaxSize, the node shall respond with * RESOURCE_EXHAUSTED. * * - Else if the list entries do not conform to the list requirements for DSTOffset attribute, the node shall * respond with CONSTRAINT_ERROR. * * If there are no errors in the list, the DSTOffset field shall be copied to the DSTOffset attribute. * * If the DSTOffset attribute change causes a corresponding change to the DST state, a DSTStatus event shall be * generated. If the list is empty, the node shall generate a DSTTableEmpty event. * * @see {@link MatterSpecification.v151.Core} § 11.17.9.5 */ export class SetDstOffsetRequest { constructor(values?: Partial); dstOffset: DstOffset[]; } /** * This event shall be generated when the node starts or stops applying a DST offset. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.2 */ export class DstStatusEvent { constructor(values?: Partial); /** * Indicates whether the current DST offset is being applied (i.e, daylight savings time is applied, as opposed * to standard time). * * @see {@link MatterSpecification.v151.Core} § 11.17.10.2.1 */ dstOffsetActive: boolean; } /** * This event shall be generated when the node changes its time zone offset or name. It shall NOT be sent for DST * changes that are not accompanied by a time zone change. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.3 */ export class TimeZoneStatusEvent { constructor(values?: Partial); /** * Current time zone offset from UTC in seconds. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.3.1 */ offset: number; /** * Current time zone name. This name SHOULD use the country/city format specified by the IANA Time Zone * Database. * * @see {@link MatterSpecification.v151.Core} § 11.17.10.3.2 */ name?: string; } /** * @see {@link MatterSpecification.v151.Core} § 11.17.6.5 */ export class FabricScopedTrustedTimeSource { constructor(values?: Partial); /** * Node ID of the trusted time source node on the Fabric of the issuer. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.5.1 */ nodeId: NodeId; /** * Endpoint on the trusted time source node that contains the Time Synchronization cluster server. This is * provided to avoid having to do discovery of the location of that endpoint by walking over all endpoints and * checking their Descriptor Cluster. * * @see {@link MatterSpecification.v151.Core} § 11.17.6.5.2 */ endpoint: EndpointNumber; } /** * @see {@link MatterSpecification.v151.Core} § 11.17.7.1 */ export enum StatusCode { /** * Node rejected the attempt to set the UTC time */ TimeNotAccepted = 2 } /** * Thrown for cluster status code {@link StatusCode.TimeNotAccepted}. * * @see {@link MatterSpecification.v151.Core} § 11.17.7.1 */ export class TimeNotAcceptedError extends StatusResponseError { constructor(message?: string, code?: Status, clusterCode?: number) } /** * Attribute metadata objects keyed by name. */ export const attributes: ClusterType.AttributeObjects; /** * Command metadata objects keyed by name. */ export const commands: ClusterType.CommandObjects; /** * Event metadata objects keyed by name. */ export const events: ClusterType.EventObjects; /** * Feature metadata objects keyed by name. */ export const features: ClusterType.Features; /** * @deprecated Use {@link TimeSynchronization}. */ export const Cluster: ClusterType.WithCompat; /** * @deprecated Use {@link TimeSynchronization}. */ export const Complete: typeof TimeSynchronization; export const Typing: TimeSynchronization; } /** * @deprecated Use {@link TimeSynchronization}. */ export declare const TimeSynchronizationCluster: typeof TimeSynchronization; export interface TimeSynchronization extends ClusterTyping { Attributes: TimeSynchronization.Attributes; Commands: TimeSynchronization.Commands; Events: TimeSynchronization.Events; Features: TimeSynchronization.Features; Components: TimeSynchronization.Components; }