9 exfotawifi-Air8000内WiFi固件升级

作者：拓毅恒　|　最后修改：2026-03-11

一、概述

exfotawifi 扩展库是 LuatOS 提供的一个 WiFi 固件自动升级系统，专为 Air8000/8000A/8000W 等 Air8000 系列带 WiFi 功能的模组设计。它通过连接合宙官方升级服务器，自动检查、下载和更新最新版本的 WiFi 固件，确保设备始终运行在最佳状态。

你可以把它想象成一个简易的自动更新助手：

检查网络连接：确保设备已连接到互联网
获取版本信息：向服务器发送设备信息，获取最新固件版本
比较版本差异：自动对比本地固件与服务器固件版本
下载升级文件：支持断点续传，高效下载固件包
执行升级操作：安全地将新固件应用到设备上
最新版本检查：重启后，通过检查版本号来确认是否已经更新到最新版本

该库适用于需要定期更新 WiFi 固件以获取性能优化和新功能的设备场景中。

二、核心示例

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

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

3、更加完整和详细的 demo，请参考 LuatOS 仓库中各个产品目录下的 demo/fota_wifi

WiFi 自动升级系统

--[[
本核心示例的业务逻辑为：
1、创建并启动一个基础task，在task的任务处理函数内初始化WiFi自动升级系统；
2、调用exfotawifi.request()检查并执行WiFi固件升级；
3、根据返回结果判断升级是否成功；
]]

PROJECT = "wifi_auto_update"
VERSION = "001.000.000"

-- 在日志中打印项目名和项目版本号
log.info("main", PROJECT, VERSION)

-- 导入exfotawifi库
local exfotawifi = require "exfotawifi"

-- 创建WiFi升级任务
local function fota_wifi_task()
    -- 调用请求升级函数
    local result = exfotawifi.request()
    if result then
        log.info("exfotawifi", "升级文件写入WiFi芯片的fota区成功，即将开始执行升级操作")
    else
        log.info("exfotawifi", "升级文件写入WiFi芯片的fota区失败，无法执行升级操作")
    end
end

-- 启动WiFi自动更新任务
sys.taskInit(fota_wifi_task)

-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

三、常量详解

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

合宙LuatOS内核固件中定义的核心库常量，和此扩展库功能有关，所以也会放到本文描述。

"AIRLINK_SFOTA_DONE"（此功能正在开发中）

常量含义：WIFI升级完毕后底层发送的系统消息；
数据类型：string；
示例代码：
         local function update_done()
             sys.waitUntil("AIRLINK_SFOTA_DONE")
             log.info("fotawifi","WIFI下载完毕，开始重启")
             sys.wait(100)
             pm.reboot()
         end

四、函数详解

4.1 exfotawifi.request()

功能

Air8000 系列模组自动升级 WiFi 固件的核心函数，执行完整的升级流程，包括检查网络连接、获取服务器版本信息、比较版本差异、下载升级文件和执行升级操作。

注意事项

必须在 task 中运行
此函数会阻塞当前任务，直到升级流程完成或超时
确保设备已完成网络初始化并成功获取 IP（以太网、WiFi、4G 均可）
升级过程中请勿断电或重启设备，否则会升级失败，需要重新升级
升级成功后，建议重启设备以确保新固件正确加载
升级到自己期望的版本之后，后续如果没有必须解决的 bug 或者必须要支持的新功能，就没必要一直检测是否需要升级为最新版本

参数

无

返回值

local result = exfotawifi.request()

result

含义说明：升级文件是否写到WiFi芯片的fota区；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示升级任务执行成功，false表示升级任务执行失败；
         返回值代表将新版本的升级文件写到了WiFi芯片的fota区，并不是完全升级完毕；
         实际升级完毕要等底层打印系统消息"AIRLINK_SFOTA_DONE"后才是升级完毕（此功能当前正在开发中）；
返回示例：成功返回：true
         失败返回：false
         local result = exfotawifi.request()
         log.info("exfotawifi", "升级文件是否写到WiFi芯片的fota区:", result)

示例

local exfotawifi = require "exfotawifi"

local result = exfotawifi.request()
if result then
    log.info("exfotawifi", "升级文件写入WiFi芯片的fota区成功，即将开始执行升级操作")
else
    log.info("exfotawifi", "升级文件写入WiFi芯片的fota区失败，无法执行升级操作")
end

-- 可以添加如下操作，在下载完毕后会重启模组，将版本更新到最新（此功能当前正在开发中）
local function update_done()
    sys.waitUntil("AIRLINK_SFOTA_DONE")
    log.info("fotawifi","WIFI下载完毕，开始重启")
    sys.wait(100)
    pm.reboot()
end

五、产品支持说明

支持 LuatOS 开发的所有 Air8000/8000A/8000W 等 Air8000 系列带 WiFi 功能的产品。