ESP32 Async Web Server – Control Outputs with Arduino IDE (ESPAsyncWebServer library)

In this tutorial you’ll learn how to build an asynchronous web server with the ESP32 board to control its outputs. The board will be programmed using Arduino IDE, and we’ll use the ESPAsyncWebServer library.

ESP32 Async Web Server Control Outputs with Arduino IDE

You might also like: ESP8266 NodeMCU Async Web Server – Control Outputs with Arduino IDE (ESPAsyncWebServer library)

Asynchronous Web Server

To build the web server we’ll use the ESPAsyncWebServer library that provides an easy way to build an asynchronous web server. Building an asynchronous web server has several advantages as mentioned in the library GitHub page, such as:

  • “Handle more than one connection at the same time”;
  • “When you send the response, you are immediately ready to handle other connections while the server is taking care of sending the response in the background”;
  • “Simple template processing engine to handle templates”;
  • And much more.

Take a look at the library documentation on its GitHub page.

Parts Required

In this tutorial we’ll control three outputs. As an example, we’ll control LEDs. So, you need the following parts:

You can use the preceding links or go directly to MakerAdvisor.com/tools to find all the parts for your projects at the best price!

Schematic

Before proceeding to the code, wire 3 LEDs to the ESP32. We’re connecting the LEDs to GPIOs 2, 4 and 33, but you can use any other GPIOs (read ESP32 GPIO Reference Guide).

ESP32 Control Three LEDs Outputs Web Server Wiring Circuit Diagram

Installing Libraries – ESP Async Web Server

To build the web server you need to install the following libraries. Click the links below to download the libraries.

These libraries aren’t available to install through the Arduino Library Manager, so you need to copy the library files to the Arduino Installation Libraries folder. Alternatively, in your Arduino IDE, you can go to Sketch Include Library > Add .zip Library and select the libraries you’ve just downloaded.

Project Overview

To better understand the code, let’s see how the web server works.

ESP32 Async Web Server Control Outputs with Arduino IDE mobile responsive web page
  • The web server contains one heading “ESP Web Server” and three buttons (toggle switches) to control three outputs. Each slider button has a label indicating the GPIO output pin. You can easily remove/add more outputs.
  • When the slider is red, it means the output is on (its state is HIGH). If you toggle the slider, it turns off the output (change the state to LOW).
  • When the slider is gray, it means the output is off (its state is LOW). If you toggle the slider, it turns on the output (change the state to HIGH).

How it Works?

ESP32 Async Web Server Control Outputs how it works

Let’s see what happens when you toggle the buttons. We’ll see the example for GPIO 2. It works similarly for the other buttons.

1. In the first scenario, you toggle the button to turn GPIO 2 on. When that happens, the browser makes an HTTP GET request on the /update?output=2&state=1 URL. Based on that URL, the ESP changes the state of GPIO 2 to 1 (HIGH) and turns the LED on.

2. In the second example, you toggle the button to turn GPIO 2 off. When that happens, the browser makes an HTTP GET request on the /update?output=2&state=0 URL. Based on that URL, we change the state of GPIO 2 to 0 (LOW) and turn the LED off.

Code for ESP Async Web Server

Copy the following code to your Arduino IDE.

/*********
  Rui Santos
  Complete project details at https://RandomNerdTutorials.com/esp32-async-web-server-espasyncwebserver-library/
  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.
*********/

// Import required libraries
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>

// Replace with your network credentials
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";

const char* PARAM_INPUT_1 = "output";
const char* PARAM_INPUT_2 = "state";

// Create AsyncWebServer object on port 80
AsyncWebServer server(80);

