Enable Terms and Conditions (TC) feature in all-clusters-app example

This commit enables the Terms and Conditions (TC) feature in the
all-clusters-app example application. The changes ensure that the app
can handle TC acknowledgements and enforce required terms and conditions
during the commissioning process.

Changes include:
- Added TC attributes and commands in the General Commissioning cluster.
- Enabled the TC feature in the application configuration.

This enables the TC feature logic in the example app, building on the
initial implementation.

examples/all-clusters-app/all-clusters-common/all-clusters-app.matter

@@ -7609,11 +7609,15 @@ endpoint 0 {
     callback attribute regulatoryConfig;
     callback attribute locationCapability;
     callback attribute supportsConcurrentConnection;
+    ram      attribute TCAcceptedVersion;
+    ram      attribute TCMinRequiredVersion default = 1;
+    ram      attribute TCAcknowledgements default = 0x0000;
+    ram      attribute TCAcknowledgementsRequired default = true;
     callback attribute generatedCommandList;
     callback attribute acceptedCommandList;
     callback attribute eventList;
     callback attribute attributeList;
-    ram      attribute featureMap default = 0;
+    ram      attribute featureMap default = 1;
     ram      attribute clusterRevision default = 1;
 
     handle command ArmFailSafe;
@@ -7622,6 +7626,8 @@ endpoint 0 {
     handle command SetRegulatoryConfigResponse;
     handle command CommissioningComplete;
     handle command CommissioningCompleteResponse;
+    handle command SetTCAcknowledgements;
+    handle command SetTCAcknowledgementsResponse;
   }
 
   server cluster NetworkCommissioning {

examples/all-clusters-app/all-clusters-common/all-clusters-app.zap

@@ -2124,6 +2124,7 @@
           "define": "GENERAL_COMMISSIONING_CLUSTER",
           "side": "server",
           "enabled": 1,
+          "apiMaturity": "provisional",
           "commands": [
             {
               "name": "ArmFailSafe",
@@ -2172,6 +2173,22 @@
               "source": "server",
               "isIncoming": 0,
               "isEnabled": 1
+            },
+            {
+              "name": "SetTCAcknowledgements",
+              "code": 6,
+              "mfgCode": null,
+              "source": "client",
+              "isIncoming": 1,
+              "isEnabled": 1
+            },
+            {
+              "name": "SetTCAcknowledgementsResponse",
+              "code": 7,
+              "mfgCode": null,
+              "source": "server",
+              "isIncoming": 0,
+              "isEnabled": 1
             }
           ],
           "attributes": [
@@ -2255,6 +2272,70 @@
               "maxInterval": 65534,
               "reportableChange": 0
             },
+            {
+              "name": "TCAcceptedVersion",
+              "code": 5,
+              "mfgCode": null,
+              "side": "server",
+              "type": "int16u",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCMinRequiredVersion",
+              "code": 6,
+              "mfgCode": null,
+              "side": "server",
+              "type": "int16u",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "1",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCAcknowledgements",
+              "code": 7,
+              "mfgCode": null,
+              "side": "server",
+              "type": "bitmap16",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "0x0000",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCAcknowledgementsRequired",
+              "code": 8,
+              "mfgCode": null,
+              "side": "server",
+              "type": "boolean",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "true",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
             {
               "name": "GeneratedCommandList",
               "code": 65528,
@@ -2329,7 +2410,7 @@
               "storageOption": "RAM",
               "singleton": 0,
               "bounded": 0,
-              "defaultValue": "0",
+              "defaultValue": "1",
               "reportable": 1,
               "minInterval": 1,
               "maxInterval": 65534,

examples/all-clusters-app/linux/include/CHIPProjectAppConfig.h

@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2022 Project CHIP Authors
+ *    Copyright (c) 2022-2024 Project CHIP Authors
  *    All rights reserved.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
@@ -51,3 +51,24 @@
 // Claim a device type while advertising that matches the device type on our
 // endpoint 1.  0x0101 is the "Dimmable Light" device type.
 #define CHIP_DEVICE_CONFIG_DEVICE_TYPE 0x0101
+
+/**
+ * @brief Configures the required terms and conditions acknowledgements.
+ *
+ * This macro defines the required terms and conditions acknowledgements bitmask. The bit-field is 16 bits long, so the possible
+ * value range is [0, 65535). This setting can be used to require that terms and conditions are presented to the user during
+ * commissioning.
+ */
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS 1 // Require that terms and conditions ordinal 1 must be accepted.
+
+/**
+ * @brief Configures the latest known version of the terms and conditions.
+ *
+ * This macro defines the version number of the latest terms and conditions. It allows the application to iterate on revisions of
+ * the terms and conditions. A value of 0 indicates that no specific version is required. This setting can be used to enforce
+ * version-specific terms and conditions acknowledgements in the application. When the set of terms and conditions needs to be
+ * changes, the version number should be monotomically increased. If the lateast terms and conditions version is updated (most
+ * likely during an OTA) then this may signal to the Administrator that updated terms and conditions should be presented to the
+ * user.
+ */
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS_VERSION 1 // The current terms and conditions revision is 1.

src/controller/AutoCommissioner.cpp

@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2021 Project CHIP Authors
+ *    Copyright (c) 2021-2024 Project CHIP Authors
  *    All rights reserved.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
@@ -365,6 +365,8 @@ CommissioningStage AutoCommissioner::GetNextCommissioningStageInternal(Commissio
     case CommissioningStage::kArmFailsafe:
         return CommissioningStage::kConfigRegulatory;
     case CommissioningStage::kConfigRegulatory:
+        return CommissioningStage::kConfigureTCAcknowledgments;
+    case CommissioningStage::kConfigureTCAcknowledgments:
         if (mDeviceCommissioningInfo.requiresUTC)
         {
             return CommissioningStage::kConfigureUTCTime;

src/controller/CHIPDeviceController.cpp

@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2020-2022 Project CHIP Authors
+ *    Copyright (c) 2020-2024 Project CHIP Authors
  *    Copyright (c) 2013-2017 Nest Labs, Inc.
  *    All rights reserved.
  *
@@ -2691,6 +2691,22 @@ void DeviceCommissioner::OnSetRegulatoryConfigResponse(
     commissioner->CommissioningStageComplete(err, report);
 }
 
+void DeviceCommissioner::OnSetTCAcknowledgementsResponse(
+    void * context, const GeneralCommissioning::Commands::SetTCAcknowledgementsResponse::DecodableType & data)
+{
+    CommissioningDelegate::CommissioningReport report;
+    CHIP_ERROR err = CHIP_NO_ERROR;
+
+    ChipLogProgress(Controller, "Received SetTCAcknowledgements response errorCode=%u", to_underlying(data.errorCode));
+    if (data.errorCode != GeneralCommissioning::CommissioningErrorEnum::kOk)
+    {
+        err = CHIP_ERROR_INTERNAL;
+        report.Set<CommissioningErrorInfo>(data.errorCode);
+    }
+    DeviceCommissioner * commissioner = static_cast<DeviceCommissioner *>(context);
+    commissioner->CommissioningStageComplete(err, report);
+}
+
 void DeviceCommissioner::OnSetTimeZoneResponse(void * context,
                                                const TimeSynchronization::Commands::SetTimeZoneResponse::DecodableType & data)
 {
@@ -2766,6 +2782,16 @@ CHIP_ERROR DeviceCommissioner::ICDRegistrationInfoReady()
     return CHIP_NO_ERROR;
 }
 
+CHIP_ERROR DeviceCommissioner::TermsAndConditionsAcknowledgementsReady()
+{
+    ReturnErrorCodeIf(mCommissioningStage != CommissioningStage::kConfigureTCAcknowledgments, CHIP_ERROR_INCORRECT_STATE);
+
+    // need to advance to next step
+    CommissioningStageComplete(CHIP_NO_ERROR);
+
+    return CHIP_NO_ERROR;
+}
+
 void DeviceCommissioner::OnNetworkConfigResponse(void * context,
                                                  const NetworkCommissioning::Commands::NetworkConfigResponse::DecodableType & data)
 {
@@ -3163,6 +3189,29 @@ void DeviceCommissioner::PerformCommissioningStep(DeviceProxy * proxy, Commissio
         }
     }
     break;
+    case CommissioningStage::kConfigureTCAcknowledgments: {
+        ChipLogProgress(Controller, "Setting Terms and Conditions");
+
+        if (!params.GetTermsAndConditionsAcknowledgement().HasValue())
+        {
+            CommissioningStageComplete(CHIP_NO_ERROR);
+            return;
+        }
+
+        GeneralCommissioning::Commands::SetTCAcknowledgements::Type request;
+        TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement = params.GetTermsAndConditionsAcknowledgement().Value();
+        request.TCUserResponse = termsAndConditionsAcknowledgement.acceptedTermsAndConditions;
+        request.TCVersion      = termsAndConditionsAcknowledgement.acceptedTermsAndConditionsVersion;
+        CHIP_ERROR err =
+            SendCommissioningCommand(proxy, request, OnSetTCAcknowledgementsResponse, OnBasicFailure, endpoint, timeout);
+        if (err != CHIP_NO_ERROR)
+        {
+            ChipLogError(Controller, "Failed to send SetTCAcknowledgements command: %" CHIP_ERROR_FORMAT, err.Format());
+            CommissioningStageComplete(err);
+            return;
+        }
+        break;
+    }
     case CommissioningStage::kSendPAICertificateRequest: {
         ChipLogProgress(Controller, "Sending request for PAI certificate");
         CHIP_ERROR err = SendCertificateChainRequestCommand(proxy, CertificateType::kPAI, timeout);

src/controller/CHIPDeviceController.h

@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2020-2022 Project CHIP Authors
+ *    Copyright (c) 2020-2024 Project CHIP Authors
  *    Copyright (c) 2013-2017 Nest Labs, Inc.
  *    All rights reserved.
  *
@@ -696,6 +696,8 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
      */
     CHIP_ERROR ICDRegistrationInfoReady();
 
+    CHIP_ERROR TermsAndConditionsAcknowledgementsReady();
+
     /**
      * @brief
      *  This function returns the current CommissioningStage for this commissioner.
@@ -947,6 +949,9 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
     static void OnSetRegulatoryConfigResponse(
         void * context,
         const chip::app::Clusters::GeneralCommissioning::Commands::SetRegulatoryConfigResponse::DecodableType & data);
+    static void OnSetTCAcknowledgementsResponse(
+        void * context,
+        const chip::app::Clusters::GeneralCommissioning::Commands::SetTCAcknowledgementsResponse::DecodableType & data);
     static void OnSetUTCError(void * context, CHIP_ERROR error);
     static void
     OnSetTimeZoneResponse(void * context,

src/controller/CommissioningDelegate.cpp

@@ -46,6 +46,9 @@ const char * StageToString(CommissioningStage stage)
     case kConfigRegulatory:
         return "ConfigRegulatory";
 
+    case kConfigureTCAcknowledgments:
+        return "ConfigureTCAcknowledgments";
+
     case kConfigureUTCTime:
         return "ConfigureUTCTime";
 

src/controller/CommissioningDelegate.h

@@ -40,6 +40,7 @@ enum CommissioningStage : uint8_t
     kReadCommissioningInfo2,     ///< Query SupportsConcurrentConnection, ICD state, check for matching fabric
     kArmFailsafe,                ///< Send ArmFailSafe (0x30:0) command to the device
     kConfigRegulatory,           ///< Send SetRegulatoryConfig (0x30:2) command to the device
+    kConfigureTCAcknowledgments, ///< Send SetTCAcknowledgements (0x30:6) command to the device
     kConfigureUTCTime,           ///< SetUTCTime if the DUT has a time cluster
     kConfigureTimeZone,          ///< Configure a time zone if one is required and available
     kConfigureDSTOffset,         ///< Configure DST offset if one is required and available