Add Terms and Conditions Acknowledgement Options to Chip Tool

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
```

.vscode/launch.json

@@ -10,7 +10,8 @@
             "request": "launch",
             "expressions": "native",
             "sourceMap": {
-                "${workspaceFolder}/examples/all-clusters-app/linux/third_party/connectedhomeip/src": "${workspaceFolder}/src"
+                "${workspaceFolder}/examples/all-clusters-app/": "${workspaceFolder}/examples/all-clusters-app/",
+                "${workspaceFolder}/examples/all-clusters-app/linux/third_party/connectedhomeip/": "${workspaceFolder}/"
             },
             "relativePathBase": "${workspaceFolder}",
             "breakpointMode": "path",
@@ -38,6 +39,36 @@
             "terminal": "integrated",
             "stopOnEntry": true
         },
+        {
+            "name": "LLDB Debugger: Chip-Tool (chip-tool)",
+            "type": "lldb", // [vadimcn/codelldb](https://github.com/vadimcn/codelldb)
+            "request": "launch",
+            "expressions": "native",
+            "sourceMap": {
+                "${workspaceFolder}/examples/chip-tool/": "${workspaceFolder}/examples/chip-tool/",
+                "${workspaceFolder}/examples/chip-tool/third_party/connectedhomeip/": "${workspaceFolder}/"
+            },
+            "relativePathBase": "${workspaceFolder}",
+            "breakpointMode": "path",
+            "sourceLanguages": ["cpp"],
+            "reverseDebugging": true,
+            "program": "${workspaceFolder}/out/linux-x64-chip-tool/chip-tool",
+            "args": [
+                "pairing",
+                "code",
+                "1",
+                "34970112332",
+                "--trace_decode",
+                "1",
+                "--country-code",
+                "US"
+            ],
+            "cwd": "${workspaceFolder}/out/linux-x64-chip-tool",
+            "env": {},
+            "stdio": [null, null, null],
+            "terminal": "console",
+            "stopOnEntry": false
+        },
         {
             "name": "Attach to running process",
             "type": "lldb",

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 "
+                        "Acknowledgements bit-field");
         }
 
         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

@@ -343,7 +343,7 @@ CommissioningStage AutoCommissioner::GetNextCommissioningStageInternal(Commissio
     case CommissioningStage::kArmFailsafe:
         return CommissioningStage::kConfigRegulatory;
     case CommissioningStage::kConfigRegulatory:
-        if (mDeviceCommissioningInfo.requiresTCAcknowledgements)
+        if (mParams.GetTCAcknowledgements().HasValue() && mParams.GetTCAcknowledgementVersion().HasValue())
         {
             return CommissioningStage::kConfigureTCAcknowledgments;
         }

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 {
@@ -159,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
@@ -331,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)
@@ -595,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;
@@ -721,7 +740,6 @@ struct ReadCommissioningInfo
     BasicClusterInfo basic;
     GeneralCommissioningInfo general;
     bool requiresUTC                  = false;
-    bool requiresTCAcknowledgements   = true;
     bool requiresTimeZone             = false;
     bool requiresDefaultNTP           = false;
     bool requiresTrustedTimeSource    = false;