chrome.serial

说明

使用 chrome.serial API 对连接到串行端口的设备执行读写操作。

权限

serial

类型

ConnectionInfo

属性

  • 比特率

    number 可选

    请参阅 ConnectionOptions.bitrate。如果使用了非标准比特率，或者在查询底层设备时发生错误，则此字段可能会被省略或不准确。

  • bufferSize

    数值

    查看ConnectionOptions.bufferSize

  • connectionId

    数值

    串行端口连接的 ID。

  • ctsFlowControl

    布尔值（可选）

    请参阅 ConnectionOptions.ctsFlowControl。如果在查询底层设备时发生错误，则可以省略此字段。

  • dataBits

    DataBits 可选

    请参阅 ConnectionOptions.dataBits。如果在查询底层设备时发生错误，则可以省略此字段。

  • name

    字符串

    查看ConnectionOptions.name

  • parityBit

    ParityBit 可选

    请参阅 ConnectionOptions.parityBit。如果在查询底层设备时发生错误，则可以省略此字段。

  • 已暂停

    布尔值

    一个标志，用于指示连接是否被阻止触发 onReceive 事件。

  • 持久性

    布尔值

    查看ConnectionOptions.persistent

  • receiveTimeout

    数值

    查看ConnectionOptions.receiveTimeout

  • sendTimeout

    数值

    查看ConnectionOptions.sendTimeout

  • stopBits

    StopBits（可选）

    请参阅 ConnectionOptions.stopBits。如果在查询底层设备时发生错误，则可以省略此字段。

ConnectionOptions

属性

  • 比特率

    number 可选

    要打开的连接的请求比特率。为了与尽可能多的硬件兼容，此数字应与常用的比特率（例如 110、300、1200、2400、4800、9600、14400、19200、38400、57600、115200）之一相匹配。当然，即使串行端口本身支持所请求的比特率，也无法保证连接到该端口的设备支持该比特率。默认情况下，系统会传递 9600。

  • bufferSize

    number 可选

    用于接收数据的缓冲区的大小。默认值为 4096。

  • ctsFlowControl

    布尔值（可选）

    一个标志，用于指示是否启用 RTS/CTS 硬件流量控制。默认值为 false。

  • dataBits

    DataBits 可选

    默认情况下，系统会传递 "eight"。

  • name

    字符串（选填）

    与连接关联的应用定义的字符串。

  • parityBit

    ParityBit 可选

    默认情况下，系统会传递 "no"。

  • 持久性

    布尔值（可选）

    一个标志，用于指示当应用处于暂停状态时（请参阅管理应用生命周期），连接是否应保持打开状态。默认值为“false”。当应用加载时，之前使用 persistent=true 打开的任何串行连接都可以通过 getConnections 获取。

  • receiveTimeout

    number 可选

    等待新数据的最长时间（以毫秒为单位），之后会引发包含“超时”错误的 onReceiveError 事件。如果为零，则不会针对连接引发接收超时错误。默认值为 0。

  • sendTimeout

    number 可选

    等待 send 操作完成的最长时间（以毫秒为单位），之后会调用回调并返回“超时”错误。如果为零，则不会触发发送超时错误。默认值为 0。

  • stopBits

    StopBits（可选）

    默认情况下，系统会传递 "one"。

DataBits

枚举

“seven”

“eight”

DeviceControlSignals

属性

  • cts

    布尔值

    CTS（允许发送）。

  • dcd

    布尔值

    DCD（数据载波检测）或 RLSD（接收线路信号/ 检测）。

  • dsr

    布尔值

    DSR（数据集就绪）。

  • ri

    布尔值

    RI（振铃指示器）。

DeviceInfo

属性

  • displayName

    字符串（选填）

    如果可以从主机驱动程序查询到基础设备的直观易懂的显示名称，则返回该名称。

  • 路径

    字符串

    设备的系统路径。应将此值作为 chrome.serial.connect 的 path 实参进行传递，以便连接到相应设备。

  • productId

    number 可选

    如果可以确定底层设备的 USB 产品 ID，则返回该 ID。

  • vendorId

    number 可选

    如果可以确定底层设备的 PCI 或 USB 供应商 ID，则为该 ID。

HostControlSignals

属性

  • dtr

    布尔值（可选）

    DTR（数据终端就绪）。

  • rts

    布尔值（可选）

    RTS（发送请求）。

ParityBit

枚举

“否”

“奇数”

“even”

ReceiveError

