Add XML definition for Commissioner Control Cluster (#34242)

* Add xml defination for Commissioner Control Cluster * Address review comments
project-chip · Oct 15, 2024 · f1d192c · f1d192c
1 parent bb3b642
commit f1d192c
Show file tree

Hide file tree

Showing 53 changed files with 5,647 additions and 0 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -112,6 +112,7 @@ jobs:
                       src/app/zap-templates/zcl/data-model/chip/channel-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/clusters-extensions.xml \
                       src/app/zap-templates/zcl/data-model/chip/color-control-cluster.xml \
+                      src/app/zap-templates/zcl/data-model/chip/commissioner-control-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/concentration-measurement-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/content-launch-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/content-app-observer-cluster.xml \

diff --git a/docs/zap_clusters.md b/docs/zap_clusters.md
@@ -131,6 +131,7 @@ Generally regenerate using one of:
 |       1294 |      0x50E | AccountLogin                                            |
 |       1295 |      0x50F | ContentControl                                          |
 |       1296 |      0x510 | ContentAppObserver                                      |
+|       1873 |      0x751 | CommissionerControl                                     |
 |       2820 |      0xB04 | ElectricalMeasurement                                   |
 | 4294048773 | 0xFFF1FC05 | UnitTesting                                             |
 | 4294048774 | 0xFFF1FC06 | FaultInjection                                          |

diff --git a/scripts/rules.matterlint b/scripts/rules.matterlint
@@ -19,6 +19,7 @@ load "../src/app/zap-templates/zcl/data-model/chip/chip-ota.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/chip-types.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/clusters-extensions.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/color-control-cluster.xml";
+load "../src/app/zap-templates/zcl/data-model/chip/commissioner-control-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/concentration-measurement-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/content-launch-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/content-app-observer-cluster.xml";

diff --git a/src/app/zap-templates/zcl/data-model/all.xml b/src/app/zap-templates/zcl/data-model/all.xml
@@ -18,6 +18,7 @@
    <xi:include href="chip/chip-types.xml" />
    <xi:include href="chip/clusters-extensions.xml" />
    <xi:include href="chip/color-control-cluster.xml" />
+   <xi:include href="chip/commissioner-control-cluster.xml" />
    <xi:include href="chip/concentration-measurement-cluster.xml" />
    <xi:include href="chip/content-launch-cluster.xml" />
    <xi:include href="chip/descriptor-cluster.xml" />

diff --git a/src/app/zap-templates/zcl/data-model/chip/commissioner-control-cluster.xml b/src/app/zap-templates/zcl/data-model/chip/commissioner-control-cluster.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!--
+Copyright (c) 2024 Project CHIP Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<configurator>
+  <domain name="CHIP"/>
+  <bitmap name="SupportedDeviceCategoryBitmap" type="bitmap32">
+    <cluster code="0x0751"/>
+    <field name="FabricSynchronization" mask="0x1"/>
+  </bitmap>
+
+  <cluster apiMaturity="provisional">
+    <domain>General</domain>
+    <name>Commissioner Control</name>
+    <code>0x0751</code>
+    <define>COMMISSIONER_CONTROL_CLUSTER</define>
+    <client init="false" tick="false">true</client>
+    <server init="false" tick="false">true</server>
+    <description>Supports the ability for clients to request the commissioning of themselves or other nodes onto a fabric which the cluster server can commission onto.</description>
+
+    <!-- cluster revision -->
+    <globalAttribute side="either" code="0xFFFD" value="1"/>
+    <attribute side="server" code="0x0000" define="SUPPORTED_DEVICE_CATEGORIES" type="SupportedDeviceCategoryBitmap" default="0" min="0x00000000" max="0x00000001">
+      <description>SupportedDeviceCategories</description>
+      <access op="read" privilege="manage"/>
+    </attribute>
+
+    <command source="client" code="0x00" name="RequestCommissioningApproval" optional="false">
+      <description>This command is sent by a client to request approval for a future CommissionNode call.</description>
+      <arg id="0" name="RequestId" type="int64u"/>
+      <arg id="1" name="VendorId" type="vendor_id"/>
+      <arg id="2" name="ProductId" type="int16u"/>
+      <arg id="3" name="Label" type="char_string" optional="true" length="64"/>
+      <access op="invoke" privilege="manage"/>
+    </command>
+
+    <command source="client" code="0x01" name="CommissionNode" response="ReverseOpenCommissioningWindow" optional="false">
+      <description>This command is sent by a client to request that the server begins commissioning a previously approved request.</description>
+      <arg id="0" name="RequestId" type="int64u"/>
+      <arg id="2" name="ResponseTimeoutSeconds" type="int16u" min="30" max="120" default="30"/>
+      <arg id="3" name="IpAddress" type="octet_string" optional="true" min="4" max="16"/>
+      <!-- Note: ipadr is not supported yet, use its base type (octet_string) here -->
+      <arg id="4" name="Port" type="int16u" optional="true"/>
+      <access op="invoke" privilege="manage"/>
+    </command>
+
+    <command source="server" code="0x02" name="ReverseOpenCommissioningWindow" optional="false">
+      <description>When received within the timeout specified by CommissionNode, the client SHALL open a commissioning window on to the node which the client called RequestCommissioningApproval to have commissioned.</description>
+      <arg id="0" name="CommissioningTimeout" type="int16u"/>
+      <arg id="1" name="PAKEPasscodeVerifier" type="octet_string"/>
+      <arg id="2" name="Discriminator" type="int16u" min="0" max="4095"/>
+      <arg id="3" name="Iterations" type="int32u" min="1000" max="100000"/>
+      <arg id="4" name="Salt" type="octet_string" length="32" minLength="16"/>
+    </command>
+
+    <event code="0x00" name="CommissioningRequestResult" priority="info" side="server" isFabricSensitive="true">
+      <description>This event SHALL be sent by the server following a RequestCommissioningApproval command which the server responded to with SUCCESS.</description>
+      <field id="0" name="RequestId" type="int64u"/>
+      <field id="1" name="ClientNodeId" type="node_id"/>
+      <field id="2" name="StatusCode" type="enum8"/>
+      <access op="read" privilege="manage"/>
+    </event>
+
+  </cluster>
+</configurator>
diff --git a/src/app/zap-templates/zcl/zcl-with-test-extensions.json b/src/app/zap-templates/zcl/zcl-with-test-extensions.json
@@ -33,6 +33,7 @@
         "channel-cluster.xml",
         "clusters-extensions.xml",
         "color-control-cluster.xml",
+        "commissioner-control-cluster.xml",
         "concentration-measurement-cluster.xml",
         "content-launch-cluster.xml",
         "content-app-observer-cluster.xml",

diff --git a/src/app/zap-templates/zcl/zcl.json b/src/app/zap-templates/zcl/zcl.json
@@ -32,6 +32,7 @@
         "channel-cluster.xml",
         "clusters-extensions.xml",
         "color-control-cluster.xml",
+        "commissioner-control-cluster.xml",
         "concentration-measurement-cluster.xml",
         "content-launch-cluster.xml",
         "content-app-observer-cluster.xml",

diff --git a/src/app/zap_cluster_list.json b/src/app/zap_cluster_list.json
@@ -23,6 +23,7 @@
         "CHANNEL_CLUSTER": [],
         "CLIENT_MONITORING_CLUSTER": [],
         "COLOR_CONTROL_CLUSTER": [],
+        "COMMISSIONER_CONTROL_CLUSTER": [],
         "COMMISSIONING_CLUSTER": [],
         "CONTENT_LAUNCHER_CLUSTER": [],
         "CONTENT_CONTROL_CLUSTER": [],
@@ -168,6 +169,7 @@
         ],
         "CHANNEL_CLUSTER": ["channel-server"],
         "COLOR_CONTROL_CLUSTER": ["color-control-server"],
