【ioqueue】 IO序列化操作全解析

从内存对象到可存储或可传输的字节流，IO序列化操作完成了数据形态的转化。这一过程不仅涉及编码与解码逻辑，还需处理版本兼容、安全性与性能开销等问题。全面掌握这一技术路径，有助于构建更加健壮的应用系统。

一、概述

ioqueue 模块提供了 IO 序列操作的功能，可以通过硬件定时器精确控制 GPIO 的操作时序。

注意事项：

对于 Air700EXX 系列、Air780EXX 系列、Air8000 系列模组，硬件定时器有如下要求：

硬件定时器 id：0-5，六个硬件定时器，

定时器精度：20 微秒，为硬件支持的最小时间单位。

3 和 5 固定被底层占用不可使用

pwm 功能依赖硬件定时器，ioqueue 不可与 pwm 功能同时使用

pwm0 对应 0

pwm4 对应 4

以此类推

注意：Air6101/Air8101 不支持此功能

1.1 使用场景

ioqueue 主要是输出一些特殊的电平序列，捕获自定义协议。

如果有以下需要就可以使用该库：

精确控制多个 GPIO 的开关时序

循环执行固定的 GPIO 操作序列

捕获 GPIO 边沿变化的精确时间戳

模拟非标准通信协议

1.1.1 输入捕获场景（以 DHT11 数据读取为例）

单总线协议要求严格的时序控制、主机需要先发送特定启动信号、传感器响应时间精确到微秒级、数据通过脉冲宽度编码

使用流程：

下面演示使用硬件定时器精确控制 DHT11 通信时序，通过捕获下降沿时间戳解码温湿度数据，实现微秒级精确通信：

dht11 通讯协议介绍：

数据分为小数部分和整数部分，一次完整的数据传输为 40bit，高位先出

数据格式：8bit 湿度整数数据 +8bit 湿度小数数据 +8bit 温度整数数据 +8bit 温度小数数据 +8bit 校验

8bit 校验 = 8bit 湿度整数数据 +8bit 湿度小数数据 +8bit 温度整数数据 +8bit 温度小数数据

校验可以判断数据是否正确发送

DHT11 工作时序：

主机发送起始信号以后，DHT11 发送响应信号，然后发送 40bit 的数据，高位在前

总时序图如下：

起始信号：总线空闲状态由 DHT11 内置上拉电阻拉高，主机拉低总线至少 18ms 后释放总线 20-40us

DHT11 响应：存在的 DHT11 会及时响应主机，同时拉低总线 80us 后，释放总线 80us，然后拉低总线，表示开始传送数据

发送数据：当总线是低电平是表示开始发送数据，同时存在 50us 低电平时隙，之后拉高总线，高电平的持续时间表示发送 0 或者 1，当高电平持续时间为 26us-28us 表示发送 0，高电平持续时间为 70us 时，表示发送 1

数据发送完毕，由上拉电阻拉高，置回空闲高电平状态

具体波形如下：

1.1.2 输出精确脉冲场景

需要不同的脉冲宽度、软件循环无法满足精度要求、需要连续输出大量脉冲

使用流程：

下面演示利用硬件定时器生成固定频率或可变宽度的精确脉冲序列，支持连续和单次延时模式，实现微秒级脉冲控制：

固定间隔脉冲

可变宽度脉冲序列

二、核心示例

示例可参考 1.1.1 章节具体使用分析。

三、常量详解

核心库常量，顾名思义是由 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

ioqueue 模块没有常量。

四、函数详解

ioqueue.init(hwtimer_id, cmd_cnt, repeat_cnt)

功能

初始化一个 io 操作队列。

参数

hwtimer_id

cmd_cnt

repeat_cnt

返回值

无返回值。

示例

ioqueue.setdelay(hwtimer_id, time_us, time_tick, continue)

功能

对 io 操作队列增加延时命令。

参数

hwtimer_id

time_us

time_tick

continue

返回值

无返回值。

示例

ioqueue.delay(hwtimer_id)

功能

对 io 操作队列增加一次重复延时，在前面必须有 setdelay 并且是连续延时。

注意事项

必须在前面的 ioqueue.setdelay 设置 continue=true

参数

hwtimer_id

返回值

无返回值。

示例

ioqueue.setgpio(hwtimer_id, pin, is_input, pull_mode, init_level)

功能

对 io 操作队列增加设置 gpio 命令。

参数

hwtimer_id

pin

is_input

pull_mode