const char index_html[] PROGMEM = R"rawliteral(
<!DOCTYPE HTML><html>
<head>
  <title>ESP Web Server</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" href="data:,">
  <style>
    html {font-family: Arial; display: inline-block; text-align: center;}
    h2 {font-size: 3.0rem;}
    p {font-size: 3.0rem;}
    body {max-width: 600px; margin:0px auto; padding-bottom: 25px;}
    .switch {position: relative; display: inline-block; width: 120px; height: 68px} 
    .switch input {display: none}
    .slider {position: absolute; top: 0; left: 0; right: 0; bottom: 0; background-color: #ccc; border-radius: 6px}
    .slider:before {position: absolute; content: ""; height: 52px; width: 52px; left: 8px; bottom: 8px; background-color: #fff; -webkit-transition: .4s; transition: .4s; border-radius: 3px}
    input:checked+.slider {background-color: #b30000}
    input:checked+.slider:before {-webkit-transform: translateX(52px); -ms-transform: translateX(52px); transform: translateX(52px)}
  </style>
</head>
<body>
  <h2>ESP Web Server</h2>
  %BUTTONPLACEHOLDER%
<script>function toggleCheckbox(element) {
  var xhr = new XMLHttpRequest();
  if(element.checked){ xhr.open("GET", "/update?output="+element.id+"&state=1", true); }
  else { xhr.open("GET", "/update?output="+element.id+"&state=0", true); }
  xhr.send();
}
</script>
</body>
</html>
)rawliteral";

// Replaces placeholder with button section in your web page
String processor(const String& var){
  //Serial.println(var);
  if(var == "BUTTONPLACEHOLDER"){
    String buttons = "";
    buttons += "<h4>Output - GPIO 2</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"2\" " + outputState(2) + "><span class=\"slider\"></span></label>";
    buttons += "<h4>Output - GPIO 4</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"4\" " + outputState(4) + "><span class=\"slider\"></span></label>";
    buttons += "<h4>Output - GPIO 33</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"33\" " + outputState(33) + "><span class=\"slider\"></span></label>";
    return buttons;
  }
  return String();
}

String outputState(int output){
  if(digitalRead(output)){
    return "checked";
  }
  else {
    return "";
  }
}

void setup(){
  // Serial port for debugging purposes
  Serial.begin(115200);

  pinMode(2, OUTPUT);
  digitalWrite(2, LOW);
  pinMode(4, OUTPUT);
  digitalWrite(4, LOW);
  pinMode(33, OUTPUT);
  digitalWrite(33, LOW);
  
  // Connect to Wi-Fi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi..");
  }

  // Print ESP Local IP Address
  Serial.println(WiFi.localIP());

  // Route for root / web page
  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request){
    request->send_P(200, "text/html", index_html, processor);
  });

  // Send a GET request to <ESP_IP>/update?output=<inputMessage1>&state=<inputMessage2>
  server.on("/update", HTTP_GET, [] (AsyncWebServerRequest *request) {
    String inputMessage1;
    String inputMessage2;
    // GET input1 value on <ESP_IP>/update?output=<inputMessage1>&state=<inputMessage2>
    if (request->hasParam(PARAM_INPUT_1) && request->hasParam(PARAM_INPUT_2)) {
      inputMessage1 = request->getParam(PARAM_INPUT_1)->value();
      inputMessage2 = request->getParam(PARAM_INPUT_2)->value();
      digitalWrite(inputMessage1.toInt(), inputMessage2.toInt());
    }
    else {
      inputMessage1 = "No message sent";
      inputMessage2 = "No message sent";
    }
    Serial.print("GPIO: ");
    Serial.print(inputMessage1);
    Serial.print(" - Set to: ");
    Serial.println(inputMessage2);
    request->send(200, "text/plain", "OK");
  });

  // Start server
  server.begin();
}

void loop() {

}

View raw code

How the Code Works

In this section we’ll explain how the code works. Keep reading if you want to learn more or jump to the Demonstration section to see the final result.

Importing libraries

First, import the required libraries. You need to include the WiFi, ESPAsyncWebserver and the AsyncTCP libraries.

#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>

Setting your network credentials

Insert your network credentials in the following variables, so that the ESP32 can connect to your local network.

const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";

Input Parameters

To check the parameters passed on the URL (GPIO number and its state), we create two variables, one for the output and other for the state.

const char* PARAM_INPUT_1 = "output";
const char* PARAM_INPUT_2 = "state";

Remember that the ESP32 receives requests like this: /update?output=2&state=0

AsyncWebServer object

Create an AsyncWebServer object on port 80.

AsyncWebServer server(80);

Building the Web Page

All the HTML text with styles and JavaScript is stored in the index_html variable. Now we’ll go through the HTML text and see what each part does.

The title goes inside the <title> and </tile> tags. The title is exactly what it sounds like: the title of your document, which shows up in your web browser’s title bar. In this case, it is “ESP Web Server”.

<title>ESP Web Server</title>
ESP32 Async Web Server web page title HTML

The following <meta> tag makes your web page responsive in any browser (laptop, tablet or smartphone).

<meta name="viewport" content="width=device-width, initial-scale=1">

The next line prevents requests on the favicon. In this case, we don’t have a favicon. The favicon is the website icon that shows next to the title in the web browser tab. If we don’t add the following line, the ESP32 will receive a request for the favicon every time we access the web server.

<link rel="icon" href="data:,">