+        "COMMISSIONER_CONTROL_CLUSTER": ["commissioner-control-server"],
         "COMMISSIONING_CLUSTER": [],
         "CONTENT_LAUNCHER_CLUSTER": ["content-launch-server"],
         "CONTENT_CONTROL_CLUSTER": ["content-control-server"],

diff --git a/src/controller/data_model/controller-clusters.matter b/src/controller/data_model/controller-clusters.matter
@@ -9195,6 +9195,57 @@ provisional cluster ContentAppObserver = 1296 {
   command ContentAppMessage(ContentAppMessageRequest): ContentAppMessageResponse = 0;
 }
 
+/** Supports the ability for clients to request the commissioning of themselves or other nodes onto a fabric which the cluster server can commission onto. */
+provisional cluster CommissionerControl = 1873 {
+  revision 1;
+
+  bitmap SupportedDeviceCategoryBitmap : bitmap32 {
+    kFabricSynchronization = 0x1;
+  }
+
+  fabric_sensitive info event access(read: manage) CommissioningRequestResult = 0 {
+    int64u requestId = 0;
+    node_id clientNodeId = 1;
+    enum8 statusCode = 2;
+    fabric_idx fabricIndex = 254;
+  }
+
+  readonly attribute access(read: manage) SupportedDeviceCategoryBitmap supportedDeviceCategories = 0;
+  readonly attribute command_id generatedCommandList[] = 65528;
+  readonly attribute command_id acceptedCommandList[] = 65529;
+  readonly attribute event_id eventList[] = 65530;
+  readonly attribute attrib_id attributeList[] = 65531;
+  readonly attribute bitmap32 featureMap = 65532;
+  readonly attribute int16u clusterRevision = 65533;
+
+  request struct RequestCommissioningApprovalRequest {
+    int64u requestId = 0;
+    vendor_id vendorId = 1;
+    int16u productId = 2;
+    optional char_string<64> label = 3;
+  }
+
+  request struct CommissionNodeRequest {
+    int64u requestId = 0;
+    int16u responseTimeoutSeconds = 1;
+    optional octet_string ipAddress = 2;
+    optional int16u port = 3;
+  }
+
+  response struct ReverseOpenCommissioningWindow = 2 {
+    int16u commissioningTimeout = 0;
+    octet_string PAKEPasscodeVerifier = 1;
+    int16u discriminator = 2;
+    int32u iterations = 3;
+    octet_string<32> salt = 4;
+  }
+
+  /** This command is sent by a client to request approval for a future CommissionNode call. */
+  command access(invoke: manage) RequestCommissioningApproval(RequestCommissioningApprovalRequest): DefaultSuccess = 0;
+  /** This command is sent by a client to request that the server begins commissioning a previously approved request. */
+  command access(invoke: manage) CommissionNode(CommissionNodeRequest): ReverseOpenCommissioningWindow = 1;
+}
+
 /** Attributes related to the electrical properties of a device. This cluster is used by power outlets and other devices that need to provide instantaneous data as opposed to metrology data which should be retrieved from the metering cluster.. */
 deprecated cluster ElectricalMeasurement = 2820 {
   revision 3;