Add a new use-only-on-network-discovery optional option to pairing co…

…de and pairing code-paseonly (#22300)

* Add a new useOnlyOnNetworkDiscovery boolean flag to DeviceCommissioner APIs that use a setUpCode to commission a device or establish a PASE connection

* Add a new use-only-on-network-discovery optional option to pairing code and pairing code-paseonly

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

@@ -85,13 +85,26 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
 
 CHIP_ERROR PairingCommand::PaseWithCode(NodeId remoteId)
 {
-    return CurrentCommissioner().EstablishPASEConnection(remoteId, mOnboardingPayload);
+    DiscoveryType discoveryType =
+        mUseOnlyOnNetworkDiscovery.ValueOr(false) ? DiscoveryType::kDiscoveryNetworkOnly : DiscoveryType::kAll;
+    return CurrentCommissioner().EstablishPASEConnection(remoteId, mOnboardingPayload, discoveryType);
 }
 
 CHIP_ERROR PairingCommand::PairWithCode(NodeId remoteId)
 {
     CommissioningParameters commissioningParams = GetCommissioningParameters();
-    return CurrentCommissioner().PairDevice(remoteId, mOnboardingPayload, commissioningParams);
+
+    // If no network discovery behavior and no network credentials are provided, assume that the pairing command is trying to pair
+    // with an on-network device.
+    if (!mUseOnlyOnNetworkDiscovery.HasValue())
+    {
+        auto threadCredentials = commissioningParams.GetThreadOperationalDataset();
+        auto wiFiCredentials   = commissioningParams.GetWiFiCredentials();
+        mUseOnlyOnNetworkDiscovery.SetValue(!threadCredentials.HasValue() && !wiFiCredentials.HasValue());
+    }
+    DiscoveryType discoveryType = mUseOnlyOnNetworkDiscovery.Value() ? DiscoveryType::kDiscoveryNetworkOnly : DiscoveryType::kAll;
+
+    return CurrentCommissioner().PairDevice(remoteId, mOnboardingPayload, commissioningParams, discoveryType);
 }
 
 CHIP_ERROR PairingCommand::Pair(NodeId remoteId, PeerAddress address)

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

@@ -81,6 +81,7 @@ class PairingCommand : public CHIPCommand,
         case PairingMode::CodePaseOnly:
             AddArgument("payload", &mOnboardingPayload);
             AddArgument("discover-once", 0, 1, &mDiscoverOnce);
+            AddArgument("use-only-onnetwork-discovery", 0, 1, &mUseOnlyOnNetworkDiscovery);
             break;
         case PairingMode::Ble:
             AddArgument("setup-pin-code", 0, 134217727, &mSetupPINCode);
@@ -163,6 +164,7 @@ class PairingCommand : public CHIPCommand,
     NodeId mNodeId;
     chip::Optional<uint16_t> mTimeout;
     chip::Optional<bool> mDiscoverOnce;
+    chip::Optional<bool> mUseOnlyOnNetworkDiscovery;
     uint16_t mRemotePort;
     uint16_t mDiscriminator;
     uint32_t mSetupPINCode;

src/app/tests/suites/commands/commissioner/CommissionerCommands.cpp

@@ -32,7 +32,11 @@ CommissionerCommands::PairWithCode(const char * identity,
     memset(code, '\0', sizeof(code));
     memcpy(code, value.payload.data(), value.payload.size());
     ChipLogError(chipTool, "Pairing Code is %s", code);
-    return GetCommissioner(identity).PairDevice(value.nodeId, code);
+
+    // To reduce the scanning latency in some setups, and since the primary use for PairWithCode is to commission a device to
+    // another commissioner, assume that the commissionable device is available on the network.
+    chip::Controller::DiscoveryType discoveryType = chip::Controller::DiscoveryType::kDiscoveryNetworkOnly;
+    return GetCommissioner(identity).PairDevice(value.nodeId, code, discoveryType);
 }
 
 CHIP_ERROR CommissionerCommands::Unpair(const char * identity,

src/controller/CHIPDeviceController.cpp

@@ -572,7 +572,8 @@ CHIP_ERROR DeviceCommissioner::GetDeviceBeingCommissioned(NodeId deviceId, Commi
     return CHIP_NO_ERROR;
 }
 
-CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, const char * setUpCode, const CommissioningParameters & params)
+CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, const char * setUpCode, const CommissioningParameters & params,
+                                          DiscoveryType discoveryType)
 {
     MATTER_TRACE_EVENT_SCOPE("PairDevice", "DeviceCommissioner");
     if (mDefaultCommissioner == nullptr)
@@ -582,21 +583,13 @@ CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, const char * se
     }
     ReturnErrorOnFailure(mDefaultCommissioner->SetCommissioningParameters(params));
 
