/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ /*** THIS FILE IS GENERATED, DO NOT EDIT ***/ import { Resource } from "#models/Resource.js"; Resource.add({ tag: "cluster", name: "AdministratorCommissioning", pics: "CADMIN", xref: "core§11.19", details: "This cluster is used to trigger a Node to allow a new Administrator to commission it. It defines " + "Attributes, Commands and Responses needed for this purpose." + "\n" + "There are two methods of commissioning, Basic Commissioning which may be supported and is described " + "in Section 5.6.2, \"Basic Commissioning Method (BCM)\" and Enhanced Commissioning which shall be " + "supported and is described in Section 5.6.3, \"Enhanced Commissioning Method (ECM)\"." + "\n" + "For the management of Operational Credentials and Trusted Root Certificates, the Operational " + "Credentials cluster is used." + "\n" + "If the Administrator Commissioning Cluster server instance is present on an endpoint with the Root " + "Node device type in the Descriptor cluster DeviceTypeList, then:" + "\n" + " - The Commissioning Window shall be opened or closed on the node that the Root Node endpoint is " + "on." + "\n" + " - The attributes shall indicate the state of the node that the Root Node endpoint is on." + "\n" + "If the Administrator Commissioning Cluster server instance is present on an endpoint with the " + "Bridged Node device type in the Descriptor cluster DeviceTypeList, then:" + "\n" + " - The Commissioning Window shall be opened or closed on the node represented by the Bridged Node." + "\n" + " - The attributes shall indicate the state of the node that is represented by the Bridged Node.", children: [ { tag: "attribute", name: "FeatureMap", xref: "core§11.19.4", children: [{ tag: "field", name: "BC", details: "Node supports Basic Commissioning Method" }] }, { tag: "attribute", name: "WindowStatus", xref: "core§11.19.7.1", details: "Indicates whether a new Commissioning window has been opened by an Administrator, using either the " + "OpenCommissioningWindow command or the OpenBasicCommissioningWindow command." + "\n" + "This attribute shall revert to WindowNotOpen upon expiry of a commissioning window." + "\n" + "> [!NOTE]" + "\n" + "> NOTE: An initial commissioning window is not opened using either the OpenCommissioningWindow " + "command or the OpenBasicCommissioningWindow command, and therefore this attribute shall be set to " + "WindowNotOpen on initial commissioning." }, { tag: "attribute", name: "AdminFabricIndex", xref: "core§11.19.7.2", details: "When the WindowStatus attribute is not set to WindowNotOpen, this attribute shall indicate the " + "FabricIndex associated with the Fabric scoping of the Administrator that opened the window. This may " + "be used to cross-reference in the Fabrics attribute of the Operational Credentials cluster." + "\n" + "If, during an open commissioning window, the fabric for the Administrator that opened the window is " + "removed, then this attribute shall be set to null." + "\n" + "When the WindowStatus attribute is set to WindowNotOpen, this attribute shall be set to null." }, { tag: "attribute", name: "AdminVendorId", xref: "core§11.19.7.3", details: "When the WindowStatus attribute is not set to WindowNotOpen, this attribute shall indicate the " + "Vendor ID associated with the Fabric scoping of the Administrator that opened the window. This field " + "shall match the VendorID field of the Fabrics attribute list entry associated with the Administrator " + "having opened the window, at the time of window opening. If the fabric for the Administrator that " + "opened the window is removed from the node while the commissioning window is still open, this " + "attribute shall NOT be updated." + "\n" + "When the WindowStatus attribute is set to WindowNotOpen, this attribute shall be set to null." }, { tag: "command", name: "OpenCommissioningWindow", xref: "core§11.19.8.1", details: "This command is used by a current Administrator to instruct a Node to go into commissioning mode. " + "The Enhanced Commissioning Method specifies a window of time during which an already commissioned " + "Node accepts PASE sessions. The current Administrator shall specify a timeout value for the duration " + "of the OpenCommissioningWindow command." + "\n" + "When the OpenCommissioningWindow command expires or commissioning completes, the Node shall remove " + "the Passcode by deleting the PAKE passcode verifier as well as stop publishing the DNS-SD record " + "corresponding to this command as described in Section 4.3.1, \"Commissionable Node Discovery\". The " + "commissioning into a new Fabric completes when the Node successfully receives a Section 11.10.7.6, " + "\"CommissioningComplete\" command, see Section 5.5, \"Commissioning Flows\"." + "\n" + "The parameters for OpenCommissioningWindow command are as follows:" + "\n" + "A current Administrator may invoke this command to put a node in commissioning mode for the next " + "Administrator. On completion, the command shall return a cluster specific status code from the " + "Section 11.19.6, \"Status Codes\" below reflecting success or reasons for failure of the operation. " + "The new Administrator shall discover the Node on the IP network using DNS-based Service Discovery " + "(DNS-SD) for commissioning." + "\n" + "If any format or validity errors related to the PAKEPasscodeVerifier, Iterations or Salt arguments " + "arise, this command shall fail with a cluster specific status code of PAKEParameterError." + "\n" + "If a commissioning window is already currently open, this command shall fail with a cluster specific " + "status code of Busy." + "\n" + "If the fail-safe timer is currently armed, this command shall fail with a cluster specific status " + "code of Busy, since it is likely that concurrent commissioning operations from multiple separate " + "Commissioners are about to take place." + "\n" + "In case of any other parameter error, this command shall fail with a status code of COMMAND_INVALID.", children: [ { tag: "field", name: "CommissioningTimeout", xref: "core§11.19.8.1.1", details: "This field shall specify the time in seconds during which commissioning session establishment is " + "allowed by the Node. This timeout value shall follow guidance as specified in the initial Section " + "5.4.2.3, \"Announcement Duration\". The CommissioningTimeout applies only to cessation of any " + "announcements and to accepting of new commissioning sessions; it does not apply to abortion of " + "connections, i.e., a commissioning session SHOULD NOT abort prematurely upon expiration of this " + "timeout." }, { tag: "field", name: "PakePasscodeVerifier", xref: "core§11.19.8.1.2", details: "This field shall specify an ephemeral PAKE passcode verifier (see Section 3.10, " + "\"Password-Authenticated Key Exchange (PAKE)\") computed by the existing Administrator to be used for " + "this commissioning. The field is concatenation of two values (w0 || L) shall be " + "(CRYPTO_GROUP_SIZE_BYTES + CRYPTO_PUBLIC_KEY_SIZE_BYTES)-octets long as detailed in " + "Crypto_PAKEValues_Responder. It shall be derived from an ephemeral passcode (See PAKE). It shall be " + "deleted by the Node at the end of commissioning or expiration of the OpenCommissioningWindow " + "command, and shall be deleted by the existing Administrator after sending it to the Node(s)." }, { tag: "field", name: "Discriminator", xref: "core§11.19.8.1.3", details: "This field shall be used by the Node as the long discriminator for DNS-SD advertisement (see Section " + "4.3.1.5, \"TXT key for discriminator (D)\") for discovery by the new Administrator. The new " + "Administrator can find and filter DNS-SD records by long discriminator to locate and initiate " + "commissioning with the appropriate Node." }, { tag: "field", name: "Iterations", xref: "core§11.19.8.1.4", details: "This field shall be used by the Node as the PAKE iteration count associated with the ephemeral PAKE " + "passcode verifier to be used for this commissioning, which shall be sent by the Node to the new " + "Administrator's software as response to the Section 4.14.1.2.3, \"PBKDFParamRequest\" during PASE " + "negotiation. The permitted range of values shall match the range specified in Section 3.9, " + "\"Password-Based Key Derivation Function (PBKDF)\", within the definition of the " + "Crypto_PBKDFParameterSet." }, { tag: "field", name: "Salt", xref: "core§11.19.8.1.5", details: "This field shall be used by the Node as the PAKE Salt associated with the ephemeral PAKE passcode " + "verifier to be used for this commissioning, which shall be sent by the Node to the new " + "Administrator's software as response to the Section 4.14.1.2.3, \"PBKDFParamRequest\" during PASE " + "negotiation. The constraints on the value shall match those specified in Section 3.9, " + "\"Password-Based Key Derivation Function (PBKDF)\", within the definition of the " + "Crypto_PBKDFParameterSet." + "\n" + "When a Node receives the Section 11.19.8.1, \"OpenCommissioningWindow\" command, it shall begin " + "advertising on DNS-SD as described in Section 4.3.1, \"Commissionable Node Discovery\" and for a time " + "period as described in Section 11.19.8.1.1, \"CommissioningTimeout\"." + "\n" + "When the command is received by a ICD, it shall enter into active mode. The ICD shall remain in " + "Active Mode as long as one of these conditions is met:" + "\n" + " - A commissioning window is open." + "\n" + " - There is an armed fail-safe timer." } ] }, { tag: "command", name: "OpenBasicCommissioningWindow", xref: "core§11.19.8.2", details: "This command may be used by a current Administrator to instruct a Node to go into commissioning " + "mode, if the node supports the Basic Commissioning Method. The Basic Commissioning Method specifies " + "a window of time during which an already commissioned Node accepts PASE sessions. The current " + "Administrator shall specify a timeout value for the duration of the OpenBasicCommissioningWindow " + "command." + "\n" + "If a commissioning window is already currently open, this command shall fail with a cluster specific " + "status code of Busy." + "\n" + "If the fail-safe timer is currently armed, this command shall fail with a cluster specific status " + "code of Busy, since it is likely that concurrent commissioning operations from multiple separate " + "Commissioners are about to take place." + "\n" + "In case of any other parameter error, this command shall fail with a status code of COMMAND_INVALID." + "\n" + "The commissioning into a new Fabric completes when the Node successfully receives a Section " + "11.10.7.6, \"CommissioningComplete\" command, see Section 5.5, \"Commissioning Flows\". The new " + "Administrator shall discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) " + "for commissioning.", children: [{ tag: "field", name: "CommissioningTimeout", xref: "core§11.19.8.2.1", details: "This field shall specify the time in seconds during which commissioning session establishment is " + "allowed by the Node. This timeout shall follow guidance as specified in the initial Section 5.4.2.3, " + "\"Announcement Duration\"." + "\n" + "When a Node receives the Section 11.19.8.2, \"OpenBasicCommissioningWindow\" command, it shall begin " + "advertising on DNS-SD as described in Section 4.3.1, \"Commissionable Node Discovery\" and for a time " + "period as described in Section 11.19.8.2.1, \"CommissioningTimeout\". When the command is received by " + "a ICD, it shall enter into active mode. The ICD shall remain in Active Mode as long as one of these " + "conditions is met:" + "\n" + " - A commissioning window is open." + "\n" + " - There is an armed fail-safe timer." }] }, { tag: "command", name: "RevokeCommissioning", xref: "core§11.19.8.3", details: "This command is used by a current Administrator to instruct a Node to revoke any active Section " + "11.19.8.1, \"OpenCommissioningWindow\" or Section 11.19.8.2, \"OpenBasicCommissioningWindow\" command. " + "This is an idempotent command." }, { tag: "datatype", name: "CommissioningWindowStatusEnum", xref: "core§11.19.5.1", children: [ { tag: "field", name: "WindowNotOpen", description: "Commissioning window not open" }, { tag: "field", name: "EnhancedWindowOpen", description: "An Enhanced Commissioning Method window is open" }, { tag: "field", name: "BasicWindowOpen", description: "A Basic Commissioning Method window is open" } ] }, { tag: "datatype", name: "StatusCodeEnum", xref: "core§11.19.6.1", children: [ { tag: "field", name: "Busy", description: "Could not be completed because another commissioning is in progress" }, { tag: "field", name: "PakeParameterError", description: "Provided PAKE parameters were incorrectly formatted or otherwise invalid" }, { tag: "field", name: "WindowNotOpen", description: "No commissioning window was currently open" } ] } ] });