ESP32: Create a Wi-Fi Manager (AsyncWebServer library)

In this guide, you’ll create and set up a Wi-Fi Manager with the ESPAsyncWebServer library that you can modify to use with your web server projects or with any project that needs a connection to a Wi-Fi network. The Wi-Fi Manager allows you to connect the ESP32 board to different Access Points (networks) without hard-coding network credentials (SSID and password) and upload new code to your board. Your ESP will automatically join the last saved network or set up an Access Point that you can use to configure the network credentials.
To better understand how this project works, we recommend taking a look at the following tutorials:
Input Data on HTML Form ESP32/ESP8266 Web Server using Arduino IDE
How to Set an ESP32 Access Point (AP) for Web Server
ESP32 Static/Fixed IP Address
We also use this Wi-Fi Manager approach on the following project:
ESP32 Neopixel Status Indicator and Sensor PCB Shield with Wi-Fi Manager
How it Works
Take a look at the following diagram to understand how the Wi-Fi Manager we’ll create works.
When the ESP first starts, it tries to read the
ssid.txt
pass.txt
and
ip.txt
files* (
1
);
If the files are empty (
2
) (the first time you run the board, the files are empty), your board is set as an access point (
3
);
Using any Wi-Fi enabled device with a browser, you can connect to the newly created Access Point (default name
ESP-WIFI-MANAGER
);
After establishing a connection with the ESP-WIFI-MANAGER, you can go to the default IP address
192.168.4.1
to open a web page that allows you to configure your SSID and password (
4
);
The SSID, password, and IP address inserted in the form are saved in the corresponding files:
ssid.txt
pass.txt
, and
ip.txt
(
5
);
After that, the ESP board restarts (
6
);
This time, after restarting, the files are not empty, so the ESP will try to connect to the network in station mode using the settings you’ve inserted in the form (
7
);
If it establishes a connection, the process is completed successfully, and you can access the main web server page that can do whatever you want (control sensor readings, control outputs, display some text, etc.) (
9
). Otherwise, it will set the Access Point (
3
), and you can access the default IP address (
192.168.4.1
) to add another SSID/password combination.
*
we also created a
gateway
field and a
gateway.txt
file to save the IP address gateway (this is not shown in the diagram).
To show you how to set the Wi-Fi Manager, we’ll set up a web server that controls one output (GPIO2—the built-in LED). You can apply the Wi-Fi Manager to any web server project built with the ESPAsyncWebServer library or to any project that requires the ESP to be connected to a wi-fi network.
Prerequisites
We’ll program the ESP32 board using Arduino IDE. So make sure you have the ESP32 board add-on installed.
Installing ESP32 Board in Arduino IDE (Windows, Mac OS X, and Linux)
If you want to program the ESP32 using VS Code + PlatformIO, follow the next tutorial:
Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266 (Windows, Mac OS X, Linux Ubuntu)
Installing Libraries (Arduino IDE)
We’ll build the web server using the following libraries:
ESPAsyncWebServer
AsyncTCP
You can install these libraries in the Arduino Library Manager. Open the Library Manager by clicking the Library icon at the left sidebar.
ESPAsyncWebServer
and install the
ESPAsyncWebServer by ESP32Async
Then, install the AsyncTCP library. Search for
AsyncTCP
and install the
AsyncTCP by ESP32Async
Filesystem Uploader
Before proceeding, you need to have the ESP32 Uploader Plugin installed in your Arduino IDE.
Arduino IDE 2: Install ESP32 LittleFS Uploader (Upload Files to the Filesystem)
Organizing your Files
To keep the project organized and make it easier to understand, we’ll create four different files to build the web server:
Arduino sketch
that handles the web server;
index.html
: to define the content of the web page in station mode to control the output (or any other web page you want to build);
style.css
: to style the web pages;
wifimanager.html
: to define the web page’s content to display the Wi-Fi Manager when the ESP is in access point mode.
You should save the HTML and CSS files inside a folder called
data
inside the Arduino sketch folder, as shown in the previous diagram. We’ll upload these files to the ESP32 filesystem (LittleFS).
You can download all project files:
Download All the Arduino Project Files
Creating the HTML Files
For this project, you need two HTML files. One to build the main page that controls the output (
index.html
) and another to build the Wi-Fi Manager page (
wifimanager.html
).
index.html
Here’s the text you should copy to your
index.html
file.
<!DOCTYPE html>
<html>
<head>
<title>ESP WEB SERVER</title>
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">
<link rel=\"stylesheet\" type=\"text/css\" href=\"style.css\">
<link rel=\"icon\" type=\"image/png\" href=\"favicon.png\">
<link rel=\"stylesheet\" href=\"https://use.fontawesome.com/releases/v5.7.2/css/all.css\" integrity=\"sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr\" crossorigin=\"anonymous\">
</head>
<body>
<div class=\"topnav\">
ESP WEB SERVER</h1>
</div>
<div class=\"content\">
<div class=\"card-grid\">
<div class=\"card\">
<p class=\"card-title\"><i class=\"fas fa-lightbulb\"></i> GPIO 2</p>

<a href=\"on\"><button class=\"button-on\">ON</button></a>
<a href=\"off\"><button class=\"button-off\">OFF</button></a>
</p>
<p class=\"state\">State: %STATE%</p>
</div>
</div>
</div>
</body>
</html>
We won’t explain how this HTML file works because that’s not the purpose of this tutorial. The purpose of this tutorial is to explain the parts related to the Wi-Fi Manager.
wifimanager.html
The Wi-Fi Manager web page looks like this:
Copy the following to the
wifimanager.html
file. This creates a web page with a form with three input fields and a
Submit
button.
<!DOCTYPE html>
<html>
<head>
<title>ESP Wi-Fi Manager</title>
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">
<link rel=\"icon\" href=\"data:,\">
<link rel=\"stylesheet\" type=\"text/css\" href=\"style.css\">
</head>
<body>
<div class=\"topnav\">
ESP Wi-Fi Manager</h1>
</div>
<div class=\"content\">
<div class=\"card-grid\">
<div class=\"card\">
<form action=\"/\" method=\"POST\">

<label for=\"ssid\">SSID</label>
<input type=\"text\" id =\"ssid\" name=\"ssid\">
<label for=\"pass\">Password</label>
<input type=\"text\" id =\"pass\" name=\"pass\">
<label for=\"ip\">IP Address</label>
<input type=\"text\" id =\"ip\" name=\"ip\" value=\"192.168.1.200\">
<label for=\"gateway\">Gateway Address</label>
<input type=\"text\" id =\"gateway\" name=\"gateway\" value=\"192.168.1.1\">
<input type =\"submit\" value =\"Submit\">
</p>
</form>
</div>
</div>
</div>
</body>
</html>
In this HTML file, we create an HTML form that will make an HTTP POST request with the data submitted to the server.
<form action=\"/\" method=\"POST\">
The form contains three input fields and corresponding labels: SSID, password, and IP address.
This is the input field for the SSID:
<label for=\"ssid\">SSID</label>
<input type=\"text\" id =\"ssid\" name=\"ssid\">
This is the input field for the password.
<label for=\"pass\">Password</label>
<input type=\"text\" id =\"pass\" name=\"pass\">
There is an input field for the IP address that you want to attribute to the ESP in station mode. As default, we set it to
192.168.1.200
(you can set another default IP address, or you can delete the
value
parameter—it won’t have a default value).
<input type=\"text\" id =