add ScanNetworks step to CHIPDeviceController

src/android/CHIPTool/app/src/main/java/com/google/chip/chiptool/GenericChipDeviceListener.kt

@@ -23,6 +23,26 @@ open class GenericChipDeviceListener : ChipDeviceController.CompletionListener {
     // No op
   }
 
+  override fun onReadCommissioningInfo(vendorId: Int,productId: Int, wifiEndpointId: Int, threadEndpointId: Int) {
+    // No op
+  }
+
+  override fun onCommissioningStatusUpdate(nodeId: Long, stage: String, errorCode: Int) {
+    // No op
+  }
+
+  override fun onScanNetworksFailure(errorCode: Int) {
+    // No op
+  }
+
+  override fun onScanNetworksSuccess(
+          networkingStatus: Int,
+          debugText: Optional<String>,
+          wiFiScanResults: Optional<ArrayList<ChipStructs.NetworkCommissioningClusterWiFiInterfaceScanResult>>,
+          threadScanResults: Optional<ArrayList<ChipStructs.NetworkCommissioningClusterThreadInterfaceScanResult>>) {
+    // No op
+  }
+
   override fun onNotifyChipConnectionClosed() {
     // No op
   }

src/controller/AutoCommissioner.cpp

@@ -159,6 +159,26 @@ CommissioningStage AutoCommissioner::GetNextCommissioningStageInternal(Commissio
         }
         return CommissioningStage::kArmFailsafe;
     case CommissioningStage::kArmFailsafe:
+        if (mNeedsNetworkSetup)
+        {
+            // if there is a WiFi or a Thread endpoint, then perform scan
+            if ((mParams.GetAttemptWiFiNetworkScan() && mDeviceCommissioningInfo.network.wifi.endpoint != kInvalidEndpointId) ||
+                (mParams.GetAttemptThreadNetworkScan() && mDeviceCommissioningInfo.network.thread.endpoint != kInvalidEndpointId))
+            {
+                return CommissioningStage::kScanNetworks;
+            }
+            else
+            {
+                ChipLogProgress(Controller, "No NetworkScan enabled or WiFi/Thread endpoint not specified, skipping ScanNetworks");
+            }
+        }
+        else
+        {
+            ChipLogProgress(Controller, "Not a BLE connection, skipping ScanNetworks");
+        }
+        // skip scan step
+        return CommissioningStage::kConfigRegulatory;
+    case CommissioningStage::kScanNetworks:
         return CommissioningStage::kConfigRegulatory;
     case CommissioningStage::kConfigRegulatory:
         return CommissioningStage::kSendPAICertificateRequest;

src/controller/AutoCommissioner.h

@@ -38,6 +38,8 @@ class AutoCommissioner : public CommissioningDelegate
 
     CHIP_ERROR CommissioningStepFinished(CHIP_ERROR err, CommissioningDelegate::CommissioningReport report) override;
 
+    ReadCommissioningInfo GetReadCommissioningInfo() const { return mDeviceCommissioningInfo; }
+
 protected:
     CommissioningStage GetNextCommissioningStage(CommissioningStage currentStage, CHIP_ERROR & lastErr);
     DeviceCommissioner * GetCommissioner() { return mCommissioner; }

src/controller/CHIPDeviceController.cpp

@@ -1557,6 +1557,41 @@ void DeviceCommissioner::SendCommissioningCompleteCallbacks(NodeId nodeId, const
     }
 }
 
