webserial-core
Version:
A strongly-typed, event-driven, abstract TypeScript library for the Web Serial API with custom parsers, command queue, handshake validation, and auto-reconnect.
128 lines (127 loc) • 4.62 kB
TypeScript
import { SerialPolyfillOptions, SerialPortFilter, SerialProvider } from '../../types/index.js';
interface USBDeviceFilter {
vendorId?: number;
productId?: number;
classCode?: number;
subclassCode?: number;
protocolCode?: number;
serialNumber?: string;
}
interface USBEndpoint {
readonly endpointNumber: number;
readonly direction: "in" | "out";
readonly type: "bulk" | "interrupt" | "isochronous";
readonly packetSize: number;
}
interface USBAlternateInterface {
readonly alternateSetting: number;
readonly interfaceClass: number;
readonly interfaceSubclass: number;
readonly interfaceProtocol: number;
readonly interfaceName: string | undefined;
readonly endpoints: readonly USBEndpoint[];
}
interface USBInterface {
readonly interfaceNumber: number;
readonly alternate: USBAlternateInterface;
readonly alternates: readonly USBAlternateInterface[];
readonly claimed: boolean;
}
interface USBConfiguration {
readonly configurationValue: number;
readonly configurationName: string | undefined;
readonly interfaces: readonly USBInterface[];
}
interface USBInTransferResult {
readonly data: DataView | undefined;
readonly status: "ok" | "stall" | "babble";
}
interface USBOutTransferResult {
readonly bytesWritten: number;
readonly status: "ok" | "stall";
}
interface USBControlTransferParameters {
requestType: "standard" | "class" | "vendor";
recipient: "device" | "interface" | "endpoint" | "other";
request: number;
value: number;
index: number;
}
interface USBDevice {
readonly vendorId: number;
readonly productId: number;
readonly configuration: USBConfiguration | null;
readonly configurations: readonly USBConfiguration[];
readonly opened: boolean;
open(): Promise<void>;
close(): Promise<void>;
forget(): Promise<void>;
selectConfiguration(configurationValue: number): Promise<void>;
claimInterface(interfaceNumber: number): Promise<void>;
releaseInterface(interfaceNumber: number): Promise<void>;
controlTransferOut(setup: USBControlTransferParameters, data?: BufferSource): Promise<USBOutTransferResult>;
transferIn(endpointNumber: number, length: number): Promise<USBInTransferResult>;
transferOut(endpointNumber: number, data: ArrayBuffer): Promise<USBOutTransferResult>;
}
interface USB {
requestDevice(options: {
filters: USBDeviceFilter[];
}): Promise<USBDevice>;
getDevices(): Promise<USBDevice[]>;
}
declare global {
interface Navigator {
readonly usb: USB;
}
}
/**
* A {@link SerialProvider} implementation that uses the WebUSB API.
*
* Supported protocols (auto-detected unless overridden via `protocol`):
* - `cdc_acm` — Standard CDC ACM (auto-detected for interface class 2).
* - `cp210x` — Silicon Labs CP2102/CP2104 (auto-detected for vendorId `0x10c4`).
* - `none` — Raw bulk transfer, no initialization commands sent.
*
* @example
* ```ts
* import { WebUsbProvider, AbstractSerialDevice } from 'webserial-core';
*
* // Standard CDC ACM device (class 2, auto-detected)
* AbstractSerialDevice.setProvider(new WebUsbProvider());
*
* // Vendor-specific device with CP210x (e.g. ESP32 with CP2102)
* AbstractSerialDevice.setProvider(new WebUsbProvider({
* usbControlInterfaceClass: 255,
* usbTransferInterfaceClass: 255,
* }));
* ```
*/
export declare class WebUsbProvider implements SerialProvider {
private readonly options_;
/**
* @param options - Optional USB interface class and protocol settings.
* Defaults to CDC ACM (interface class 2).
*/
constructor(options?: SerialPolyfillOptions);
/**
* Prompts the user to select a USB device and returns a `SerialPort`-
* compatible wrapper for it.
*
* @param options - Optional filter list to narrow the USB device picker.
* @param polyfillOptions - Per-request override of polyfill settings.
* @returns A `SerialPort`-compatible object backed by the selected USB device.
* @throws {DOMException} If the user cancels the device picker.
*/
requestPort(options?: {
filters?: SerialPortFilter[];
}, polyfillOptions?: SerialPolyfillOptions): Promise<SerialPort>;
/**
* Returns `SerialPort`-compatible wrappers for all previously granted
* USB devices.
*
* @param polyfillOptions - Per-request override of polyfill settings.
* @returns An array of `SerialPort`-compatible objects.
*/
getPorts(polyfillOptions?: SerialPolyfillOptions): Promise<SerialPort[]>;
}
export {};