-    auto threadCredentials = params.GetThreadOperationalDataset();
-    auto wiFiCredentials   = params.GetWiFiCredentials();
-    bool hasCredentials    = threadCredentials.HasValue() || wiFiCredentials.HasValue();
-
-    // If there is no network credentials, we assume that the pairing command as been issued to pair with a
-    // device that is already on the network.
-    auto pairerBehaviour = hasCredentials ? SetupCodePairerBehaviour::kCommission : SetupCodePairerBehaviour::kCommissionOnNetwork;
-
-    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, pairerBehaviour);
+    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, SetupCodePairerBehaviour::kCommission, discoveryType);
 }
 
-CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, const char * setUpCode)
+CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, const char * setUpCode, DiscoveryType discoveryType)
 {
     MATTER_TRACE_EVENT_SCOPE("PairDevice", "DeviceCommissioner");
-    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, SetupCodePairerBehaviour::kCommission);
+    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, SetupCodePairerBehaviour::kCommission, discoveryType);
 }
 
 CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, RendezvousParameters & params)
@@ -614,10 +607,10 @@ CHIP_ERROR DeviceCommissioner::PairDevice(NodeId remoteDeviceId, RendezvousParam
     return Commission(remoteDeviceId, commissioningParams);
 }
 
-CHIP_ERROR DeviceCommissioner::EstablishPASEConnection(NodeId remoteDeviceId, const char * setUpCode)
+CHIP_ERROR DeviceCommissioner::EstablishPASEConnection(NodeId remoteDeviceId, const char * setUpCode, DiscoveryType discoveryType)
 {
     MATTER_TRACE_EVENT_SCOPE("EstablishPASEConnection", "DeviceCommissioner");
-    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, SetupCodePairerBehaviour::kPaseOnly);
+    return mSetUpCodePairer.PairDevice(remoteDeviceId, setUpCode, SetupCodePairerBehaviour::kPaseOnly, discoveryType);
 }
 
 CHIP_ERROR DeviceCommissioner::EstablishPASEConnection(NodeId remoteDeviceId, RendezvousParameters & params)

src/controller/CHIPDeviceController.h

@@ -403,9 +403,11 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
      *
      * @param[in] remoteDeviceId        The remote device Id.
      * @param[in] setUpCode             The setup code for connecting to the device
+     * @param[in] discoveryType         The network discovery type, defaults to DiscoveryType::kAll.
      */
-    CHIP_ERROR PairDevice(NodeId remoteDeviceId, const char * setUpCode);
-    CHIP_ERROR PairDevice(NodeId remoteDeviceId, const char * setUpCode, const CommissioningParameters & CommissioningParameters);
+    CHIP_ERROR PairDevice(NodeId remoteDeviceId, const char * setUpCode, DiscoveryType discoveryType = DiscoveryType::kAll);
+    CHIP_ERROR PairDevice(NodeId remoteDeviceId, const char * setUpCode, const CommissioningParameters & CommissioningParameters,
+                          DiscoveryType discoveryType = DiscoveryType::kAll);
 
     /**
      * @brief
@@ -466,8 +468,10 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
      *
      * @param[in] remoteDeviceId        The remote device Id.
      * @param[in] setUpCode             The setup code for connecting to the device
+     * @param[in] discoveryType         The network discovery type, defaults to DiscoveryType::kAll.
      */
