Types & Interfaces

All types are exported from the main webserial-core entry point.

SerialDeviceOptions<T>

Passed to super() in your AbstractSerialDevice subclass.

interface SerialDeviceOptions<T> {
  /** Serial baud rate (e.g. 9600, 115200). */
  baudRate: number;

  /** Data bits per byte. Default: 8 */
  dataBits?: 7 | 8;

  /** Stop bits. Default: 1 */
  stopBits?: 1 | 2;

  /** Parity mode. Default: "none" */
  parity?: "none" | "even" | "odd";

  /** Hardware flow control. Default: "none" */
  flowControl?: "none" | "hardware";

  /** Internal read buffer size in bytes. Default: 255 */
  bufferSize?: number;

  /** Parser that transforms raw bytes into values of type T. */
  parser: SerialParser<T>;

  /** Timeout (ms) before a queued command is considered failed. Default: 0 (disabled) */
  commandTimeout?: number;

  /** Automatically reconnect on unexpected disconnect. Default: false */
  autoReconnect?: boolean;

  /** Delay (ms) between auto-reconnect attempts. Default: 1000 */
  autoReconnectInterval?: number;

  /** Timeout (ms) allowed for handshake() to complete. Default: 5000 */
  handshakeTimeout?: number;

  /** USB vendor/product ID filters shown in the port picker. Default: [] */
  filters?: SerialPortFilter[];

  /**
   * Custom serial provider for THIS instance only (e.g. `WebUsbProvider`,
   * `createBluetoothProvider()`, `createWebSocketProvider(...)`).
   * Takes precedence over the global provider set via
   * `AbstractSerialDevice.setProvider()`.
   */
  provider?: SerialProvider;

  /**
   * Polyfill options forwarded to `provider` when requesting or listing
   * ports for THIS instance. Only used when `provider` is set.
   */
  polyfillOptions?: SerialPolyfillOptions;
}

---

SerialProvider

interface SerialProvider {
  /**
   * Opens the browser port picker (or equivalent) and returns the selected
   * SerialPort-compatible object.
   */
  requestPort(options?: { filters?: SerialPortFilter[] }): Promise<SerialPort>;

  /** Returns all previously authorized (already-paired) ports. */
  getPorts(): Promise<SerialPort[]>;
}

---

SerialParser<T>

interface SerialParser<T> {
  transform(chunk: Uint8Array, push: (value: T) => void): void;
  flush?(push: (value: T) => void): void;
}

---

SerialEventMap<T>

interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}

---

SerialPortFilter

interface SerialPortFilter {
  usbVendorId?: number;
  usbProductId?: number;
}

---

SerialPolyfillOptions

Options for WebUsbProvider. Controls which USB interface classes are used for control and bulk transfer.

interface SerialPolyfillOptions {
  /** USB interface class used for control messages. Default: 10 (CDC) */
  usbControlInterfaceClass?: number;

  /** USB interface class used for bulk data transfer. Default: 10 (CDC) */
  usbTransferInterfaceClass?: number;
}

---

CommandQueueOptions

Options accepted by the CommandQueue constructor.

interface CommandQueueOptions {
  /** Timeout (ms) per command. 0 = no timeout. Default: 0 */
  timeout?: number;
}

---

Error classes

Class	When thrown
SerialPortConflictError	Two devices attempt to open the same port
SerialPermissionError	User denies port access
SerialTimeoutError	commandTimeout exceeded for a queued command
SerialReadError	Error reading from the port's ReadableStream
SerialWriteError	Error writing to the port's WritableStream

All extend the built-in Error class and include name and message.