@matter/types 0.12.6-alpha.0-20250304-03716637c → 0.13.0-alpha.0-20250307-ebf84a05a

package/src/clusters/thread-network-directory.ts

@@ -0,0 +1,256 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE IS GENERATED, DO NOT EDIT ***/
+
+import { MutableCluster } from "../cluster/mutation/MutableCluster.js";
+import { WritableAttribute, Attribute, FixedAttribute, Command, TlvNoResponse } from "../cluster/Cluster.js";
+import { TlvByteString, TlvString } from "../tlv/TlvString.js";
+import { TlvNullable } from "../tlv/TlvNullable.js";
+import { AccessLevel } from "#model";
+import { TlvArray } from "../tlv/TlvArray.js";
+import { TlvField, TlvObject } from "../tlv/TlvObject.js";
+import { TlvUInt16, TlvUInt64, TlvUInt8 } from "../tlv/TlvNumber.js";
+import { TypeFromSchema } from "../tlv/TlvSchema.js";
+import { Identity } from "#general";
+import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
+
+export namespace ThreadNetworkDirectory {
+    /**
+     * Represents the data associated with a Thread Network.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1
+     */
+    export const TlvThreadNetwork = TlvObject({
+        /**
+         * This field shall indicate the Extended PAN ID from the OperationalDataset for the given Thread network.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1.1
+         */
+        extendedPanId: TlvField(0, TlvByteString.bound({ length: 8 })),
+
+        /**
+         * This field shall indicate the Network Name from the OperationalDataset for the given Thread network.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1.2
+         */
+        networkName: TlvField(1, TlvString.bound({ minLength: 1, maxLength: 16 })),
+
+        /**
+         * This field shall indicate the Channel from the OperationalDataset for the given Thread network.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1.3
+         */
+        channel: TlvField(2, TlvUInt16),
+
+        /**
+         * This field shall indicate the Active Timestamp from the OperationalDataset for the given Thread network.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1.4
+         */
+        activeTimestamp: TlvField(3, TlvUInt64)
+    });
+
+    /**
+     * Represents the data associated with a Thread Network.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.4.1
+     */
+    export interface ThreadNetwork extends TypeFromSchema<typeof TlvThreadNetwork> {}
+
+    /**
+     * Input to the ThreadNetworkDirectory addNetwork command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.1
+     */
+    export const TlvAddNetworkRequest = TlvObject({
+        /**
+         * This field shall represent the Operational Dataset for the network, using the encoding defined in the Thread
+         * specification. It shall contain at least the following sub-TLVs: Active Timestamp, Channel, Channel Mask,
+         * Extended PAN ID, Network Key, Network Mesh-Local Prefix, Network Name, PAN ID, PSKc, and Security Policy.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.1.1
+         */
+        operationalDataset: TlvField(0, TlvByteString.bound({ maxLength: 254 }))
+    });
+
+    /**
+     * Input to the ThreadNetworkDirectory addNetwork command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.1
+     */
+    export interface AddNetworkRequest extends TypeFromSchema<typeof TlvAddNetworkRequest> {}
+
+    /**
+     * Input to the ThreadNetworkDirectory removeNetwork command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.2
+     */
+    export const TlvRemoveNetworkRequest = TlvObject({ extendedPanId: TlvField(0, TlvByteString.bound({ length: 8 })) });
+
+    /**
+     * Input to the ThreadNetworkDirectory removeNetwork command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.2
+     */
+    export interface RemoveNetworkRequest extends TypeFromSchema<typeof TlvRemoveNetworkRequest> {}
+
+    /**
+     * Input to the ThreadNetworkDirectory getOperationalDataset command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.3
+     */
+    export const TlvGetOperationalDatasetRequest = TlvObject({
+        extendedPanId: TlvField(0, TlvByteString.bound({ length: 8 }))
+    });
+
+    /**
+     * Input to the ThreadNetworkDirectory getOperationalDataset command
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.3
+     */
+    export interface GetOperationalDatasetRequest extends TypeFromSchema<typeof TlvGetOperationalDatasetRequest> {}
+
+    /**
+     * Contains the Thread Operational Dataset for the Extended PAN specified in GetOperationalDataset.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.4
+     */
+    export const TlvOperationalDatasetResponse = TlvObject({
+        operationalDataset: TlvField(0, TlvByteString.bound({ maxLength: 254 }))
+    });
+
+    /**
+     * Contains the Thread Operational Dataset for the Extended PAN specified in GetOperationalDataset.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.4
+     */
+    export interface OperationalDatasetResponse extends TypeFromSchema<typeof TlvOperationalDatasetResponse> {}
+
+    /**
+     * @see {@link Cluster}
+     */
+    export const ClusterInstance = MutableCluster({
+        id: 0x453,
+        name: "ThreadNetworkDirectory",
+        revision: 1,
+
+        attributes: {
+            /**
+             * Indicates the Thread Extended PAN ID value for the Thread network designated by the user to be their
+             * preferred network for commissioning of Thread devices. If not null, the value of this attribute shall
+             * match the ExtendedPanID of a network in the ThreadNetworks attribute. A write operation with a non-null
+             * value that does not match any network in the ThreadNetworks list shall be rejected with a status of
+             * CONSTRAINT_ERROR.
+             *
+             * The purpose of designating one Thread network as preferred is to help a commissioner to select a Thread
+             * network when a Thread device is within suitable range of more than one Thread network which appears in
+             * the ThreadNetworks list. A value of null indicates that there is no current preferred network: All
+             * networks may be treated as equally preferred by a commissioner with access to this cluster.
+             *
+             * This attribute may be automatically set to the ExtendedPanID of the first Thread network added to the
+             * ThreadNetworks list.
+             *
+             * A client shall obtain user consent before changing the value of this attribute from a non-null value.
+             *
+             * On a factory reset this attribute shall be reset to null.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.5.1
+             */
+            preferredExtendedPanId: WritableAttribute(
+                0x0,
+                TlvNullable(TlvByteString.bound({ length: 8 })),
+                { persistent: true, default: null, writeAcl: AccessLevel.Manage }
+            ),
+
+            /**
+             * Indicates the list of Thread Networks known about by this cluster. If the node hosting this cluster
+             * includes a Thread Border Router, then an entry for its Thread Network shall be included in this list.
+             *
+             * The list can be modified via the AddNetwork and RemoveNetwork commands.
+             *
+             * For each entry in the list, the cluster server also stores a Thread Operational Dataset. Clients use the
+             * GetOperationalDataset command to obtain the Operational Dataset for an entry in this list.
+             *
+             * On a factory reset this list shall be cleared, and any Thread Operational datasets previously stored
+             * shall be removed from the Node.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.5.2
+             */
+            threadNetworks: Attribute(0x1, TlvArray(TlvThreadNetwork), { persistent: true, default: [] }),
+
+            /**
+             * Indicates the maximum number of entries that can be held in the ThreadNetworks list; it shall be at
+             * least 2 times the number of SupportedFabrics advertised in the Operational Credentials Cluster on the
+             * root endpoint of this node.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.5.3
+             */
+            threadNetworkTableSize: FixedAttribute(0x2, TlvUInt8, { default: 10 })
+        },
+
+        commands: {
+            /**
+             * Adds an entry to the ThreadNetworks attribute with the specified Thread Operational Dataset.
+             *
+             * If there is an existing entry with the Extended PAN ID then the Thread Operational Dataset for that
+             * entry is replaced. As a result, changes to the network parameters (e.g. Channel, Network Name, PSKc, …)
+             * of an existing entry with a given Extended PAN ID can be made using this command.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.1
+             */
+            addNetwork: Command(
+                0x0,
+                TlvAddNetworkRequest,
+                0x0,
+                TlvNoResponse,
+                { invokeAcl: AccessLevel.Manage, timed: true }
+            ),
+
+            /**
+             * Removes the network with the given Extended PAN ID from the ThreadNetworks attribute.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.2
+             */
+            removeNetwork: Command(
+                0x1,
+                TlvRemoveNetworkRequest,
+                0x1,
+                TlvNoResponse,
+                { invokeAcl: AccessLevel.Manage, timed: true }
+            ),
+
+            /**
+             * Retrieves the Thread Operational Dataset with the given Extended PAN ID.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 10.4.6.3
+             */
+            getOperationalDataset: Command(
+                0x2,
+                TlvGetOperationalDatasetRequest,
+                0x3,
+                TlvOperationalDatasetResponse,
+                { invokeAcl: AccessLevel.Manage }
+            )
+        }
+    });
+
+    /**
+     * This cluster stores a list of Thread networks (including the credentials required to access each network), as
+     * well as a designation of the user’s preferred network, to facilitate the sharing of Thread networks across
+     * fabrics.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 10.4
+     */
+    export interface Cluster extends Identity<typeof ClusterInstance> {}
+
+    export const Cluster: Cluster = ClusterInstance;
+    export const Complete = Cluster;
+}
+
+export type ThreadNetworkDirectoryCluster = ThreadNetworkDirectory.Cluster;
+export const ThreadNetworkDirectoryCluster = ThreadNetworkDirectory.Cluster;
+ClusterRegistry.register(ThreadNetworkDirectory.Complete);