枚举

“已断开连接”
连接已断开。

“超时”
已 receiveTimeout 毫秒未收到任何数据。

“device_lost”
设备很可能已与主机断开连接。

“中断”
设备检测到中断情况。

“frame_error”
设备检测到帧错误。

“过冲”
发生了字符缓冲区过冲。下一个字符丢失。

“buffer_overflow”
发生了输入缓冲区溢出。输入缓冲区中没有空间，或者在文件结束 (EOF) 字符之后收到了一个字符。

“parity_error”
设备检测到奇偶校验错误。

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

ReceiveErrorInfo

属性

  • connectionId

    数值

    连接标识符。

  • 错误

    ReceiveError

    一个错误代码，用于指明出了什么问题。

ReceiveInfo

属性

  • connectionId

    数值

    连接标识符。

  • 数据

    ArrayBuffer

    收到的数据。

SendError

枚举

“已断开连接”
连接已断开。

“待处理”
发送操作已处于待处理状态。

“超时”
发送超时。

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

SendInfo

属性

  • bytesSent

    数值

    发送的字节数。

  • 错误

    SendError 可选

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

StopBits

枚举

“one”

“two”

方法

clearBreak()

Promise Chrome 45 及更高版本 
chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

恢复给定连接上的字符传输，并将传输线路置于非中断状态。

参数

  • connectionId

    数值

    连接的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

connect()

Promise 
chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
): Promise<ConnectionInfo>

连接到给定的串行端口。

参数

  • 路径

    字符串

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

  • 选项

    ConnectionOptions 可选

    端口配置选项。

  • callback

    函数 可选

    callback 参数如下所示： 

    (connectionInfo: ConnectionInfo) => void

返回

  • Promise<ConnectionInfo>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

disconnect()

Promise 
chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
): Promise<boolean>

断开与串行端口的连接。

参数

  • connectionId

    数值

    已打开连接的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

flush()

Promise 
chrome.serial.flush(
  connectionId: number,
  callback?: function,
): Promise<boolean>

刷新给定连接的输入和输出缓冲区中的所有字节。

参数

  • connectionId

    数值

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getConnections()

Promise 
chrome.serial.getConnections(
  callback?: function,
): Promise<ConnectionInfo[]>

检索应用当前拥有的已打开的串行端口连接的列表。

参数

返回

  • Promise<ConnectionInfo[]>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getControlSignals()

Promise 
chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
): Promise<DeviceControlSignals>

检索给定连接上的控制信号的状态。

参数

返回

  • Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDevices()

Promise 
chrome.serial.getDevices(
  callback?: function,
): Promise<DeviceInfo[]>

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (ports: DeviceInfo[]) => void

返回

  • Promise<DeviceInfo[]>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getInfo()

Promise 
chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
): Promise<ConnectionInfo>

检索指定连接的状态。

参数

  • connectionId

    数值

    已打开连接的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (connectionInfo: ConnectionInfo) => void

返回

  • Promise<ConnectionInfo>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

send()

Promise 
chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<SendInfo>

将数据写入指定连接。

参数

  • connectionId

    数值

    连接的 ID。

  • 数据

    ArrayBuffer

    要发送的数据。

  • callback

    函数 可选

    callback 参数如下所示： 

    (sendInfo: SendInfo) => void

返回

  • Promise<SendInfo>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setBreak()

Promise Chrome 45 及更高版本 
chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

暂停指定连接上的字符传输，并将传输线路置于中断状态，直到调用 clearBreak。

参数

  • connectionId

    数值

    连接的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setControlSignals()

Promise 
chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
): Promise<boolean>

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

参数

  • connectionId

    数值

    连接的 ID。

  • 要发送到设备的一组信号更改。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setPaused()

Promise 
chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

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

参数

  • connectionId

    数值

    已打开连接的 ID。

  • 已暂停

    布尔值

    用于指示是暂停还是取消暂停的标志。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

update()

Promise 
chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
): Promise<boolean>

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

参数

  • connectionId

    数值

    已打开连接的 ID。

  • 端口配置选项。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onReceive

chrome.serial.onReceive.addListener(
  callback: function,
)

当数据已从连接中读取时引发的事件。

参数

onReceiveError

chrome.serial.onReceiveError.addListener(
  callback: function,
)

运行时等待串行端口上的数据时发生错误时引发的事件。引发此事件后，连接可能会设置为 paused。"timeout" 错误不会暂停连接。

参数