chrome.serial

Description

Use the chrome.serial API to read from and write to a device connected to a serial port.

Permissions

serial

Types

ConnectionInfo

Properties

  • bitrate

    number optional

    See ConnectionOptions.bitrate. This field may be omitted or inaccurate if a non-standard bitrate is in use, or if an error occurred while querying the underlying device.

  • bufferSize

    number

    See ConnectionOptions.bufferSize

  • connectionId

    number

    The id of the serial port connection.

  • ctsFlowControl

    boolean optional

    See ConnectionOptions.ctsFlowControl. This field may be omitted if an error occurred while querying the underlying device.

  • dataBits

    DataBits optional

    See ConnectionOptions.dataBits. This field may be omitted if an error occurred while querying the underlying device.

  • name

    string

    See ConnectionOptions.name

  • parityBit

    ParityBit optional

    See ConnectionOptions.parityBit. This field may be omitted if an error occurred while querying the underlying device.

  • paused

    boolean

    Flag indicating whether the connection is blocked from firing onReceive events.

  • persistent

    boolean

    See ConnectionOptions.persistent

  • receiveTimeout

    number

    See ConnectionOptions.receiveTimeout

  • sendTimeout

    number

    See ConnectionOptions.sendTimeout

  • stopBits

    StopBits optional

    See ConnectionOptions.stopBits. This field may be omitted if an error occurred while querying the underlying device.

ConnectionOptions

Properties

  • bitrate

    number optional

    The requested bitrate of the connection to be opened. For compatibility with the widest range of hardware, this number should match one of commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course, that the device connected to the serial port will support the requested bitrate, even if the port itself supports that bitrate. 9600 will be passed by default.

  • bufferSize

    number optional

    The size of the buffer used to receive data. The default value is 4096.

  • ctsFlowControl

    boolean optional

    Flag indicating whether or not to enable RTS/CTS hardware flow control. Defaults to false.

  • dataBits

    DataBits optional

    "eight" will be passed by default.

  • name

    string optional

    An application-defined string to associate with the connection.

  • parityBit

    ParityBit optional

    "no" will be passed by default.

  • persistent

    boolean optional

    Flag indicating whether or not the connection should be left open when the application is suspended (see Manage App Lifecycle). The default value is "false." When the application is loaded, any serial connections previously opened with persistent=true can be fetched with getConnections.

  • receiveTimeout

    number optional

    The maximum amount of time (in milliseconds) to wait for new data before raising an onReceiveError event with a "timeout" error. If zero, receive timeout errors will not be raised for the connection. Defaults to 0.

  • sendTimeout

    number optional

    The maximum amount of time (in milliseconds) to wait for a send operation to complete before calling the callback with a "timeout" error. If zero, send timeout errors will not be triggered. Defaults to 0.

  • stopBits

    StopBits optional

    "one" will be passed by default.

DataBits

Enum

"seven"

"eight"

DeviceControlSignals

Properties

  • cts

    boolean

    CTS (Clear To Send).

  • dcd

    boolean

    DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect).

  • dsr

    boolean

    DSR (Data Set Ready).

  • ri

    boolean

    RI (Ring Indicator).

DeviceInfo

Properties

  • displayName

    string optional

    A human-readable display name for the underlying device if one can be queried from the host driver.

  • path

    string

    The device's system path. This should be passed as the path argument to chrome.serial.connect in order to connect to this device.

  • productId

    number optional

    A USB product ID if one can be determined for the underlying device.

  • vendorId

    number optional

    A PCI or USB vendor ID if one can be determined for the underlying device.

HostControlSignals

Properties

  • dtr

    boolean optional

    DTR (Data Terminal Ready).

  • rts

    boolean optional

    RTS (Request To Send).

ParityBit

Enum

"no"

"odd"

"even"

ReceiveError

Enum

"disconnected"
The connection was disconnected.

"timeout"
No data has been received for receiveTimeout milliseconds.

"device_lost"
The device was most likely disconnected from the host.

"break"
The device detected a break condition.

"frame_error"
The device detected a framing error.

"overrun"
A character-buffer overrun has occurred. The next character is lost.

"buffer_overflow"
An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character.

"parity_error"
The device detected a parity error.

"system_error"
A system error occurred and the connection may be unrecoverable.

ReceiveErrorInfo

