Debug Arduino Sketch with WebSerial for ESP8266 and ESP32: Web-based Serial Monitor

What is WebSerial?

I use the Serial.print() a lot when I debug my Arduino code(sketch). The Serial.print() allows passing in arguments and displays the values on the Serial Monitor. Therefore, I can trace my code execution and check the data held by variables.

However, It will be hard to debug when the board's not connecting with the computer.

After a few searches, I found an Arduino library specified for ESP8266 and ESP32 called WebSerial. WebSerial works similar to the Serial Monitor, except it's a website now.

I will use my previous MQTT temperature and humidity sensor project to demonstrate the WebSerial.

How to install?

We can download the WebSerial from the Library Manager in Arduino IDE. But the WebSerial relies on the other two libraries called ESPAsyncTCP and ESPAsyncWebServer are not available in the Library Manager.

We need to download the two libraries(ESPAsyncTCP & ESPAsyncWebServer) from GitHub, unzip the folders, and place both in the Arduino IDE libraries folder(Go to Arduino IDE -> Sketch -> Include Library -> add .ZIP library... -> select the two folders).

Include the library.

At the beginning of the code, only including the WebSerial is enough. The WebSerial.h will include ESP8266WiFi, ESPAsyncTCP, and ESPAsyncWebServer.h for us.

  #include <DHT.h>
  #include <PubSubClient.h>
  #include <ArduinoJson.h>
  #include <WebSerial.h> //Include this. Also, you can remove the ESP8266WiFi, but it's optional. 
  

Declare an AsyncWebServer object.

Declare a variable for the AsyncWebServer object called server and initialize with 80 as the port number(80 is the default port number for the HTTP).

  ...
  
  AsyncWebServer server(80);
  
  ...
  

In the setup().

In the setup(), we need to start the WebSerial and the AsyncWebServer libraries. Also, the AsyncWebServer object that initialized early will pass into the WebSerial.

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

Use the WebSerial.print() or WebSerial.println().

Now, we can use the WebSerial.print() to debug.

One of my use cases is to trace the DHT22 reading, for example as below code:

  void loop() {
    ...
 
    if(now - lastMsg > intervel) {
      ...
      if (isnan(humidity) || isnan(temperature)) {
        ...

        WebSerial.println("ERROR: Failed to read from DHT Sensor!"); //use WebSerial to print the error message.

        client.publish(PUB_STAT_TOPIC, "ERROR: Failed to read from DHT Sensor!");
        return;
      } else {
        snprintf (msg, MSG_BUFFER_SIZE, "Humidity: %.02f and Temperature: %.02f Celsius.", humidity, temperature);
        Serial.println(msg);

        WebSerial.println(msg); // use WebSerial to print out the reading. 

        client.publish(PUB_STAT_TOPIC, msg);
        publishJson(temperature, humidity);
      }
    }
  }
  

Full Code.

Get the WebSerial's website address and debug.

After code modification, we can upload the sketch to the ESP-01S.

To access the WebSerial website, we need to know about the ESP-01S IP address.

The setup_wifi() will print out the IP address on Serial Monitor when the ESP-01S connects with the Wi-Fi access point.

This portion of the code does the job to print the IP address on Serial Monitor:

  void setup_wifi() {
    ...

    WiFi.mode(WIFI_STA);
    WiFi.begin(WIFI_SSID, WIFI_PASS);

    while (WiFi.status() != WL_CONNECTED) {
      Serial.print(".");
      delay(500);  
    }

    Serial.println("");
    Serial.println("WiFi connected.");
    Serial.println("IP address: ");
    Serial.println(WiFi.localIP()); // Here print the IP address on Serial Monitor.
  }
  

Result on Serial Monitor:

ESP-01S IP Address on Serial Monitor.

So, you can enter the "IP address/webserial" to access the web-based Serial Monitor.

ESP-01S publishes a local WebSerial website.