# Getting Started | WebSerial Docs
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.

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();
    }