Implement Terms and Conditions Acknowledgements in Chip Tool

This commit adds the necessary logic to AutoCommissioner.cpp and
CHIPDeviceController.cpp to facilitate the sending of Terms and
Conditions acknowledgements commands during the commissioning process.
This enhancement ensures that the commissioning workflow includes the
crucial step of acknowledging Terms and Conditions, contributing to a
more robust and comprehensive device setup.

This commit introduces functionality to the chip tool that allows users
to pass TC (Terms and Conditions) Acknowledgements mask and TC
Acknowledgement Version from the command line. This feature enables
users to specify the terms and conditions acknowledgements to be used
for setting the General Commissioning cluster's TC Acknowledgements
bit-field.

Example Usage:

```bash
/workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool pairing code 1 34970112332 --country-code US --tc-acknowledgements 1 --tc-acknowledgement-version 1
```

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

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2020 Project CHIP Authors
+ *   Copyright (c) 2020-2024 Project CHIP Authors
  *   All rights reserved.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
@@ -118,6 +118,12 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
         params.SetCountryCode(CharSpan::fromCharString(mCountryCode.Value()));
     }
 
+    if (mTCAcknowledgements.HasValue() && mTCAcknowledgementVersion.HasValue())
+    {
+        params.SetTCAcknowledgements(mTCAcknowledgements.Value());
+        params.SetTCAcknowledgementVersion(mTCAcknowledgementVersion.Value());
+    }
+
     // mTimeZoneList is an optional argument managed by TypedComplexArgument mComplex_TimeZones.
     // Since optional Complex arguments are not currently supported via the <chip::Optional> class,
     // we will use mTimeZoneList.data() value to determine if the argument was provided.

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

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2020 Project CHIP Authors
+ *   Copyright (c) 2020-2024 Project CHIP Authors
  *   All rights reserved.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
@@ -55,8 +55,7 @@ class PairingCommand : public CHIPCommand,
     PairingCommand(const char * commandName, PairingMode mode, PairingNetworkType networkType,
                    CredentialIssuerCommands * credIssuerCmds,
                    chip::Dnssd::DiscoveryFilterType filterType = chip::Dnssd::DiscoveryFilterType::kNone) :
-        CHIPCommand(commandName, credIssuerCmds),
-        mPairingMode(mode), mNetworkType(networkType), mFilterType(filterType),
+        CHIPCommand(commandName, credIssuerCmds), mPairingMode(mode), mNetworkType(networkType), mFilterType(filterType),
         mRemoteAddr{ IPAddress::Any, chip::Inet::InterfaceId::Null() }, mComplex_TimeZones(&mTimeZoneList),
         mComplex_DSTOffsets(&mDSTOffsetList), mCurrentFabricRemoveCallback(OnCurrentFabricRemove, this)
     {
@@ -182,6 +181,14 @@ class PairingCommand : public CHIPCommand,
             AddArgument("dst-offset", &mComplex_DSTOffsets,
                         "DSTOffset list to use when setting Time Synchronization cluster's DSTOffset attribute",
                         Argument::kOptional);
+
+            AddArgument("tc-acknowledgements", 0, UINT16_MAX, &mTCAcknowledgements,
+                        "Terms and Conditions acknowledgements to use to set the General Commissioning cluster's TC "
+                        "Acknowledgements bit-field");
+
+            AddArgument("tc-acknowledgement-version", 0, UINT16_MAX, &mTCAcknowledgementVersion,
+                        "Terms and Conditions acknowledgement version to use to set the General Commissioning cluster's TC "
+                        "Acknowledgement version");
         }
 
         AddArgument("timeout", 0, UINT16_MAX, &mTimeout);
@@ -233,6 +240,8 @@ class PairingCommand : public CHIPCommand,
     chip::Optional<bool> mBypassAttestationVerifier;
     chip::Optional<std::vector<uint32_t>> mCASEAuthTags;
     chip::Optional<char *> mCountryCode;
