ESP32 WiFi Library –WiFiMulti.scanComplete

Home / References / ESP32 Library / WiFi API / WiFiScan

Description

The WiFi.scanComplete method is part of the ESP32 WiFi Library and is used to check the status of an asynchronous WiFi network scan initiated by WiFi.scanNetworks(true). This method allows developers to determine whether the scan has finished and retrieve the number of discovered networks without blocking the program’s execution, making it ideal for non-blocking IoT applications.

Syntax and Usage

The WiFi.scanComplete method is straightforward and does not accept any arguments. It is typically used after starting an asynchronous scan with WiFi.scanNetworks(true). Below is the syntax:

int16_t WiFi.scanComplete();

There is only one way to use this method:

• Without Arguments: Call WiFi.scanComplete() to check the status of an ongoing or completed asynchronous scan and retrieve the number of networks found.

Argument(s)

This method does not require any arguments.

Return Value

The WiFi.scanComplete method returns an int16_t value indicating the status of the scan:

• Positive value (≥ 0): The scan is complete, and the value represents the number of WiFi networks discovered.
• -1 (WIFI_SCAN_RUNNING): The scan is still in progress.
• -2 (WIFI_SCAN_FAILED): The scan has not been triggered or has failed.

Example Codes

This code demonstrates how to use the ESP32 WiFiScan class’s scanComplete() method to check the status of an asynchronous WiFi scan. The scanComplete() method allows you to determine whether the scan is still running, has completed successfully, or has failed. Once the scan is complete, the code retrieves and displays the list of detected networks, including their SSID and signal strength (RSSI). This approach is useful for non-blocking WiFi scanning, enabling the ESP32 to perform other tasks while waiting for the scan results.

To use this code, upload it to your ESP32 and open the Serial Monitor at 115200 baud. The ESP32 starts an asynchronous WiFi scan and continuously checks its status using scanComplete(). If networks are found, their details are printed; otherwise, a failure message is shown. Ensure the ESP32 is within range of WiFi signals for accurate results. You can adjust the delay or add further actions after the scan completes, such as initiating another scan or processing the results.

/*
 * Author: Avant Maker
 * Date: February 21, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to 
 * use WiFi.scanComplete in an asynchronous WiFi scan. 
 * It starts a scan in the background and periodically checks
 * for completion, printing the results once the scan is done.
 *
 * License: MIT 
 * 
 * Code Source: This example code is sourced from the Comprehensive 
 * Guide to the ESP32 Arduino Core Library, accessible on 
 * AvantMaker.com. For additional code examples and in-depth 
 * documentation related to the ESP32 Arduino Core Library, 
 * please visit:
 *
 * https://avantmaker.com/references/esp32-arduino-core-index/
 *
 * AvantMaker.com, your premier destination for all things 
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated 
 * to empowering makers,learners, and enthusiasts with the resources
 *  they need to bring their innovative ideas to life.
 */

#include <WiFi.h>

void setup() {
    Serial.begin(115200);
    
    // Set WiFi to station mode
    WiFi.mode(WIFI_STA);
    WiFi.disconnect();
    delay(100);

    // Start an asynchronous scan
    Serial.println("Starting asynchronous WiFi scan...");
    WiFi.scanNetworks(true); // true for async
}

void loop() {
    // Check scan status
    int16_t scanResult = WiFi.scanComplete();
    
    if (scanResult == WIFI_SCAN_RUNNING) {
        Serial.println("Scan in progress...");
        delay(500); // Wait before checking again
    } else if (scanResult >= 0) {
        Serial.printf("Scan complete! %d networks found:\n", scanResult);
        for (int i = 0; i < scanResult; i++) {
            Serial.printf("%d: %s (RSSI: %d)\n", i + 1, WiFi.SSID(i).c_str(), WiFi.RSSI(i));
        }
        WiFi.scanDelete(); // Clear scan results from memory
        delay(5000); // Wait before next action
    } else if (scanResult == WIFI_SCAN_FAILED) {
        Serial.println("Scan failed or not triggered.");
        delay(5000); // Wait before retrying or next action
    }
    
}