WebSerial bindings for serialport module.

NodeJS 22.12 or newer is required.

npm i serialport-bindings-webserial
yarn add serialport-bindings-webserial
pnpm add serialport-bindings-webserial

1. List available and paired ports:

   import { WebSerialBinding } from 'serialport-bindings-webserial';
   
   const ports = await WebSerialBinding.list();
   console.log(ports);

2. Open any port:

   The browser will show pop-up with all available ports.

   import { WebSerialBinding, WebSerialBindingInterface } from 'serialport-bindings-webserial';
   import { SerialPortStream } from '@serialport/stream';
   
   const port = new SerialPortStream<WebSerialBindingInterface>({
       binding: WebSerialBinding,
       path: 'webserial://any',
       baudRate: 115200
   });

3. Open any port with custom options for SerialPort.open:

   The browser will show pop-up with all available ports.

   import { WebSerialBinding, WebSerialBindingInterface } from 'serialport-bindings-webserial';
   import { SerialPortStream } from '@serialport/stream';
   
   const port = new SerialPortStream<WebSerialBindingInterface>({
       binding: WebSerialBinding,
       path: 'webserial://any',
       baudRate: 115200,
       webSerialOpenOptions: {
           bufferSize: 4 * 1024 // https://developer.mozilla.org/en-US/docs/Web/API/SerialPort/open#buffersize
       }
   }); 

4. Open any port with filters:

   The browser will show pop-up with all available ports which fit the requested filter.

   import { WebSerialBinding, WebSerialBindingInterface } from 'serialport-bindings-webserial'; 
   import { SerialPortStream } from '@serialport/stream';
   
   const port = new SerialPortStream<WebSerialBindingInterface>({
      binding: WebSerialBinding,
      path: 'webserial://any',
      baudRate: 115200,
      webSerialRequestOptions: {
          filters: [{ usbVendorId: 0x067B, usbProductId: 0x2303 }]
      }
   });

5. Open with native SerialPort:

   You can open a port using reference to the native SerialPort object.

   import { WebSerialBinding, WebSerialBindingInterface } from 'serialport-bindings-webserial'; 
   import { SerialPortStream } from '@serialport/stream';
   
   const webSerialPort = await navigator.serial.requestPort();
   
   const port = new SerialPortStream({
      binding: WebSerialBinding,
      path: 'webserial://any',
      baudRate: 115200,
      webSerialPort
   });

6. Open port by virtual path:

   import { WebSerialBinding, WebSerialBindingInterface } from 'serialport-bindings-webserial'; 
   import { SerialPortStream } from '@serialport/stream';
   
   const ports = await WebSerialBinding.list();
   
   const port = new SerialPortStream({
      binding: WebSerialBinding,
      path: ports[0].path, // for example: webserial://usb0
      baudRate: 115200,
   });

You need something like vite-plugin-node-polyfills or node-stdlib-browser for using the serialport module in the browser.

pnpm typecheck
pnpm test
pnpm test:unit

Hardware tests are skipped by default. Browser tests run in Playwright Chromium.

Install Playwright Chromium before running browser hardware tests:

pnpm exec playwright install chromium

Loopback

Connect the device's RX and TX pins together before running the test. It verifies transfers up to 256 KiB and runs 20-second stress phases with small and large packets.

pnpm test:hardware

The default selector is FTDI VID 0403. Use WEBSERIAL_DEV and WEBSERIAL_BAUD_RATES to select another adapter and its test rates:

WEBSERIAL_DEV=067B:2303 WEBSERIAL_BAUD_RATES=115200,1228800 pnpm test:hardware

BREAK

Connect an adapter or target that produces incoming BREAK conditions. RX and TX do not need to be connected together.

WEBSERIAL_DEV=067B:2303 pnpm test:hardware:break

USB serial emulator

Firmware for RP2040 boards that implements the version 2 cdc-test protocol. The tests cover serial errors, controls, lifecycle, baud-rate updates, reopen cycles, pending-read cancellation, and mixed transfers up to 256 KiB.

pnpm test:hardware:cdc
pnpm test:hardware:cdc:errors
pnpm test:hardware:cdc:control
pnpm test:hardware:cdc:stress

The default selector is VID 2E8A:PID 000A. Use WEBSERIAL_CDC_DEV and WEBSERIAL_CDC_BAUD_RATE to select another device and baud rate. The stress test runs for 20 seconds; override its duration with WEBSERIAL_CDC_STRESS_SECONDS.