Skip to main content

# Getting Started

This guide will help you integrate WebSerial into your project. WebSerial allows you to log, monitor or debug your firmware without being connected by wire.

## Prerequisites​

- A supported wireless microcontroller ( Check list here )
- Arduino IDE with the necessary board packages installed
- WebSerial dependencies installed

## Step-by-Step Guide​

### 1. Include Necessary Libraries​

Start by including the required libraries in your code. This ensures your code can use WiFi and WebSerial functionalities.

    #include <Arduino.h>
    #if defined(ESP8266)
      #include <ESP8266WiFi.h>
      #include <ESPAsyncTCP.h>
    #elif defined(ESP32)
      #include <WiFi.h>
      #include <AsyncTCP.h>
    #endif
    #include <ESPAsyncWebServer.h>
    #include <WebSerial.h>

### 2. Create Server Instance​

Create an instance of `AsyncWebServer` to handle HTTP requests.

    AsyncWebServer server(80);

### 3. Define WiFi Credentials​

Set your WiFi credentials.

    const char* ssid = "your-SSID";       // Your WiFi SSID
    const char* password = "your-PASSWORD"; // Your WiFi Password

### 4. Setup Function​

In the `setup` function, connect to WiFi and initialize WebSerial.

    void setup() {
      Serial.begin(115200);
      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());

      // Serve a simple webpage
      server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
        request->send(200, "text/plain", "Hi! This is WebSerial demo. You can access the WebSerial interface at http://" + WiFi.localIP().toString() + "/webserial");
      });

      // Initialize WebSerial
      WebSerial.begin(&server);

      // Attach a callback function to handle incoming messages
      WebSerial.onMessage([](uint8_t *data, size_t len) {
        Serial.printf("Received %lu bytes from WebSerial: ", len);
        Serial.write(data, len);
        Serial.println();
        WebSerial.println("Received Data...");
        String d = "";
        for(size_t i = 0; i < len; i++){
          d += char(data[i]);
        }
        WebSerial.println(d);
      });

      // Start the server
      server.begin();
    }

### 5. Loop Function​

In the `loop` function, print some information periodically and call `WebSerial.loop()`.

    void loop() {
      static unsigned long last_print_time = millis();

      // Print every 2 seconds (non-blocking)
      if ((unsigned long)(millis() - last_print_time) > 2000) {
        WebSerial.print(F("IP address: "));
        WebSerial.println(WiFi.localIP());
        WebSerial.printf("Uptime: %lums\n", millis());
        WebSerial.printf("Free heap: %u\n", ESP.getFreeHeap());
        last_print_time = millis();
      }

      WebSerial.loop();
    }

### Full Example Code​

Here is the complete code for reference:

    /*
      WebSerial Demo
      ------
      This example code works for both ESP8266 & ESP32 Microcontrollers
      WebSerial is accessible at your ESP's <IPAddress>/webserial URL.

      Author: Ayush Sharma
      Checkout WebSerial Pro: https://webserial.pro
    */

    #include <Arduino.h>
    #if defined(ESP8266)
      #include <ESP8266WiFi.h>
      #include <ESPAsyncTCP.h>
    #elif defined(ESP32)
      #include <WiFi.h>
      #include <AsyncTCP.h>
    #endif
    #include <ESPAsyncWebServer.h>
    #include <WebSerial.h>

    AsyncWebServer server(80);

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

    void setup() {
      Serial.begin(115200);
      WiFi.mode(WIFI_STA);
      WiFi.begin(ssid, password);

      if (WiFi.waitForConnectResult() != WL_CONNECTED) {
          Serial.printf("WiFi Failed!\n");
          return;
      }

      // Once connected, print IP
      Serial.print("IP Address: ");
      Serial.println(WiFi.localIP());

      server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
        request->send(200, "text/plain", "Hi! This is WebSerial demo. You can access webserial interface at http://" + WiFi.localIP().toString() + "/webserial");
      });

      // WebSerial is accessible at "<IP Address>/webserial" in browser
      WebSerial.begin(&server);

      /* Attach Message Callback */
      WebSerial.onMessage([&](uint8_t *data, size_t len) {
        Serial.printf("Received %lu bytes from WebSerial: ", len);
        Serial.write(data, len);
        Serial.println();
        WebSerial.println("Received Data...");
        String d = "";
        for(size_t i=0; i < len; i++){
          d += char(data[i]);
        }
        WebSerial.println(d);
      });

      // Start server
      server.begin();
    }

    void loop() {
      static unsigned long last_print_time = millis();

      // Print every 2 seconds (non-blocking)
      if ((unsigned long)(millis() - last_print_time) > 2000) {
        WebSerial.print(F("IP address: "));
        WebSerial.println(WiFi.localIP());
        WebSerial.printf("Uptime: %lums\n", millis());
        WebSerial.printf("Free heap: %u\n", ESP.getFreeHeap());
        last_print_time = millis();
      }

      WebSerial.loop();
    }