chrome.serial

Description:	Use the `chrome.serial` API to read from and write to a device connected to a serial port.
Availability:	Stable since Chrome 23.
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)`
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

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", 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.

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