init_level

返回值

无返回值。

示例

ioqueue.input(hwtimer_id, pin)

功能

对 io 操作队列增加读取 gpio 命令。

应用场景：在精确时序点读取 GPIO 电平状态

使用时必须先调用 ioqueue.setgpio 设置输入模式，然后通过 ioqueue.get()读取输入数据

参数

hwtimer_id

pin

返回值

无返回值。读取的数据需要通过 ioqueue.get 获取。

示例

ioqueue.output(hwtimer_id, pin, level)

功能

对 io 操作队列增加输出 GPIO 命令。

参数

hwtimer_id

pin

level

返回值

无返回值。

示例

ioqueue.set_cap(hwtimer_id, pin, pull_mode, irq_mode, max_tick)

功能

对 io 操作队列增加设置捕获某个 IO 命令。

捕获的配置命令

参数

hwtimer_id

pin

pull_mode

irq_mode

max_tick

返回值

无返回值。

示例

ioqueue.capture(hwtimer_id)

功能

对 io 操作队列增加捕获一次 IO 状态命令。

捕获的执行命令，必须先经过 ioqueue.set_cap 配置后才能使用 ioqueue.capture 来捕获，一个 set_cap 配置可以被多个 capture 命令复用

参数

hwtimer_id

返回值

无返回值。捕获的数据需要通过 ioqueue.get 获取。

示例

ioqueue.cap_done(hwtimer_id, pin)

功能

对 io 操作队列结束捕获某个 IO 命令。

使用场景：

1.捕获任务完成时 ：主动结束，告诉系统数据读取完成，停止 gpio 捕获

2.切换捕获目标时：比如从捕获 gpio1 切换到捕获 gpio2，需要先结束捕获 gpio1。

3.错误处理或者提前退出时调用。

参数

hwtimer_id

pin

返回值

无返回值。

示例

ioqueue.get(hwtimer_id, input_buff, capture_buff)

功能

获取 io 操作队列中输入和捕获的数据。

注意事项

input，set_cap，capture 这三个配置接口配置的功能，缓存到的输入数据和捕获数据，都是通过 get 接口来读取出来

input_buff ← 存储 ioqueue.input() 的即时电平采样结果

capture_buff ← 存储 ioqueue.capture() 的边沿事件 + 时间戳

input_cnt = 成功的 ioqueue.input() 操作数量

capture_cnt = 成功的 ioqueue.icapture() 操作数量（可能因超时而小于计划数）

参数

hwtimer_id

input_buff

capture_buff

返回值

local input_cnt, capture_cnt = ioqueue.get(hwtimer_id, input_buff, capture_buff)

input_cnt

capture_cnt

示例

ioqueue.start(hwtimer_id)

功能

启动 io 操作队列。

参数

hwtimer_id

返回值

无返回值。

示例

ioqueue.stop(hwtimer_id)

功能

停止 io 操作队列，可以通过 start 从头开始。

参数

hwtimer_id

返回值

local loop_cnt, cmd_cnt = ioqueue.stop(hwtimer_id)

loop_cnt

cmd_cnt

示例

ioqueue.release(hwtimer_id)

功能

释放 io 操作队列的资源，下次使用必须重新 init。

参数

hwtimer_id

返回值

无返回值。

示例

ioqueue.clear(hwtimer_id)

功能

清空 io 操作队列。

此接口重置了命令队列但保留了硬件定时器资源，可以直接添加新的命令。前提是你确信之前队列的状态完全被清空，且新的命令序列与之前的结构兼容。

参数

hwtimer_id

返回值

无返回值。

示例

ioqueue.done(hwtimer_id)

功能

检测 io 操作队列是否已经执行完成。

参数

hwtimer_id

返回值

local is_done = ioqueue.done(hwtimer_id)

is_done

示例

ioqueue.exti(pin, pull_mode, irq_mode, onoff)

功能

启动/停止一个带系统 tick 返回的外部中断。

ioqueue.exti 是一个独立的外部中断接口，与 ioqueue 队列系统完全分离，提供简单的 GPIO 边沿事件捕获功能。

使用场景：简单的按键检测、传感器状态监控、旋转编码器计数

参数

pin

pull_mode

irq_mode

onoff

返回值

无返回值。

示例

五、模组支持说明

仅支持 Air700EXX 系列、Air780EXX 系列、Air8000 系列模组，Air6101/Air8101 不支持此功能。

今天的内容就分享到这里了~

审核编辑 黄宇