+    chip::Optional<uint16_t> mTCAcknowledgements;
+    chip::Optional<uint16_t> mTCAcknowledgementVersion;
     chip::Optional<bool> mSkipICDRegistration;
     chip::Optional<NodeId> mICDCheckInNodeId;
     chip::Optional<chip::ByteSpan> mICDSymmetricKey;

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");
@@ -343,13 +343,25 @@ CommissioningStage AutoCommissioner::GetNextCommissioningStageInternal(Commissio
     case CommissioningStage::kArmFailsafe:
         return CommissioningStage::kConfigRegulatory;
     case CommissioningStage::kConfigRegulatory:
+        if (mParams.GetTCAcknowledgements().HasValue() && mParams.GetTCAcknowledgementVersion().HasValue())
+        {
+            return CommissioningStage::kConfigureTCAcknowledgments;
+        }
+        else if (mDeviceCommissioningInfo.requiresUTC)
+        {
+            return CommissioningStage::kConfigureUTCTime;
+        }
+        else
+        {
+            return CommissioningStage::kSendPAICertificateRequest;
+        }
+    case CommissioningStage::kConfigureTCAcknowledgments:
         if (mDeviceCommissioningInfo.requiresUTC)
         {
             return CommissioningStage::kConfigureUTCTime;
         }
         else
         {
-            // Time cluster is not supported, move right to DA
             return CommissioningStage::kSendPAICertificateRequest;
         }
     case 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.
  *
@@ -2426,6 +2426,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)
 {
@@ -2874,6 +2890,23 @@ void DeviceCommissioner::PerformCommissioningStep(DeviceProxy * proxy, Commissio
         }
     }
     break;
+    case CommissioningStage::kConfigureTCAcknowledgments: {
+        ChipLogProgress(Controller, "Setting Terms and Conditions");
+
+        GeneralCommissioning::Commands::SetTCAcknowledgements::Type request;
+        request.TCUserResponse = params.GetTCAcknowledgements().Value();
+        request.TCVersion      = params.GetTCAcknowledgementVersion().Value();
+        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.
  *
@@ -893,6 +893,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.h

@@ -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");
@@ -23,6 +23,7 @@
 #include <credentials/attestation_verifier/DeviceAttestationDelegate.h>
 #include <credentials/attestation_verifier/DeviceAttestationVerifier.h>
 #include <lib/support/Variant.h>
+#include <sys/types.h>
 #include <system/SystemClock.h>
 
 namespace chip {
@@ -38,6 +39,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
@@ -158,6 +160,10 @@ class CommissioningParameters
     // The country code to be used for the node, if set.
     Optional<CharSpan> GetCountryCode() const { return mCountryCode; }
 
+    Optional<uint16_t> GetTCAcknowledgements() const { return mTCAcknowledgements; }
+
+    Optional<uint16_t> GetTCAcknowledgementVersion() const { return mTCAcknowledgementVersion; }
+
     // Time zone to set for the node
     // If required, this will be truncated to fit the max size allowable on the node
     Optional<app::DataModel::List<app::Clusters::TimeSynchronization::Structs::TimeZoneStruct::Type>> GetTimeZone() const
@@ -330,6 +336,18 @@ class CommissioningParameters
         return *this;
     }
 
+    CommissioningParameters & SetTCAcknowledgements(uint16_t tcAcknowledgements)
+    {
+        mTCAcknowledgements.SetValue(tcAcknowledgements);
+        return *this;
+    }
+
+    CommissioningParameters & SetTCAcknowledgementVersion(uint16_t tcAcknowledgementVersion)
+    {
+        mTCAcknowledgementVersion.SetValue(tcAcknowledgementVersion);
+        return *this;
+    }
+
     // The lifetime of the list buffer needs to exceed the lifetime of the CommissioningParameters object.
     CommissioningParameters &
     SetTimeZone(app::DataModel::List<app::Clusters::TimeSynchronization::Structs::TimeZoneStruct::Type> timeZone)
@@ -594,6 +612,8 @@ class CommissioningParameters
     Optional<ByteSpan> mAttestationNonce;
     Optional<WiFiCredentials> mWiFiCreds;
     Optional<CharSpan> mCountryCode;
+    Optional<uint16_t> mTCAcknowledgements;
+    Optional<uint16_t> mTCAcknowledgementVersion;
     Optional<ByteSpan> mThreadOperationalDataset;
     Optional<NOCChainGenerationParameters> mNOCChainGenerationParameters;
     Optional<ByteSpan> mRootCert;