Between the <style></style> tags, we add some CSS to style the web page. We won’t go into detail on how this CSS styling works.

<style>
    html {font-family: Arial; display: inline-block; text-align: center;}
    h2 {font-size: 3.0rem;}
    p {font-size: 3.0rem;}
    body {max-width: 600px; margin:0px auto; padding-bottom: 25px;}
    .switch {position: relative; display: inline-block; width: 120px; height: 68px} 
    .switch input {display: none}
    .slider {position: absolute; top: 0; left: 0; right: 0; bottom: 0; background-color: #ccc; border-radius: 6px}
    .slider:before {position: absolute; content: ""; height: 52px; width: 52px; left: 8px; bottom: 8px; background-color: #fff; -webkit-transition: .4s; transition: .4s; border-radius: 3px}
    input:checked+.slider {background-color: #b30000}
    input:checked+.slider:before {-webkit-transform: translateX(52px); -ms-transform: translateX(52px); transform: translateX(52px)}
</style>

HTML Body

Inside the <body></body> tags is where we add the web page content.

The <h2></h2> tags add a heading to the web page. In this case, the “ESP Web Server” text, but you can add any other text.

<h2>ESP Web Server</h2>

After the heading, we have the buttons. The way the buttons show up on the web page (red: if the GPIO is on; or gray: if the GPIO is off) varies depending on the current GPIO state.

When you access the web server page, you want it to show the right current GPIO states. So, instead of adding the HTML text to build the buttons, we’ll add a placeholder %BUTTONPLACEHOLDER%. This palceholder will then be replaced with the actual HTML text to build the buttons with the right states, when the web page is loaded.

%BUTTONPLACEHOLDER%

JavaScript

Then, there’s some JavaScript that is responsible to make an HTTP GET request when you toggle the buttons as we’ve explained previously.

<script>function toggleCheckbox(element) {
  var xhr = new XMLHttpRequest();
  if(element.checked){ xhr.open("GET", "/update?output="+element.id+"&state=1", true); }
  else { xhr.open("GET", "/update?output="+element.id+"&state=0", true); }
  xhr.send();
}
</script>

Here’s the line that makes the request:

if(element.checked){ xhr.open("GET", "/update?output="+element.id+"&state=1", true); }

element.id returns the id of an HTML element. The id of each button will be the GPIO controlled as we’ll see in the next section:

  • GPIO 2 button » element.id = 2
  • GPIO 4 button » element.id = 4
  • GPIO 33 button » element.id = 33

Processor

Now, we need to create the processor() function, that replaces the placeholders in the HTML text with what we define.

When the web page is requested, check if the HTML has any placeholders. If it finds the %BUTTONPLACEHOLDER% placeholder, it returns the HTML text to create the buttons.

String processor(const String& var){
  //Serial.println(var);
  if(var == "BUTTONPLACEHOLDER"){
    String buttons = "";
    buttons += "<h4>Output - GPIO 2</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"2\" " + outputState(2) + "><span class=\"slider\"></span></label>";
    buttons += "<h4>Output - GPIO 4</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"4\" " + outputState(4) + "><span class=\"slider\"></span></label>";
    buttons += "<h4>Output - GPIO 33</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"33\" " + outputState(33) + "><span class=\"slider\"></span></label>";
    return buttons;
  }
  return String();
}

You can easily delete or add more lines to create more buttons.

Let’s take a look at how the buttons are created. We create a String variable called buttons that contains the HTML text to build the buttons. We concatenate the HTML text with the current output state so that the toggle button is either gray or red. The current output state is returned by the outputState(<GPIO>) function (it accepts as argument the GPIO number). See below:

buttons += "<h4>Output - GPIO 2</h4><label class=\"switch\"><input type=\"checkbox\" onchange=\"toggleCheckbox(this)\" id=\"2\" " + outputState(2) + "><span class=\"slider\"></span></label>";

The \ is used so that we can pass “” inside the String.

The outputState() function returns either “checked” if the GPIO is on or and empty field “” if the GPIO is off.

String outputState(int output){
  if(digitalRead(output)){
    return "checked";
  }
  else {
    return "";
  }
}

So, the HTML text for GPIO 2 when it is on, would be:

<h4>Output - GPIO 2</h4>
<label class="switch">
<input type="checkbox" onchange="toggleCheckbox(this)" id="2" checked><span class="slider"></span>
</label>

Let’s break this down into smaller sections to understand how it works.

In HTML, a toggle switch is an input type. The <input> tag specifies an input field where the user can enter data. The toggle switch is an input field of type checkbox. There are many other input field types.

<input type="checkbox">

The checkbox can be checked or not. When it is check, you have something as follows:

<input type="checkbox" checked>

The onchange is an event attribute that occurs when we change the value of the element (the checkbox). Whenever you check or uncheck the toggle switch, it calls the toggleCheckbox() JavaScript function for that specific element id (this).

The id specifies a unique id for that HTML element. The id allows us to manipulate the element using JavaScript or CSS.

<input type="checkbox" onchange="toggleCheckbox(this)" id="2" checked>

setup()

In the setup() initialize the Serial Monitor for debugging purposes.

Serial.begin(115200);

Set the GPIOs you want to control as outputs using the pinMode() function and set them to LOW when the ESP32 first starts. If you’ve added more GPIOs, do the same procedure.

pinMode(2, OUTPUT);
digitalWrite(2, LOW);
pinMode(4, OUTPUT);
digitalWrite(4, LOW);
pinMode(33, OUTPUT);
digitalWrite(33, LOW);

Connect to your local network and print the ESP32 IP address.

WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
  delay(1000);
  Serial.println("Connecting to WiFi..");
}

// Print ESP Local IP Address
Serial.println(WiFi.localIP());

In the setup(), you need to handle what happens when the ESP32 receives requests. As we’ve seen previously, you receive a request of this type:

<ESP_IP>/update?output=<inputMessage1>&state=<inputMessage2>

So, we check if the request contains the PARAM_INPUT1 variable value (output) and the PARAM_INPUT2(state) and save the corresponding values on the input1Message and input2Message variables.

if (request->hasParam(PARAM_INPUT_1) && request->hasParam(PARAM_INPUT_2)) {
  inputMessage1 = request->getParam(PARAM_INPUT_1)->value();
  inputMessage2 = request->getParam(PARAM_INPUT_2)->value();

Then, we control the corresponding GPIO with the corresponding state (the inputMessage1 variable saves the GPIO number and the inputMessage2 saves the state – 0 or 1)

digitalWrite(inputMessage1.toInt(), inputMessage2.toInt());

Here’s the complete code to handle the HTTP GET /update request:

server.on("/update", HTTP_GET, [] (AsyncWebServerRequest *request) {
  String inputMessage1;
  String inputMessage2;
  // GET input1 value on <ESP_IP>/update?output=<inputMessage1>&state=<inputMessage2>
  if (request->hasParam(PARAM_INPUT_1) && request->hasParam(PARAM_INPUT_2)) {
    inputMessage1 = request->getParam(PARAM_INPUT_1)->value();
    inputMessage2 = request->getParam(PARAM_INPUT_2)->value();
    digitalWrite(inputMessage1.toInt(), inputMessage2.toInt());
  }
  else {
    inputMessage1 = "No message sent";
    inputMessage2 = "No message sent";
  }
  Serial.print("GPIO: ");
  Serial.print(inputMessage1);
  Serial.print(" - Set to: ");
  Serial.println(inputMessage2);
  request->send(200, "text/plain", "OK");
});

Finally, start the server:

server.begin();

Demonstration

After uploading the code to your ESP32, open the Serial Monitor at a baud rate of 115200. Press the on-board RST/EN button. You should get its IP address.

Open a browser and type the ESP IP address. You’ll get access to a similar web page.

ESP32 Async Web Server Control Outputs web browser demonstration GPIOs

Press the toggle buttons to control the ESP32 GPIOs. At the same time, you should get the following messages in the Serial Monitor to help you debug your code.

ESP32 Async Web Server Control Outputs demonstration mobile

You can also access the web server from a browser in your smartphone. Whenever you open the web server, it shows the current GPIO states. Red indicates the GPIO is on, and gray that the GPIO is off.

Web Server

Wrapping Up

In this tutorial you’ve learned how to create an asynchronous web server with the ESP32 to control its outputs using toggle switches. Whenever you open the web page, it shows the updated GPIO states.

We have other web server examples using the ESPAsyncWebServer library that you may like:

We hope you found this tutorial useful. If you have any questions, post a comment below and we’ll try to get back to you.

If you like ESP32, you might consider enrolling in our course “Learn ESP32 with Arduino IDE“. You can also access our free ESP32 resources here.

Thank you for reading.



Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »

Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our weekly newsletter!

14 thoughts on “ESP32 Async Web Server – Control Outputs with Arduino IDE (ESPAsyncWebServer library)”

  1. Hey guys!

    Thanks for this new tutorial!

    I’ve been following your work around the ESP32 for a while now. And I continually notice your habit (or preference?) of systematically using the Javascript object XMLHttpRequest. And I must admit that I find it hard to understand this trend, when there are nowadays other, more efficient, lighter and above all faster ways to manage asynchronous interactions between a server and clients. For example, Javascript now offers the more modern Fetch and Async/Await APIs. You can take a look at one of my GitHub project which uses the Async/Await Promises for example:

    ESP32 Asynchronous Web Controlled Thermostat
    https://github.com/m1cr0lab-esp32/asynchronous-web-controlled-thermostat

    I had made this mini-project for Yves B., following a discussion on RNT Lab to help him start his own project:
    https://rntlab.com/question/java-script-code-to-refresh-home-page-only-once/

    I had also posted a reference to my project to share it with your community:
    https://rntlab.com/question/full-project-esp32-asynchronous-web-controlled-thermostat/

    But there is another technology supported by Javascript even more interesting: the WebSocket protocol. Today, I would like to shed some light on how to implement it efficiently for the ESP32. You’ll see that it has only advantages over other techniques. I have recently written a comprehensive tutorial on the subject:

    ESP32 Remote Control with WebSocket
    https://m1cr0lab-esp32.github.io/remote-control-with-websocket/

    I’m sharing it here, because I think it may also be of interest to most of your readers.
    If you take the time to read it, feel free to share your opinion with me on this thread:

    https://rntlab.com/question/full-tutorial-esp32-remote-control-with-websocket/

    My intention is not to overshadow your work, quite the contrary, but rather to add to it what I think is interesting. I hope that you’ll welcome my approach.

    Best wishes,
    Steph

    Reply
    • Hi Steph.
      Thank you so much for your contribution. This can be very useful for our readers.
      I’ll take a look at those tutorials and see what we can implement to improve our projects.
      The methods we were using for automatically updating the web page worked well, but as you stated are not the most efficient. That’s true.
      Now, we’ve been implementing server-sent events to automatically send data from the server to the client when there are new sensor readings available. See the project that we’ll release today or this project: https://randomnerdtutorials.com/esp32-esp-now-wi-fi-web-server/
      However, for automatically updating the state of the buttons and GPIOs on all clients at the same time, a two way communication like web sockets should be more suitable. I’ll take a look on how to implement that and improve our projects.
      Thanks for sharing this valuable information.
      Regards,
      Sara

      Reply
      • Thank you, Sara,

        Yes, I read your article on server-sent events. It’s good that you presented it to your readers. It complements the unidirectional approach of XMLHttpRequest with another approach… but still unidirectional 🙂

        If you read my tutorial in detail, you’ll see that WebSockets solve this problem by killing two birds with one stone. The interactions are bidirectional and the implementation remains very simple. In addition, the WebSocket protocol is much faster and lighter than HTTP.

        Reply
      • Too bad you can’t edit your own comments…

        I just wanted to add that in projects where you want to take measurements from various sensors, and as soon as they are available at ESP32, WebSockets are also the best solution. And this, whether there is a single customer or a whole colony 😉

        WebSockets is an advanced technology that allows real-time interactive bidirectional communication between the client and a server. In simple terms, WebSockets make it possible for data to be transferred from the client to the server and vice versa in real time. With WebSocket protocol, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

        Server-Sent Events (SSE) are unidirectional: only allowing client(s) to receive data from the server.

        Reply
  2. Hey,
    That’s really nice!
    Is there any tutorial where it is ecplained how to do the opposit? send http values to an existing webserver?

    Reply
  3. Dear Sara,

    thank you very much for this useful tutorial.

    In reference to the RNT Course “Learn ESP32 with Arduino IDE – 2nd Edition”, Module 4 “ESP32 Web Server”, Unit 6 “Making Your ESP32 Web Server Password Protected”, how would you implement the same password protection (with Base64 encryption) under the present context, meaning with an object ‘AsyncWebServer’ instead of an object ‘WiFiServer’ as this is the case in the course.

    Thank you and best regards,

    JM

    Reply
  4. He Sara,

    first of all, thanks for the tutorials! I’m trying to combine 2 tutorials of you, the one where you make a website with temperature and humidity via the DHT sensor, and the second is this tutorial. Sadly I didn’t succeed yet, it says: ‘outputState’ not declared in this scope . How can I fix this?

    Thanks!

    Reply
  5. Hi Sara,
    Is there any way to control the ESP32 outputs from anywhere in the world, and not just only when being connected to the same wifi network?

    Reply

Leave a Reply to Sara Santos Cancel reply

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.