+void DeviceCommissioner::PauseCommissioning()
+{
+    VerifyOrReturn(mDeviceBeingCommissioned != nullptr);
+    mCommissioningPaused = true;
+}
+
+void DeviceCommissioner::ResumeCommissioning()
+{
+    VerifyOrReturn(mCommissioningPaused);
+    VerifyOrReturn(mDeviceBeingCommissioned != nullptr);
+
+    NodeId nodeId            = mDeviceBeingCommissioned->GetDeviceId();
+    DeviceProxy * proxy      = mDeviceBeingCommissioned;
+    mDeviceBeingCommissioned = nullptr;
+    CommissioningDelegate::CommissioningReport report;
+
+    if (mCommissioningDelegate == nullptr)
+    {
+        return;
+    }
+    report.stageCompleted = mCommissioningStage;
+    CHIP_ERROR status     = mCommissioningDelegate->CommissioningStepFinished(mCommissioningPausedErr, report);
+    if (status != CHIP_NO_ERROR)
+    {
+        // Commissioning delegate will only return error if it failed to perform the appropriate commissioning step.
+        // In this case, we should complete the commissioning for it.
+        CompletionStatus completionStatus;
+        completionStatus.err         = status;
+        completionStatus.failedStage = MakeOptional(report.stageCompleted);
+        mCommissioningStage          = CommissioningStage::kCleanup;
+        mDeviceBeingCommissioned     = proxy;
+        CleanupCommissioning(proxy, nodeId, completionStatus);
+    }
+}
+
 void DeviceCommissioner::CommissioningStageComplete(CHIP_ERROR err, CommissioningDelegate::CommissioningReport report)
 {
     // Once this stage is complete, reset mDeviceBeingCommissioned - this will be reset when the delegate calls the next step.
@@ -1569,6 +1604,13 @@ void DeviceCommissioner::CommissioningStageComplete(CHIP_ERROR err, Commissionin
     {
         mPairingDelegate->OnCommissioningStatusUpdate(PeerId(GetCompressedFabricId(), nodeId), mCommissioningStage, err);
     }
+
+    if (mCommissioningPaused)
+    {
+        mDeviceBeingCommissioned = proxy;
+        mCommissioningPausedErr  = err;
+        return;
+    }
     if (mCommissioningDelegate == nullptr)
     {
         return;
@@ -1724,20 +1766,24 @@ void DeviceCommissioner::OnDone(app::ReadClient *)
                 {
                     if (features.Has(app::Clusters::NetworkCommissioning::NetworkCommissioningFeature::kWiFiNetworkInterface))
                     {
+                        ChipLogError(Controller, "----- NetworkCommissioning Features: has WiFi.");
                         info.network.wifi.endpoint = path.mEndpointId;
                     }
                     else if (features.Has(
                                  app::Clusters::NetworkCommissioning::NetworkCommissioningFeature::kThreadNetworkInterface))
                     {
+                        ChipLogError(Controller, "----- NetworkCommissioning Features: has Thread.");
                         info.network.thread.endpoint = path.mEndpointId;
                     }
                     else if (features.Has(
                                  app::Clusters::NetworkCommissioning::NetworkCommissioningFeature::kEthernetNetworkInterface))
                     {
+                        ChipLogError(Controller, "----- NetworkCommissioning Features: has Ethernet.");
                         info.network.eth.endpoint = path.mEndpointId;
                     }
                     else
                     {
+                        ChipLogError(Controller, "----- NetworkCommissioning Features: no features.");
                         // TODO: Gross workaround for the empty feature map on all clusters. Remove.
                         if (info.network.thread.endpoint == kInvalidEndpointId)
                         {
@@ -1786,6 +1832,13 @@ void DeviceCommissioner::OnDone(app::ReadClient *)
     }
     mAttributeCache = nullptr;
     mReadClient     = nullptr;
+
+    // todo - callback for read commissioning info
+    if (mPairingDelegate != nullptr)
+    {
+        mPairingDelegate->OnReadCommissioningInfo(info);
+    }
+
     CommissioningDelegate::CommissioningReport report;
     report.Set<ReadCommissioningInfo>(info);
     CommissioningStageComplete(return_err, report);
@@ -1824,6 +1877,39 @@ void DeviceCommissioner::OnSetRegulatoryConfigResponse(
     commissioner->CommissioningStageComplete(err, report);
 }
 
+void DeviceCommissioner::OnScanNetworksFailure(void * context, CHIP_ERROR error)
+{
+    ChipLogProgress(Controller, "Received ScanNetworks failure response %s\n", chip::ErrorStr(error));
+
+    DeviceCommissioner * commissioner = static_cast<DeviceCommissioner *>(context);
+    if (commissioner->GetPairingDelegate() != nullptr)
+    {
+        commissioner->GetPairingDelegate()->OnScanNetworksFailure(error);
+    }
+    // need to advance to next step
+    // clear error so that we don't abort the commissioning when ScanNetworks fails
+    commissioner->CommissioningStageComplete(CHIP_NO_ERROR);
+}
+
+void DeviceCommissioner::OnScanNetworksResponse(void * context,
+                                                const NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & data)
+{
+    CommissioningDelegate::CommissioningReport report;
+
+    ChipLogProgress(Controller, "Received ScanNetwork response, networkingStatus=%u debugText=%s",
+                    to_underlying(data.networkingStatus),
+                    (data.debugText.HasValue() ? std::string(data.debugText.Value().data(), data.debugText.Value().size()).c_str()
+                                               : "none provided"));
+    DeviceCommissioner * commissioner = static_cast<DeviceCommissioner *>(context);
+
+    if (commissioner->GetPairingDelegate() != nullptr)
+    {
+        commissioner->GetPairingDelegate()->OnScanNetworksSuccess(data);
+    }
+    // need to advance to next step
+    commissioner->CommissioningStageComplete(CHIP_NO_ERROR);
+}
+
 void DeviceCommissioner::OnNetworkConfigResponse(void * context,
                                                  const NetworkCommissioning::Commands::NetworkConfigResponse::DecodableType & data)
 {
@@ -1953,6 +2039,16 @@ void DeviceCommissioner::PerformCommissioningStep(DeviceProxy * proxy, Commissio
         mReadClient     = std::move(readClient);
     }
     break;
+    case CommissioningStage::kScanNetworks: {
+        NetworkCommissioning::Commands::ScanNetworks::Type request;
+        if (params.GetWiFiCredentials().HasValue())
+        {
+            request.ssid.Emplace(params.GetWiFiCredentials().Value().ssid);
+        }
+        request.breadcrumb.Emplace(breadcrumb);
+        SendCommand<NetworkCommissioningCluster>(proxy, request, OnScanNetworksResponse, OnScanNetworksFailure, endpoint, timeout);
+        break;
+    }
     case CommissioningStage::kConfigRegulatory: {
         // To set during config phase:
         // UTC time

src/controller/CHIPDeviceController.h

@@ -560,6 +560,18 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
      */
     CHIP_ERROR ValidateAttestationInfo(const Credentials::DeviceAttestationVerifier::AttestationInfo & info);
 
+    /**
+     * @brief
+     *   This function puts the commissioner in a paused state to prevent advancing to the next stage.
+     * It is expected that a DevicePairingDelegate may call this method when processing the
+     * OnCommissioningStatusUpdate, for example, in order to obtain network credentials from the user based
+     * upon the results of the NetworkScan.
+     * Use ResumeCommissioning to continue the commissioning process.
+     *
+     */
+    void PauseCommissioning();
+    void ResumeCommissioning();
+
     /**
      * @brief
      * Sends CommissioningStepComplete report to the commissioning delegate. Function will fill in current step.
@@ -764,6 +776,10 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
         void * context,
         const chip::app::Clusters::GeneralCommissioning::Commands::SetRegulatoryConfigResponse::DecodableType & data);
     static void
+    OnScanNetworksResponse(void * context,
+                           const chip::app::Clusters::NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & data);
+    static void OnScanNetworksFailure(void * context, CHIP_ERROR err);
+    static void
     OnNetworkConfigResponse(void * context,
                             const chip::app::Clusters::NetworkCommissioning::Commands::NetworkConfigResponse::DecodableType & data);
     static void OnConnectNetworkResponse(
@@ -871,6 +887,8 @@ class DLL_EXPORT DeviceCommissioner : public DeviceController,
     Platform::UniquePtr<app::ReadClient> mReadClient;
     Credentials::AttestationVerificationResult mAttestationResult;
     Credentials::DeviceAttestationVerifier * mDeviceAttestationVerifier = nullptr;
+    bool mCommissioningPaused                                           = false;
+    CHIP_ERROR mCommissioningPausedErr                                  = CHIP_NO_ERROR;
 };
 
 } // namespace Controller

src/controller/CommissioningDelegate.h

@@ -35,6 +35,7 @@ enum CommissioningStage : uint8_t
     kSecurePairing,
     kReadCommissioningInfo,
     kArmFailsafe,
+    kScanNetworks,
     kConfigRegulatory,
     kSendPAICertificateRequest,
     kSendDACCertificateRequest,
@@ -352,6 +353,20 @@ class CommissioningParameters
 
     Credentials::DeviceAttestationDelegate * GetDeviceAttestationDelegate() const { return mDeviceAttestationDelegate; }
 
+    bool GetAttemptWiFiNetworkScan() const { return mAttemptWiFiNetworkScan; }
+    CommissioningParameters & SetAttemptWiFiNetworkScan(bool attemptWiFiNetworkScan)
+    {
+        mAttemptWiFiNetworkScan = attemptWiFiNetworkScan;
+        return *this;
+    }
+
+    bool GetAttemptThreadNetworkScan() const { return mAttemptThreadNetworkScan; }
+    CommissioningParameters & SetAttemptThreadNetworkScan(bool attemptThreadNetworkScan)
+    {
+        mAttemptThreadNetworkScan = attemptThreadNetworkScan;
+        return *this;
+    }
+
 private:
     // Items that can be set by the commissioner
     Optional<uint16_t> mFailsafeTimerSeconds;
@@ -379,6 +394,8 @@ class CommissioningParameters
     CompletionStatus completionStatus;
     Credentials::DeviceAttestationDelegate * mDeviceAttestationDelegate =
         nullptr; // Delegate to handle device attestation failures during commissioning
+    bool mAttemptWiFiNetworkScan   = false;
+    bool mAttemptThreadNetworkScan = true; // TODO: consider whether default value should be enabled or disabled
 };
 
 struct RequestedCertificate

src/controller/DevicePairingDelegate.h

@@ -75,6 +75,26 @@ class DLL_EXPORT DevicePairingDelegate
     {}
 
     virtual void OnCommissioningStatusUpdate(PeerId peerId, CommissioningStage stageCompleted, CHIP_ERROR error) {}
+
+    /**
+     * @brief
+     *  Called with the ReadCommissioningInfo returned from the target
+     */
+    virtual void OnReadCommissioningInfo(ReadCommissioningInfo info) {}
+
+    /**
+     * @brief
+     *  Called with the NetworkScanResponse returned from the target
+     */
+    virtual void OnScanNetworksSuccess(
+        const chip::app::Clusters::NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & dataResponse)
+    {}
+
+    /**
+     * @brief
+     *  Called when the NetworkScan request fails.
+     */
+    virtual void OnScanNetworksFailure(CHIP_ERROR error) {}
 };
 
 } // namespace Controller