In this guide, you’ll learn how to create and use a web-based “Serial Monitor” for your ESP8266 NodeMCU projects using the WebSerial library. This creates a web-based interface to output debugging messages, as you would do with a regular serial monitor. You can also send messages from the web-based serial monitor to the ESP8266.

We have a similar tutorial for the ESP32 board:ESP32 WebSerial Web-based Remote Serial Monitor

Web-based Serial Monitor

In most of your ESP8266 projects, you use the serial monitor to output debugging messages that help better understand what’s happening with the microcontroller.

You create a Serial communication between your board and your computer, and then you can visualize the messages using the serial monitor. However, when your board is not connected to your computer, you can’t see the debugging messages.

A workaround for this issue is to use a web-based serial monitor—the ESP8266 hosts a web server that serves a page to visualize the messages as you would with the “regular” serial monitor. The WebSerial web page also allows you to send data from the web page to your board.

For this tutorial, we’ll use theWebSerial library.

If you like this library and you’ll use it in your projects, considersupporting the developer’s work.

WebSerial Features

List of WebSerial features:

• Works on WebSockets;
• Realtime logging;
• Any number of serial monitors can be opened on the browser;
• UsesAsyncWebserver for better performance.

WebSerial Functions

Using WebSerial is similar to use the serial monitor. Its main functions areprint() andprintln():

• print(): prints the data on the web-based serial monitor without newline character (on the same line);
• println(): prints the data on the web-based serial monitor with a newline character (on the next line);

Installing the WebSerial Library

For this project, we’ll use theWebSerial.h library. To install the library:

1. In your Arduino IDE, go toSketch >Include Library >Manage Libraries …
2. Search forwebserial.
3. Install the WebSerial library by Ayush Sharma.

You also need to install theESPAsyncWebServerand theAsyncTCP libraries. Click the following links to download the libraries’ files.

• ESPAsyncWebServer
• ESPAsyncTCP

To install these libraries, click on the previous links to download the libraries’ files. Then, in your Arduino IDE, go toSketch>Include Library >Add .ZIP Library…

If you’re using VS Code with the PlatformIO extension, copy the following to the platformio.ini file to include the libraries.

lib_deps = ESP Async WebServer  ayushsharma82/WebSerial @ ^1.1.0

ESP8266 WebSerial Example

The library provides a simple example of creating the Web Serial Monitor to output and receive messages. We’ve modified the example a bit to make it more interactive.

This example printsHello! to the web-based serial monitor every two seconds. Additionally, you can send messages from the web-based serial monitor to the board. You can send the messageON to light up the board’s built-in LED or the messageOFF to turn it off.

/*  Rui Santos  Complete project details at https://RandomNerdTutorials.com/esp8266-nodemcu-webserial-library/    This sketch is based on the WebSerial library example: ESP8266_Demo  https://github.com/ayushsharma82/WebSerial*/#include <Arduino.h>#include <ESP8266WiFi.h>#include <ESPAsyncTCP.h>#include <ESPAsyncWebServer.h>#include <WebSerial.h>#define LED 2AsyncWebServer server(80);const char* ssid = "REPLACE_WITH_YOUR_SSID";          // Your WiFi SSIDconst char* password = "REPLACE_WITH_YOUR_PASSWORD";  // Your WiFi Passwordvoid recvMsg(uint8_t *data, size_t len){  WebSerial.println("Received Data...");  String d = "";  for(int i=0; i < len; i++){    d += char(data[i]);  }  WebSerial.println(d);  if (d == "ON"){    digitalWrite(LED, LOW);  }  if (d=="OFF"){    digitalWrite(LED, HIGH);  }}void setup() {  Serial.begin(115200);  pinMode(LED, OUTPUT);  digitalWrite(LED, HIGH);  WiFi.mode(WIFI_STA);  WiFi.begin(ssid, password);  if (WiFi.waitForConnectResult() != WL_CONNECTED) {    Serial.printf("WiFi Failed!\n");    return;  }  Serial.println("IP Address: ");  Serial.println(WiFi.localIP());  // WebSerial is accessible at "<IP Address>/webserial" in browser  WebSerial.begin(&server);  WebSerial.msgCallback(recvMsg);  server.begin();}void loop() {  WebSerial.println("Hello!");  delay(2000);}

