serialport-web


Web Serial API for the browser. Use serial ports with Firmata and Johnny-Five.

Successor to browser-serialport, updated for the modern Web Serial API.

Part of the -web family of browser implementations:
- http-web - HTTP for browser
- net-web - TCP sockets for browser
- serialport-web - Serial ports for browser

Requirements

- Browser with Web Serial API support (Chrome, Edge, Opera)
- HTTPS (required by Web Serial API)
- User gesture for initial port selection

Installation

``bash
npm install serialport-web
`

Usage

$3

`javascript
import { SerialPort, requestPort } from 'serialport-web';

// First, request user to select a port (requires user gesture like button click)
const button = document.getElementById('connect');
button.addEventListener('click', async () => {
// Request port selection
const { port } = await requestPort();

// Open the port
const serial = new SerialPort({
_port: port, // Pass the selected port
baudRate: 57600,
});

serial.on('open', () => {
console.log('Port opened!');
});

serial.on('data', (data) => {
console.log('Received:', data);
});

// Write data
serial.write('Hello Arduino!');
});
`

$3

`javascript
import { SerialPort, requestPort } from 'serialport-web';
import { Firmata } from 'firmata';

const button = document.getElementById('connect');
button.addEventListener('click', async () => {
const { port } = await requestPort();

const transport = new SerialPort({
_port: port,
baudRate: 57600,
});

const board = new Firmata(transport);

board.on('ready', () => {
console.log('Firmata ready!');
// Blink LED on pin 13
let state = true;
setInterval(() => {
board.digitalWrite(13, state ? 1 : 0);
state = !state;
}, 500);
});
});
`

$3

`javascript
import { SerialPort, requestPort } from 'serialport-web';
import { Board, Led } from 'johnny-five';
import { Firmata } from 'firmata';

const button = document.getElementById('connect');
button.addEventListener('click', async () => {
const { port } = await requestPort();

const transport = new SerialPort({
_port: port,
baudRate: 57600,
});

const io = new Firmata(transport);

io.on('ready', () => {
const board = new Board({ io, repl: false });

board.on('ready', () => {
const led = new Led(13);
led.blink(500);
});
});
});
`

API

$3

Request user to select a serial port. Must be called from a user gesture (click, etc.).

`javascript
import { requestPort } from 'serialport-web';

// No filters - show all ports
const { port, path, vendorId, productId } = await requestPort();

// With filters - only show specific devices
const { port } = await requestPort({ usbVendorId: 0x2341 }); // Arduino
`

Returns:
- port - The Web Serial API port object (pass to SerialPort as _port)
- path - Generated path string for this port
- vendorId - USB vendor ID (hex string) if available
- productId - USB product ID (hex string) if available

$3

Check if Web Serial API is available.

`javascript
import { isSupported } from 'serialport-web';

if (isSupported()) {
// Show connect button
} else {
// Show "not supported" message
}
`

$3

EventEmitter-style serial port class compatible with Firmata and Johnny-Five.

`javascript
import { SerialPort } from 'serialport-web';

const port = new SerialPort({
_port: webSerialPort,
baudRate: 9600,
dataBits: 8,
stopBits: 1,
parity: 'none',
});

port.on('open', () => { });
port.on('data', (data) => { });
port.on('error', (err) => { });
port.on('close', () => { });

port.write(new Uint8Array([0x01, 0x02, 0x03]));
port.write('string data');
port.close();
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| _port | SerialPort | required | Web Serial API port from requestPort() |
| baudRate | number | required | Baud rate (9600, 57600, 115200, etc.) |
| dataBits | number | 8 | Data bits (7 or 8) |
| stopBits | number | 1 | Stop bits (1 or 2) |
| parity | string | 'none' | Parity ('none', 'even', 'odd') |
| flowControl | string | 'none' | Flow control ('none' or 'hardware') |
| bufferSize | number | 255 | Read buffer size |

Browser Support

Web Serial API is supported in:
- Chrome 89+
- Edge 89+
- Opera 75+

Not supported in: Firefox, Safari

Notes

- The Web Serial API requires HTTPS (or localhost)
- Initial port selection requires a user gesture (button click, etc.)
- Once a port is selected, it can be reconnected without user gesture
- Use navigator.serial.getPorts() or SerialPort.list()` to get previously-granted ports

License

MIT

Author

Luis Montes (@monteslu)