Skip to content

Commit

Permalink
Integrate Terms and Conditions Acknowledgements in Commissioning Process
Browse files Browse the repository at this point in the history 
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
    ```
  • Loading branch information
@swan-amazon
swan-amazon committed May 23, 2024
1 parent 4790af5 commit d185f66
Show file tree
Hide file tree
Showing 23 changed files with 1,059 additions and 41 deletions.
82 changes: 81 additions & 1 deletion examples/all-clusters-app/all-clusters-common/all-clusters-app.zap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -2328,7 +2408,7 @@
"storageOption": "RAM",
"singleton": 0,
"bounded": 0,
"defaultValue": "0",
"defaultValue": "1",
"reportable": 1,
"minInterval": 1,
"maxInterval": 65534,
Expand Down
13 changes: 12 additions & 1 deletion examples/chip-tool/commands/pairing/PairingCommand.cpp
View file
Original file line number Diff line number Diff line change
@@ -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");
Expand Down Expand Up @@ -118,6 +118,17 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
params.SetCountryCode(CharSpan::fromCharString(mCountryCode.Value()));
}

// mTCAcknowledgements and mTCAcknowledgementVersion are options, 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.
Expand Down
12 changes: 11 additions & 1 deletion examples/chip-tool/commands/pairing/PairingCommand.h
View file
Original file line number Diff line number Diff line change
@@ -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");
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand Down
118 changes: 89 additions & 29 deletions src/app/clusters/general-commissioning-server/general-commissioning-server.cpp
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/**
*
* Copyright (c) 2021 Project CHIP Authors
* Copyright (c) 2021-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.
Expand All @@ -26,6 +26,7 @@
#include <app/CommandHandler.h>
#include <app/ConcreteCommandPath.h>
#include <app/server/CommissioningWindowManager.h>
#include <app/server/EnhancedSetupFlowProvider.h>
#include <app/server/Server.h>
#include <app/util/af.h>
#include <app/util/attribute-storage.h>
Expand Down Expand Up @@ -95,9 +96,32 @@ CHIP_ERROR GeneralCommissioningAttrAccess::Read(const ConcreteReadAttributePath
case SupportsConcurrentConnection::Id: {
return ReadSupportsConcurrentConnection(aEncoder);
}
default: {
break;
case TCAcceptedVersion::Id: {
uint16_t tcAcceptedVersion;
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
CHIP_ERROR err = enhancedSetupFlowProvider->GetTermsAndConditionsAcceptedAcknowledgementsVersion(tcAcceptedVersion);
return (CHIP_NO_ERROR != err) ? err : aEncoder.Encode(tcAcceptedVersion);
}
case TCMinRequiredVersion::Id: {
uint16_t tcRequiredVersion;
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
CHIP_ERROR err = enhancedSetupFlowProvider->GetTermsAndConditionsRequiredAcknowledgementsVersion(tcRequiredVersion);
return (CHIP_NO_ERROR != err) ? err : aEncoder.Encode(tcRequiredVersion);
}
case TCAcknowledgements::Id: {
uint16_t tcAcknowledgements;
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
CHIP_ERROR err = enhancedSetupFlowProvider->GetTermsAndConditionsAcceptedAcknowledgements(tcAcknowledgements);
return (CHIP_NO_ERROR != err) ? err : aEncoder.Encode(tcAcknowledgements);
}
case TCAcknowledgementsRequired::Id: {
uint16_t tcAcknowledgementsRequired;
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
CHIP_ERROR err = enhancedSetupFlowProvider->GetTermsAndConditionsRequiredAcknowledgements(tcAcknowledgementsRequired);
return (CHIP_NO_ERROR != err) ? err : aEncoder.Encode(tcAcknowledgementsRequired);
}
default:
break;
}
return CHIP_NO_ERROR;
}
Expand Down Expand Up @@ -214,9 +238,10 @@ bool emberAfGeneralCommissioningClusterCommissioningCompleteCallback(
{
MATTER_TRACE_SCOPE("CommissioningComplete", "GeneralCommissioning");

DeviceControlServer * devCtrl = &DeviceLayer::DeviceControlServer::DeviceControlSvr();
auto & failSafe = Server::GetInstance().GetFailSafeContext();
auto & fabricTable = Server::GetInstance().GetFabricTable();
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
DeviceControlServer * devCtrl = &DeviceLayer::DeviceControlServer::DeviceControlSvr();
auto & failSafe = Server::GetInstance().GetFailSafeContext();
auto & fabricTable = Server::GetInstance().GetFabricTable();

ChipLogProgress(FailSafe, "GeneralCommissioning: Received CommissioningComplete");

Expand All @@ -239,34 +264,43 @@ bool emberAfGeneralCommissioningClusterCommissioningCompleteCallback(
}
else
{
if (failSafe.NocCommandHasBeenInvoked())
CHIP_ERROR err;

if (!enhancedSetupFlowProvider->HasTermsAndConditionsRequiredAcknowledgementsBeenAccepted())
{
CHIP_ERROR err = fabricTable.CommitPendingFabricData();
if (err != CHIP_NO_ERROR)
{
// No need to revert on error: CommitPendingFabricData always reverts if not fully successful.
ChipLogError(FailSafe, "GeneralCommissioning: Failed to commit pending fabric data: %" CHIP_ERROR_FORMAT,
err.Format());
}
else
ChipLogError(AppServer, "Required terms and conditions have not been accepted");
Breadcrumb::Set(commandPath.mEndpointId, 0);
response.errorCode = CommissioningErrorEnum::kRequiredTCNotAccepted;
}

else if (!enhancedSetupFlowProvider->HasTermsAndConditionsRequiredAcknowledgementsVersionBeenAccepted())
{
ChipLogError(AppServer, "Minimum terms and conditions version has not been accepted");
Breadcrumb::Set(commandPath.mEndpointId, 0);
response.errorCode = CommissioningErrorEnum::kTCMinVersionNotMet;
}

else
{
if (failSafe.NocCommandHasBeenInvoked())
{
err = fabricTable.CommitPendingFabricData();
CheckSuccess(err, Failure);
ChipLogProgress(FailSafe, "GeneralCommissioning: Successfully commited pending fabric data");
}
CheckSuccess(err, Failure);
}

/*
* Pass fabric of commissioner to DeviceControlSvr.
* This allows device to send messages back to commissioner.
* Once bindings are implemented, this may no longer be needed.
*/
failSafe.DisarmFailSafe();
CheckSuccess(
devCtrl->PostCommissioningCompleteEvent(handle->AsSecureSession()->GetPeerNodeId(), handle->GetFabricIndex()),
Failure);
/*
* Pass fabric of commissioner to DeviceControlSvr.
* This allows device to send messages back to commissioner.
* Once bindings are implemented, this may no longer be needed.
*/
failSafe.DisarmFailSafe();
err = devCtrl->PostCommissioningCompleteEvent(handle->AsSecureSession()->GetPeerNodeId(), handle->GetFabricIndex());
CheckSuccess(err, Failure);

Breadcrumb::Set(commandPath.mEndpointId, 0);
response.errorCode = CommissioningErrorEnum::kOk;
Breadcrumb::Set(commandPath.mEndpointId, 0);
response.errorCode = CommissioningErrorEnum::kOk;
}
}
}

Expand Down Expand Up @@ -328,13 +362,39 @@ bool emberAfGeneralCommissioningClusterSetRegulatoryConfigCallback(app::CommandH
return true;
}

bool emberAfGeneralCommissioningClusterSetTCAcknowledgementsCallback(
chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
const chip::app::Clusters::GeneralCommissioning::Commands::SetTCAcknowledgements::DecodableType & commandData)
{
MATTER_TRACE_SCOPE("SetTCAcknowledgements", "GeneralCommissioning");
Commands::SetTCAcknowledgementsResponse::Type response;
EnhancedSetupFlowProvider * const enhancedSetupFlowProvider = Server::GetInstance().GetEnhancedSetupFlowProvider();
uint16_t acknowledgements = commandData.TCUserResponse;
uint16_t acknowledgementsVersion = commandData.TCVersion;
CheckSuccess(enhancedSetupFlowProvider->SetTermsAndConditionsAcceptance(acknowledgements, acknowledgementsVersion), Failure);
response.errorCode = CommissioningErrorEnum::kOk;

commandObj->AddResponse(commandPath, response);
return true;
}

namespace {
void OnPlatformEventHandler(const DeviceLayer::ChipDeviceEvent * event, intptr_t arg)
{
if (event->Type == DeviceLayer::DeviceEventType::kFailSafeTimerExpired)
switch (event->Type)
{
case DeviceLayer::DeviceEventType::kFailSafeTimerExpired: {
// Spec says to reset Breadcrumb attribute to 0.
Breadcrumb::Set(0, 0);
break;
}
case DeviceLayer::DeviceEventType::kServerReady: {
Server::GetInstance().GetEnhancedSetupFlowProvider()->Init();
break;
}
default: {
break;
}
}
}

Expand Down
8 changes: 7 additions & 1 deletion src/app/server/BUILD.gn
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -36,14 +36,20 @@ static_library("server") {
"CommissioningWindowManager.h",
"DefaultAclStorage.cpp",
"DefaultAclStorage.h",
"DefaultEnhancedSetupFlowProvider.cpp",
"DefaultEnhancedSetupFlowProvider.h",
"DefaultTermsAndConditionsProvider.cpp",
"DefaultTermsAndConditionsProvider.h",
"Dnssd.cpp",
"Dnssd.h",
"EchoHandler.cpp",
"EchoHandler.h",
"EnhancedSetupFlowProvider.h",
"OnboardingCodesUtil.cpp",
"OnboardingCodesUtil.h",
"Server.cpp",
"Server.h",
"TermsAndConditionsProvider.h",
]

public_configs = [ ":server_config" ]
Expand Down
Loading

0 comments on commit d185f66

Please sign in to comment.