Integrate Terms and Conditions Acknowledgements in Commissioning Process

1. **Add support for setting Terms and Conditions acknowledgements** - Added functionality to set Terms and Conditions acknowledgements and acknowledgment version in the General Commissioning cluster. - Implemented corresponding commands and responses to handle acknowledgements. 2. **Enhance setup flow handling** - Refactored the setup flow handling to accommodate setting Terms and Conditions acknowledgements. - Updated the commissioning stages to include configuring Terms and Conditions acknowledgements. 3. **Handle setting Terms and Conditions acknowledgements** - Implemented setting Terms and Conditions acknowledgements in the commissioning process. - Implemented proper handling of command responses and error checking. 1. **Initial setup** ```bash mkdir -p $HOME/workspace git -C $HOME/workspace clone https://github.com/project-chip/zap.git --depth 1 git -C $HOME/workspace clone [email protected]:swan-amazon/connectedhomeip.git -b feature/enhanced-setup-flow --depth 1 git -C $HOME/workspace/connectedhomeip submodule update --init --recursive --depth 1 ``` 2. **Zap regen** ```bash ./scripts/tools/zap/zap_bootstrap.sh python3 ./scripts/tools/zap_regen_all.py python3 ./scripts/tools/zap_convert_all.py ``` 3. **Build the Application**: Configure and build the `chip-all-clusters-app` with Bluetooth and WiFi disabled to simulate an on-network only commissioning environment. ```bash gn gen --check --fail-on-unused-args --export-compile-commands --root=/workspace/connectedhomeip/examples/all-clusters-app/linux --args="chip_tc_required_acknowledgements=1 chip_tc_required_acknowledgements_version=1 chip_config_network_layer_ble=false chip_enable_wifi=false is_debug=true" /workspace/connectedhomeip/out/linux-x64-all-clusters-no-ble-no-wifi ninja -C out/linux-x64-all-clusters-no-ble-no-wifi ``` 4. **Build the `chip-tool`**: Configure and compile the `chip-tool`, which is used to commission and control the `chip-all-clusters-app`. ```bash gn gen --check --fail-on-unused-args --export-compile-commands --root=/workspace/connectedhomeip/examples/chip-tool /workspace/connectedhomeip/out/linux-x64-chip-tool ninja -C out/linux-x64-chip-tool ``` 5. **Run the Test Application**: Execute the application, specifying a local Key-Value Store file and enabling trace decoding. ```bash rm -f /tmp/chip_* /tmp/kvs.bin && /workspace/connectedhomeip/out/linux-x64-all-clusters-no-ble-no-wifi/chip-all-clusters-app --KVS=/tmp/kvs.bin --trace_decode 1 ``` 6. **Commissioning Test Application**: Commission the test application with `chip-tool` ```bash /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool pairing code 1 34970112332 --trace_decode 1 --tc-acknowledgements 1 --tc-acknowledgements-version 1 /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool onoff off 1 1 ``` 7. **Probe Test Application**: ```bash /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool generalcommissioning read-by-id 5 1 0 /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool generalcommissioning read-by-id 6 1 0 /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool generalcommissioning read-by-id 7 1 0 /workspace/connectedhomeip/out/linux-x64-chip-tool/chip-tool generalcommissioning set-tcacknowledgements 1 1 1 0 ``` wip fix
swan-amazon · Jun 12, 2024 · 9a535a0 · 9a535a0
1 parent 4790af5
commit 9a535a0
Show file tree

Hide file tree

Showing 27 changed files with 1,782 additions and 156 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -10,8 +10,7 @@
             "request": "launch",
             "expressions": "native",
             "sourceMap": {
-                "${workspaceFolder}/examples/all-clusters-app/": "${workspaceFolder}/examples/all-clusters-app/",
-                "${workspaceFolder}/examples/all-clusters-app/linux/third_party/connectedhomeip/": "${workspaceFolder}/"
+                "${workspaceFolder}/examples/all-clusters-app/linux/third_party/connectedhomeip": "${workspaceFolder}"
             },
             "relativePathBase": "${workspaceFolder}",
             "breakpointMode": "path",
@@ -21,20 +20,6 @@
             "program": "${workspaceFolder}/out/linux-x64-all-clusters-no-ble-no-wifi/chip-all-clusters-app",
             "args": ["--KVS=/tmp/kvs.bin", "--trace_decode=1"],
             "cwd": "${workspaceFolder}/out/linux-x64-all-clusters-no-ble-no-wifi",
-            "env": {
-                "_PW_ACTUAL_ENVIRONMENT_ROOT": "${workspaceFolder}/.environment",
-                "_PW_ENVIRONMENT_CONFIG_FILE": "${workspaceFolder}/scripts/setup/environment.json",
-                "_PW_ROSETTA": "0",
-                "PW_ARM_CIPD_INSTALL_DIR": "${workspaceFolder}/.environment/cipd/packages/arm",
-                "PW_BRANDING_BANNER": "${workspaceFolder}/scripts/setup/banner.txt",
-                "PW_PACKAGE_ROOT": "${workspaceFolder}/.environment/packages",
-                "PW_PIGWEED_CIPD_INSTALL_DIR": "${workspaceFolder}/.environment/cipd/packages/pigweed",
-                "PW_PROJECT_ROOT": "${workspaceFolder}",
-                "PW_PYTHON_CIPD_INSTALL_DIR": "${workspaceFolder}/.environment/cipd/packages/python",
-                "PW_ROOT": "${workspaceFolder}/third_party/pigweed/repo",
-                "PW_ZAP_CIPD_INSTALL_DIR": "${workspaceFolder}/.environment/cipd/packages/zap",
-                "PATH": "${workspaceFolder}/third_party/pigweed/repo/out/host/host_tools:${workspaceFolder}/.environment/pigweed-venv/bin:${workspaceFolder}/.environment/cipd/packages/arm/bin:${workspaceFolder}/.environment/cipd/packages/arm:${workspaceFolder}/.environment/cipd/packages/zap:${workspaceFolder}/.environment/cipd/packages/pigweed/bin:${workspaceFolder}/.environment/cipd/packages/pigweed:${workspaceFolder}/.environment/cip:${containerEnv:PATH}"
-            },
             "stdio": [null, null, null],
             "terminal": "integrated",
             "stopOnEntry": true
