ESP32 WiFi Library –WiFiMulti.scanNetworks

Home / References / ESP32 Library / WiFi API / WiFiScan

Description

The WiFi.scanNetworks method is a powerful function in the ESP32 WiFi Library that allows you to scan for available Wi-Fi networks within the range of your ESP32 device. This method is particularly useful for IoT projects where you need to detect nearby access points (APs), analyze signal strength, or select a network to connect to. It returns the number of networks found, making it an essential tool for network discovery and diagnostics in DIY and STEM applications.

Syntax and Usage

The WiFi.scanNetworks method can be used with or without arguments, depending on your project’s needs. Below are the different ways to call this method:

– Without Arguments:

int16_t n = WiFi.scanNetworks();

Scans for all available Wi-Fi networks synchronously, using default settings. This is the simplest way to perform a scan and is suitable for basic use cases.

– With Arguments:

int16_t n = WiFi.scanNetworks(async, show_hidden, passive, max_ms_per_chan, channel);

Provides advanced options to customize the scan behavior, such as asynchronous scanning, detecting hidden networks, or specifying a channel. This is ideal for more complex IoT or network analysis projects.

For practical applications and examples of this method, please consult the “Example Code” section on this page. This section provides comprehensive guidance to help you better understand and apply the method effectively.

Argument(s)

The WiFi.scanNetworks method supports the following optional arguments:

• async (bool): If set to true, the scan is performed asynchronously, allowing other tasks to run while scanning. Default is false (synchronous).
• show_hidden (bool): If true, hidden networks (those not broadcasting their SSID) are included in the results. Default is false.
• passive (bool): If true, performs a passive scan (listening only) instead of an active scan (sending probe requests). Default is false.
• max_ms_per_chan (uint32_t): Maximum time (in milliseconds) spent scanning each channel. Default is 300 ms.
• channel (uint8_t): Limits the scan to a specific channel (1-13). If set to 0, scans all channels. Default is 0.

Return Value

The WiFi.scanNetworks method returns an int16_t value representing the number of Wi-Fi networks found during the scan. If the scan fails, it returns WIFI_SCAN_FAILED (typically -2). A return value of 0 indicates no networks were detected.

Example Codes

Example 1: Basic Synchronous Scan

This code demonstrates how to use the ESP32 WiFiScan class’s scanNetworks() method to detect and list all available WiFi networks in the surrounding area. The method performs a synchronous scan, identifying nearby networks and providing details such as their SSID (name) and signal strength (RSSI). This functionality is useful for applications like network monitoring, device discovery, or analyzing WiFi environments.

To use this code, upload it to your ESP32 and open the Serial Monitor at 115200 baud. The code sets the ESP32 to station mode and disconnects from any previous connections before scanning. It then prints the number of networks found, along with their names and signal strengths, every 5 seconds. Ensure the ESP32 is powered on and within range of WiFi networks to see the scan results. Replace any delays or parameters if you need faster or customized scans.

/*
 * Author: Avant Maker
 * Date: February 21, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to 
 * use WiFi.scanNetworks to conduct a simple synchronous scan
 * with ESP32 to list all visible networks with their 
 * SSID and signal strength (RSSI).
 *
 * 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);
    WiFi.mode(WIFI_STA); // Set WiFi to station mode
    WiFi.disconnect();   // Disconnect from any previous connection
    delay(100);
}

void loop() {
    Serial.println("Starting WiFi scan...");
    int16_t n = WiFi.scanNetworks(); // Perform synchronous scan
    Serial.println("Scan complete!");

    if (n == 0) {
        Serial.println("No networks found.");
    } else {
        Serial.print(n);
        Serial.println(" networks found:");
        for (int i = 0; i < n; ++i) {
            Serial.print(i + 1);
            Serial.print(": ");
            Serial.print(WiFi.SSID(i));     // Network name
            Serial.print(" (");
            Serial.print(WiFi.RSSI(i));     // Signal strength
            Serial.println(" dBm)");
            delay(10);
        }
    }
    Serial.println("");
    delay(5000); // Wait 5 seconds before scanning again
}

Example 2: Asynchronous Scan with Hidden Networks

This code demonstrates how to use the ESP32 WiFiScan class’s scanNetworks() method in asynchronous mode to scan for available WiFi networks, including hidden ones. By setting the method’s parameters to true, the scan runs in the background, allowing the ESP32 to perform other tasks while detecting networks. The code retrieves details like SSID (network name) and signal strength (RSSI), even identifying hidden networks that don’t broadcast their names. This approach is useful for applications requiring non-blocking network scanning.

To use this code, upload it to your ESP32 and open the Serial Monitor at 115200 baud. The ESP32 starts an asynchronous WiFi scan, checks the results after a short delay, and prints the number of networks found along with their details. If no networks are detected, it notifies accordingly. Ensure the ESP32 is powered on and within range of WiFi signals for accurate results. Adjust the delay or parameters if you need faster scans or want to customize behavior further.

/*
 * Author: Avant Maker
 * Date: February 21, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to 
 * use WiFi.scanNetworks to perform an asynchronous scan 
 * hidden networks.
 *
 * 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);
    WiFi.mode(WIFI_STA); // Set WiFi to station mode
    WiFi.disconnect();
    delay(100);
}

void loop() {
    Serial.println("Starting asynchronous WiFi scan...");
    int16_t n = WiFi.scanNetworks(true, true); // Async scan with hidden networks
    Serial.println("Scan initiated (running in background)...");

    // Check scan status after some delay
    delay(2000); // Wait for scan to complete (adjust based on max_ms_per_chan)
    if (n == WIFI_SCAN_FAILED) {
        Serial.println("Scan failed!");
    } else if (n == 0) {
        Serial.println("No networks found.");
    } else {
        Serial.print(n);
        Serial.println(" networks found:");
        for (int i = 0; i < n; ++i) {
            Serial.print(i + 1);
            Serial.print(": ");
            Serial.print(WiFi.SSID(i).length() > 0 ? WiFi.SSID(i) : "[Hidden]");
            Serial.print(" (");
            Serial.print(WiFi.RSSI(i));
            Serial.println(" dBm)");
            delay(10);
        }
    }
    Serial.println("");
    delay(5000); // Wait before next scan
}