WebSocketProvider

createWebSocketProvider(serverUrl) returns a SerialProvider that relays serial I/O to a Node.js bridge server over a WebSocket connection.

When to use

• Access serial ports on a remote machine (e.g. a Raspberry Pi) from a browser.
• Build web UIs for devices connected to a server behind a firewall.
• Test serial code in an environment where Web Serial is unavailable.

Import

import { createWebSocketProvider } from "webserial-core";

Factory function

createWebSocketProvider(serverUrl: string): SerialProvider

Parameter	Type	Description
serverUrl	string	WebSocket URL of the bridge server (e.g. "ws://localhost:8080")

Usage

import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

AbstractSerialDevice.setProvider(
  createWebSocketProvider("ws://localhost:8080"),
);

class MyDevice extends AbstractSerialDevice<string> {
  constructor() {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

const device = new MyDevice();
await device.connect(); // Connects to the first port listed by the bridge

Per-instance usage

Pass provider in the constructor options to scope the WebSocket provider to a single device instance. This is useful when different devices connect to different bridge servers, or when one device uses WebSocket while another uses a different provider in the same app.

import {
  AbstractSerialDevice,
  delimiter,
  createWebSocketProvider,
} from "webserial-core";

class RemoteDevice extends AbstractSerialDevice<string> {
  constructor(bridgeUrl: string) {
    super({
      baudRate: 9600,
      parser: delimiter("\n"),
      autoReconnect: true,
      provider: createWebSocketProvider(bridgeUrl), // WS only for this instance
    });
  }

  protected async handshake(): Promise<boolean> {
    return true;
  }
}

// Two independent instances, each with its own bridge URL
const deviceA = new RemoteDevice("ws://pi-sensor.local:8080");
const deviceB = new RemoteDevice("ws://pi-actuator.local:8080");

await deviceA.connect();
await deviceB.connect();

Bridge server

A ready-to-use Node.js bridge server is included at demos/websocket/server.js. See the WebSocket Bridge demo README for setup instructions.

Wire protocol

All messages are JSON objects sent over the WebSocket connection.

Direction	Type	Payload description
Browser → Server	list-ports	{ filters: SerialPortFilter[] }
Server → Browser	port-list	{ payload: PortInfo[] }
Browser → Server	open	{ path, baudRate, dataBits, stopBits, parity, parser }
Server → Browser	opened	acknowledge
Browser → Server	write	{ bytes: number[] }
Server → Browser	data	{ bytes: number[] }
Browser → Server	close	—
Server → Browser	closed	—
Server → Browser	error	{ payload: { message: string } }

Port selection

requestPort() opens a new WebSocket connection, requests the port list, and auto-selects the first available port. For production apps, display a UI picker over the returned port list before calling open.

Security note

The bridge server has raw access to serial ports. Deploy it only on trusted networks and add authentication for any internet-facing setup.