串口

串口 协议的接口以「jc.serial」作为对象访问前缀。串口 通信流程包含以下步骤：

1. 通过startAsync创建串口设备连接「SerialConnection」。
2. 操作串口连接实例，通过 sendAsync 或 inPacketAsync 接口获取数据包实例「SerialPacket」。
3. 操作数据包实例，通过接口 replyAsync 向数据来源发送数据。

操作接口

串口 协议的操作接口由入口函数 startAsync 和不同层级（连接/数据包）的工具类接口共同组成。

startAsync()

串口入口函数。启动1个串口连接，返回 SerialConnection 实例。

• 函数签名

type SerialInfo = {
    parity: 'none' | 'odd' | 'even';
    flow: 'none' | 'onoff' | 'rtscts';
    stopBits: 1 | 1.5 | 2;
    dataBits: 5 | 6 | 7 | 8;
    /** 串口设备名称 */
    inputPort: string;
    /** 波特率 */
    inputBaudRate: string;
};

type SerialStartInfo = string | Partial<SerialInfo>;

function startAsync (info?: SerialStartInfo): Promise<SerialConnection>;

• 输入参数
  • info（可选） 开启串口设备的参数设置。可以只传入目标设备名称（字符串），其他设置采用默认值。

参数说明

参数名	默认值	说明
parity	'none'	校验位，用于错误检测，可选无校验（None）、奇校验（Odd）或偶校验（Even）。
flow	'none'	流控制，管理数据流，常用方式为无流控（None）、硬件流控（RTS/CTS）或软件流控（XON/XOFF）。
stopBits	1	停止位，标志数据包结束的位数，通常为1或2位。
dataBits	8	数据位，每个数据包的位数，通常为5、6、7或8位。
inputBaudRate	'9600'	波特率，数据传输速度，单位bps（比特/秒）。
inputPort	本机串口设备列表的第一个设备	设备名称。

• 返回值 SerialConnection 实例对象。

startWithAsync()

入口函数的便利版本。根据指定页面的参数启动1个串口连接，返回 SerialConnection 实例。

• 函数签名

function startWithAsync (pageName: string): Promise<SerialConnection>;

• 输入参数
  • pageName 目标串口接口页面名称。查找指定名称的接口页面，获取该页面中的参数，并以此启动1个串口连接。
• 返回值 SerialConnection 实例对象。

list()

异步获取所有可用的串口设备。

• 函数签名

function list(): Promise<string[]>;

• 输入参数 无
• 返回值 Promise对象，返回串口设备名称数组。

SerialConnection

串口连接的操作接口如下：

sendAsync()

向串口设备发送数据。

• 函数签名

  sendAsync (type: string, data: any): Promise<SerialPacket>;

• 输入参数

  • type 数据类型。
  • data 数据内容。

  协议支持的数据类型如下：

  type	data类型
  'text'	string
  'hex'	string
  'raw'	Buffer

• 返回值 Promise对象，发送完成后返回所发送的SerialPacket对象。

sendWithAsync()

将其他页面中定义的已有数据内容向串口设备发送。

• 函数签名

  sendWithAsync (pageName: string, contentName: string): Promise<SerialPacket>;

• 输入参数

  • pageName 页面名称，仅限在「接口」和「模板」页面中查找。
  • contentName 内容名称

• 返回值 Promise对象，发送完成后返回所发送的SerialPacket对象。

inPacketAsync()

异步获取接收到的数据包对象。

• 函数签名

  inPacketAsync (): Promise<SerialPacket>;

• 输入参数 无

• 返回值 Promise对象，接收到数据包后返回SerialPacket对象。

onPacket()

当「发送」或「接收」数据包时触发回调。

• 函数签名

  onPacket (
    handler: (packet: SerialPacket) => void, once?: boolean
  ): CancelFunc;

• 输入参数

  • handler 新数据包的处理函数。触发时将会回调本函数，并传入新的SerialPacket实例。
  • once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。

• 返回值 取消函数，调用此函数可以解除本次注册。

onPacketIn()

当「接收」数据包时触发回调。

• 函数签名

  onPacketIn (
    handler: (packet: SerialPacket) => void, once?: boolean
  ): CancelFunc;

• 输入参数

  • handler 新数据包的处理函数。触发时将会回调本函数，并传入新的SerialPacket实例。
  • once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。

• 返回值 取消函数，调用此函数可以解除本次注册。

onPacketOut()

当「发送」数据包时触发回调。

• 函数签名

  onPacketOut (
    handler: (packet: SerialPacket) => void, once?: boolean
  ): CancelFunc;

• 输入参数

  • handler 新数据包的处理函数。触发时将会回调本函数，并传入新的SerialPacket实例。
  • once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。

• 返回值 取消函数，调用此函数可以解除本次注册。

destroyAsync()

正常断开串口设备。

• 函数签名

  destroyAsync (): Promise<void>;

• 输入参数 无

• 返回值 无

whenDestroyedAsync()

异步等待设备被断开。

• 函数签名

  whenDestroyedAsync (): Promise<void>;

• 输入参数 无

• 返回值 无

SerialPacket

串口数据包的操作接口如下：

replyAsync()

向数据包的来源回复1个数据包。

• 函数签名

  replyAsync (type: string, data: any): Promise<SerialPacket>;

• 输入参数

  • type 数据类型。
  • data 数据内容。

  协议支持的数据类型如下：

  type	data类型
  'text'	string
  'hex'	string
  'raw'	Buffer

• 返回值 Promise对象，发送完成后返回所发送的SerialPacket对象。

只读接口

SerialConnection

records()

获取连接的打开记录列表，因为连接可能被多次打开/关闭。

• 函数签名

records (): FlowConnectionRecord[];

FlowConnectionRecord

• inBytes()：返回自本次连接创建以来累计接收的字节数。
• outBytes()：返回自本次连接创建以来累计发送的字节数。
• inPackets()：返回自本次连接创建以来累计接收的数据包个数。
• outPackets()：返回自本次连接创建以来累计发送的数据包个数。

SerialPacket

• inout()：该数据包的收发方向，"in"为接收，"out"为发送。
• length()：数据包载荷的字节数。
• payload()：该数据包的原始载荷内容，即二进制数据。