ESP32 Arduino: Getting started with WiFi events

In this tutorial we will get started working with WiFi events on the ESP32, to check when the device connects to an Access Point. We will be using the Arduino core. The tests shown here were performed using an ESP32 board from DFRobot.

Introduction

In this tutorial we will get started working with WiFi events on the ESP32, to check when the device connects to an Access Point. We will be using the Arduino core.

In a lot of previous tutorials, we have been connecting the ESP32 to WiFi networks for different application scenarios. The Arduino core provides a very high level WiFi API that makes it really simple to work with this technology.

In short, we simply need to declare the credentials of the network we want to connect to (network name and password) and then call the begin method on an extern variable called WiFi. This extern variable becomes available when we include the WiFi.h library.

One particularity about this begin method is that it returns before the connection is finished. The WiFi connection procedure may take a while. Nonetheless, for the applications we have been covering so far, the rest of the code depends on being already connected to the network.

Thus, for those simpler use cases, it was acceptable to do some polling until the connection was established. Nonetheless, this might not be the case for many other use cases where it might not be feasible to block the execution until the connection is established.

So, we have the option to work with WiFi events that are triggered by the lower layers of the framework. More precisely, we can define event handling functions that are executed when the events occur.

Note however that these events are much lower level than the Arduino APIs we have been using so far. This gives us control over the different phases of the WiFi connection procedure, giving us much more flexibility (but also making the process more complex).

This document from the IDF framework (used under the hood by the Arduino core) gives a very detailed explanation about all the available events and when they are triggered.

By looking into the available events, it is easy to see that the complexity increases. For example, we have an event that indicates if the ESP32 is connected to the Access Point (SYSTEM_EVENT_STA_CONNECTED).

Nonetheless, at that point, the ESP32 still doesn’t have an IP address associated yet. This means we cannot create socket connections yet at this point. Consequently, we cannot use any other protocol that works on top of sockets (ex: HTTP).

So, there is another event that indicates the ESP32 successfully got an IP address (SYSTEM_EVENT_STA_GOT_IP).

In this introductory tutorial we will register an event handling function to catch the event that is triggered when the device connects to the Access Point (SYSTEM_EVENT_STA_CONNECTED).

The tests shown here were performed using an ESP32 board from DFRobot.

The code

We will start the code by including the WiFi.h library, which is needed to be able to connect the ESP32 to a WiFi network.

Upon including this library, we will have access to the WiFi extern variable, which we can use for operations such as registering event handlers or connecting the device to an Access Point.

#include <WiFi.h>

Then we need to declare the credentials of the WiFi network, so we can connect the ESP32 to it. We will need both the network name (SSID) and password.

const char* ssid = "yourNetworkName";
const char* password =  "yourNetworkPassword";

Moving on to the Arduino setup function, we will open a serial connection, so we can later output the results of our program.

	
Serial.begin(115200);

Then we need to register our WiFi event handler function. This is done with a call to the onEvent method on the WiFi extern variable.

As first input this method receives the event handling function. We will call this function WiFiStationConnected and we will analyze its implementation below. But, in short, its implementation will simply consist on printing a message indicating that the connection to the Access Point was established.
As second input, the method receives the ID of the event we want to catch. You can check here the list of available events. In our case, we want the SYSTEM_EVENT_STA_CONNECTED event.

WiFi.onEvent(WiFiStationConnected, SYSTEM_EVENT_STA_CONNECTED);

After registering the event handler function, we can connect the ESP32 to a WiFi network. We do this by calling the begin method on the WiFi extern variable, passing as input the network name and password we declared as global variables.

WiFi.begin(ssid, password);

As already mentioned, this method will start the connection to the WiFi network, but it will return before the connection is finished.

WiFi.begin(ssid, password);

Just to confirm that the previous method returned before the connection to the Access Point finished, we will print a message in the Arduino main loop. It is expected that this message is printed before any content from the event handling function.

void loop(){
  Serial.println("main loop..");
  delay(500);  
}

To finalize, we will take care of defining our event handling function. As already mentioned, it will be called WiFiStationConnected.

This function needs to follow a pre-defined signature, which is specified here. As can be seen, it needs to return void and receive the following two parameters:

A system_event_id_t enum value

A system_event_info_t union

For this tutorial we won’t be using any of these parameters. We will simply print a message indicating that the ESP32 is connected to the Access Point.

void WiFiStationConnected(WiFiEvent_t event, WiFiEventInfo_t info)
{
    Serial.println("Connected to AP!");
}

The final code can be seen below.

#include <WiFi.h>
 
const char* ssid = "yourNetworkName";
const char* password =  "yourNetworkPassword";
 
void WiFiStationConnected(WiFiEvent_t event, WiFiEventInfo_t info)
{
    Serial.println("Connected to AP!");
}
 
void setup()
{
    Serial.begin(115200);
 
    WiFi.onEvent(WiFiStationConnected, SYSTEM_EVENT_STA_CONNECTED);
     
    WiFi.begin(ssid, password);
 
}
 
void loop(){
  Serial.println("main loop..");
  delay(500);  
}

Testing the code

To test the code,simply compile and upload the code from the previous section to your ESP32, using the Arduino IDE.

Once the procedure finishes, open the IDE serial monitor. You should get an output similar to figure 1. As can be seen, we have obtained a “Connected to AP” message, indicating that the event handling function was correctly executed.

Also, the “main loop” message was printed twice before we got the message from the event handling function, which means that the begin method returns before the connection is established, as expected.

Figure 1 – Output of the program, showing the message printed by the event handling function.

Related Content

WiFi events documentation