API Reference
Reference for the public methods, callback types and configuration macros of the WebSerial global object in WebSerial Lite and WebSerial Pro.
WebSerial provides a single global object, WebSerial, declared by WebSerial.h (WebSerial Lite) or WebSerialPro.h (WebSerial Pro). The object derives from the Arduino Print class. This page lists every public method and configuration macro.
Setup
begin()
Attaches WebSerial to an AsyncWebServer instance and registers the terminal page and the WebSocket handler. Call it in setup() before server.begin().
void begin(AsyncWebServer *server, const char* url = "/webserial");Prop
Type
In WebSerial Lite, the WebSocket endpoint is always /wserial. In WebSerial Pro, the WebSocket and the logo routes are derived from url: a leading / is added and a trailing / is removed if necessary, the WebSocket uses the same path, and the logos are served at <url>/l/light and <url>/l/dark.
loop()
Performs housekeeping in the default (buffered) mode: flushes buffered output and periodically removes disconnected clients. Call it on every iteration of loop(), after begin() has been called. It has no effect in High Performance Mode.
void loop();Printing
WebSerial inherits print(), println() and printf() from Print and implements both write() overloads. See Printing.
size_t write(uint8_t);
size_t write(const uint8_t* buffer, size_t size);Receiving messages
onMessage()
Registers the callback invoked when a message is received from the terminal. See Callbacks.
void onMessage(WSLMessageHandler recv);
void onMessage(WSLStringMessageHandler recv);| Type | Definition |
|---|---|
WSLMessageHandler | std::function<void(uint8_t *data, size_t len)> |
WSLStringMessageHandler | std::function<void(const String& msg)> |
Security
setAuthentication()
Enables HTTP Basic Authentication for the terminal page and the WebSocket connection. See Authentication.
void setAuthentication(const char* username, const char* password);
void setAuthentication(const String& username, const String& password);Connection status
getConnectionCount()
Available in WebSerial Lite only. Reports whether clients are connected to the terminal.
bool getConnectionCount();Despite its name, getConnectionCount() returns a bool: true when at least one client is connected and false otherwise (including before begin() has been called).
High Performance Mode
These methods are used with High Performance Mode.
| Method | Description |
|---|---|
void setBuffer(size_t initialCapacity) | Enables a line buffer with the given initial capacity (maximum 65535 bytes; 0 disables it). Has no effect unless WSL_HIGH_PERF is defined. |
AsyncWebSocketMessageBuffer* makeBuffer(size_t size = 0) | Allocates a WebSocket message buffer. Only declared when WSL_HIGH_PERF is defined. |
void send(AsyncWebSocketMessageBuffer* buffer) | Sends a buffer allocated with makeBuffer() to all connected clients. Only declared when WSL_HIGH_PERF is defined. |
WebSerial Pro methods
The following methods are available in WebSerial Pro only.
| Method | Description |
|---|---|
void setTitle(const char* title) | Sets the title displayed at the top of the terminal. See Custom Title. |
void setID(const char* id) | Sets the hardware ID displayed at the bottom of the terminal. See Hardware ID. |
void enableInput() | Enables the terminal input bar. See Toggle Input. |
void disableInput() | Disables the terminal input bar. |
void setInput(bool enable) | Enables or disables the terminal input bar. |
Configuration macros
Define these macros as build flags (for example -D WSL_BUFFER_SIZE=4096 in platformio.ini) to change the default behavior. Buffer and timing macros apply to the default (buffered) mode only.
Prop
Type
WebSerial reports a compile-time error if a buffer or timing macro is outside its allowed range.