@@ -69,6 +54,24 @@
             "terminal": "console",
             "stopOnEntry": false
         },
+        {
+            "name": "LLDB Debugger: Unit Test",
+            "type": "lldb", // [vadimcn/codelldb](https://github.com/vadimcn/codelldb)
+            "request": "launch",
+            "expressions": "native",
+            "sourceMap": {},
+            "relativePathBase": "${workspaceFolder}",
+            "breakpointMode": "path",
+            "sourceLanguages": ["cpp"],
+            "reverseDebugging": true,
+            "program": "/workspace/connectedhomeip/out/unified/linux_x64_clang/tests/TestDefaultTermsAndConditionsProvider",
+            "args": [],
+            "cwd": "/workspace/connectedhomeip/out/unified",
+            "env": {},
+            "stdio": [null, null, null],
+            "terminal": "integrated",
+            "stopOnEntry": false
+        },
         {
             "name": "Attach to running process",
             "type": "lldb",

diff --git a/config/standalone/CHIPProjectConfig.h b/config/standalone/CHIPProjectConfig.h
@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2020-2022 Project CHIP Authors
+ *    Copyright (c) 2020-2024 Project CHIP Authors
  *    Copyright (c) 2016-2017 Nest Labs, Inc.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
@@ -74,6 +74,31 @@
 #define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING "1.0"
 #endif
 
+/**
+ * @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.
+ */
+#ifndef CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS 0
+#endif
+
+/**
+ * @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.
+ */
+#ifndef CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS_VERSION
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS_VERSION 0
+#endif
+
 //
 // Default of 8 ECs is not sufficient for some of the unit tests
 // that try to validate multiple simultaneous interactions.

diff --git a/examples/all-clusters-app/all-clusters-common/all-clusters-app.zap b/examples/all-clusters-app/all-clusters-common/all-clusters-app.zap
@@ -2171,6 +2171,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": [
@@ -2254,6 +2270,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,
@@ -2328,7 +2408,7 @@
               "storageOption": "RAM",
               "singleton": 0,
               "bounded": 0,
-              "defaultValue": "0",
+              "defaultValue": "1",
               "reportable": 1,
               "minInterval": 1,
               "maxInterval": 65534,

diff --git a/examples/all-clusters-app/linux/include/CHIPProjectAppConfig.h b/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");
@@ -27,6 +27,12 @@
 
 #pragma once
 
+// Require that terms and conditions ordinal 1 must be accepted.
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS 1
+
+// The current terms and conditions revision is 1.
+#define CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS_VERSION 1
+
 // include the CHIPProjectConfig from config/standalone
 #include <CHIPProjectConfig.h>
 

diff --git a/examples/chip-tool/BUILD.gn b/examples/chip-tool/BUILD.gn
@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Project CHIP Authors
+# Copyright (c) 2020-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.
@@ -105,7 +105,6 @@ static_library("chip-tool-utils") {
     "${chip_root}/examples/common/tracing:commandline",
     "${chip_root}/src/app/icd/client:handler",
     "${chip_root}/src/app/icd/client:manager",
-    "${chip_root}/src/app/server",
     "${chip_root}/src/app/tests/suites/commands/interaction_model",
     "${chip_root}/src/controller/data_model",
     "${chip_root}/src/credentials:file_attestation_trust_store",

diff --git a/examples/chip-tool/commands/pairing/PairingCommand.cpp b/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,17 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
         params.SetCountryCode(CharSpan::fromCharString(mCountryCode.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())
+    {
+        TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement = {
+            .acceptedTermsAndConditions        = mTCAcknowledgements.ValueOr(0),
+            .acceptedTermsAndConditionsVersion = mTCAcknowledgementVersion.ValueOr(0),
+        };
+        params.SetTermsAndConditionsAcknowledgement(termsAndConditionsAcknowledgement);
+    }
+
     // 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.

diff --git a/examples/chip-tool/commands/pairing/PairingCommand.h b/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");
@@ -182,6 +182,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-acknowledgements-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 +241,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;

diff --git a/src/app/BUILD.gn b/src/app/BUILD.gn
@@ -214,6 +214,7 @@ static_library("interaction-model") {
     "${chip_root}/src/lib/address_resolve",
     "${chip_root}/src/lib/support",
     "${chip_root}/src/lib/support:static-support",
+    "${chip_root}/src/messaging:messaging",
     "${chip_root}/src/protocols/interaction_model",
     "${chip_root}/src/protocols/secure_channel",
     "${chip_root}/src/system",