2 airlink-芯片间通信

作者：魏健强　|　最后修改：2026-06-10

一、概述

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

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

2. 通过 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；
示例代码: airlink.start(airlink.MODE_SPI_SLAVE)；

3.2 airlink.MODE_SPI_MASTER

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

3.3 airlink.MODE_UART

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

3.4 airlink.CONF_SPI_ID

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

3.5 airlink.CONF_SPI_CS

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

3.6 airlink.CONF_SPI_RDY

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

3.7 airlink.CONF_SPI_IRQ

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

3.8 airlink.CONF_SPI_SPEED

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

3.9 airlink.CONF_IRQ_TIMEOUT

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

3.10 airlink.CONF_UART_ID

常量含义：UART配置参数，设置UART的ID；
数据类型：number；
示例代码: 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()

功能

打印统计信息；

D/airlink 统计信息 收发总包 0 0 0 0
D/airlink 统计信息 发送IP包 0 0 0 0
D/airlink 统计信息 发送IP字节 0 0 0 0
D/airlink 统计信息 接收IP包 0 0 0 0
D/airlink 统计信息 接收IP字节 0 0 0 0
D/airlink 统计信息 等待从机 0
D/airlink 统计信息 Task超时事件 0
D/airlink 统计信息 Task新数据事件 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())

4.12 airlink.ping(data, timeout_ms)

功能

发起异步 ping 操作，用于测试 Airlink 通信链路质量，测量往返延迟（RTT）；

结果通过订阅 AIRLINK_PING_RESULT 事件接收；

支持版本：

8000系列、Air780EXX系列需要大于V2034版本；8101系列需要大于V2014版本；1601/1602系列需要大于V1014版本

参数

data

参数含义：要回显的 payload 数据；
数据类型：string 或 zbuff；
取值范围：最大 256 字节，可为空字符串；
是否必选：可选；
注意事项：nil 或不传则发送空 payload；
参数示例："hello"；

timeout_ms

参数含义：超时时间（毫秒）；
数据类型：number；
取值范围：正整数；
是否必选：可选；
注意事项：默认值为 3000 毫秒；
参数示例：5000；

返回值

local reqid = airlink.ping("hello", 3000)

reqid

含义说明：请求标识（pkgid），用于匹配响应；
数据类型：number；
取值范围：无；
注意事项：失败时返回 nil；
返回示例：1；

事件响应

通过 sys.subscribe("AIRLINK_PING_RESULT", callback) 订阅结果事件：

sys.subscribe("AIRLINK_PING_RESULT", function(id, ok, v1, v2)
    -- id: 请求标识，与 airlink.ping 返回值对应
    -- ok: 是否成功（true/false）
    -- v1: 成功时为 RTT（毫秒），失败时为错误信息（"timeout" 或错误码）
    -- v2: 成功时为 echo 数据，失败时为 nil
end)

示例

local reqid = airlink.ping("hello", 3000)
if reqid then
    log.info("ping", "发起请求", reqid)
else
    log.info("ping", "发起失败")
end

sys.subscribe("AIRLINK_PING_RESULT", function(id, ok, v1, v2)
    if id ~= reqid then return end
    if ok then
        log.info("ping", "成功", "rtt=" .. v1 .. "ms", "echo=" .. v2)
    else
        log.info("ping", "失败", v1)
    end
end)

回调参数映射说明

回调函数 function(id, ok, v1, v2) 的参数取值如下：

ok	v1	v2	含义
`true`	RTT 毫秒数（number）	echo 数据（string）	成功
`false`	`"timeout"`（string）	`nil`	超时
`false`	`-2`（number）	`nil`	资源错误（内存/信号量/槽位满）
`false`	`-3`（number）	`nil`	发送失败
`false`	`-4`（number）	`nil`	响应格式错误

注意：v1 可能是字符串（仅 "timeout"）或数字（错误码），使用时需注意类型判断。

五、产品支持说明

不同产品的LuatOS固件，对airlink核心库的支持情况如下：

1、Air780EX2/Air700ECP/Air780EPM/Air780EGP 1号固件仅支持spi从机模式，7号固件spi主机和从机模式，8号固件支持spi主机和从机、uart模式；

2、Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN/Air8000系列所有固件都支持；

3、Air8101系列所有固件都支持；

4、Air1601 / Air1602 都支持；

各产品固件支持核心库列表详细说明参考下面链接：

Air780EX2/Air700ECP/Air780EPM/Air780EGP固件支持列表

Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN固件支持列表

Air8000系列所有型号固件支持列表

Air8101系列所有型号固件支持列表

Air1601/Air1602固件支持列表