High Performance Mode

High Performance Mode changes how WebSerial transmits output. In the default mode, WebSerial collects printed data in internal buffers and sends it in batches. In High Performance Mode, each message is queued on the WebSocket immediately, without the global buffer, which reduces memory use and latency and supports more than 20 messages per second.

Enable High Performance ModeCopy Anchor Link

High Performance Mode is enabled with the WSL_HIGH_PERF macro. The macro must be visible to the WebSerial source files, so define it as a build flag or in the library header, not in your sketch.

Behavior in High Performance ModeCopy Anchor Link

• WebSerial.loop() has no effect. You do not need to call it.
• Each call to write(const uint8_t* buffer, size_t size) is sent as one message. A trailing newline is removed.
• Single-byte writes, write(uint8_t), are not supported unless a line buffer is enabled with setBuffer(). Without a buffer, a single-byte write logs an error and triggers an assertion. Because many Print methods (for example print(char) and printf()) can emit single bytes, either enable a buffer or send complete buffers with write(buffer, size) or print(String).

Line bufferCopy Anchor Link

setBuffer() enables a line buffer so that you can use all Print methods in High Performance Mode. Output is accumulated until a newline (\n) is written; the line is then sent as one message and the buffer is cleared. If the buffer grew beyond its initial capacity, it is reallocated at the initial capacity.

WebSerial.setBuffer(100);

The buffer is disabled by default. Configure it before you start printing; calling setBuffer() again discards any content in the buffer. setBuffer() has no effect when High Performance Mode is disabled.

Send pre-allocated WebSocket buffersCopy Anchor Link

In High Performance Mode, WebSerial exposes the WebSocket message buffer of ESPAsyncWebServer. Writing into this buffer avoids an additional copy when the message is queued.

String line = "sensor=42";

AsyncWebSocketMessageBuffer* wsBuffer = WebSerial.makeBuffer(line.length());
memmove(wsBuffer->get(), line.c_str(), line.length());
WebSerial.send(wsBuffer);

ExampleCopy Anchor Link

The HighPerf example sends random strings at a 50 ms interval (500 ms on ESP8266), and the Logging example shows how to use setBuffer() for line-oriented logging.

#include <Arduino.h>
#if defined(ESP8266)
  #include <ESP8266WiFi.h>
  #include <ESPAsyncTCP.h>
#elif defined(ESP32)
  #include <WiFi.h>
  #include <AsyncTCP.h>
#elif defined(TARGET_RP2040) || defined(TARGET_RP2350) || defined(PICO_RP2040) || defined(PICO_RP2350)
  #include <WiFi.h>
  #include <RPAsyncTCP.h>
#endif
#include <ESPAsyncWebServer.h>
#include <WebSerial.h>

AsyncWebServer server(80);

static uint32_t last = millis();

void setup() {
  Serial.begin(115200);

  WiFi.softAP("WSLDemo");
  Serial.print("IP Address: ");
  Serial.println(WiFi.softAPIP().toString());

  WebSerial.onMessage([](const String& msg) { Serial.println(msg); });
  WebSerial.begin(&server);
  // Enable the line buffer so that all Print methods can be used
  WebSerial.setBuffer(100);

  server.onNotFound([](AsyncWebServerRequest* request) { request->redirect("/webserial"); });
  server.begin();
}

void loop() {
  if (millis() - last > 500) {
    WebSerial.print(F("IP address: "));
    WebSerial.println(WiFi.softAPIP());
    WebSerial.printf("Uptime: %lums\n", millis());
    last = millis();
  }
}