Welcome What's new in Chrome extensions Getting started API Reference Samples

chrome.serial

This API is part of the deprecated Chrome Apps platform. Learn more about migrating your app.
  • Description

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

  • Permissions
    serial

Summary

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

Type

"seven"

, or

"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

Type

"no"

,

"odd"

,
or

"even"

ReceiveError

Type

"disconnected"

,

"timeout"

,

"device_lost"

,

"break"

,

"frame_error"

,

"overrun"

,

"buffer_overflow"

,

"parity_error"

,
or

"system_error"

ReceiveErrorInfo

Properties

  • connectionId

    number

    The connection identifier.

  • An error code indicating what went wrong.

ReceiveInfo

Properties

  • connectionId

    number

    The connection identifier.

  • data

    ArrayBuffer

    The data received.

SendError

Type

"disconnected"

,

"pending"

,

"timeout"

,
or

"system_error"

SendInfo

Properties

  • bytesSent

    number

    The number of bytes sent.

  • error

    SendError optional

    An error code if an error occurred.

StopBits

Type

"one"

, or

"two"

Methods

clearBreak

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

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

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

connect

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

    Port configuration options.

  • callback

    function

    The callback parameter looks like: (connectionInfo: ConnectionInfo) => void

disconnect

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

Disconnects from a serial port.

Parameters

  • connectionId

    number

    The id of the opened connection.

  • callback

    function

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

flush

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

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

Parameters

  • connectionId

    number

  • callback

    function

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

getConnections

chrome.serial.getConnections(
  callback: function,
)

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

Parameters

getControlSignals

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

Retrieves the state of control signals on a given connection.

Parameters

getDevices

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

getInfo

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

    The callback parameter looks like: (connectionInfo: ConnectionInfo) => void

send

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

    The callback parameter looks like: (sendInfo: SendInfo) => void

setBreak

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

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

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

setControlSignals

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

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

setPaused

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

    The callback parameter looks like: () => void

update

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

    The callback parameter looks like: (result: boolean) => void

    • result

      boolean

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