Airlink - 设备间通讯协议库

作者：魏健强

一、概述

Airlink 是合宙 luatOS 提供的一种设备间通讯协议，主要用于设备内部或设备间的数据通信，支持 SPI 和 UART 两种通信方式。主要应用于 Air8000 内部以及 Air6101/Air8101 和 Air780EXX 之间的通信；

通过 airlink 交互数据：通过 spi 或 uart 方式连接两台设备；

通过 airlink 实现多网融合功能：通过 spi 或 uart 方式连接两台设备；

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库；

-- 初始化Airlink
airlink.init()

-- 启动Airlink（SPI主机模式）
airlink.start(airlink.MODE_SPI_MASTER)

-- 等待就绪
while not airlink.ready() do
    sys.wait(100)
end

-- 发送数据
airlink.sdata("hello world")

-- 获取从机版本号
local version = airlink.sver()
log.info("airlink", "从机版本号", version)

--------------实现多网融合功能--------------------------
--Air780EPM-------------------------------------------
-- 初始化airlink。
airlink.init()
-- 创建桥接网络设备。
log.info("创建桥接网络设备")
netdrv.setup(socket.LWIP_USER0, netdrv.WHALE)
-- 启动airlink，配置Air780EPM作为SPI主机模式。
airlink.start(airlink.MODE_SPI_MASTER)
-- 配置IPv4地址。
log.info("配置IPv4地址", "192.168.111.2", "255.255.255.0", "192.168.111.1")
netdrv.ipv4(socket.LWIP_USER0, "192.168.111.2", "255.255.255.0", "192.168.111.1")
-- 等待网络就绪，默认事件主题为IP_READY，设置超时时间为10秒。
sys.waitUntil("IP_READY", 10000)
-- 配置网络地址端口转换（NAPT），此处使用4G网络作为主网关出口。
netdrv.napt(socket.LWIP_GP)
-- 设置DNS代理。
dnsproxy.setup(socket.LWIP_USER0, socket.LWIP_GP)
--Air8101--------------------------------------------
-- 初始化airlink。
airlink.init()
-- 创建桥接网络设备。
log.info("创建桥接网络设备")
netdrv.setup(socket.LWIP_USER0, netdrv.WHALE)
-- 启动airlink，配置Air8101作为SPI从机模式。
airlink.start(airlink.MODE_SPI_SLAVE)
-- 配置IPv4地址。
log.info("配置IPv4地址", "192.168.111.1", "255.255.255.0", "192.168.111.2")
netdrv.ipv4(socket.LWIP_USER0, "192.168.111.1", "255.255.255.0", "192.168.111.2")
--------------实现多网融合功能--------------------------

三、常量详解

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

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 airlink.MODE_SPI_SLAVE

常量含义：SPI从机模式；
数据类型：number；
常量取值：0；
示例代码: airlink.start(airlink.MODE_SPI_SLAVE)；

3.2 airlink.MODE_SPI_MASTER

常量含义：SPI主机模式；
数据类型：number；
常量取值：1；
示例代码: airlink.start(airlink.MODE_SPI_MASTER)；

3.3 airlink.MODE_UART

常量含义：UART模式；
数据类型：number；
常量取值：2；
示例代码: airlink.start(airlink.MODE_UART)；

3.4 airlink.CONF_SPI_ID

常量含义：SPI配置参数，设置SPI的ID；
数据类型：number；
常量取值：256；
示例代码: airlink.config(airlink.CONF_SPI_ID, 1)；

3.5 airlink.CONF_SPI_CS

常量含义：SPI配置参数，设置SPI的CS脚的GPIO；
数据类型：number；
常量取值：258；
示例代码: airlink.config(airlink.CONF_SPI_CS, 10)；

3.6 airlink.CONF_SPI_RDY

常量含义：SPI/UART配置参数，设置RDY脚的GPIO；
数据类型：number；
常量取值：259；
示例代码: airlink.config(airlink.CONF_SPI_RDY, 11)；

3.7 airlink.CONF_SPI_IRQ

常量含义：SPI/UART配置参数，设置IRQ脚的GPIO；
数据类型：number；
常量取值：260；
示例代码: airlink.config(airlink.CONF_SPI_IRQ, 12)；

3.8 airlink.CONF_SPI_SPEED

常量含义：SPI配置参数，设置SPI的波特率；
数据类型：number；
常量取值：261；
示例代码: airlink.config(airlink.CONF_SPI_SPEED, 20*1000000)；

3.9 airlink.CONF_IRQ_TIMEOUT

常量含义：SPI/UART配置参数，设置IRQ模式的等待超时时间；
数据类型：number；
常量取值：263；
示例代码: airlink.config(airlink.CONF_IRQ_TIMEOUT, 5000)；

3.10 airlink.CONF_UART_ID

常量含义：UART配置参数，设置UART的ID；
数据类型：number；
常量取值：262；
示例代码: airlink.config(airlink.CONF_UART_ID, 1)；

四、函数详解

4.1 airlink.init()

功能

初始化 Airlink；

参数

无参数

返回值

无返回值

示例

-- 对于Air8000, 本函数已自动执行, 无需手动调用
-- 对于Air780EPM+Air8101的组合, 需要执行一次
airlink.init()

4.2 airlink.start(mode)

功能

启动 Airlink；

参数

mode

参数含义：工作模式；
数据类型：number；
取值范围：airlink.MODE_SPI_SLAVE/airlink.MODE_SPI_MASTER/airlink.MODE_UART；
是否必选：必选；
注意事项：暂无；
参数示例：airlink.start(airlink.MODE_SPI_MASTER)；

返回值

无返回值

示例