package/src/clusters/time-synchronization.ts

@@ -298,10 +298,9 @@ export namespace TimeSynchronization {
      */
     export const TlvSetTimeZoneResponse = TlvObject({
         /**
-         * 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 DSTOffsetsRequired field shall be set to false, otherwise it shall be set to true.
+         * 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
+         * DSTOffsetsRequired field shall be set to false, otherwise it shall be set to true.
          *
          * @see {@link MatterSpecification.v13.Core} § 11.17.9.4.1
          */
@@ -334,7 +333,15 @@ export namespace TimeSynchronization {
      *
      * @see {@link MatterSpecification.v13.Core} § 11.17.10.2
      */
-    export const TlvDstStatusEvent = TlvObject({ dstOffsetActive: TlvField(0, TlvBoolean) });
+    export const TlvDstStatusEvent = TlvObject({
+        /**
+         * Indicates whether the current DST offset is being applied (i.e, daylight savings time is applied, as opposed
+         * to standard time).
+         *
+         * @see {@link MatterSpecification.v13.Core} § 11.17.10.2.1
+         */
+        dstOffsetActive: TlvField(0, TlvBoolean)
+    });
 
     /**
      * Body of the TimeSynchronization dstStatus event
@@ -513,14 +520,14 @@ export namespace TimeSynchronization {
         utcTime: TlvField(0, TlvEpochUs),
 
         /**
-         * This shall give the Client’s Granularity, as described in Section 11.17.8.2, “Granularity Attribute”.
+         * This shall give the Client’s Granularity, as described in Granularity.
          *
          * @see {@link MatterSpecification.v13.Core} § 11.17.9.1.2
          */
         granularity: TlvField(1, TlvEnum<Granularity>()),
 
         /**
-         * This shall give the Client’s TimeSource, as described in Section 11.17.8.3, “TimeSource Attribute”.
+         * This shall give the Client’s TimeSource, as described in TimeSource.
          *
          * @see {@link MatterSpecification.v13.Core} § 11.17.9.1.3
          */
@@ -551,8 +558,9 @@ export namespace TimeSynchronization {
         attributes: {
             /**
              * A Node ID, endpoint, and associated fabric index of a Node that may be used as trusted time source. See
-             * 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.
+             * 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.v13.Core} § 11.17.8.4
              */
@@ -561,11 +569,14 @@ export namespace TimeSynchronization {
 
         commands: {
             /**
-             * This command shall 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.
+             * This command shall 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.v13.Core} § 11.17.9.2
              */
@@ -658,7 +669,6 @@ export namespace TimeSynchronization {
              * 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
@@ -780,7 +790,8 @@ export namespace TimeSynchronization {
              * 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.
+             *
+             * RESOURCE_EXHAUSTED.
              *
              *   • Else if the list entries do not conform to the list requirements for DSTOffset attribute, the node
              *     shall respond with CONSTRAINT_ERROR.
@@ -815,11 +826,6 @@ export namespace TimeSynchronization {
             /**
              * This event shall be generated when the node starts or stops applying a DST offset.
              *
-             * DSTOffsetActive
-             *
-             * Indicates whether the current DST offset is being applied (i.e, daylight savings time is applied, as
-             * opposed to standard time).
-             *
              * @see {@link MatterSpecification.v13.Core} § 11.17.10.2
              */
             dstStatus: Event(0x1, EventPriority.Info, TlvDstStatusEvent),
@@ -944,8 +950,9 @@ export namespace TimeSynchronization {
              * 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.
+             * 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

package/src/clusters/unit-localization.ts

@@ -100,10 +100,9 @@ export namespace UnitLocalization {
 
     /**
      * Nodes should be expected to be deployed to any and all regions of the world. These global regions may have
-     * differing preferences for the units in which values are conveyed in communication to a
-     *
-     * user. As such, Nodes that visually or audibly convey measurable values to the user need a mechanism by which
-     * they can be configured to use a user’s preferred unit.
+     * differing preferences for the units in which values are conveyed in communication to a user. As such, Nodes that
+     * visually or audibly convey measurable values to the user need a mechanism by which they can be configured to use
+     * a user’s preferred unit.
      *
      * This cluster supports an interface to a Node. It provides attributes for determining and configuring the units
      * that a Node shall utilize when conveying values in communication to a user.

package/src/clusters/user-label.ts

@@ -39,7 +39,8 @@ export namespace UserLabel {
     });
 
     /**
-     * This cluster provides a feature to tag an endpoint with zero or more labels.
+     * This cluster is derived from the Label cluster and provides a feature to tag an endpoint with zero or more
+     * writable labels.
      *
      * @see {@link MatterSpecification.v13.Core} § 9.9
      */