DOCSEARCHbyAlgolia
Submit Docs

webserial-core Documentation

website·Indexed 29 days ago

https://webserial.dev

A library for serial communication in the browser. It provides a unified interface via AbstractSerialDevice<T> and supports multiple transport layers including the native Web Serial API, WebUSB (via WebUsbProvider), Web Bluetooth (via WebBluetoothProvider), and WebSockets (via WebSocketProvider). The library includes built-in parsers to transform raw Uint8Array chunks into structured values.

Tokens
32K
Snippets
180
Records
214
Agent score
56%

What's inside webserial-core

  1. Overview of Serial Parsers

    Parsers in webserial-core transform a stream of raw Uint8Array chunks into structured values of type T. To use a parser, pass it to the parser property within SerialDeviceOptions.

  2. Implement BLE serial communication using WebBluetoothProvider

    The createBluetoothProvider() factory function returns a SerialProvider that uses the Web Bluetooth API over GATT to emulate a serial connection. It specifically implements the Nordic UART Service (NUS), making it compatible with nRF52 series, ESP32 BLE UART, HC-08 / AT-09 BLE modules, and any firmware advertising the NUS service.

    Supported NUS UUIDs:

    • Primary service: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
    • TX characteristic (browser writes): 6e400002-b5a3-f393-e0a9-e50e24dcca9e
    • RX characteristic (browser reads via notifications): 6e400003-b5a3-f393-e0a9-e50e24dcca9e

  3. Handle serial communication errors with SerialError

    The SerialError class is a structured error wrapper used in webserial-core to categorize serial communication failures using a typed code and optional context. Note: This is part of the v1 legacy API, which is currently on security fixes only.
    import { SerialError, SerialErrorCode } from "webserial-core";

  4. Emulate serial connections using WebBluetoothProvider

    The createBluetoothProvider() function returns a SerialProvider that uses the Web Bluetooth API over GATT to emulate a serial connection. It specifically implements the Nordic UART Service (NUS) with the following UUIDs:

    • Primary Service: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
    • TX Characteristic (Browser writes): 6e400002-b5a3-f393-e0a9-e50e24dcca9e
    • RX Characteristic (Browser reads via notifications): 6e400003-b5a3-f393-e0a9-e50e24dcca9e

    Compatible hardware includes nRF52 series, ESP32 BLE UART, HC-08 / AT-09 BLE modules, or any firmware announcing the NUS service.

    import { createBluetoothProvider } from "webserial-core";

  5. Update device implementation for webserial-core v2

    When migrating to v2, you must delete any existing extensions of the v1 SerialDevice class. Instead, create a new class that extends AbstractSerialDevice<T> to align with the new v2 architecture.
    // Example: Extend AbstractSerialDevice in v2
class MyDevice extends AbstractSerialDevice<MyDeviceOptions> {
  // Implementation details
}

  6. Communicate with BLE UART devices using WebBluetoothProvider

    Use the WebBluetoothProvider to communicate with BLE UART modules that implement the Nordic UART Service (NUS) over GATT. Compatible hardware includes any device advertising the NUS service UUID 6e400001-b5a3-f393-e0a9-e50e24dcca9e, such as nRF52840, nRF52832, ESP32 (with Arduino BLE UART sketch), and BLE-to-UART modules like HC-08, AT-09, or HM-10.

  7. Communicate with BLE UART modules using WebBluetoothProvider

    The WebBluetoothProvider allows communication with BLE UART modules via the Nordic UART Service (NUS) over GATT. It is compatible with any device advertising the NUS service UUID 6e400001-b5a3-f393-e0a9-e50e24dcca9e, including nRF52840/nRF52832 (NUS firmware), ESP32 (Arduino BLE UART), and HC-08, AT-09, or HM-10 modules.

  8. Use WebUsbProvider as a Web Serial polyfill

    WebUsbProvider implements the SerialProvider interface using the WebUSB API. It is used as a polyfill for the native Web Serial API in scenarios where Web Serial is unavailable or unsupported, such as:

    • Android Chrome: Where Web Serial is not available.
    • Custom USB devices: Devices not exposed via Web Serial (e.g., custom vendor-class USB).
    • Desktop testing: To force the WebUSB code path for verification.

    It supports CDC ACM (Class 0x02), common USB-UART bridges like CP210x and CH340 (Vendor-specific), and generic raw bulk-transfer devices.

    Requirements: Requires a Chromium-based browser, HTTPS or localhost. Not supported in Firefox or Safari.

  9. Migrate webserial-core from v1 to v2

    webserial-core v2 is a complete rewrite and is not backwards compatible with v1. It introduces a new architecture, adapter system, folder structure, build output format, and changes to all public APIs. Because there is no incremental upgrade path, the recommended approach is to start fresh by uninstalling the old version and implementing a new device class.
    npm remove webserial-core
npm install webserial-core@latest

  10. Use WebUsbProvider as a Web Serial API polyfill

    WebUsbProvider implements SerialProvider using the WebUSB API. It is used as a polyfill for the native Web Serial API in scenarios where Web Serial is unavailable or unsupported, such as:

    • Android Chrome: Where Web Serial is not available, making WebUSB the only way to communicate with USB-serial adapters.
    • Desktop Testing: To force the WebUSB code path to verify behavior before deploying to Android.
    • Custom USB Devices: For devices not exposed via Web Serial (e.g., custom vendor class USB devices).

    Browser Support: Requires a Chromium-based browser with WebUSB enabled. It is not available in Firefox or Safari. Connection requires HTTPS or localhost.

  11. Relay serial I/O to a remote server using WebSocketProvider

    The createWebSocketProvider factory function returns a SerialProvider that relays serial I/O to a Node.js bridge server over a WebSocket connection. This is useful for accessing serial ports on remote machines (e.g., Raspberry Pi), building web UIs for devices behind firewalls, or testing serial code where the Web Serial API is unavailable.
    import { createWebSocketProvider } from "webserial-core";

// Create a provider pointing to the bridge server
const provider = createWebSocketProvider("ws://127.0.0.1:8080/?token=TOKEN");

  12. Run webserial-core interactive demos

    webserial-core provides browser-based demos that run as static HTML pages using the UMD bundle, requiring no installation or build step. These demos require Chrome 89+ or Edge 89+ as they rely on browser-exclusive APIs. Safari and Firefox are not supported.

    Available demos include:

    • Web Serial: Uses the native Web Serial API for TXT/HEX data and auto-reconnect.
    • WebUSB: Uses a WebUSB polyfill for CP210x, CH340, and Arduino (CDC-ACM) devices; compatible with Android Chrome and Desktop.
    • Web Bluetooth (BLE UART): Uses the Nordic UART Service (NUS) over GATT for ESP32 BLE, nRF52, HC-08, and AT-09 devices, featuring auto-chunked writes at 20-byte BLE MTU.