View raw code

Before uploading the code to your board, don’t forget to insert your network credentials.

In this example, the ESP8266 is in station mode. This example also works in access point mode. To learn how to set up your ESP8266 as an access point, read:

• ESP8266 NodeMCU Access Point (AP) for Web Server

How the Code Works

Continue reading to learn how the code works or skip to thedemonstration section.

First, you need to include the required libraries for WebSerial. TheESP8266WiFi.h library is needed to connect the ESP8266 to a Wi-Fi network.

#include <ESP8266WiFi.h>

TheWebSerial library uses theESPAsyncTCP and theESPAsyncWebServer libraries to create the web-based serial monitor.

#include <ESPAsyncTCP.h>#include <ESPAsyncWebServer.h>

Finally, theWebSerial library provides easy methods to build the web-based serial monitor.

#include <WebSerial.h>

Create a variable calledLED for the built-in LED on GPIO 2.

#define LED 2

Initialize anAsyncWebServer object on port 80 to set up the web server.

AsyncWebServer server(80);

Insert your network credentials in the following variables:

const char* ssid = "REPLACE_WITH_YOUR_SSID"; // Your WiFi SSIDconst char* password = "REPLACE_WITH_YOUR_PASSWORD"; // Your WiFi Password

Handling Received Messages

The following function receives incoming messages sent from the web-based serial monitor. The message is saved on thed variable. Then, it is printed on the web serial monitor usingWebSerial.println(d).