Properties

  • connectionId

    number

    The connection identifier.

  • error

    ReceiveError

    An error code indicating what went wrong.

ReceiveInfo

Properties

  • connectionId

    number

    The connection identifier.

  • data

    ArrayBuffer

    The data received.

SendError

Enum

"disconnected"
The connection was disconnected.

"pending"
A send was already pending.

"timeout"
The send timed out.

"system_error"
A system error occurred and the connection may be unrecoverable.

SendInfo

Properties

  • bytesSent

    number

    The number of bytes sent.

  • error

    SendError optional

    An error code if an error occurred.

StopBits

Enum

"one"

"two"

Methods

clearBreak()

Promise Chrome 45+ 
chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
)

Restore character transmission on a given connection and place the transmission line in a nonbreak state.

Parameters

  • connectionId

    number

    The id of the connection.

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

connect()

Promise 
chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
)

Connects to a given serial port.

Parameters

  • path

    string

    The system path of the serial port to open.

  • options

    ConnectionOptions optional

    Port configuration options.

  • callback

    function optional

    The callback parameter looks like: 

    (connectionInfo: ConnectionInfo) => void

Returns

  • Promise<ConnectionInfo>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

disconnect()

Promise 
chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
)

Disconnects from a serial port.

Parameters

  • connectionId

    number

    The id of the opened connection.

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

flush()

Promise 
chrome.serial.flush(
  connectionId: number,
  callback?: function,
)

Flushes all bytes in the given connection's input and output buffers.

Parameters

  • connectionId

    number

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getConnections()

Promise 
chrome.serial.getConnections(
  callback?: function,
)

Retrieves the list of currently opened serial port connections owned by the application.

Parameters

  • callback

    function optional

    The callback parameter looks like: 

    (connectionInfos: ConnectionInfo[]) => void

Returns

  • Promise<ConnectionInfo[]>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getControlSignals()

Promise 
chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
)

Retrieves the state of control signals on a given connection.

Parameters

Returns

  • Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDevices()

Promise 
chrome.serial.getDevices(
  callback?: function,
)

Returns information about available serial devices on the system. The list is regenerated each time this method is called.

Parameters

  • callback

    function optional

    The callback parameter looks like: 

    (ports: DeviceInfo[]) => void

Returns

  • Promise<DeviceInfo[]>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getInfo()

Promise 
chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
)

Retrieves the state of a given connection.

Parameters

  • connectionId

    number

    The id of the opened connection.

  • callback

    function optional

    The callback parameter looks like: 

    (connectionInfo: ConnectionInfo) => void

Returns

  • Promise<ConnectionInfo>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

send()

Promise 
chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
)

Writes data to the given connection.

Parameters

  • connectionId

    number

    The id of the connection.

  • data

    ArrayBuffer

    The data to send.

  • callback

    function optional

    The callback parameter looks like: 

    (sendInfo: SendInfo) => void

Returns

  • Promise<SendInfo>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setBreak()

Promise Chrome 45+ 
chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
)

Suspends character transmission on a given connection and places the transmission line in a break state until the clearBreak is called.

Parameters

  • connectionId

    number

    The id of the connection.

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setControlSignals()

Promise 
chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
)

Sets the state of control signals on a given connection.

Parameters

  • connectionId

    number

    The id of the connection.

  • The set of signal changes to send to the device.

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setPaused()

Promise 
chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
)

Pauses or unpauses an open connection.

Parameters

  • connectionId

    number

    The id of the opened connection.

  • paused

    boolean

    Flag to indicate whether to pause or unpause.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

update()

Promise 
chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
)

Update the option settings on an open serial port connection.

Parameters

  • connectionId

    number

    The id of the opened connection.

  • Port configuration options.

  • callback

    function optional

    The callback parameter looks like: 

    (result: boolean) => void

    • result

      boolean

Returns

  • Promise<boolean>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

Events

onReceive

chrome.serial.onReceive.addListener(
  callback: function,
)

Event raised when data has been read from the connection.

Parameters

onReceiveError

chrome.serial.onReceiveError.addListener(
  callback: function,
)

Event raised when an error occurred while the runtime was waiting for data on the serial port. Once this event is raised, the connection may be set to paused. A "timeout" error does not pause the connection.

Parameters