API in Capabilities
Web Serial API
Published Updated
The Web Serial API connects a page to a serial device chosen by the user through navigator.serial.requestPort(). The returned SerialPort provides readable and writable streams for exchanging bytes. It supports USB-to-serial adapters, built-in UART ports, and (from Chrome 117) Bluetooth RFCOMM services. WHATWG publishes the specification; the older WICG URL redirects to it.
Chrome 89 and Edge 89 ship it on desktop and Firefox 151 followed; on Android, Chrome 148 exposes USB and Bluetooth ports while Chrome 138 to 147 and Samsung Internet 30 list Bluetooth RFCOMM ports only (BCD api.Serial). Safari, Firefox for Android, and Android WebView (crbug.com/40740509) have no implementation.
Syntax
Section titled “Syntax”navigator.serial.requestPort()navigator.serial.requestPort(options)navigator.serial.getPorts()
port.open(options)port.close()port.forget()port.getInfo()port.getSignals()port.setSignals(signals)requestPort() resolves with one SerialPort chosen in the browser’s picker; getPorts() resolves with the array of ports this origin was already granted and that are attached. open(), close(), forget(), getSignals(), and setSignals() return promises. A SerialPort also exposes readable (a ReadableStream of Uint8Array, null while closed), writable (a WritableStream), and connected (a boolean, Chrome 130 and Firefox 151), and fires connect and disconnect events that bubble to navigator.serial. Every interface is [SecureContext] and requestPort() additionally needs transient user activation.
Parameters
Section titled “Parameters”requestPort(options) takes a SerialPortRequestOptions dictionary; open(options) takes a SerialOptions dictionary in which only baudRate is required.
| Dictionary | Member | Type | Required | Description |
|---|---|---|---|---|
SerialPortRequestOptions |
filters |
sequence<SerialPortFilter> |
No | Restricts the picker to matching ports; without it every port is listed. |
SerialPortRequestOptions |
allowedBluetoothServiceClassIds |
sequence<BluetoothServiceUUID> |
No | Extra Bluetooth service class IDs to offer besides the standard Serial Port Profile (Chrome 117). |
SerialPortFilter |
usbVendorId |
unsigned short |
Only when usbProductId is set |
USB vendor ID of the adapter. |
SerialPortFilter |
usbProductId |
unsigned short |
No | USB product ID; requires usbVendorId. |
SerialPortFilter |
bluetoothServiceClassId |
BluetoothServiceUUID |
No | Bluetooth service class; a filter that also sets a USB member is rejected with TypeError. |
SerialOptions |
baudRate |
unsigned long |
Yes | Bits per second; must be greater than 0. |
SerialOptions |
dataBits |
octet |
No, default 8 |
7 or 8. |
SerialOptions |
stopBits |
octet |
No, default 1 |
1 or 2. |
SerialOptions |
parity |
ParityType |
No, default "none" |
"none", "even", or "odd". |
SerialOptions |
bufferSize |
unsigned long |
No, default 255 |
Size of the read and write buffers in bytes; must be greater than 0. |
SerialOptions |
flowControl |
FlowControlType |
No, default "none" |
"none" or "hardware" (RTS/CTS). |
setSignals(signals) takes a SerialOutputSignals dictionary with the booleans dataTerminalReady, requestToSend, and break; at least one member must be present. getSignals() resolves with SerialInputSignals (dataCarrierDetect, clearToSend, ringIndicator, dataSetReady), and getInfo() returns usbVendorId, usbProductId, and bluetoothServiceClassId when the port exposes them.
Exceptions
Section titled “Exceptions”| Method | Exception | Condition |
|---|---|---|
requestPort() |
SecurityError |
The document is not allowed to use the serial Permissions Policy feature, or the call has no transient activation. |
requestPort() |
TypeError |
A filter combines bluetoothServiceClassId with a USB member, or sets usbProductId without usbVendorId. |
requestPort() |
NotFoundError |
The user closed the picker without choosing a port. |
getPorts() |
SecurityError |
The serial Permissions Policy feature is disallowed. |
open() |
InvalidStateError |
The port state is not "closed" (already open, or an open() or close() is in flight). |
open() |
TypeError |
baudRate is 0, dataBits is not 7 or 8, stopBits is not 1 or 2, bufferSize is 0 or larger than the implementation supports. |
open() |
NetworkError |
The operating system failed to open the port. |
readable (stream error) |
BufferOverrunError, BreakError, FramingError, ParityError |
The matching line condition was detected; the stream errors and must be re-acquired from port.readable. |
readable / writable |
UnknownError |
An operating system error occurred while reading or writing. |
readable / writable |
NetworkError |
The device was disconnected; writable also sets a fatal flag so the port must be closed. |
writable |
TypeError |
A written chunk is not a BufferSource. |
setSignals(), getSignals(), close() |
InvalidStateError |
The port is not "opened". |
setSignals() |
TypeError |
The signals dictionary has no member. |
setSignals(), getSignals() |
NetworkError |
The operating system refused to set or read the control lines. |
Examples
Section titled “Examples”Check for navigator.serial and handle browsers without it. Only requestPort() needs a user gesture; subsequent calls can run from ordinary code.
Reusing a granted port before asking for a new one
Section titled “Reusing a granted port before asking for a new one”getPorts() returns ports the user already approved, so a returning visitor should not see the picker again. When the API is missing (Safari, Firefox for Android, WebView) the function reports that and leaves the caller to offer a desktop link or a native companion app.
async function connect(vendorId) { if (!('serial' in navigator)) { return { port: null, reason: 'Web Serial is not available in this browser.' }; }
const granted = await navigator.serial.getPorts(); let port = granted.find((p) => p.getInfo().usbVendorId === vendorId);
if (!port) { try { port = await navigator.serial.requestPort({ filters: [{ usbVendorId: vendorId }] }); } catch (err) { if (err.name === 'NotFoundError') return { port: null, reason: 'No device chosen.' }; throw err; } }
await port.open({ baudRate: 115200 }); return { port, reason: null };}The filters entry keeps unrelated ports out of the picker; omit it to list every port on the machine.
Reading text lines until the device disconnects
Section titled “Reading text lines until the device disconnects”Pipe readable through a TextDecoderStream and loop on the reader. A disconnect errors the stream with NetworkError; a parity or framing fault errors it with the specific name while the port stays open, so the loop re-acquires port.readable and continues.
async function readLines(port, onLine) { while (port.readable) { const reader = port.readable.pipeThrough(new TextDecoderStream()).getReader(); let buffer = ''; try { for (;;) { const { value, done } = await reader.read(); if (done) break; buffer += value; const lines = buffer.split('\n'); buffer = lines.pop(); lines.forEach(onLine); } } catch (err) { if (err.name === 'NetworkError') return; // device gone console.warn(`${err.name}: ${err.message}`); // parity, framing, break, overrun } finally { reader.releaseLock(); } }}Call releaseLock() in finally. Otherwise, port.close() waits indefinitely for the readable lock to be released.
Sending a command and closing cleanly
Section titled “Sending a command and closing cleanly”Writing uses a WritableStream writer; close() requires both streams to be unlocked, so release the writer first.
async function sendAndClose(port, command) { const writer = port.writable.getWriter(); try { await writer.write(new TextEncoder().encode(`${command}\r\n`)); } finally { writer.releaseLock(); } await port.close();}After close() resolves, port.readable and port.writable are null until the next open().
See also
Section titled “See also”- WebUSB API, for devices without a serial profile
- WebHID API
- Web Bluetooth API, for GATT rather than RFCOMM devices
- Web Serial API: requestPort() method (whatwg.org)
- Web Serial API: SerialOptions dictionary (whatwg.org)
- Read from and write to a serial port (developer.chrome.com)
- Chromium bug 40740509: Web Serial in Android WebView (crbug.com)
Specifications
| Specification | Status |
|---|---|
| Web Serial API | WICG draft |
| Web Serial API: requestPort() method | WHATWG living standard |
| Web Serial API: open() method | WHATWG living standard |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 89 | high | source | — |
| Chrome (Android)# | Partial | 138 → 148 | high | source | 1 |
| Edge (Desktop)# | Yes | 89 | high | source | 2 |
| Firefox (Desktop)# | Yes | 151 | high | source | — |
| Firefox (Android)# | No | — | high | source | 3 |
| Safari (macOS)# | No | — | high | source | 4 |
| Safari (iOS)# | No | — | high | source | 56 |
| Samsung Internet# | Partial | 30.0 → 31.0 | high | source | 78 |
| WebView (Android)# | No | — | high | source | 9 |
- Serial ports are only available if they're provided by Bluetooth RFCOMM serial port emulation.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox for Android support is recorded in browser-compat-data.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- Serial ports are only available if they're provided by Bluetooth RFCOMM serial port emulation.
- Derived by browser-compat-data mirroring from Chrome Android.
- Implementation tracking: https://crbug.com/40740509.