void recvMsg(uint8_t *data, size_t len){  WebSerial.println("Received Data...");  String d = "";  for(int i=0; i < len; i++){    d += char(data[i]);  }  WebSerial.println(d);

Next, we check if the content of thed variable isON orOFF and light up the LED accordingly.

if (d == "ON"){  digitalWrite(LED, LOW);}if (d=="OFF"){  digitalWrite(LED, HIGH);}

The built-in LED works with inverted logic: send a HIGH signal to turn it off and a LOW signal to turn it on.

setup()

In thesetup(), set theLED as anOUTPUT and turn it off by default.

pinMode(LED, OUTPUT);digitalWrite(LED, HIGH);

Connect your board to your local network:

WiFi.mode(WIFI_STA);WiFi.begin(ssid, password);if (WiFi.waitForConnectResult() != WL_CONNECTED) {  Serial.printf("WiFi Failed!\n");  return;}Serial.print("IP Address: ");Serial.println(WiFi.localIP());

Initialize the web-based serial monitor with thebegin() method on theWebSerial object. This function accepts as an argument anAsyncWebServer object.

WebSerial.begin(&server);

Register therecvMsg() as a callback function using themsgCallback() method on theWebSerial object. TherecvMsg() function will run whenever you send a message from the monitor to the board.

WebSerial.msgCallback(recvMsg);

Finally, initialize the server.

server.begin();

It is just after calling this line that the web-based serial monitor will start working.

loop()

In theloop(), print theHello! message every 2000 milliseconds (2 seconds) using theprintln() function on theWebSerial object.

void loop() {  WebSerial.println("Hello!");  delay(2000);}

Demonstration

After inserting your network credentials, you can upload the code to your board.

After uploading, open the “regular” serial monitor at a baud rate of 115200. The board’s IP address will be printed.

Now, open a browser on your local network and type the ESP IP address followed by/webserial. For example, in my case:

192.168.1.100/webserial

The WebSerial page should load.

As you can see, it is printingHello! every two seconds. Additionally, you can send commands to the ESP8266. All the commands that you send are printed back on the web serial monitor. You can send theON andOFF commands to control the built-in LED.

This was just a simple example showing how you can use the WebSerial library to create a web-based serial monitor to send and receive data.

Now, you can easily add a web-based serial monitor to any of your projects using theWebSerial library.

Wrapping Up

In this quick tutorial, you learned how to create a web-based serial monitor. This is especially useful if your project is not connected to your computer via Serial communication and you still want to visualize debugging messages. The communication between the web-based serial monitor and the ESP8266 uses WebSocket protocol.

We hope you find this tutorial useful. We have other web server tutorials you may like:

• ESP8266 Web Server using Server-Sent Events (Update Sensor Readings Automatically)
• ESP8266 WebSocket Server: Control Outputs (Arduino IDE)
• ESP8266 OTA (Over-the-Air) Updates – AsyncElegantOTA using Arduino IDE

Learn more about the ESP8266 board with our resources:

• Build Web Servers with ESP32 and ESP8266 eBook
• Home Automation using ESP8266
• More ESP8266 tutorials and projects…

Thank you for reading.

23 thoughts on “ESP8266 NodeMCU WebSerial: Web-based Remote Serial Monitor”

1. Great!

   Reply

2. Thanks for this guide, thanks to you I learned something new again.

   Can I protect the webserial HTTP with a password?

   Reply

3. Hai! I have the error message “call of overloaded ‘println(IPAddress)’ is ambiguous” while compiling code attached below. Please find the solution for that.

   #include <Arduino.h>
   #include <ESP8266WiFi.h>
   #include <ESPAsyncTCP.h>
   #include <ESPAsyncWebServer.h>
   #include <WebSerial.h>
   #include <AsyncElegantOTA.h>;

   AsyncWebServer server(80);

   const char* ssid = “”; // Your WiFi SSID
   const char* password = “”; // Your WiFi Password

   // only for sent message from webserial
   //void recvMsg(uint8_t *data, size_t len) {
   // WebSerial.println(“Received Data…”);
   // String d = “”;
   // for (int i = 0; i < len; i++) {
   // d += char(data[i]);
   // }
   // WebSerial.println(d);
   //}

   void setup() {
   Serial.begin(115200);
   WiFi.mode(WIFI_STA);
   WiFi.begin(ssid, password);
   if (WiFi.waitForConnectResult() != WL_CONNECTED) {
   Serial.printf(“WiFi Failed!\n”);
   WebSerial.print(“WiFi Failed!\n”);
   return;
   }
   Serial.print(“IP Address: “);
   Serial.println(WiFi.localIP());
   WebSerial.print(“IP Address: “);
   WebSerial.println(WiFi.localIP());
   // WebSerial is accessible at “/webserial” in browser
   WebSerial.begin(&server);
   //WebSerial.msgCallback(recvMsg);//Sent message from webserial
   AsyncElegantOTA.begin(&server);
   server.begin();
   }

   void loop() {
   AsyncElegantOTA.loop();
   WebSerial.print(“Hello”);

   }

   Reply

   • Hi.
     Instead of the following lines:

     Serial.print("IP Address: ");
Serial.println(WiFi.localIP());
WebSerial.print("IP Address: ");
WebSerial.println(WiFi.localIP());

     Use these ones instead:

     Serial.print("IP Address: ");
String IP = WiFi.localIP().toString();
Serial.println(IP);
WebSerial.print("IP Address: ");
WebSerial.println(IP);

     I hope this helps.
     Regards,
     Sara

     Reply

4. Happy birthday Rui

   Reply

5. There seems to be a slight error in the examples, that crept into your example as well:
   it is not necessary to declare
   #include <ESPAsyncTCP.h>
   #include <ESPAsyncWebServer.h>
   as these are declared in the webserial.h file

   Reply

6. When first run The board’s IP address will be printed. e.g. 192.168.1.16.
   Is there a way to specify the local IP address?

   Reply

   • Hi.
     Yes.
     You can set a specific IP address for your board. See it here:https://randomnerdtutorials.com/esp8266-nodemcu-static-fixed-ip-address-arduino/
     Regards,
     Sara

     Reply

7. Hai Sara,

   I want to use WebSerial with an I2C-scanner. Problem is that a “Serial.print(address,HEX);” works but a “WebSerial.println(address,HEX);” not.

   The error message gives: no matching function for call to ‘WebSerialClass::println(byte&, int)’…

   Can you help? Thanks…

   Reply

   • Hi.
     I think you need to convert the I2C address to a string.
     See this discussion that might help:https://stackoverflow.com/questions/36058764/store-hex-value-as-string-arduino-project/36059758
     Regards,
     Sara

     Reply

8. Hi Sara, Very pleased to see this tutorial as I have some project boxes in inaccessible places!

   However, will I still be able to serial print via USB cable with this solution, or has it over WiFi only?

   Also can I use this to set values on the ESP?

   Many thansk,

   Paul

   Reply

   • Hi Paul.
     You can still use the Serial.print() functions via USB cable.
     Yes, you can use this to set values on the ESP. You just need to save the received messages on a variable, check its content, and then act according to its value.
     Regards,
     Sara

     Reply

     • Hi Sara, I have tried to implement WebSerial print in my existing code, but firstly I noticed that the regular serial print commands no longer produced an output, so I was unable to check the IP address. However I had several log files from my code previously, so I used that IP address/webserial but I couldn’t connect. So then I changed references to Serial.print to WebSerial.print and now the code will not compile. I am using PlatformIO. I am getting several warnings and an error:-

       Compiling .pio\build\nodemcuv2\src\main.cpp.o
       src\main.cpp: In function ‘void recvMsg(uint8_t*, size_t)’:
       src\main.cpp:59:20: warning: comparison between signed and unsigned integer expressions [-Wsign-compare]
       for(int i=0; i < len; i++)
       ^
       src\main.cpp: In function ‘void loop()’:
       src\main.cpp:180:50: error: call of overloaded ‘println(long unsigned int)’ is ambiguous
       WebSerial.println (currentTime – previousTime);
       ^
       src\main.cpp:180:50: note: candidates are:
       In file included from src\main.cpp:8:0:
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:57:10: note: void WebSerialClass::println(String)
       void println(String m = “”);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:57:10: note: no known conversion for argument 1 from ‘long unsigned int’ to ‘String’
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:59:10: note: void WebSerialClass::println(const char)
       void println(const char *m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:59:10: note: no known conversion for argument 1 from ‘long unsigned int’ to ‘const char‘
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:61:10: note: void WebSerialClass::println(char)
       void println(char *m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:61:10: note: no known conversion for argument 1 from ‘long unsigned int’ to ‘char‘
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:63:10: note: void WebSerialClass::println(int)
       void println(int m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:65:10: note: void WebSerialClass::println(uint8_t)
       void println(uint8_t m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:67:10: note: void WebSerialClass::println(uint16_t)
       void println(uint16_t m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:69:10: note: void WebSerialClass::println(uint32_t)
       void println(uint32_t m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:71:10: note: void WebSerialClass::println(float)
       void println(float m);
       ^
       .pio\libdeps\nodemcuv2\WebSerial\src/WebSerial.h:73:10: note: void WebSerialClass::println(double)
       void println(double m);
       ^
       src\main.cpp:223:45: warning: suggest parentheses around ‘&&’ within ‘||’ [-Wparentheses]
       if (((pIRiNStatus != priorpIRiNStatus && pIRiNStatus == 1
       ^
       *** [.pio\build\nodemcuv2\src\main.cpp.o] Error 1
       =========================================== [FAILED] Took 13.35 seconds =

       Reply

       • Hi Sara – I noticed that when I changed back WebSerial on one line to Serial.Print, the code compiled fine. The previousTime became unrecognised when I used WebSerial.Print….

         Here is the error message:-src\main.cpp: In function ‘void loop()’:
         src\main.cpp:180:50: error: call of overloaded ‘println(long unsigned int)’ is ambiguous
         WebSerial.println (currentTime – previousTime);
         ^
         And here is the block of code, which now compiles when I change one specific reference from WebSerial to Serial.

         Any ideas what is happening here?

         if (systemState != priorSystemState)
         {
         WebSerial.print (F(“States – FROM:- “));
         WebSerial.print (messages[priorSystemState]);
         WebSerial.print (F(” TO -> “));
         WebSerial.println (messages[systemState]);
         WebSerial.print (F(“doorSensorStatus:- “));
         WebSerial.println (doorSensorStatus);
         WebSerial.print (F(“masterSwitchStatus:- “));
         WebSerial.println (masterSwitchStatus);
         WebSerial.print (F(“Current Time:- “));
         WebSerial.print (currentHour);
         WebSerial.print (F(“H:”));
         WebSerial.print (currentMin);
         WebSerial.print (F(“m:”));
         WebSerial.print (currentSecs);
         WebSerial.println (F(“s:”));
         WebSerial.print (F(“PriorPIR / CurrentPIR – INSIDE “));
         WebSerial.print (priorpIRiNStatus);
         WebSerial.print (F(” / “));
         WebSerial.println (pIRiNStatus);
         WebSerial.print (F(“PriorPIR / CurrentPIR – OUTSIDE “));
         WebSerial.print (priorpIRoUTStatus);
         WebSerial.print (F(” / “));
         WebSerial.println (pIRoUTStatus);
         WebSerial.print (F(“HBridge 1 / HBridge 2:- “));
         WebSerial.print (digitalRead(HBridge1));
         WebSerial.print (F(” / “));
         WebSerial.println (digitalRead(HBridge2));
         WebSerial.print (F(“Flap Elapsed Time: “));
         Serial.println (currentTime – previousTime);
         WebSerial.print(F(“motorEnable Pin: “));
         WebSerial.println(digitalRead(motorEnable));
         WebSerial.println (F(“***********************”));

         Reply

         • Hi.
           Save the result of the currentTime – previousTime in a variable and convert it to a string before printing it using webserial.
           Regards,
           Sara

9. This is nice, but what I have already a web server running using the ESP8266WebServer library?

   Reply

   • I was able to change the port on which either the server you want, or webserial, when instantiating the server. Of course, you will have to change the name of the server from the examples, and any references to them in your code.

     Example:
     AsyncWebServer serial_server(80);
     AsyncWebServer ota_server(81);

     I have webserial running on port 80, and then I start the OTA server on port 81. I can assume any number of servers running all on different ports.

     Reply

10. can i change the web page layout???

    Reply

11. I am more interested to know if there is a color implementation for this. Particularly using the standard ANSI color codes.

    Reply

12. I have ran this code fine in the past fine, but now I get an error when compiling the code.

    C:\Users\bigda\AppData\Local\Temp.arduinoIDE-unsaved2024817-19916-1su3lgj.39p5\sketch_sep17a\sketch_sep17a.ino: In function ‘void setup()’:
    C:\Users\bigda\AppData\Local\Temp.arduinoIDE-unsaved2024817-19916-1su3lgj.39p5\sketch_sep17a\sketch_sep17a.ino:51:13: error: ‘class WebSerialClass’ has no member named ‘msgCallback’
    51 | WebSerial.msgCallback(recvMsg);
    | ^~~~~~~~~~~
    Multiple libraries were found for “ESPAsyncTCP.h”
    Used: C:\Users\bigda\OneDrive\Documents\Arduino\libraries\ESPAsyncTCP
    Not used: C:\Users\bigda\OneDrive\Documents\Arduino\libraries\ESPAsyncTCP-master
    Multiple libraries were found for “ESPAsyncWebServer.h”
    Used: C:\Users\bigda\OneDrive\Documents\Arduino\libraries\ESPAsyncWebServer-master
    Not used: C:\Users\bigda\OneDrive\Documents\Arduino\libraries\ESP_Async_WebServer
    exit status 1

    Compilation error: ‘class WebSerialClass’ has no member named ‘msgCallback’

    I am using the 2.0.7 version of webserial.
    I have another sketch that used to work fine but now gives me the same error.
    Is it possible when the library updated that something has changed?

    Reply

13. I am having issues getting your example to compile. I have installed all of the libraries. I am getting:
    Compilation error: ‘class WebSerialClass’ has no member named ‘msgCallback’.
    I am running versions:
    ESPAsyncTCP 1.2.4
    ESPAsyncWebServer 3.1.0
    WebSerial 2.0.7
    I searched the src files for WebSerial using the find command. msgCallback was not in the file.
    Could the library have updated and left this out?

    Reply

14. Hello
    As I can see you should use version 1.x of WebSerial.. me too I was having the same issue and at the moment I don’t have time to investigate and fix it with new functions.

    Reply

    • I have figured it out. Use webseriallite library. Also the msgCallback() function has been replaced with onMessage(). Just swap the words. Webseriallite still uses regular webserial commands. After the change I have had no issues.

      Reply