chrome.serial

Description: Use the chrome.serial API to read from and write to a device connected to a serial port.
Availability: Since Chrome 35.
Permissions: "serial"
Learn More: Accessing Hardware Devices

Summary

Types
DataBits
ParityBit
StopBits
ConnectionOptions
ConnectionInfo
Methods
getDevices − chrome.serial.getDevices(function callback)
connect − chrome.serial.connect(string path, ConnectionOptions options, function callback)
update − chrome.serial.update(integer connectionId, ConnectionOptions options, function callback)
disconnect − chrome.serial.disconnect(integer connectionId, function callback)
setPaused − chrome.serial.setPaused(integer connectionId, boolean paused, function callback)
getInfo − chrome.serial.getInfo(integer connectionId, function callback)
getConnections − chrome.serial.getConnections(function callback)
send − chrome.serial.send(integer connectionId, ArrayBuffer data, function callback)
flush − chrome.serial.flush(integer connectionId, function callback)
getControlSignals − chrome.serial.getControlSignals(integer connectionId, function callback)
setControlSignals − chrome.serial.setControlSignals(integer connectionId, object signals, function callback)
setBreak − chrome.serial.setBreak(integer connectionId, function callback)
clearBreak − chrome.serial.clearBreak(integer connectionId, function callback)
Events
onReceive
onReceiveError

Types

DataBits

Enum
"seven", or "eight"

ParityBit

Enum
"no", "odd", or "even"

StopBits

Enum
"one", or "two"

ConnectionOptions

properties
boolean (optional) persistent

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.

string (optional) name

An application-defined string to associate with the connection.

integer (optional) bufferSize

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

integer (optional) bitrate

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.

DataBits (optional) dataBits

"eight" will be passed by default.

ParityBit (optional) parityBit

"no" will be passed by default.

StopBits (optional) stopBits

"one" will be passed by default.

boolean (optional) ctsFlowControl

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

integer (optional) receiveTimeout

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.

integer (optional) sendTimeout

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.

ConnectionInfo

properties
integer connectionId

The id of the serial port connection.

boolean paused

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

boolean persistent

See ConnectionOptions.persistent

string name

See ConnectionOptions.name

integer bufferSize

See ConnectionOptions.bufferSize

integer receiveTimeout

See ConnectionOptions.receiveTimeout

integer sendTimeout

See ConnectionOptions.sendTimeout

integer (optional) bitrate

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.

DataBits (optional) dataBits

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

ParityBit (optional) parityBit

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

StopBits (optional) stopBits

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

boolean (optional) ctsFlowControl

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

Methods

getDevices

chrome.serial.getDevices(function callback)

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

Parameters
function callback

Called with the list of DeviceInfo objects.

The callback parameter should be a function that looks like this:

function(array of object ports) {...};
array of object ports

Properties of each object

string path

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

integer (optional) vendorId

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

integer (optional) productId

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

string (optional) displayName

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

connect

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

Connects to a given serial port.

Parameters
string path

The system path of the serial port to open.

ConnectionOptions (optional) options

Port configuration options.

function callback

Called when the connection has been opened.

The callback parameter should be a function that looks like this:

function( ConnectionInfo connectionInfo) {...};
ConnectionInfo connectionInfo

update

chrome.serial.update(integer connectionId, ConnectionOptions options, function callback)

Update the option settings on an open serial port connection.

Parameters
integer connectionId

The id of the opened connection.

ConnectionOptions options

Port configuration options.

function callback

Called when the configuation has completed.

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

disconnect

chrome.serial.disconnect(integer connectionId, function callback)

Disconnects from a serial port.

Parameters
integer connectionId

The id of the opened connection.

function callback

Called when the connection has been closed.

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

setPaused

chrome.serial.setPaused(integer connectionId, boolean paused, function callback)

Pauses or unpauses an open connection.

Parameters
integer connectionId

The id of the opened connection.

boolean paused

Flag to indicate whether to pause or unpause.

function callback

Called when the connection has been successfully paused or unpaused.

The callback parameter should be a function that looks like this:

function() {...};

getInfo

chrome.serial.getInfo(integer connectionId, function callback)

Retrieves the state of a given connection.

Parameters
integer connectionId

The id of the opened connection.

function callback

Called with connection state information when available.

The callback parameter should be a function that looks like this:

function( ConnectionInfo connectionInfo) {...};
ConnectionInfo connectionInfo

getConnections

chrome.serial.getConnections(function callback)

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

Parameters
function callback

Called with the list of connections when available.

The callback parameter should be a function that looks like this:

function(array of ConnectionInfo connectionInfos) {...};
array of ConnectionInfo connectionInfos

send

chrome.serial.send(integer connectionId, ArrayBuffer data, function callback)

Writes data to the given connection.

Parameters
integer connectionId

The id of the connection.

ArrayBuffer data

The data to send.

function callback

Called when the operation has completed.

The callback parameter should be a function that looks like this:

function(object sendInfo) {...};
object sendInfo
integer bytesSent

The number of bytes sent.

enum of "disconnected", "pending", "timeout", or "system_error" (optional) error

An error code if an error occurred.

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.

flush

chrome.serial.flush(integer connectionId, function callback)

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

Parameters
integer connectionId
function callback

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

getControlSignals

chrome.serial.getControlSignals(integer connectionId, function callback)

Retrieves the state of control signals on a given connection.

Parameters
integer connectionId

The id of the connection.

function callback

Called when the control signals are available.

The callback parameter should be a function that looks like this:

function(object signals) {...};
object signals
boolean dcd

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

boolean cts

CTS (Clear To Send).

boolean ri

RI (Ring Indicator).

boolean dsr

DSR (Data Set Ready).

setControlSignals

chrome.serial.setControlSignals(integer connectionId, object signals, function callback)

Sets the state of control signals on a given connection.

Parameters
integer connectionId

The id of the connection.

object signals

The set of signal changes to send to the device.

boolean (optional) dtr

DTR (Data Terminal Ready).

boolean (optional) rts

RTS (Request To Send).

function callback

Called once the control signals have been set.

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

setBreak

chrome.serial.setBreak(integer connectionId, function callback)

Since Chrome 45.

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

Parameters
integer connectionId

The id of the connection.

function callback

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

clearBreak

chrome.serial.clearBreak(integer connectionId, function callback)

Since Chrome 45.

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

Parameters
integer connectionId

The id of the connection.

function callback

The callback parameter should be a function that looks like this:

function(boolean result) {...};
boolean result

Events

onReceive

Event raised when data has been read from the connection.

addListener

chrome.serial.onReceive.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object info) {...};
object info

Event data.

integer connectionId

The connection identifier.

ArrayBuffer data

The data received.

onReceiveError

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.

addListener

chrome.serial.onReceiveError.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object info) {...};
object info
integer connectionId

The connection identifier.

enum of "disconnected", "timeout", "device_lost", "break", "frame_error", "overrun", "buffer_overflow", "parity_error", or "system_error" error

An error code indicating what went wrong.

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.