-- 对于Air8000, 本函数已自动执行, 无需手动调用
-- 对于Air780EPM+Air8101的组合, 需要执行一次
-- Air780EPM作为SPI主机
airlink.start(airlink.MODE_SPI_MASTER)
-- Air8101作为SPI从机
airlink.start(airlink.MODE_SPI_SLAVE)

4.3 airlink.config(key, value)

功能

配置 Airlink 参数；

参数

key

参数含义：配置项；
数据类型：number；
取值范围：参考常量章节中的3.4到3.10小节；
是否必选：必选；
注意事项：暂无；
参数示例：airlink.config(airlink.CONF_SPI_ID, 1)；

value

参数含义：配置值；
数据类型：number；
取值范围：取决于配置项；
是否必选：必选；
注意事项：暂无；
参数示例：airlink.config(airlink.CONF_SPI_ID, 1)；

返回值

local res = airlink.config(key, value)

log.info("airlink.config",res)

res

含义说明：配置结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true

示例

--配置AirLink的SPI ID为1, CS引脚为10, RDY引脚为11, IRQ引脚为12
airlink.config(airlink.CONF_SPI_ID, 1)
airlink.config(airlink.CONF_SPI_CS, 10)
airlink.config(airlink.CONF_SPI_RDY, 11)
airlink.config(airlink.CONF_SPI_IRQ, 12)

4.4 airlink.ready()

功能

判断 AirLink 是否就绪, 指底层通信是否通畅, 最近一次通信是否超时(默认 2s)；

本函数仅用于判断 AirLink 是否就绪, 不能用于判断是否收到对端设备通过 sdata 接口发送的数据；

参数

无参数

返回值

local res = airlink.ready()

log.info("airlink.ready",res)

res

含义说明：Airlink是否就绪；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

if airlink.ready() then
    log.info("airlink", "已就绪")
else
    log.info("airlink", "未就绪")
end

4.5 airlink.sdata(data)

功能

发送自定义数据；

通过订阅 airlink 的 SDATA 事件，打印接收到的信息。

示例代码如下：

local function airlink_sdata(data)

log.info("收到AIRLINK_SDATA!!", data)

end

sys.subscribe("AIRLINK_SDATA", airlink_sdata)

参数

data

参数含义：待发送的数据；
数据类型：string或zbuff；
取值范围：最大1500字节；
是否必选：必选；
注意事项：暂无；
参数示例：airlink.sdata("hello world")；

返回值

local res = airlink.sdata(data)

log.info("airlink.sdata",res)

res

含义说明：发送结果；
数据类型：boolean；
取值范围：true/nil；
注意事项：返回值为true代表成功，nil代表填写的数据格式或长度异常；
返回示例：true；

示例

airlink.sdata("hello world")

4.6 airlink.statistics()

功能

打印统计信息；

print_stat("收发总包", &tmp.tx_pkg, 1);

print_stat("发送IP包",   &tmp.tx_ip, 1);

print_stat("发送IP字节", &tmp.tx_bytes, 1);

print_stat("接收IP包",   &tmp.rx_ip, 1);

print_stat("接收IP字节", &tmp.rx_bytes, 1);

或

print_stat("等待从机", &tmp.wait_rdy, 0);

print_stat("Task超时事件", &tmp.event_timeout, 0);

print_stat("Task新数据事件", &tmp.event_new_data, 0);

参数

无参数

返回值

无返回值

示例

airlink.statistics()

4.7 airlink.slave_reboot()

功能

重启从机；

参数

无参数

返回值

无返回值

示例

airlink.slave_reboot()

4.8 airlink.debug(mode)

功能

调试开关；

打开后会增加相关日志的打印，如："RDY 引脚中断模式已启用"；

参数

mode

参数含义：调试模式；
数据类型：number；
取值范围：0-关闭，1-打开；
是否必选：必选；
注意事项：暂无；
参数示例：airlink.debug(1)；

返回值

无返回值

示例

airlink.debug(1)

4.9 airlink.pause(mode)

功能

暂停或恢复 airlink 通信；

暂停后主机和从机停止通信，如：Air8000 无法在获取 gpio>100 的引脚的状态。

恢复后通讯正常；

参数

mode

参数含义：模式；
数据类型：number；
取值范围：0-恢复，1-暂停；
是否必选：必选；
注意事项：仅当airlink运行在轮询模式时有效；
参数示例：airlink.pause(1)；

返回值

无返回值

示例

airlink.pause(1)

4.10 airlink.power(enable)

功能

关闭 Air8000 内部的 WiFi 芯片供电, 通常用于省电；

当前仅对 Air8000 带 wifi 功能的模组有效

关闭之后, 如需使用 wifi 功能, 需要重新执行 wifi.init 等操作

注意, wifi 供电关掉后, >=128 的 GPIO 也会变成输入高阻态

airlink.power(false)

开启 wifi 芯片,恢复 airlink 通信

airlink.power(true)

参数

enable

参数含义：是否使能；
数据类型：boolean；
取值范围：true/false；
是否必选：必选；
注意事项：当前仅对Air8000带wifi功能的模组有效；
参数示例：airlink.power(false)；

返回值

无返回值

示例

airlink.power(false)

4.11 airlink.sver()

功能

获取从机版本号,只有 Air780EXX 和 Air8000 主机模式可以获取从机版本号；

参数

无参数

返回值

local num = airlink.sver()

log.info( "从机固件版本号",num)

res

含义说明：从机固件版本号；
数据类型：number；
取值范围：无；
注意事项：无；
返回示例：14

示例

-- 注意, 获取之前, 需要确定airlink.ready()已经返回true
log.info("airlink", "从机固件版本号", airlink.sver())

五、产品支持说明

支持 LuatOS 开发的以下几种产品或者产品组合：

1、Air8000；

2、Air6101+Air780EXX；

3、Air8101+Air780EXX；