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
ConnectionOptions
DataBits
DeviceControlSignals
DeviceInfo
HostControlSignals
ParityBit
ReceiveError
ReceiveErrorInfo
ReceiveInfo
SendError
SendInfo
StopBits
Methods
clearBreak
connect
disconnect
flush
getConnections
getControlSignals
getDevices
getInfo
send
setBreak
setControlSignals
setPaused
update
Events
onReceive
onReceiveError

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.
error
ReceiveError
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
ConnectionOptions optional
Port configuration options.
callback
function
The callback parameter looks like: (connectionInfo: ConnectionInfo) => void
- connectionInfo
  ConnectionInfo

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

callback
function
The callback parameter looks like: (connectionInfos: ConnectionInfo[]) => void
- connectionInfos
  ConnectionInfo[]

getControlSignals

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

Retrieves the state of control signals on a given connection.

Parameters

connectionId
number
The id of the connection.
callback
function
The callback parameter looks like: (signals: DeviceControlSignals) => void
- signals
  DeviceControlSignals

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

callback
function
The callback parameter looks like: (ports: DeviceInfo[]) => void
- ports
  DeviceInfo[]

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
- connectionInfo
  ConnectionInfo

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
- sendInfo
  SendInfo

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.
signals
HostControlSignals
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.
options
ConnectionOptions
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

callback
function
The callback parameter looks like: (info: ReceiveInfo) => void
- info
  ReceiveInfo

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

callback
function
The callback parameter looks like: (info: ReceiveErrorInfo) => void
- info
  ReceiveErrorInfo