chrome.serial

描述：	使用 `chrome.serial` API 读取和写入连接到串行端口的设备。
可用版本：	从 Chrome 23 开始支持。
权限：	"serial"
了解更多：	访问硬件设备

摘要

类型
DataBits
ParityBit
StopBits
ConnectionOptions
ConnectionInfo
方法
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)`
事件
onReceive
onReceiveError

类型

DataBits

从 Chrome 33 开始支持。

枚举
`"seven"`, or `"eight"`

ParityBit

从 Chrome 31 开始支持。

枚举
`"no"`, `"odd"`, or `"even"`

StopBits

从 Chrome 33 开始支持。

枚举
`"one"`, or `"two"`

ConnectionOptions

从 Chrome 33 开始支持。

属性
boolean	（可选） persistent	应用关闭时连接是否应该保持打开状态（参见Chrome 应用的生命周期），默认值为 `false`。应用加载时，之前使用 `persistent: true` 打开的串口连接可以通过 `getConnections` 获取。
string	（可选） name	与连接相关联的字符串，由应用定义。
integer	（可选） bufferSize	用于接收数据的缓冲区大小，默认值为 4096。
integer	（可选） bitrate	打开连接时请求的比特率。为了尽可能地与各种硬件兼容，该数值应该匹配常用的比特率，例如 110、300、1200、2400、4800、9600、14400、19200、38400、57600、115200。当然，不能保证连接到串行端口的设备能支持请求的比特率，即使端口本身支持该比特率。默认为 `9600`。
DataBits	（可选） dataBits	默认为 `"eight"`。
ParityBit	（可选） parityBit	默认为 `"no"`。
StopBits	（可选） stopBits	默认为 `"one"`。
boolean	（可选） ctsFlowControl	是否启用 RTS/CTS 硬件流控制，默认为 false。
integer	（可选） receiveTimeout	产生 "timeout"（超时）错误的 `onReceiveError` 事件前等待新数据的最长时间（以毫秒为单位）。如果为零，该连接不会产生接收超时错误。默认为 0。
integer	（可选） sendTimeout	调用回调函数产生 "timeout"（超时）错误前等待 `send`（发送）操作完成的最长时间（以毫秒为单位）。如果为零，不会产生发送超时错误。默认为 0。

ConnectionInfo

从 Chrome 33 开始支持。

属性
integer	connectionId	串行端口连接标识符。
boolean	paused	是否阻止连接产生 onReceive 事件。
boolean	persistent	参见 `ConnectionOptions.persistent`。
string	name	参见 `ConnectionOptions.name`。
integer	bufferSize	参见 `ConnectionOptions.bufferSize`。
integer	receiveTimeout	参见 `ConnectionOptions.receiveTimeout`。
integer	sendTimeout	参见 `ConnectionOptions.sendTimeout`。
integer	（可选） bitrate	参见 `ConnectionOptions.bitrate`。如果使用了非标准的比特率或者查询下层设备时产生错误，该字段可能不精确或省略。
DataBits	（可选） dataBits	参见 `ConnectionOptions.dataBits`，如果查询下层设备时产生错误，该字段可能会省略。
ParityBit	（可选） parityBit	参见 `ConnectionOptions.parityBit`，如果查询下层设备时产生错误，该字段可能会省略。
StopBits	（可选） stopBits	参见 `ConnectionOptions.stopBits`，如果查询下层设备时产生错误，该字段可能会省略。
boolean	（可选） ctsFlowControl	参见 `ConnectionOptions.ctsFlowControl`，如果查询下层设备时产生错误，该字段可能会省略。

方法

getDevices


              chrome.serial.getDevices(function callback)

从 Chrome 33 开始支持。

返回系统中可用串行设备的有关信息，每次调用该方法时都会重新生成该列表。

参数

function

callback

调用时传递 DeviceInfo 对象列表。

callback 参数应该是一个如下形式的函数：

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

array of object

ports

每一个对象的属性

string	path	设备的系统路径，应该传递给 `chrome.serial.connect` 的 `path` 参数，以便连接到该设备。
integer	（可选） vendorId	PCI 或 USB 制造商标识符（如果可以从底层设备获取）。
integer	（可选） productId	USB 产品标识符（如果可以从底层设备获取）。
string	（可选） displayName	底层设备的可读显示名称（如果可以从宿主设备获取）。

connect


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

从 Chrome 33 开始支持。

连接到指定的串行端口。

参数

string

path

要打开的串行端口的系统路径。

ConnectionOptions

（可选）
options

端口配置选项。

function

callback

连接打开后调用。

callback 参数应该是一个如下形式的函数：

function( ConnectionInfo connectionInfo) {...};

ConnectionInfo

connectionInfo

update


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

从 Chrome 33 开始支持。

更新打开的串行端口连接的选项设置。

参数

integer

connectionId

打开的连接的标识符。

ConnectionOptions

options

端口配置选项。

function

callback

配置完成后调用。

callback 参数应该是一个如下形式的函数：

function(boolean result) {...};

boolean

result

disconnect


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

从 Chrome 33 开始支持。

断开串行端口连接。

参数

integer

connectionId

打开的连接的标识符。

function

callback

连接关闭后调用。

callback 参数应该是一个如下形式的函数：

function(boolean result) {...};

boolean

result

setPaused


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

从 Chrome 33 开始支持。

暂停打开的连接，或取消暂停。

参数

integer

connectionId

参数
integer	connectionId	打开的连接的标识符。
boolean	paused	暂停还是取消暂停。
function	callback	连接暂停或取消暂停成功后调用。 callback 参数应该是一个如下形式的函数： `function() {...};`

打开的连接的标识符。

boolean

paused

暂停还是取消暂停。

function

callback

连接暂停或取消暂停成功后调用。

callback 参数应该是一个如下形式的函数：

function() {...};

getInfo


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

从 Chrome 33 开始支持。

获取指定连接的状态。

参数

integer

connectionId

打开的连接的标识符。

function

callback

连接状态信息可用时调用。

callback 参数应该是一个如下形式的函数：

function( ConnectionInfo connectionInfo) {...};

ConnectionInfo

connectionInfo

getConnections


              chrome.serial.getConnections(function callback)

从 Chrome 33 开始支持。

获取当前应用拥有并打开的串行端口连接列表。

参数

function

callback

连接列表可用时调用。

callback 参数应该是一个如下形式的函数：

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

array of ConnectionInfo

connectionInfos

send


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

从 Chrome 33 开始支持。

向指定连接写入数据。

参数

integer

connectionId

连接标识符。

ArrayBuffer

data

要发送的数据。

function

callback

操作完成时调用。

callback 参数应该是一个如下形式的函数：

function(object sendInfo) {...};

object

sendInfo

integer

bytesSent

发送的字节数。

enum of "disconnected", "pending", "timeout", or "system_error"

（可选）
error

如果发生错误则为错误代码。

disconnected: 连接已断开。

pending: 发送操作正在进行。

timeout: 发送操作超时。

system_error: 发生系统错误，连接可能无法恢复。

flush


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

清洗指定连接输入输出缓存中的所有内容。

参数

integer connectionId

function

callback

callback 参数应该是一个如下形式的函数：

function(boolean result) {...};

boolean

result

getControlSignals


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

获取指定连接上控制信号的状态。

参数

integer

connectionId

连接标识符。

function

callback

控制信号可用时调用。

callback 参数应该是一个如下形式的函数：

function(object signals) {...};

object

signals

boolean	dcd	DCD（数据载波检测）或 RLSD（接收线信号检出）。
boolean	cts	清除发送。
boolean	ri	振铃指示。
boolean	dsr	数据装置就绪。

setControlSignals


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

设置指定连接上控制信号的状态。

参数

integer

connectionId

连接标识符。

object

signals

从 Chrome 33 开始支持。

要向设备发送的信号变化。

boolean	（可选） dtr	DTR（数据终端就绪）。
boolean	（可选） rts	RTS（请求发送）。

function

callback

控制信号设置后调用。

callback 参数应该是一个如下形式的函数：

function(boolean result) {...};

boolean

result

事件

onReceive

从 Chrome 33 开始支持。

数据从连接读取时产生该事件。

addListener


                    chrome.serial.onReceive.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object info) {...};

object

info

事件数据。

integer	connectionId	连接标识符。
ArrayBuffer	data	接收的数据。

onReceiveError

从 Chrome 33 开始支持。

运行时等待串行端口上的数据时如果发生错误，则产生该事件。产生该事件后，连接状态将设置为 paused（暂停）。"timeout"（超时）错误不会暂停连接。

addListener


                    chrome.serial.onReceiveError.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object info) {...};

object

info

integer

connectionId

连接标识符。

enum of "disconnected", "timeout", "device_lost", or "system_error"

error

表示错误信息的错误代码。

disconnected: 连接已断开。

timeout: 经过 receiveTimeout 毫秒后仍然未接收到数据。

device_lost: 设备可能已经从主机断开。

system_error: 发生系统错误，连接可能无法恢复。