ESP32: WebSerial console over Soft AP

Introduction

In this tutorial we will learn how to setup a web based Serial Monitor, working over a network hosted by the ESP32.

The WebSerial library provides a very simple to use solution when we want to print messages (ex: for debugging) and the ESP32 is no longer connected to a computer but is connected to a WiFi network. Nonetheless, there might also be similar situations where we want to receive these messages, but there is no WiFi Access Point available where we are testing our application.

For those cases, we can leverage the capabilities of the ESP32 of hosting a WiFi network, which makes using the WebSerial solution viable.

For an introductory tutorial on how to set a Soft AP on the ESP32, please check here. To learn how to get started with the Web Serial library, please check this previous post.

Please note that the WebSerial library needs an instance of the Async HTTP web server to work. Although most of server related code is simple, you can check here how to install the library and a getting started example.

The tests shown below were performed on a ESP32-E FireBeetle board from DFRobot.

The code

We will start our code by the library includes. We will need the following 3 libraries:

  • WiFi.h: Allows to setup the ESP32 to work in SoftAP mode.
  • ESPAsyncWebServer.h: Allows to setup an async HTTP web server, which is used under the hood by the WebSerial library.
  • WebSerial.h: Allows to setup the Web Serial console.
#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include <WebSerial.h>

After this, we will define two variables to hold the credentials of the network that the ESP32 will host: the network name (SSID) and the password.

const char *ssid = "MyESP32AP";
const char *password = "testpassword";

We will also create an object of class AsyncWebServer which, as already mentioned, will be used under the hood by the WebSerial library. As input of the constructor, we need to pass the number of the port where the server will be listening to incoming requests. We will be using port 80, which corresponds to the default HTTP port.

AsyncWebServer server(80);

Moving on to the Arduino Setup function, we will start by opening a serial connection. This will allow us to print the IP address of the ESP32, which we will need to reach the Web Serial console.

Serial.begin(115200);

Next we will take care of setting up the Soft AP. This is very simply: we only need to call the softAP method on the WiFi extern variable (this extern variable becomes available when we import the WiFi.h library). As input of the method we need to pass the network name and the password, which we defined before as global variables.

WiFi.softAP(ssid, password);

Then we will print the IP address of the ESP32. This can be done with a call to the softAPIP method on the WiFi variable. This method takes no arguments.

Serial.println(WiFi.softAPIP());

After doing the Soft AP setup, we will now take care of initializing the Web Serial interface. To do so, we simply need to call the begin method on the WebSerial variable (this one becomes available from the WebSerial.h include), passing as input the address of the AsyncWebServer instance we created earlier.

WebSerial.begin(&server);  

To finish the Setup function, the only operation left to do is starting our server with a call to the begin method.

server.begin();

The whole Arduino Setup function is shown in the snippet below and it includes some additional prints for better readability of the program outputs.

void setup() {
 
  Serial.begin(115200);
  WiFi.softAP(ssid, password);
 
  Serial.println();
  Serial.print("IP address: ");
  Serial.println(WiFi.softAPIP());

  WebSerial.begin(&server);   
  server.begin();
}

Moving on to the Arduino setup, we will periodically print a “Hello World” message to the WebSerial interface. Pretty much like if we wanted to print the message to a regular serial connection, we will call the println method on the WebSerial object, passing as input the message we want to print.

WebSerial.println("Hello World");

We will add a 1 second delay to each iteration of the Arduino loop.

delay(1000);    

The whole loop function is summarized below.

void loop() {
  WebSerial.println("Hello World");
  delay(1000);    
}

The complete code can be seen below.

#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include <WebSerial.h>
  
const char *ssid = "MyESP32AP";
const char *password = "testpassword";

AsyncWebServer server(80);
 
void setup() {
 
  Serial.begin(115200);
  WiFi.softAP(ssid, password);
 
  Serial.println();
  Serial.print("IP address: ");
  Serial.println(WiFi.softAPIP());

  WebSerial.begin(&server);   
  server.begin();
}
 
void loop() {
  WebSerial.println("Hello World");
  delay(1000);    
}

Testing the code

To test the code, as usual, the first step consists in compiling and uploading it to the ESP32, using the Arduino IDE. Once the procedure is finished, you should open the IDE serial monitor and copy the IP address that gets printed.

After that, using a computer or other WiFi enabled device, you should see a network called MyESP32AP, like we defined in our code. Connect to it and use the password also defined in the code.

Once your device is connected to the ESP32 network, open a web browser of your choice and paste the following in the address bar, changing #yourEspIp# by the IP you copied before:

http://#yourEspIp#/webserial

You should get a page similar to figure 1, which displays the Web Serial console and shows the “Hello World” message getting printed every 1 second.

WebSerial console, working over the ESP32 Soft AP interface.
Figure 1 – WebSerial console, working over the ESP32 Soft AP interface.

Leave a Reply