ESP32 WiFi Library – WiFi.waitForConnectResult

Home / References / ESP32 Library / WiFi API / Station

Description

The waitForConnectResult method in the ESP32 WiFi library is designed to wait for the outcome of a WiFi connection attempt, allowing the developer to specify a timeout period. It checks repeatedly if the ESP32 has successfully connected to the specified WiFi network or if the connection attempt has failed, returning one of several status codes such as WL_CONNECTED or WL_CONNECT_FAILED. Notably, this method does not always block for the entire duration of the specified timeout; instead, it exits immediately upon detecting a successful connection or an early failure (e.g., incorrect credentials or unavailable SSID)

Syntax and Usage

The waitForConnectResult method can be used in the following ways:

– Without Arguments:

WiFi.waitForConnectResult();

Calling waitForConnectResult() without any arguments in the ESP32 WiFi library invokes the method with a default timeout period. This method waits for the WiFi connection attempt to conclude, either by successfully connecting to the specified network or failing to do so, and it returns a status code indicating the outcome of the connection attempt. By not specifying an argument, you rely on the library’s default timeout value, which may vary depending on the implementation but is typically set to a reasonable duration to allow sufficient time for the connection process to complete. However, similar to calling the method with a specified timeout, it will exit early if the connection succeeds or fails before the default timeout elapses, ensuring efficient use of resources while avoiding indefinite blocking.

– With Arguments:

WiFi.waitForConnectResult(timeout);

Calling waitForConnectResult(timeout) with an argument allows you to specify a custom timeout duration (in milliseconds) for the WiFi connection attempt. This method waits up to the given timeout for the connection to succeed or fail, returning a status code indicating the outcome. By setting a specific timeout, you control how long the method will wait before giving up on the connection attempt, providing flexibility for different application needs. If the connection is established or fails within the timeout period, the method returns immediately; otherwise, it waits until the timeout elapses. This approach offers precise management of connection attempts, especially useful for ensuring that your application can handle connection delays or failures gracefully without being blocked indefinitely.

Argument(s)

The waitForConnectResult method accepts the following argument:

• timeout: (Optional, unsigned long) The maximum time in milliseconds to wait for the connection result. If omitted, the method uses the default timeout value. The default timeout is determined by the library settings.

Return Value

The waitForConnectResult method returns an integer representing the status code of the connection attempt. This list describes the various status codes returned by the ESP32 WiFi library that indicate the current state of the WiFi connection. Understanding these statuses can help in debugging connection issues and ensuring smooth operation of your IoT projects.

• WL_IDLE_STATUS (0): The WiFi radio is in an idle state, not attempting to connect.
• WL_NO_SSID_AVAIL (1): The configured SSID is not available or cannot be found.
• WL_SCAN_COMPLETED (2): A WiFi network scan has been completed successfully.
• WL_CONNECTED (3): Successfully connected to the configured WiFi network.
• WL_CONNECT_FAILED (4): Failed to connect to the configured WiFi network, possibly due to incorrect credentials or other issues.
• WL_CONNECTION_LOST (5): The connection to the WiFi network was lost, indicating a problem maintaining the connection.
• WL_DISCONNECTED (6): The WiFi module is disconnected from any WiFi network.

Example Codes

Below are examples demonstrating how to use the waitForConnectResult method:

Example 1: Wait for the Connection Using Default Timeout

This example demonstrates how to wait for the WiFi connection result using the default timeout:

Note: Replace YourSSID and YourPassword with your WiFi credentials. Monitor the Serial output to see the connection result.

/*
 * Author: Avant Maker
 * Date: February 7, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to wait
 * for the WiFi connection result using ESP32 WiFi Library's
 * waitForConnectResult method. Call the method without arguments
 * to wait for the connection result using the default timeout.
 *
 * 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/home/all-about-esp32-arduino-core-library/
 *
 * 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);

    // Attempt to connect to a WiFi network
    WiFi.begin("YourSSID", "YourPassword");

    // Wait for the connection result
    int result = WiFi.waitForConnectResult();

    // Check the result
    if (result == WL_CONNECTED) {
        Serial.println("Connected to WiFi successfully.");
    } else {
        Serial.println("Failed to connect to WiFi.");
    }
}

void loop() {
    // Your code here
}

Example 2: Wait for the Connection Using a Custom Timeout

This example demonstrates how to wait for the WiFi connection result with a custom timeout:

Note: Replace YourSSID and YourPassword with your WiFi credentials. Adjust the timeout value (in milliseconds) as needed.

/*
 * Author: Avant Maker
 * Date: February 7, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to wait for
 * the WiFi connection result using ESP32 WiFi Library's
 * waitForConnectResult method. Call the method with a custom
 * timeout in milliseconds to specify how long the program
 * should wait for the connection result.
 *
 * 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/home/all-about-esp32-arduino-core-library/
 *
 * 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);

    // Attempt to connect to a WiFi network
    WiFi.begin("YourSSID", "YourPassword");

    // Wait for the connection result with a custom timeout (e.g., 10,000 ms)
    int result = WiFi.waitForConnectResult(10000);

    // Check the result
    if (result == WL_CONNECTED) {
        Serial.println("Connected to WiFi successfully.");
    } else {
        Serial.println("Failed to connect to WiFi within the timeout period.");
    }
}

void loop() {
    // Your code here
}