From e175d46494cbea912b19d78f3dd90b27ba64a232 Mon Sep 17 00:00:00 2001
From: James Swan <122404367+swan-amazon@users.noreply.github.com>
Date: Mon, 29 Jul 2024 20:49:14 +0000
Subject: [PATCH] Add TC feature definitions to General Commissioning Cluster
 XML files

This commit introduces the "Terms and Conditions" (TC) feature
definitions to the General Commissioning Cluster XML data model files.
The changes include new attributes, commands, and commissioning errors
related to the TC feature.

Changes include:
- Added TC feature definition with bitmask.
- Introduced new commissioning errors related to TC:
  - RequiredTCNotAccepted
  - TCAcknowledgementsNotReceived
  - TCMinVersionNotMet
- Added new attributes for TC:
  - TCAcceptedVersion
  - TCMinRequiredVersion
  - TCAcknowledgements
  - TCAcknowledgementsRequired
- Added new commands for TC acknowledgements:
  - SetTCAcknowledgements
  - SetTCAcknowledgementsResponse

These changes only modify the XML files. A follow-up commit will
regenerate the necessary files.
---
 .../clusters/GeneralCommissioningCluster.xml  | 93 ++++++++++++-------
 .../chip/general-commissioning-cluster.xml    | 40 +++++++-
 2 files changed, 100 insertions(+), 33 deletions(-)

diff --git a/data_model/master/clusters/GeneralCommissioningCluster.xml b/data_model/master/clusters/GeneralCommissioningCluster.xml
index ed10afa8406a5a..ad6c3484aa9835 100644
--- a/data_model/master/clusters/GeneralCommissioningCluster.xml
+++ b/data_model/master/clusters/GeneralCommissioningCluster.xml
@@ -65,7 +65,7 @@ Davis, CA 95616, USA
   </clusterIds>
   <classification hierarchy="base" role="utility" picsCode="CGEN" scope="Node"/>
   <features>
-    <feature bit="0" code="TC" name="Terms" summary="Supports Terms &amp; Conditions acknowledgement">
+    <feature bit="0" code="TC" name="Terms and Conditions" summary="Supports Terms and Conditions acknowledgement">
       <optionalConform/>
     </feature>
   </features>
@@ -87,19 +87,28 @@ Davis, CA 95616, USA
         <mandatoryConform/>
       </item>
       <item value="5" name="RequiredTCNotAccepted" summary="[[ref_RequiredTCNotAccepted]] One or more required TC features from the Enhanced Setup Flow were not accepted.">
-        <mandatoryConform>
-          <feature name="TC"/>
-        </mandatoryConform>
+        <otherwiseConform>
+          <provisionalConform/>
+          <mandatoryConform>
+            <feature name="TC"/>
+          </mandatoryConform>
+        </otherwiseConform>
       </item>
       <item value="6" name="TCAcknowledgementsNotReceived" summary="[[ref_TCAcknowledgementsNotReceived]] No acknowledgements from the user for the TC features were received.">
-        <mandatoryConform>
-          <feature name="TC"/>
-        </mandatoryConform>
+        <otherwiseConform>
+          <provisionalConform/>
+          <mandatoryConform>
+            <feature name="TC"/>
+          </mandatoryConform>
+        </otherwiseConform>
       </item>
       <item value="7" name="TCMinVersionNotMet" summary="[[ref_TCMinVersionNotMet]] The version of the TC features acknowledged by the user did not meet the minimum required version.">
-        <mandatoryConform>
-          <feature name="TC"/>
-        </mandatoryConform>
+        <otherwiseConform>
+          <provisionalConform/>
+          <mandatoryConform>
+            <feature name="TC"/>
+          </mandatoryConform>
+        </otherwiseConform>
       </item>
     </enum>
     <enum name="RegulatoryLocationTypeEnum">
@@ -150,27 +159,43 @@ Davis, CA 95616, USA
     </attribute>
     <attribute id="0x0005" name="TCAcceptedVersion" type="uint16">
       <access read="true" readPrivilege="admin"/>
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+      <quality changeOmitted="false" nullable="false" scene="false" persistence="fixed" reportable="false"/>
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
     </attribute>
     <attribute id="0x0006" name="TCMinRequiredVersion" type="uint16">
       <access read="true" readPrivilege="admin"/>
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+      <quality changeOmitted="false" nullable="false" scene="false" persistence="fixed" reportable="false"/>
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
     </attribute>
     <attribute id="0x0007" name="TCAcknowledgements" type="map16">
       <access read="true" readPrivilege="admin"/>
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+      <quality changeOmitted="false" nullable="false" scene="false" persistence="fixed" reportable="false"/>
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
     </attribute>
     <attribute id="0x0008" name="TCAcknowledgementsRequired" type="bool" default="true">
       <access read="true" readPrivilege="admin"/>
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+      <quality changeOmitted="false" nullable="false" scene="false" persistence="fixed" reportable="false"/>
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
     </attribute>
   </attributes>
   <commands>
@@ -231,10 +256,13 @@ Davis, CA 95616, USA
       </field>
     </command>
     <command id="0x06" name="SetTCAcknowledgements" direction="commandToServer" response="SetTCAcknowledgementsResponse">
-      <access invokePrivilege="admin"/>
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+      <access invokePrivilege="admin" fabricScoped="true"/>
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
       <field id="0" name="TCVersion" type="uint16">
         <mandatoryConform/>
       </field>
@@ -242,13 +270,16 @@ Davis, CA 95616, USA
         <mandatoryConform/>
       </field>
     </command>
