Skip to content

API

Jump to bottom
Jordan Yoon-Buck edited this page Mar 9, 2021 · 6 revisions

static methods

checkSupport()

Returns whether the browser supports the Web Serial API.

Note: Even in compatible browsers, support will not be available on insecure origins. Websites/applications need to be served using HTTPS to use Web Serial.

properties

Note: readonly properties are not enforced at runtime or by the typings, but modification may lead to undefined behavior.

portOpen

  • type: boolean
  • readonly

Whether or not the serial port is currently open.

portInfo

  • type: SerialPortInfo
  • readonly

An object containing the serial port's info including USB device ID and vendor ID. This is the getInfo() of the WebSerial's port.

port

The browser native SerialPort wrapped by the WebSerial object.

methods

async requestPort(filters?)

Prompt the user to select a port using the browser's native mechanism. Emits portavailable on success and requesterror if user cancels or no port is available.

Important: this user will only be prompted to choose a serial port if this method is called as a result of a user-triggered event, e.g., a button click.

Arguments

filters

  • optional (default: [])
  • type: SerialPortFilter[]

Vender/device ID filters to apply on the port options offered to the user. By default all devices are shown.

Return

  • type: Promise<void>

Resolves once the user makes a selection or cancels the request.

async getPorts(choosePort?)

Select a port from the ports the user has previously granted access to. This method can be called without user interaction. Emits portavailable on success and noport if no port is available.

The choosePort callback will be used to allow the client to choose which port to use. By default, the first port returned from the browser API will be used. If no port is available, the callback will not be called.

Arguments

choosePort

  • optional
  • type: (ports: SerialPort[]) => SerialPort

Used to control which port is used by this WebSerial.

Return

  • type: Promise<void>

Resolves once a port (if available) has been chosen.

async open(options?)

Opens the serial port. Emits openerror if no serial port is selected, if the port is already opened or in the process of opening, or if another error occurs while opening the port. Otherwise, emits open when the port is ready.

Arguments

options

  • optional (default: {baudRate: 9600})
  • type: SerialOptions: an object with any of the following values:
    • baudRate: A positive, non-zero value indicating the baud rate at which serial communication should be established.
    • optional bufferSize: An unsigned long integer indicating the size of the read and write buffers that are to be established. If not passed, defaults to 255.
    • optional dataBits: An integer value of 7 or 8 indicating the number of data bits per frame. If not passed, defaults to 8.
    • optional flowControl: The flow control type, either "none" or "hardware". If not passed, defaults to "none".
    • optional parity: The parity mode, either "none", "even", or "odd". If not passed, defaults to "none".
    • optional stopBits: An integer value of 1 or 2 indicating the number of stop bits at the end of the frame. If not passed, defaults to 1.

Return

  • type: Promise<void>

Resolves when the operation is done.

close()

Close the serial port.

read()

Reads the next byte received over serial.

Return

  • type: number

The next byte as a number, or -1 if no bytes are available.

readChar()

Reads the next byte received over serial as a character.

Return

  • type: string

The next byte as a single character, or null if no bytes are available

readBytes()

Reads all data currently available over serial.

Return

  • type: Uint8Array

The full contents of the serial receive buffer.

readBytesUntil(charToFind, returnAllIfNotFound?)

Reads bytes until a certain character is found.

Arguments

charToFind

  • type: string

Character to read bytes until. The byte corresponding to this character will not included in the result.

returnAllIfNotFound

  • optional (default value: false)
  • type: boolean

Dictates the behavior if the given character is not found. If true, the entire buffer will be returned; if false, null will be returned.

Return

  • type: Uint8Array

The serial data received until the given character, or null if the character was not found and returnAllIfNotFound is false or not provided. Note the distinction between null (the character was not found) and an empty Uint8Array (the character was the first byte in the buffer)

readString()

Reads the entire buffer as a string.

Return

  • type: string

The full contents of the serial receive buffer.

readStringUntil(stringToFind, returnAllIfNotFound?)

Reads the buffer as a string until a certain string is found.

Arguments

stringToFind

  • type: string

The string to find in the buffer. The bytes corresponding to this string will not be included in the result.

returnAllIfNotFound

  • optional (default value: false)
  • type: boolean

Dictates the behavior if the given character is not found. If true, the entire buffer will be returned as a string; if false, null will be returned.

Return

  • type: string

The serial data received until the given string, or null if the string was not found and returnAllIfNotFound is false or not provided. Note the distinction between null (the string was not found) and "" (the string was at the start of the buffer).

readLine()

Reads a string until a line ending is found. The line ending will not be included in the result.

Return

The next line available in the buffer. If no line ending was found, null.

available()

Return

The number of bytes available in the buffer.

clear()

Clears the input buffer without reading it.

async write(data)

Write data to the serial port.

Emits writeerror if an error occurs.

Arguments

data

  • type: number | number[] | string | Uint8Array

Data to be written to the serial port. If string, encoded using UTF-8; otherwise, sent directly as bytes.

Returns

  • type: Promise<void>

Resolves once the write is complete.

print(data)

Synonym of write().

Arguments

data

  • type: string

println(data)

Writes data to the serial port, along with a line ending.

Arguments

data

  • type: string

setLineEnding(ending)

Set the line ending (usually \r\n or \n).

Arguments

ending

  • type: string

The line ending to use.

on(event, listener)

Add an event listener.

Arguments

event

  • type: "noport" | "portavailable" | "open" | "close" | "error" | "requesterror" | "openerror" | "closeerror" | "readerror" | "writeerror" | "data"

The name of the event to listen for

listener

  • type: (detail: any, stopPropagation: () => void) => void

The listener for the event.

off(event, listener)

Removes an event listener.

Clone this wiki locally