-    CHIP_ERROR EstablishPASEConnection(NodeId remoteDeviceId, const char * setUpCode);
+    CHIP_ERROR EstablishPASEConnection(NodeId remoteDeviceId, const char * setUpCode,
+                                       DiscoveryType discoveryType = DiscoveryType::kAll);
 
     /**
      * @brief

src/controller/SetUpCodePairer.cpp

@@ -36,12 +36,14 @@ constexpr uint32_t kDeviceDiscoveredTimeout = CHIP_CONFIG_SETUP_CODE_PAIRER_DISC
 namespace chip {
 namespace Controller {
 
-CHIP_ERROR SetUpCodePairer::PairDevice(NodeId remoteId, const char * setUpCode, SetupCodePairerBehaviour commission)
+CHIP_ERROR SetUpCodePairer::PairDevice(NodeId remoteId, const char * setUpCode, SetupCodePairerBehaviour commission,
+                                       DiscoveryType discoveryType)
 {
     VerifyOrReturnError(mSystemLayer != nullptr, CHIP_ERROR_INCORRECT_STATE);
 
     SetupPayload payload;
     mConnectionType = commission;
+    mDiscoveryType  = discoveryType;
 
     bool isQRCode = strncmp(setUpCode, kQRCodePrefix, strlen(kQRCodePrefix)) == 0;
     if (isQRCode)
@@ -73,7 +75,7 @@ CHIP_ERROR SetUpCodePairer::Connect(SetupPayload & payload)
 
     bool searchOverAll = !payload.rendezvousInformation.HasValue();
 
-    if (mConnectionType != SetupCodePairerBehaviour::kCommissionOnNetwork)
+    if (mDiscoveryType == DiscoveryType::kAll)
     {
         if (searchOverAll || payload.rendezvousInformation.Value().Has(RendezvousInformationFlag::kBLE))
         {
@@ -229,8 +231,7 @@ bool SetUpCodePairer::ConnectToDiscoveredDevice()
         ExpectPASEEstablishment();
 
         CHIP_ERROR err;
-        if (mConnectionType == SetupCodePairerBehaviour::kCommission ||
-            mConnectionType == SetupCodePairerBehaviour::kCommissionOnNetwork)
+        if (mConnectionType == SetupCodePairerBehaviour::kCommission)
         {
             err = mCommissioner->PairDevice(mRemoteId, params);
         }

src/controller/SetUpCodePairer.h

@@ -51,18 +51,24 @@ class DeviceCommissioner;
 enum class SetupCodePairerBehaviour : uint8_t
 {
     kCommission,
-    kCommissionOnNetwork,
     kPaseOnly,
 };
 
+enum class DiscoveryType : uint8_t
+{
+    kDiscoveryNetworkOnly,
+    kAll,
+};
+
 class DLL_EXPORT SetUpCodePairer : public DevicePairingDelegate
 {
 public:
     SetUpCodePairer(DeviceCommissioner * commissioner) : mCommissioner(commissioner) { ResetDiscoveryState(); }
     virtual ~SetUpCodePairer() {}
 
     CHIP_ERROR PairDevice(chip::NodeId remoteId, const char * setUpCode,
-                          SetupCodePairerBehaviour connectionType = SetupCodePairerBehaviour::kCommission);
+                          SetupCodePairerBehaviour connectionType = SetupCodePairerBehaviour::kCommission,
+                          DiscoveryType discoveryType             = DiscoveryType::kAll);
 
     // Called by the DeviceCommissioner to notify that we have discovered a new device.
     void NotifyCommissionableDeviceDiscovered(const chip::Dnssd::DiscoveredNodeData & nodeData);
@@ -152,6 +158,7 @@ class DLL_EXPORT SetUpCodePairer : public DevicePairingDelegate
     chip::NodeId mRemoteId;
     uint32_t mSetUpPINCode                   = 0;
     SetupCodePairerBehaviour mConnectionType = SetupCodePairerBehaviour::kCommission;
+    DiscoveryType mDiscoveryType             = DiscoveryType::kAll;
 
     // While we are trying to pair, we intercept the DevicePairingDelegate
     // notifications from mCommissioner.  We want to make sure we send them on