ESP32 WiFi Library – WiFiMulti.setConnectionTestCallbackFunc

Home / References / ESP32 Library / WiFi API / WiFiMulti

Description

The setConnectionTestCallbackFunc method in the ESP32 WiFiMulti class allows you to define a custom callback function to evaluate the suitability of a connected WiFi network based on specific criteria. While it is commonly used to test for internet connectivity, its functionality is not limited to this purpose. You can use it to perform a wide range of tests, such as verifying signal quality, checking for the availability of specific services or devices, ensuring authentication with a private network, or validating network-specific conditions.

To use this method, you need to create a custom callback function that implements your desired test logic and then pass it to setConnectionTestCallbackFunc. The ESP32 will execute this function after connecting to a network, and only if the callback returns true will the connection be considered valid. This flexibility makes setConnectionTestCallbackFunc a powerful tool for tailoring WiFi connections to meet the unique requirements of your application.

Syntax and Usage

The setConnectionTestCallbackFunc method is used by assigning a callback function to it. Below is the syntax:

wifiMulti.setConnectionTestCallbackFunc(callbackFunction);

• With a Callback Function: Pass a user-defined function that returns a bool value. This function is called after connecting to an AP to test the connection’s validity (e.g., internet availability). The callback should return true if the connection meets your criteria, or false to trigger a switch to another AP.
• With NULL: Pass NULL to disable the callback feature. When disabled, WiFiMulti.run() considers any successful AP connection valid without further testing.

Argument(s)

• callbackFunction: A function pointer of type ConnectionTestCB_t, which is a typedef for std::function. This argument is the callback function you define to test the connection. It takes no parameters and returns a bool.

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.

Return Value

The setConnectionTestCallbackFunc method does not return a value (i.e., its return type is void). It configures the WiFiMulti object to use the provided callback function during connection attempts.

Example Codes

Example: Testing Internet Connectivity with a Callback

This code demonstrates how to use the ESP32 WiFiMulti class’s setConnectionTestCallbackFunc() method to ensure that the ESP32 connects only to WiFi networks with active internet access. The callback function, testConnection(), checks for internet connectivity by sending an HTTP request and verifying the response. If the test passes, the connection is considered valid; otherwise, the ESP32 will attempt to connect to another network from the list.

To use this code, replace “Network1”, “password1”, and other placeholders with your actual WiFi credentials. Upload the code to your ESP32 and open the Serial Monitor at 115200 baud. The code adds multiple networks using addAP(), sets the callback function with setConnectionTestCallbackFunc(), and attempts to connect to a network with internet access using run(). If successful, it prints the SSID and IP address; otherwise, it notifies of the failure. Ensure the ESP32 is within range of at least one network with internet access for a successful connection.

/*
 * Author: Avant Maker
 * Date: February 18, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to 
 * use setConnectionTestCallbackFunc to ensure the 
 * ESP32 only stays connected to an AP with internet access.
 *
 * 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>
#include <WiFiMulti.h>
#include <HTTPClient.h>

WiFiMulti wifiMulti;

// Callback function to test internet connectivity
bool testConnection() {
  HTTPClient http;
  http.begin("http://www.espressif.com");
  int httpCode = http.GET();
  // we expect to get a 301 because it will ask to use HTTPS instead of HTTP
  if (httpCode == HTTP_CODE_MOVED_PERMANENTLY) {
    return true;
  }
  return false;
}

void setup() {
    Serial.begin(115200);
    delay(10);

    // Add multiple APs
    wifiMulti.addAP("Network1", "password1");
    wifiMulti.addAP("Network2", "password2");
    wifiMulti.addAP("Network3", "password3");

    // Set the connection test callback
    wifiMulti.setConnectionTestCallbackFunc(testConnection);

    Serial.println("Connecting to WiFi with internet access...");
    if (wifiMulti.run() == WL_CONNECTED) {
        Serial.println("Connected to WiFi with internet!");
        Serial.print("SSID: ");
        Serial.println(WiFi.SSID());
        Serial.print("IP Address: ");
        Serial.println(WiFi.localIP());
    } else {
        Serial.println("Failed to connect to any AP with internet.");
    }
}

void loop() {
    // Maintain connection with internet check
    if (wifiMulti.run() != WL_CONNECTED) {
        Serial.println("Lost connection, retrying...");
    }
    delay(5000);
}