This post explains the reasoning and philosophy behind the ESP8266 IoT Framework. Since the framework is evolving over time, some of this post might be outdated. Find the latest on GitHub .

One crucial component for the ESP8266 IoT framework is a WiFi manager. It is not hard to connect an ESP8266 to a WiFi network with the standard Arduino libraries if you manually enter your credentials in your code. But of course that is not how we want to approach it here. The WiFi manager should allow the user to enter the right WiFi details in the browser, and try to connect to that network automatically.

To start with the credits first: there is already a popular WiFi manager out there by tzapu . The WiFi code in this class is robust and proven in use, but what I liked less, is that the web interface for managing WiFi credentials is completely integrated into the application. Instead, I preferred the web interface to be separate and to communicate with the rest of the application through an API, as discussed in my previous post. Therefore I decided to take only the WiFi code from the existing class, and reshape it to fit my own architecture.

I will discuss the implementation with two examples. First I will show what happens when you initialize the application, and secondly I will present the state machine for updating the WiFi credentials when the application is running.

Starting the Application

All you need to write in the setup of your program is the following line:

WiFiManager.begin("your-access-point-name");

The function argument is the network name that will be used in case a hotspot has to be started by the ESP8266. The flow chart that is implemented by this function is shown below.

The flowchart of the WiFiManager.begin function

In short, the WiFi manager tries to connect to existing network details, and if this fails, or these are not available a hotspot will be started. This is implemented as a captive portal so that as soon as you connect to this network from a computer or phone, a web page should pop up where you can enter the WiFi details. This is implemented by redirecting all requested URLs automatically to the WiFi page.

One other nice thing I found out is that the WiFi functions from the ESP8266 store the SSID and password in flash automatically. In past implementations I did, I stored these in EEPROM, but it turns out this was completely unneccessary. The WiFi details are already inherently persistent between power cycles.

Web interface

The page for changing the WiFi details is integrated with the rest of the web interface and is served from the default address of 192.168.4.1 in case of a captive portal.

This page shows the current WiFi status and allows you to change the network

If the save button is clicked, the following callback is executed within the web server class:

//update WiFi details
server.on(PSTR("/api/wifi/set"), HTTP_GET, [](AsyncWebServerRequest *request) 
{
    request->send(200, PSTR("text/html"), ""); //respond first because of wifi change
    WiFiManager.setNewWifi(request->arg("ssid"), request->arg("pass"));
});

This function sets a flag which is checked in the WifiManager.loop. This function in turn calls WiFiManager.connectNewWiFi in which the actual change will be performed. This mechanism is needed to make the WiFi update asynchronous from the web server callback.

Changing WiFi settings

If the WiFi settings are saved from the GUI, WiFiManager.connectNewWiFi is called to update the WiFi details accordingly. This function follows the flow shown in the diagram below.

This process is quite easy to understand. First the method tries to connect to the new WiFi details. If this fails it checks if it is currently connected to another network, or if it is running a hotspot with a captive portal. In this second case it keeps the hotspot and waits for new input. If the connection to new details has failed and old details are still known, the WiFi manager reverts to these. If even that fails, again a hotspot is started to capture new user input.

The flowchart of the WiFiManager.connectNewWifi function

Full Source Code

This post only contained some snippets of the code to explain the high level approach that was taken. The full implementation for the ESP8266 IoT framework is found on GitHub . The documentation for the WiFi manager can be found here .