03 远程固件升级服务(第三方服务器)
作者：孟伟
一、FOTA 概述
FOTA 即远程升级功能，此功能可以让客户在不方便大量线刷升级(设备不在身边/量产 PCB 没引出 USB/需要大批量进行功能升级)的情况下，快速进行底层固件/脚本/脚本 + 底层固件的远程更新。
LuatOS 开发模式下，固件分为两部分：core 和 script
远程升级时：升级 script 和 core+script 为全量覆盖升级
远程升级时：可以仅升级 script；也可以仅升级 core，也可以同时升级 core+script
支持合宙 iot 平台升级和自建第三方服务器(HTTP)升级
二、演示功能概述
上一篇文章讲了使用合宙 IOT 云平台进行 OTA 的三种场景，另外此教程演示了自建服务器的三种升级相关场景：
(1) 使用自建服务器升级，演示最简单的升级逻辑。
(2) 使用自建服务器升级，通过tcp下发升级指令控制设备升级，指令格式使用json字符串，包含版本、url、是否升级参数，演示如何通过服务器控制下发指令去升级。
(3) 休眠状态下升级，此场景是针对psm状态下升级没完成就进入休眠导致升级失败的情况写的一个例子。
三、准备硬件环境
1、Air8101 核心板一块
2、TYPE-C USB 数据线一根
3、Air8101 核心板和数据线的硬件接线方式为
- Air8101 核心板通过 TYPE-C USB 口供电；（核心板背面的功耗测试开关拨到 OFF 一端）
- 如果测试发现软件频繁重启，重启原因值为：poweron reason 0，可能是供电不足，此时再通过直流稳压电源对核心板的 vbat 管脚进行 4V 供电，或者 VIN 管脚进行 5V 供电；
- TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；
4、可选 AirPHY_1000 配件板一块，Air8101 核心板和 AirPHY_1000 配件板的硬件接线方式为:
6、可选 AirETH_1000 配件板一块，Air8101 核心板和 AirETH_1000 配件板的硬件接线方式为:
四、软件环境
在开始实践本示例之前，先筹备一下软件环境：
- Luatools 工具；
- Air8101 V1006 版本固件（理论上，2025 年 7 月 26 日之后发布的固件都可以）；
- LuatOS 需要的脚本和资源文件
脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8101/demo/fota2/self_server
准备好软件环境之后，接下来查看如何烧录项目文件到 Air8101 核心板，将本篇文章中演示使用的项目文件烧录到 Air8101 核心板中。
4.为了方便测试，合宙提供了免费的不可商用的 TCP/UDP web 测试工具：合宙 TCP/UDP web 工具 (luatos.com)
五、API 接口说明
六、合宙自有服务器 FOTA
FOTA 有多种方式，可以使用合宙的 iot 平台进行升级，也可以使用用户自建平台升级，可以只升级 core，可以只升级用户脚本，也可以 core+ 脚本一起升级，接下来先介绍合宙自有服务器升级，第三方升级在下一篇文章中介绍。
6.1 网卡切换
fota 功能需要联网去下载升级包，所以需要选择一种联网方式：
netdrv_device：配置连接外网使用的网卡，目前支持以下五种选择（五选一）
(1) netdrv_wifi：WIFI STA 网卡
(2) netdrv_eth_spi：通过 SPI 外挂 CH390H 芯片的以太网卡
(3) netdrv_eth_rmii：通过 MAC 层的 rmii 接口外挂 PHY 芯片（LAN8720Ai）的以太网卡
(4) netdrv_4g：通过 SPI 接口外挂 4G 模组(Air780EHM/Air780EHV/Air780EGH/Air780EPM)的 4G 网卡
(5) netdrv_multiple：多网卡驱动模块，支持以上四种网卡，可以配置四种网卡的优先级
在 netdrv_device.lua 文件中选择一种使用即可。
6.2 云平台配置
每一家的云平台都不一样，但是本质上都一样，都是给模块下发正确的升级文件。建议平台做一些验证，比如 imei 验证、版本号验证，循环请求验证，这样能够有效的避免因为升级包下载不对导致的模块循环升级，不跑代码其他逻辑，引起的假死机现象。
6.3 升级包制作并上传
自建服务器可以使用此服务器来做测试：http://airtest.openluat.com/download ，该服务器只能上传文件，上传后可以获得一个下载链接，复制的链接用作自建服务器的 url。
所以我们在最开始先要生成一个链接，步骤如下：在进行脚本改动前，需要在你的电脑上随便生成一个.bin 后缀，大小不为 0 的文件(可以随便往里面写点什么)，然后将这个 bin 文件上传到模块请求的地址去，目的是为了获取升级的 url。
比如我的 bin 文件升级 url 为”http://airtest.openluat.com:2900/download/FOTA2_DEMO_1006.001.001_LuatOS-SoC_Air8101.bin“
6.3.1 旧版本本地烧录
1.脚本中修改 url 为自己的升级 url，然后打开 luatools 的项目管理界面，点击生成量产文件，默认放在 luatools 根目录下的"SOC 量产及远程升级文件\Air8000"目录下
注：一定要注意 url 前的"###"标志位，如果不加###，模块进行 HTTP 请求时，会在请求头里加上 version、project_key,imei,firmware_name 等参数
修改好升级的 url 后，将固件和脚本烧录到模组中，烧录教程可看这里如何烧录项目文件到 Air8101 核心板。
6.3.2 新版本软件升级包制作并上传
1、因为模块烧录的是 001.000.000 版本，所以我们需要给脚本里的版本号改一下，改为 001.000.001 版本
2、可以适当的加一些逻辑代码，单纯演示的话修改 VERSION 也可以看作脚本升级，然后把固件版本从 v1004 换成 v1006。然后生成一次量产固件：
3、生成的文件如下：
其中 full_fota 文件夹下为 core+script 的全量升级包，script_ota 目录下是单脚本升级的升级包，8101 的固件升级为全量升级，不需要差分。
4、然后将升级包上传到自建服务器平台，如果仅升级脚本，就选择 script_ota 目录下的文件，如果是要升级固件和脚本，就选择 full_fota 目录下的。
6.4 示例结果展示
本 demo 将会演示三种场景下的 fota 升级，场景在 main.lua 中切换。
6.4.1 场景一：fota 升级简单演示
主要代码如下：
-- 升级结果的回调函数
-- 功能:获取fota的回调函数
-- 参数:
-- result:number类型
-- 0表示成功
-- 1表示连接失败
-- 2表示url错误
-- 3表示服务器断开
-- 4表示接收报文错误
-- 5表示使用iot平台VERSION需要使用 xxx.yyy.zzz形式
local function fota_cb(ret)
log.info("fota", ret)
if ret == 0 then
log.info("升级包下载成功,重启模块")
rtos.reboot()
elseif ret == 1 then
log.info("连接失败", "请检查url拼写或服务器配置(是否为内网)")
elseif ret == 2 then
log.info("url错误", "检查url拼写")
elseif ret == 3 then
log.info("服务器断开", "检查服务器白名单配置")
elseif ret == 4 then
log.error("FOTA 失败",
"原因可能有：\n" ..
"1) 服务器返回 200/206 但报文体为空(0 字节）—— 通常是升级包文件缺失或 URL 指向空文件；\n" ..
"2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效；\n"..
"3) 已经是最新版本，无需升级" )
elseif ret == 5 then
log.info("版本号书写错误", "iot平台版本号需要使用xxx.yyy.zzz形式")
else
log.info("不是上面几种情况 ret为", ret)
end
end
-- 使用第三方服务器，配置ota_opts参数
--[[
-- opts参数说明, 所有参数都是可选的
-- 1. opts.url string 升级所需要的URL, 若使用合宙iot平台,则不需要填
-- 2. opts.version string 版本号, 默认是 BSP版本号.x.z格式
-- 3. opts.timeout int 请求超时时间, 默认300000毫秒,单位毫秒
-- 4. opts.project_key string 合宙IOT平台的项目key, 默认取全局变量PRODUCT_KEY. 自建服务器不用填
-- 5. opts.imei string 设备识别码, 默认取IMEI(Cat.1模块)或WLAN MAC地址(wifi模块)或MCU唯一ID
-- 6. opts.firmware_name string 固件名称,默认是 _G.PROJECT.. "_LuatOS-SoC_" .. rtos.bsp()
-- 7. opts.server_cert string 服务器证书, 默认不使用
-- 8. opts.client_cert string 客户端证书, 默认不使用
-- 9. opts.client_key string 客户端私钥, 默认不使用
-- 10. opts.client_password string 客户端私钥口令, 默认不使用
-- 11. opts.method string 请求方法, 默认是GET
-- 12. opts.headers table 额外添加的请求头,默认不需要
-- 13. opts.body string 额外添加的请求body,默认不需要
]]
local opts = {
url = "###http://airtest.openluat.com:2900/download/FOTA2_DEMO_2012.001.001_LuatOS-SoC_Air8000.bin",
-- 合宙IOT平台的默认升级URL, 不填就是这个默认值
-- 如果是自建的OTA服务器, 则需要填写正确的URL, 例如 http://192.168.1.5:8000/update
-- 如果自建OTA服务器,且url包含全部参数,不需要额外添加参数, 请在url前面添加 ###
-- 如果不加###，则默认会上传如下参数
-- 1. opts.version string 版本号, 默认是 BSP版本号.x.z格式
-- 2. opts.timeout int 请求超时时间, 默认300000毫秒,单位毫秒
-- 3. opts.project_key string 合宙IOT平台的项目key, 默认取全局变量PRODUCT_KEY. 自建服务器不用填
-- 4. opts.imei string 设备识别码, 默认取IMEI(Cat.1模块)或WLAN MAC地址(wifi模块)或MCU唯一ID
-- 5. opts.firmware_name string 底层版本号
-- 请求的版本号, 合宙IOT有一套版本号体系,不传就是合宙规则, 自建服务器的话当然是自行约定版本号了
-- version = ""
-- 其他更多参数, 请查阅libfota2的文档 https://wiki.luatos.com/api/libs/libfota2.html
}
function fota_task_func()
-- 如果当前时间点设置的默认网卡还没有连接成功，一直在这里循环等待
while not socket.adapter(socket.dft()) do
log.warn("fota_task_func", "wait IP_READY", socket.dft())
-- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
-- 或者等待1秒超时退出阻塞等待状态;
-- 注意：此处的1000毫秒超时不要修改的更长；
-- 因为当使用libnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
-- 当libnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
-- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- 检测到了IP_READY消息
log.info("fota_task_func", "recv IP_READY", socket.dft())
----这个判断是提醒要设置url的,且不要使用本文中的测试服务器,实际生产请删除
-- if not opts.url or string.find(opts.url,"airtest.openluat.com") then
-- while 1 do
-- sys.wait(1000)
-- log.info("fota", "当前URL",opts.url,"请修改正确的url")
-- end
-- end
log.info("开始检查升级")
libfota2.request(fota_cb, opts)
end
--创建并且启动一个task
--运行这个task的主函数fota_task_func
sys.taskInit(fota_task_func)
-- 演示定时自动升级, 每隔4小时自动检查一次
sys.timerLoopStart(libfota2.request, 4 * 3600000, fota_cb, opts)
升级中：模块请求升级，下载完升级包以后会重启程序，然后等待升级完成开机
升级后：升级成功后按我们之前的脚本，每隔 5S，打印一次"降功耗,找合宙"以及当前脚本版本号，可以看出，当前版本号已经由原来的 001.000.000 变为了 001.000.001，固件版本从 1004 变为 1006。
6.4.2 场景二：tcp 服务器下发升级指令
通过 tcp 服务器下发升级指令（指令格式使用 json 字符串，包含是否升级参数），控制设备使用 fota 功能模块。此场景下，设备会先连接到 TCP 服务器，等待服务器下发升级指令。在 air_srv_fota.lua 中会有一个参数控制，防止升级过程中重复下载升级包。
合宙测试服务器链接：https://netlab.luatos.com/ ，打开一个 tcp 服务器，
在 tcp_self_main.lua 中配置 tcp 服务器信息：
升级前：设备连接到 TCP 服务器，等待指令下发：{"fota": "true", "url": "###http://airtest.openluat.com:2900/download/FOTA2_DEMO_1006.001.001_LuatOS-SoC_Air8101.bin"}
升级中：模组收到服务器下发的升级指令后，设备开始下载升级包并进行验证：
升级后：升级包下载完成后设备重启升级，并循环打印新的版本号信息
6.4.3 场景三：psm 低功耗 fota
此场景是防止 psm 状态下升级没完成就进入休眠导致升级失败的情况写的一个例子。需要注意的是要等待升级成功后再去进入休眠。
主要代码如下：
-- 升级结果的回调函数
-- 功能:获取fota的回调函数
-- 参数:
-- result:number类型
-- 0表示成功
-- 1表示连接失败
-- 2表示url错误
-- 3表示服务器断开
-- 4表示接收报文错误
-- 5表示使用iot平台VERSION需要使用 xxx.yyy.zzz形式
local function fota_cb(ret)
log.info("fota", ret)
--升级结束，触发升级回调，发布消息升级结束，可以进入休眠模式
sys.publish("FOTA_END")
if ret == 0 then
log.info("升级包下载成功,重启模块")
rtos.reboot()
elseif ret == 1 then
log.info("连接失败", "请检查url拼写或服务器配置(是否为内网)")
elseif ret == 2 then
log.info("url错误", "检查url拼写")
elseif ret == 3 then
log.info("服务器断开", "检查服务器白名单配置")
elseif ret == 4 then
log.error("FOTA 失败",
"原因可能有：\n" ..
"1) 服务器返回 200/206 但报文体为空(0 字节）—— 通常是升级包文件缺失或 URL 指向空文件；\n" ..
"2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效；\n"..
"3) 已经是最新版本，无需升级" )
elseif ret == 5 then
log.info("版本号书写错误", "iot平台版本号需要使用xxx.yyy.zzz形式")
else
log.info("不是上面几种情况 ret为", ret)
end
end
-- 使用合宙iot平台进行升级, 支持自定义参数, 也可以不配置，如果要配置参数可以参考此链接https://docs.openluat.com/osapi/ext/libfota2/
local opts = {
url = "###http://airtest.openluat.com:2900/download/FOTA2_DEMO_2012.001.001_LuatOS-SoC_Air8000.bin",
-- 合宙IOT平台的默认升级URL, 不填就是这个默认值
-- 如果是自建的OTA服务器, 则需要填写正确的URL, 例如 http://192.168.1.5:8000/update
-- 如果自建OTA服务器,且url包含全部参数,不需要额外添加参数, 请在url前面添加 ###
-- 如果不加###，则默认会上传如下参数
-- 1. opts.version string 版本号, 默认是 BSP版本号.x.z格式
-- 2. opts.timeout int 请求超时时间, 默认300000毫秒,单位毫秒
-- 3. opts.project_key string 合宙IOT平台的项目key, 默认取全局变量PRODUCT_KEY. 自建服务器不用填
-- 4. opts.imei string 设备识别码, 默认取IMEI(Cat.1模块)或WLAN MAC地址(wifi模块)或MCU唯一ID
-- 5. opts.firmware_name string 底层版本号
-- 请求的版本号, 合宙IOT有一套版本号体系,不传就是合宙规则, 自建服务器的话当然是自行约定版本号了
-- version = ""
-- 其他更多参数, 请查阅libfota2的文档 https://wiki.luatos.com/api/libs/libfota2.html
}
function psm_fota_task_func()
-- 如果是被定时器唤醒，因为上次进入PSM+时是开启了飞行模式，所以在唤醒后第一时间关闭飞行模式。
mobile.flymode(0, false)
log.info("开始测试PSM+模式功耗。")
-- 如果当前时间点设置的默认网卡还没有连接成功，一直在这里循环等待
while not socket.adapter(socket.dft()) do
log.warn("fota_task_func", "wait IP_READY", socket.dft())
-- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
-- 或者等待1秒超时退出阻塞等待状态;
-- 注意：此处的1000毫秒超时不要修改的更长；
-- 因为当使用libnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
-- 当libnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
-- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- 检测到了IP_READY消息
log.info("fota_task_func", "recv IP_READY", socket.dft())
log.info("开始检查升级")
libfota2.request(fota_cb, opts)
-- 打印版本号, 方便看版本号变化, 非必须
log.info("fota", "脚本版本号", VERSION, "core版本号", rtos.version())
-- 等待下载升级包结束, 发布消息"FOTA_END",
-- 如果15秒内没有收到消息，则15秒的时长到达后进入PSM+模式。
-- 需要注意的是在fota_cb回调函数中，升级包下载成功后，会立马重启并升级模组。如果还有其他事情要做不想立马重启升级,需自行决定reboot的时机
-- 升级包下载成功后，本demo默认是立即自动重启并且将升级包更新到模组中，更新成功后，会再次走到这里
-- 再次走到这里后，合宙iot平台会返回“已经是最新版本，不需要升级”，fota_cb回调函数中会发布消息"FOTA_END"
-- 至此，才会继续向下执行代码，进入PSM+模式
sys.waitUntil("FOTA_END", 15000)
log.info("升级结束,进入PSM模式")
-- 关闭gps备电以及gsensor供电使能，防止休眠模式下漏电导致功耗增加
gpio.close(24)
-- 定时检查升级 (每4小时唤醒一次)
pm.dtimerStart(2, 4 * 3600000)
-- 启动飞行模式，规避可能会出现的网络问题
mobile.flymode(0, true)
-- 进入PSM模式
pm.power(pm.WORK_MODE, 3)
-- 防御机制：15秒后如果未进入PSM则重启
sys.wait(15000)
log.info("进入PSM+失败,重启")
rtos.reboot()
end
sys.taskInit(psm_fota_task_func)
升级前：设备会在开机的时候去请求下配置的 url 的升级包，定期唤醒检查是否有升级任务
在此过程中模组会保持唤醒状态并等待升级包下载成功并校验通过，以及检查版本是否一致。如果版本不一致或升级包检验没通过则进入休眠等待下次唤醒检查升级包。没问题的话升级包下载成功后会重启并升级，升级流程如下：
升级后：升级完成后设备显示新的版本号，并重新去请求升级包，没有新的升级包则会进入 PSM 状态
七、常见问题与注意事项
7.1 注意事项：
1、 版本号格式：使用合宙 IoT 平台时，项目的 VERSION 必须为 xxx.yyy.zzz 的三段数字格式（如 "001.000.001"），否则平台版本比对可能出错。
2、PRODUCT_KEY：使用合宙 IoT 平台时，必须在 main.lua 中正确定义全局变量 PRODUCT_KEY，其值需从 IoT 平台的项目中获取。
3、重启时机：下载升级包成功（result 为 0）后，通常需要调用 rtos.reboot() 重启设备以更新。你可以根据需要延迟重启。
4、自建服务器规则：
需要升级时，服务器应返回 HTTP 200，消息体为升级文件内容。
无需升级时，服务器应返回 HTTP 300 或以上的状态码。
5、固件类型：使用合宙 IoT 平台进行脚本升级时，使用 Luatools 生成的 .bin 量产文件。
7.2 为什么升级后我的模块没有任何反应了，像是变砖一样
有多种可能，
7.2.1 检查脚本
首先先检查下用户自己的脚本，有可能是引起重启/死机的代码写在了最前面，例如新加的某个值或者函数为 nil 但是还是去做了些加减乘除或者判断大小的逻辑。可以直接本地烧录下新版本的 core+ 脚本验证，如果有 fskv 等用到 flash 的代码，可能需要仔细检查才能排除问题，比如下载的时候勾选如下图所示的两个选项。
7.2.2 检查 core
如果是仅脚本升级，但是没注意使用了新 core 中才有的接口，就有可能引起循环重启，如果重启在代码最开头，模块可能来不及打印任何日志就重启了，可以直接本地烧录下新版本的 core+ 脚本验证，如果有 fskv 等用到 flash 的代码，可能需要仔细检查。
7.3 检查过脚本和 core，没问题，为什么会循环升级 6 次以后禁止升级
检查下升级包是否正常，有时候因为人员误操作，经常会出现旧脚本 + 新 core 或者新脚本 + 旧 core 的意外组合，
例如：
本来应该如下表描述的一样
操作人员失误后变成了如下
然后误操作旧版本(1) 和误操作新版本(1)进行差分，这样虽然脚本版本号旧版本大于了新版本，但是 core 的旧版本小于新版本，所以升级平台依旧认为是依次有效的升级，下发了升级包。
升级完成后，模块内部脚本版本号变成了 001.000.000 core 版本号为 V2008，下次模块请求升级的时候，当前固件上报的脚本版本号(001.000.000)依旧小于云平台存储的脚本版本号(001.000.001)，然后继续下发升级包，就这么循环 6 次，然后触发合宙 iot 平台的禁止升级规则
在正确生成差分包，并且上传成功后，可以在 iot 平台里解除禁止升级的限制
在"我的设备"中选择升级 imei 所在的项目，然后点击右边的"解除禁止升级"，
确定“导致设备循环升级的异常”已经处理完成后，点击确定解除，即可解除限制升级
7.4 我想在服务器发送特定的字符串如"update"时再触发升级，应该怎么做
只需要在你希望的升级升级逻辑后面加上升级语句即可，例如 mqtt 的 demo 里增加几句话
elseif event == "recv" then
libfota2 = require "libfota2"
log.info("mqtt", "downlink", "topic", data, "payload", payload)
--假定mqtt发过来的字符串为"update"就启动升级
if payload =="update" then
libfota2.request(fota_cb, ota_opts)
end
sys.publish("mqtt_payload", data, payload)
又或者希望按键升级：
--这里假定使用GPIO0进行按键升级
gpio.debounce(0, 3000, 1)
gpio.setup(0, function()
libfota2.request(fota_cb, ota_opts)
end, gpio.PULLUP)