-    <command id="0x07" name="SetTCAcknowledgementsResponse" direction="responseFromServer">
-      <mandatoryConform>
-        <feature name="TC"/>
-      </mandatoryConform>
+    <command id="0x05" name="SetTCAcknowledgementsResponse" direction="responseFromServer">
+      <otherwiseConform>
+        <provisionalConform/>
+        <mandatoryConform>
+          <feature name="TC"/>
+        </mandatoryConform>
+      </otherwiseConform>
       <field id="0" name="ErrorCode" type="CommissioningErrorEnum" default="OK">
         <mandatoryConform/>
       </field>
     </command>
   </commands>
-</cluster>
\ No newline at end of file
+</cluster>
diff --git a/src/app/zap-templates/zcl/data-model/chip/general-commissioning-cluster.xml b/src/app/zap-templates/zcl/data-model/chip/general-commissioning-cluster.xml
index eabc56a4d95916..da813b60fef2e4 100644
--- a/src/app/zap-templates/zcl/data-model/chip/general-commissioning-cluster.xml
+++ b/src/app/zap-templates/zcl/data-model/chip/general-commissioning-cluster.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!--
-Copyright (c) 2021 Project CHIP Authors
+Copyright (c) 2021-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.
@@ -23,6 +23,9 @@ limitations under the License.
     <item name="InvalidAuthentication" value="0x2"/>
     <item name="NoFailSafe" value="0x3"/>
     <item name="BusyWithOtherAdmin" value="0x4"/>
+    <item name="RequiredTCNotAccepted" value="0x5" apiMaturity="provisional"/>
+    <item name="TCAcknowledgementsNotReceived" value="0x6" apiMaturity="provisional"/>
+    <item name="TCMinVersionNotMet" value="0x7" apiMaturity="provisional"/>
   </enum>
   <enum name="RegulatoryLocationTypeEnum" type="enum8">
     <cluster code="0x0030"/>
@@ -41,6 +44,14 @@ limitations under the License.
     <code>0x0030</code>
     <define>GENERAL_COMMISSIONING_CLUSTER</define>
     <description>This cluster is used to manage global aspects of the Commissioning flow.</description>
+    <features>
+      <feature bit="0" code="TC" name="TermsAndConditions" summary="Supports Terms and Conditions acknowledgement" apiMaturity="provisional">
+        <otherwiseConform>
+          <provisionalConform/>
+          <optionalConform/>
+        </otherwiseConform>
+      </feature>
+    </features>
     <attribute side="server" code="0x00" define="BREADCRUMB" type="int64u" writable="true" default="0x0000000000000000" optional="false">
       <description>Breadcrumb</description>
       <access op="read" privilege="view"/>
@@ -50,7 +61,22 @@ limitations under the License.
     <attribute side="server" code="0x02" define="REGULATORY_CONFIG" type="RegulatoryLocationTypeEnum" writable="false" optional="false">RegulatoryConfig</attribute>
     <attribute side="server" code="0x03" define="LOCATION_CAPABILITY" type="RegulatoryLocationTypeEnum" writable="false" optional="false">LocationCapability</attribute>
     <attribute side="server" code="0x04" define="SUPPORTS_CONCURRENT_CONNECTION" type="boolean" writable="false" default="1" optional="false">SupportsConcurrentConnection</attribute>
-
+    <attribute side="server" code="0x05" define="TC_ACCEPTED_VERSION" type="int16u" writable="false" optional="true" apiMaturity="provisional">
+      <description>TCAcceptedVersion</description>
+      <access op="read" privilege="administer"/>
+    </attribute>
+    <attribute side="server" code="0x06" define="TC_MIN_REQUIRED_VERSION" type="int16u" writable="false" optional="true" apiMaturity="provisional">
+      <description>TCMinRequiredVersion</description>
+      <access op="read" privilege="administer"/>
+    </attribute>
+    <attribute side="server" code="0x07" define="TC_ACKNOWLEDGEMENTS" type="bitmap16" writable="false" default="0x0000" optional="true" apiMaturity="provisional">
+      <description>TCAcknowledgements</description>
+      <access op="read" privilege="administer"/>
+    </attribute>
+    <attribute side="server" code="0x08" define="TC_ACKNOWLEDGEMENTS_REQUIRED" type="boolean" writable="false" optional="true" apiMaturity="provisional">
+      <description>TCAcknowledgementsRequired</description>
+      <access op="read" privilege="administer"/>
+    </attribute>
     <command source="client" code="0x00" name="ArmFailSafe" response="ArmFailSafeResponse" optional="false" cli="chip fabric_commissioning armfailsafe">
       <description>Arm the persistent fail-safe timer with an expiry time of now + ExpiryLengthSeconds using device clock</description>
       <arg name="ExpiryLengthSeconds" type="int16u"/>
@@ -83,5 +109,15 @@ limitations under the License.
       <arg name="ErrorCode" type="CommissioningErrorEnum"/>
       <arg name="DebugText" type="char_string"/>
     </command>
+    <command source="client" code="0x06" name="SetTCAcknowledgements" optional="true" response="SetTCAcknowledgementsResponse" cli="chip fabric_commissioning settcacknowledgements" apiMaturity="provisional">
+      <description>This command sets the user acknowledgements received in the Enhanced Setup Flow Terms and Conditions into the node.</description>
+      <arg name="TCVersion" type="int16u"/>
+      <arg name="TCUserResponse" type="bitmap16"/>
+      <access op="invoke" privilege="administer"/>
+    </command>
+    <command source="server" code="0x07" name="SetTCAcknowledgementsResponse" optional="true" cli="chip fabric_commissioning settcacknowledgementsresponse" apiMaturity="provisional">
+      <description>This command is used to convey the result from SetTCAcknowledgements.</description>
+      <arg name="ErrorCode" type="CommissioningErrorEnum"/>
+    </command>
   </cluster>
 </configurator>