Introduction
In this post we are going to learn how to receive messages sent from the WebSerial UI, on the ESP32. We will be using the Arduino core to program the ESP32.
For an introductory tutorial on how to get started using WebSerial and how to print data to the console, please check this previous post.
On this tutorial we are going to learn how to handle the reception of messages introduced in the WebSerial UI and sent to the ESP32. This will be done with a callback function, which is executed every time data is sent from WebSerial and gives us access to that data. For illustration purposes, our handling function will simply print the received content to the wired serial interface. In a real application scenario you can instead use this data for many purposes, such as controlling some peripheral, for example.
The tests shown below were performed on a ESP32-E FireBeetle board from DFRobot. The Arduino core version used was 2.0.0 and the Arduino IDE version was 1.8.15, working on Windows 8.1. The code was also tested on Platformio.
The Code
The first thing we will do is taking care of all the library includes. We will need the following ones:
- WiFi.h: Allows to connect the ESP32 to a WiFi network.
- ESPAsyncWebServer.h: Allows to setup a HTTP webserver on the ESP32, which will be used under the hood by the WebSerial library.
- WebSerial.h: Exposes the WebSerial functionality. Note that this will expose a variable called WebSerial, which is an instance of class WebSerialClass.
#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include <WebSerial.h>
After this we will define two global variables to hold the credentials of the WiFi network (the network name and password). Below I’ll be using placeholders that you should replace by the actual credentials of your WiFi network.
const char* ssid = "yourNetworkName";
const char* password = "yourNetworkPassword";
Then we will take care of creating an object of class AsyncWebServer, which we will use to setup the HTTP server to run on the ESP32. The constructor of this class receives as argument the port where the HTTP server will be listening for incoming requests. As usual, we will be using port 80, which corresponds to the default HTTP port.
AsyncWebServer server(80);
Now we will move to the Arduino setup function implementation. The first thing we will do is opening a wired serial connection, so we can later output the data we have received from WebSerial.
Serial.begin(115200);
Then we will connect the ESP32 to the WiFi network. Note that we are printing the IP address assigned to the ESP32 on the local network after the connection is established. We will need this IP address to be able to reach the WebSerial page.
WiFi.begin(ssid, password);
if (WiFi.waitForConnectResult() != WL_CONNECTED) {
Serial.println("Could not initialize WiFi");
return;
}
Serial.println(WiFi.localIP());
After this we will initialize the WebSerial instance with a call to the begin method. As input of this method we should pass the address of our AsyncWebServer object.
WebSerial.begin(&server);
Then we will register the callback function that will handle the WebSerial message received event. This is done with a call to the msgCallback method on the WebSerial extern variable, passing as input the callback function. We will call this function handleMessage and check its implementation later.
WebSerial.msgCallback(handleMessage);
To finalize the Arduino setup, we will initialize the HTTP async server with a call to the begin method on our AsyncWebServer object. After this point, the server should be ready to start receiving incoming requests.
The full Arduino setup already with this method call, can be seen below.
void setup() {
Serial.begin(115200);
WiFi.begin(ssid, password);
if (WiFi.waitForConnectResult() != WL_CONNECTED) {
Serial.println("Could not initialize WiFi");
return;
}
Serial.println(WiFi.localIP());
WebSerial.begin(&server);
WebSerial.msgCallback(handleMessage);
server.begin();
}
Since the reception of the message will be based on a callback function and we don’t have any additional computation to do, we can leave the Arduino main loop empty.
void loop() {}
Finally, we will analyze the implementation of the handleMessage callback function. Note that this function must respect the signature defined here:
- The function returns void
- The function receives a pointer to a data buffer containing the message, and the length of the data.
void handleMessage(uint8_t *data, size_t len){
// function implementation
}
In the implementation of the function we will simply iterate through all the bytes of the data and print them to the wired serial interface.
for(int i=0; i < len; i++){
Serial.print((char)data[i]);
}
Serial.println();
The full callback is available below.
void handleMessage(uint8_t *data, size_t len){
for(int i=0; i < len; i++){
Serial.print((char)data[i]);
}
Serial.println();
}
The complete code can be seen below.
#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include <WebSerial.h>
const char* ssid = "yourNetworkName";
const char* password = "yourNetworkPassword";
AsyncWebServer server(80);
void handleMessage(uint8_t *data, size_t len){
for(int i=0; i < len; i++){
Serial.print((char)data[i]);
}
Serial.println();
}
void setup() {
Serial.begin(115200);
WiFi.begin(ssid, password);
if (WiFi.waitForConnectResult() != WL_CONNECTED) {
Serial.println("Could not initialize WiFi");
return;
}
Serial.println(WiFi.localIP());
WebSerial.begin(&server);
WebSerial.msgCallback(handleMessage);
server.begin();
}
void loop() {}
Testing the code
To test the code, simply compile it and upload it to your ESP32 using the tool of your choice. Once the procedure finishes, open a serial monitor tool and wait for the WiFi connection to be established. After that, the IP address assigned to the ESP32 on the network should get printed. Copy it.
Then, open a web browser of your choice and type the following, changing YourESPIp by the IP address you have just copied.
http://YourESPIp/webserial
You should then access the WebSerial UI. On the text box, introduce some content (like shown below in figure 1) and click in the “Send” button.
If you then go to the serial monitor tool you are using, you should see the message you have sent from WebSerial getting printed, as illustrated below in figure 2.
