uart - 串口操作库
以下为关键点梳理
一、UART 模块概述
UART（Universal Asynchronous Receiver/Transmitter）即通用异步收发传输器，在嵌入式系统中用于实现串行通信。合宙 Luatos 系统为 AIR780EPM 模组提供了完善的 UART API，方便开发者进行串口通信相关的开发工作。以下是对该 UART 模块 API 的详细梳理。
二、核心函数解析
uart.setup()
功能：配置串口参数，是使用串口前的必要初始化步骤。
参数解析：
id：串口号，指定要配置的串口设备。baud_rate：波特率，常见的有 9600、115200 等，决定了串行通信的数据传输速率。data_bits：数据位，通常为 7 或 8，表示每个数据帧中的数据位数。stop_bits：停止位，可为 1 或 2，用于标识数据帧的结束。parity：校验位，有 uart.NONE（无校验）、uart.ODD（奇校验）、uart.EVEN（偶校验）等选项，用于错误检测。bit_order：比特顺序，默认为 uart.LSB（ Least Significant Bit，低位在前），也可设置为 uart.MSB（高位在前）。buff_size：缓冲区大小，根据通信数据量合理设置，避免数据溢出。rs485_gpio、rs485_level、rs485_delay：当使用 RS485 通信时，用于配置收发转换相关的 GPIO 口、电平及延时参数。debug_enable、error_drop：调试使能及错误丢弃设置，error_drop为 0 表示接收错误时不抛弃缓存数据。
示例说明：
lua 复制
-- 常见的 115200 波特率、8 数据位、1 停止位、无校验的配置
uart.setup(1, 115200, 8, 1, uart.NONE)
-- RS485 模式配置，GPIO10 作为收发转换脚
uart.setup(1, 115200, 8, 1, uart.NONE, uart.LSB, 1024, 10, 0, 2000)
-- 遇到接收错误不抛弃缓存数据的配置_
uart.setup(1, 115200, 8, 1, uart.NONE, nil, 1024, nil, nil, nil, nil, 0)
uart.write()
功能：向指定串口写入数据，实现串行数据发送。
参数：
id：目标串口号。data：要发送的数据，可以是字符串形式的可见字符，也可以是通过string.char()转换的十六进制数据。
示例：
lua 复制
-- 发送文本字符串_
uart.write(1, "rdy\r\n")
-- 发送十六进制数据_
uart.write(1, string.char(0x55,0xAA,0x4B,0x03,0x86))
uart.read()
功能：从指定串口读取数据，获取接收到的串行数据。
参数：
id：源串口号。len：要读取的数据长度，根据实际需求指定，可避免读取过多无用数据。
返回值：读取到的数据内容，类型通常为字符串。
- uart.close()
功能：关闭指定串口，释放相关资源，当不再使用某串口时应调用此函数。
参数：
id：要关闭的串口号。
uart.on()
功能：注册串口事件回调，使程序能响应串口的特定事件，如接收数据到达。
参数：
id：串口号。event：事件类型，如 "receive" 表示接收数据事件。func：回调函数，在事件发生时执行，可对事件进行处理。
示例：
lua 复制
uart.on(1, "receive", function(id, len)local data = uart.read(id, len)
log.info("uart", id, len, data)
-- 打印接收到的数据信息_end)
uart.wait485()
功能：在 RS485 模式下，等待发送完成。适用于 MCU 不支持串口发送移位寄存器空或类似中断的情况，在 sent 事件回调后使用，确保数据完全发送。
uart.exist()
功能：检查指定串口号是否存在，可用于验证串口设备是否可用。
uart.rx()
功能：以 buff（缓冲区）形式读取串口数据，一次读出全部数据并存入 buff 中。若 buff 空间不足，会自动扩展。
参数：
id：串口号。buff：用于存储读取数据的缓冲区。
uart.rxSize()
功能：读取串口 Rx（接收）缓存中剩余的数据量，便于了解还有多少数据未读取。
返回值：Rx 缓存中剩余数据的字节数。
示例：
lua 复制
local size = uart.rxSize(1)
-- 获取串口 1 接收缓存的剩余数据量_
uart.rxClear()
功能：清除串口 Rx 缓存中的剩余数据，当不需要之前接收的数据时可调用此函数释放缓存空间。
uart.tx()
功能：以 buff 形式写串口，等同于 C 语言中的 uart_tx(uart_id, &buff[start], len)，提供更灵活的数据发送方式。
参数：
id：串口号。buff：要发送的数据缓冲区。start：发送数据的起始位置。len：要发送的数据长度。
三、总结
合宙 Luatos 的 UART 模块提供了全面且灵活的 API，涵盖了串口通信的各个方面，从基本的参数配置、数据读写，到高级的事件回调、软件 UART 设置等，满足了不同场景下的串行通信需求。开发者在使用时，应根据具体的硬件平台（如 Air780EPM）和应用场景，合理选择和调用这些 API，以实现高效、稳定的串口通信功能。
以下为详细说明
常量
| 常量 | 类型 | 解释 |
|---|---|---|
| uart.Odd | number | 奇校验,大小写兼容性 |
| uart.Even | number | 偶校验,大小写兼容性 |
| uart.None | number | 无校验,大小写兼容性 |
| uart.ODD | number | 奇校验 |
| uart.EVEN | number | 偶校验 |
| uart.NONE | number | 无校验 |
| uart.LSB | number | 小端模式 |
| uart.MSB | number | 大端模式 |
| uart.VUART_0 | number | 虚拟串口0 |
| uart.ERROR_DROP | number | 遇到错误时抛弃缓存的数据 |
| uart.DEBUG | number | 开启调试功能 |
uart.setup(id, baud_rate, data_bits, stop_bits, partiy, bit_order, buff_size, rs485_gpio, rs485_level, rs485_delay, debug_enable, error_drop)
配置串口参数
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1, 如此类推, 最大值取决于设备 |
| int | 波特率, 默认115200，可选择波特率表:{2000000,921600,460800,230400,115200,57600,38400,19200,9600,4800,2400} |
| int | 数据位，默认为8, 可选 7/8 |
| int | 停止位，默认为1, 根据实际情况，可以有0.5/1/1.5/2等 |
| int | 校验位，可选 uart.None/uart.Even/uart.Odd |
| int | 大小端，默认小端 uart.LSB, 可选 uart.MSB |
| int | 缓冲区大小，默认值1024 |
| int | 485模式下的转换GPIO, 默认值0xffffffff |
| int | 485模式下的rx方向GPIO的电平, 默认值0 |
| int | 485模式下tx向rx转换的延迟时间，默认值12bit的时间，单位us, 9600波特率填20000 |
| int | 开启调试功能，默认使能，填写uart.DEBUG或者非数字使能，其他值都是关闭 |
| int | 遇到接收错误是否放弃缓存数据，默认使能，填写uart.ERROR_DROP或者非数字使能，其他值都是关闭，目前只有移芯平台支持 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 成功返回0,失败返回其他值 |
例子
-- 最常用115200 8N1
uart.setup(1, 115200, 8, 1, uart.NONE)
-- 可以简写为 uart.setup(1)
-- 485自动切换, 选取GPIO10作为收发转换脚
uart.setup(1, 115200, 8, 1, uart.NONE, uart.LSB, 1024, 10, 0, 2000)
-- 遇到接收错误不抛弃缓存数据
uart.setup(1, 115200, 8, 1, uart.NONE, nil, 1024, nil, nil, nil, nil, 0)
uart.write(id, data)
写串口
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
| string/zbuff | 待写入的数据，如果是zbuff会从指针起始位置开始读 |
| int | 可选，要发送的数据长度，默认全发 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 成功的数据长度 |
例子
-- 写入可见字符串
uart.write(1, "rdy\r\n")
-- 写入十六进制的数据串
uart.write(1, string.char(0x55,0xAA,0x4B,0x03,0x86))
uart.read(id, len)
读串口
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
| int | 读取长度 |
| file/zbuff | 可选：文件句柄或zbuff对象 |
返回值
| 返回值类型 | 解释 |
|---|---|
| string | 读取到的数据 / 传入zbuff时，返回读到的长度，并把zbuff指针后移 |
例子
uart.read(1, 16)
uart.close(id)
关闭串口
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
返回值
| 返回值类型 | 解释 |
|---|---|
| nil | 无返回值 |
例子
uart.close(1)
uart.on(id, event, func)
注册串口事件回调
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
| string | 事件名称 |
| function | 回调方法 |
返回值
| 返回值类型 | 解释 |
|---|---|
| nil | 无返回值 |
例子
uart.on(1, "receive", function(id, len)
local data = uart.read(id, len)
log.info("uart", id, len, data)
end)
uart.wait485(id)
等待485模式下TX完成，mcu不支持串口发送移位寄存器空或者类似中断时才需要，在sent事件回调后使用
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 等待了多少次循环才等到tx完成，用于粗劣的观察delay时间是否足够，返回不为0说明还需要放大delay |
例子
无
uart.exist(id)
检查串口号是否存在
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1, 如此类推 |
返回值
| 返回值类型 | 解释 |
|---|---|
| bool | 存在返回true |
例子
无
uart.rx(id, buff)
buff形式读串口，一次读出全部数据存入buff中，如果buff空间不够会自动扩展
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
| zbuff | zbuff对象 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 返回读到的长度，并把zbuff指针后移 |
例子
uart.rx(1, buff)
uart.rxSize(id)
读串口Rx缓存中剩余数据量
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 返回读到的长度 |
例子
local size = uart.rxSize(1)
uart.rxClear(id)
清除串口Rx缓存中剩余数据量
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
返回值
无
例子
uart.rxClear(1)
uart.tx(id, buff, start, len)
buff形式写串口,等同于c语言uart_tx(uart_id, &buff[start], len);
参数
| 传入值类型 | 解释 |
|---|---|
| int | 串口id, uart0写0, uart1写1 |
| zbuff | 待写入的数据，如果是zbuff会从指针起始位置开始读 |
| int | 可选，要发送的数据起始位置，默认为0 |
| int | 可选，要发送的数据长度，默认为zbuff内有效数据，最大值不超过zbuff的最大空间 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 成功的数据长度 |
例子
uart.tx(1, buf)