Enable Terms and Conditions (TC) feature for AutoCommissioner

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/chip-tool/commands/pairing/PairingCommand.cpp

@@ -129,6 +129,11 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
         params.SetCountryCode(CharSpan::fromCharString(mCountryCode.Value()));
     }
 
+    if (mRequireTCAcknowledgements.HasValue())
+    {
+        params.SetRequireTermsAndConditionsAcknowledgement(mRequireTCAcknowledgements.Value());
+    }
+
     // mTCAcknowledgements and mTCAcknowledgementVersion are optional, but related. When one is missing, default the value to 0, to
     // increase the test tools ability to test the applications.
     if (mTCAcknowledgements.HasValue() || mTCAcknowledgementVersion.HasValue())

examples/chip-tool/commands/pairing/PairingCommand.h

@@ -203,6 +203,10 @@ class PairingCommand : public CHIPCommand,
                         "DSTOffset list to use when setting Time Synchronization cluster's DSTOffset attribute",
                         Argument::kOptional);
 
+            AddArgument("require-tc-acknowledgements", 0, 1, &mRequireTCAcknowledgements,
+                        "Terms and Conditions acknowledgements is known to be required or not, (when required, the commissioner "
+                        "will wait until they are provided)");
+
             AddArgument("tc-acknowledgements", 0, UINT16_MAX, &mTCAcknowledgements,
                         "Terms and Conditions acknowledgements to use to set the General Commissioning cluster's TC "
                         "Acknowledgements bit-field");
@@ -267,6 +271,7 @@ class PairingCommand : public CHIPCommand,
     chip::Optional<uint64_t> mICDMonitoredSubject;
     chip::Optional<chip::app::Clusters::IcdManagement::ClientTypeEnum> mICDClientType;
     chip::Optional<uint32_t> mICDStayActiveDurationMsec;
+    chip::Optional<bool> mRequireTCAcknowledgements;
     chip::Optional<uint16_t> mTCAcknowledgements;
     chip::Optional<uint16_t> mTCAcknowledgementVersion;
     chip::app::DataModel::List<chip::app::Clusters::TimeSynchronization::Structs::TimeZoneStruct::Type> mTimeZoneList;

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,10 @@ CommissioningStage AutoCommissioner::GetNextCommissioningStageInternal(Commissio
     case CommissioningStage::kArmFailsafe:
         return CommissioningStage::kConfigRegulatory;
     case CommissioningStage::kConfigRegulatory:
+        return CommissioningStage::kGetTCAcknowledgments;
+    case CommissioningStage::kGetTCAcknowledgments:
+        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::kGetTCAcknowledgments, 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,56 @@ void DeviceCommissioner::PerformCommissioningStep(DeviceProxy * proxy, Commissio
         }
     }
     break;
+    case CommissioningStage::kGetTCAcknowledgments: {
+        ChipLogProgress(Controller, "Get Terms and Conditions Acknowledgments");
+
+        bool acknowledgementReady       = params.GetTermsAndConditionsAcknowledgement().HasValue();
+        bool acknowledgementNotRequired = params.GetRequireTermsAndConditionsAcknowledgement().HasValue() &&
+            !params.GetRequireTermsAndConditionsAcknowledgement().Value();
+
+        // If terms and conditions acknowledgements were provided, or not required, in the commissioning parameters, then skip ahead
+        if (acknowledgementReady || acknowledgementNotRequired)
+        {
+            TermsAndConditionsAcknowledgementsReady();
+            return;
+        }
+
+        ChipLogProgress(Controller, "Waiting for Terms and Conditions");
+        break;
+    }
+    case CommissioningStage::kConfigureTCAcknowledgments: {
+        ChipLogProgress(Controller, "Setting Terms and Conditions");
+
+        bool acknowledgementNotRequired = params.GetRequireTermsAndConditionsAcknowledgement().HasValue() &&
+            !params.GetRequireTermsAndConditionsAcknowledgement().Value();
+
+        if (acknowledgementNotRequired)
+        {
+            CommissioningStageComplete(CHIP_NO_ERROR);
+            return;
+        }
+
+        if (!params.GetTermsAndConditionsAcknowledgement().HasValue())
+        {
+            ChipLogError(Controller, "No acknowledgements provided");
+            CommissioningStageComplete(CHIP_ERROR_INVALID_ARGUMENT);
+            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,25 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
      */
     CHIP_ERROR ICDRegistrationInfoReady();
 
+    /**
+     * @brief
+     *   This function is called by the upper layer application to indicate that the required terms and conditions
+     *   acknowledgements have been set. This function should be called after the terms and conditions bitmask and version
+     *   have been defined using the appropriate configuration macros and the application has gathered the necessary
+     *   acknowledgements from the user.
+     *
+     * The upper layer application should call this method once it has successfully presented and obtained acknowledgements
+     * for the required terms and conditions from the user. This indicates that the commissioning process can advance to the
+     * next stage.
+     *
+     * When the terms and conditions acknowledgements process is completed, this function will signal the readiness to proceed
+     * to the next step in the commissioning process.
+     *
+     * @return CHIP_ERROR   The return status. Returns CHIP_ERROR_INCORRECT_STATE if the function is called when the device
+     *                      is not in the correct state to accept terms and conditions acknowledgements.
+     */
+    CHIP_ERROR TermsAndConditionsAcknowledgementsReady();
+
     /**
      * @brief
      *  This function returns the current CommissioningStage for this commissioner.
@@ -947,6 +966,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,12 @@ const char * StageToString(CommissioningStage stage)
     case kConfigRegulatory:
         return "ConfigRegulatory";
 
+    case kGetTCAcknowledgments:
+        return "GetTCAcknowledgments";
+
+    case kConfigureTCAcknowledgments:
+        return "ConfigureTCAcknowledgments";
+
     case kConfigureUTCTime:
         return "ConfigureUTCTime";
 

src/controller/CommissioningDelegate.h

@@ -40,6 +40,8 @@ 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
+    kGetTCAcknowledgments,       ///< Waiting for the higher layer to provide terms and conditions acknowledgements.
+    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
@@ -174,6 +176,8 @@ class CommissioningParameters
     // The country code to be used for the node, if set.
     Optional<CharSpan> GetCountryCode() const { return mCountryCode; }
 
+    Optional<bool> GetRequireTermsAndConditionsAcknowledgement() const { return mRequireTermsAndConditionsAcknowledgement; }
+
     Optional<TermsAndConditionsAcknowledgement> GetTermsAndConditionsAcknowledgement() const
     {
         return mTermsAndConditionsAcknowledgement;
@@ -351,6 +355,12 @@ class CommissioningParameters
         return *this;
     }
 
+    CommissioningParameters & SetRequireTermsAndConditionsAcknowledgement(bool requireTermsAndConditionsAcknowledgement)
+    {
+        mRequireTermsAndConditionsAcknowledgement.SetValue(requireTermsAndConditionsAcknowledgement);
+        return *this;
+    }
+
     CommissioningParameters &
     SetTermsAndConditionsAcknowledgement(TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement)
     {
@@ -629,6 +639,7 @@ class CommissioningParameters
     Optional<ByteSpan> mAttestationNonce;
     Optional<WiFiCredentials> mWiFiCreds;
     Optional<CharSpan> mCountryCode;
+    Optional<bool> mRequireTermsAndConditionsAcknowledgement;
     Optional<TermsAndConditionsAcknowledgement> mTermsAndConditionsAcknowledgement;
     Optional<ByteSpan> mThreadOperationalDataset;
     Optional<NOCChainGenerationParameters> mNOCChainGenerationParameters;