02 FOTA(合宙iot平台远程固件升级)
作者：孟伟
一、FOTA 概述
FOTA 即远程升级功能，此功能可以让客户在不方便大量线刷升级(设备不在身边/量产 PCB 没引出 USB/需要大批量进行功能升级)的情况下，快速进行底层固件/脚本/脚本 + 底层固件的远程更新。
LuatOS 开发模式下，固件分为两部分：core 和 script
远程升级时：core 为差分升级；script 为全量覆盖升级
远程升级时：可以仅升级 script；可以仅升级 core；也可以同时升级 core+script
AIR8000 支持合宙 iot 平台升级和自建第三方服务器(HTTP)升级
二、演示功能概述
本文将详细讲述如何使用合宙 iot 服务器进行远程升级。另外此教程会演示了三种场景：
(1) fota 升级简单演示：使用合宙 iot 服务器进行远程升级功能模块，简单升级演示；
(2) tcp 服务器下发升级指令：通过 tcp 服务器下发升级指令（指令格式使用 json 字符串，包含是否升级参数），控制设备使用 fota 功能模块；
(3) psm 低功耗 fota：低功耗 fota 功能模块，此场景是针对 psm 状态下升级没完成就进入休眠导致升级失败的情况写的一个示例。
三、准备硬件环境
参考：硬件环境清单第二章节内容，准备以及组装好硬件环境。
3.1 Air8000 核心板
本次使用的开发板为 Air8000 核心板，如下图所示：
点击链接购买：Air8000 核心板淘宝购买链接 ；
此开发板的详细使用说明参考：Air8000 核心板资料链接 。
3.2 SIM 卡
请准备一张可正常上网的 SIM 卡，该卡可以是物联网卡或您的个人手机卡。
特别提醒：请确保 SIM 卡未欠费且网络功能正常，以便顺利进行后续操作。
将 SIM 卡插入开发板卡槽中，用 USB 数据线连接开发板与电脑。
四、软件环境
在开始实践本示例之前，先筹备一下软件环境：
- Luatools 工具；
- 内核固件文件（底层 core 固件文件）：LuatOS-SoC_V2014_Air8000；参考项目使用的内核固件；
- luatos 需要的脚本和资源文件
脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8000/demo/fota2
准备好软件环境之后，接下来查看如何烧录项目文件到 Air8000 核心板，将本篇文章中演示使用的项目文件烧录到 Air8000 核心板中。
五、API 接口说明
六、合宙自有服务器 FOTA
FOTA 有多种方式，可以使用合宙的 iot 平台进行升级，也可以使用用户自建平台升级，可以只升级 core，可以只升级用户脚本，也可以 core+ 脚本一起升级，接下来先介绍合宙自有服务器升级，第三方升级在下一篇文章中介绍
6.1 网卡切换
fota 功能需要联网去下载升级包，所以需要选择一种联网方式：
netdrv_device：配置连接外网使用的网卡，目前支持以下四种选择（四选一）
(1) netdrv_4g：4G 网卡
(2) netdrv_wifi：WIFI STA 网卡
(3) netdrv_eth_spi：通过 SPI 外挂 CH390H 芯片的以太网卡
(4) netdrv_multiple：支持以上三种网卡，可以配置三种网卡的优先级
在 netdrv_device.lua 文件中选择一种使用即可。
6.2 云平台配置
使用合宙iot服务器的话，需要先登录合宙 IOT 平台，如下图所示，没有账号的，可以先注册一个 客户向合宙采购 4G 模块时，如果采购人员没有告知合宙这批模块放在 iot.openluat.com 上的哪个产品下，则合宙会以采购人的手机号为账号，默认密码 888888，创建一个“合宙标准模块”的项目，此次采购的所有模块都会放在这个项目下，如果你的账号下没有对应 imei，可以联系合宙销售帮忙添加模块进对应项目下(最好还是从哪里买的模块，就让他给你转移到你自己名下)
如果不在自己账号下，也可以通过烧录专属固件的方法，把模块归属到您指定的项目下，可以通过点击帮助中心，查看详细说明。
登录以后点击红框所示位置
然后依次点击如下图所示红框所示的地方，创建一个新项目
在所有项目的最后，找到自己刚刚新建的项目，并且点击红框内的"查看/点击复制"复制后面升级所需要的校验码，复制到自己剪切板中
至此，合宙云平台上的预备动作就做完了
6.3 升级包制作并上传
6.3.1 单脚本升级
如果用户只是新增一些自己的脚本逻辑，没有更新底层，可以选择仅脚本升级
1.打开 luatools 的项目管理界面，点击生成量产文件，Air8000 的纯脚本升级文件放在 luatools 根目录下的"SOC 量产及远程升级文件\Air8000"目录下
2.因为模块烧录的是 001.000.000 版本，所以我们需要给脚本里的版本号改一下，改为 001.000.001 版本
3.再将脚本中增加几行打印(为了模拟用户修改脚本的动作)
4.然后重新生成一次量产固件
5.打开刚刚的合宙 iot 平台点击我的项目--固件列表--创建固件
6.点击选择文件，把刚刚的 bin 后缀文件上传到 iot 平台
7.文件名、固件名、版本号都是自动识别的，用户无需修改。点击提交，等待上传成功的动画提示
8.模块刚开机，luatools 会打印模块的 imei 号，当然也可以使用手机扫描模块上的二维码获得模块 imei 号，或者将模块屏蔽盖上二维码的下方第一排模块的 imei 号，记录下来。在刚刚创建固件的地方，下拉，找到刚刚创建的升级任务，然后按下图所示，添加模块的 imei
6.3.2 含 core 升级
注意：对于不同后缀的固件，不能直接升级，分区有差异，强行升级可能无法启动。 比如：LuatOS-SoC_V2012_Air8000_1.soc 只能升级LuatOS-SoC_V2014_Air8000_1.soc 后缀的固件，不能升级 LuatOS-SoC_V2014_Air8000_2.soc 后缀的固件。
每一次 core 的升级都会带来一些网络上的优化(例如信号差时的网络稳定性)以及一些 bug 修复，所以在发布新版本以后，用户可以先测试下 core 对自己脚本有无明显影响或性能提升，然后进行远程 FOTA
1.这里选择升级到 2012 的 core 版本进行演示，001.000.000 脚本选择搭配的 core 为 V2010 版本，再次点击"生成量产文件"，稍等即可在 luatools 根目录下的"SOC 量产及远程升级文件\Air8000"目录下，找到 core 版本号为 V2010 且脚本版本号为 001.000.001 的 soc 后缀文件
2.
生成了这个版本以后，再去脚本中改动脚本版本号为 001.000.002(只要前后两位有一位大于 1 即可(当然第一位大于 1 的时候，整个版本号自然大于 001.000.001)，如 002.000.200,001.000.002,030.000.311 等)
脚本版本号分为 A.B.C 三段；
因为历史原因，中间这一段 B 没有任何意义，但是必须存在；
假设旧的脚本版本号为 A1.B1.C1，新的脚本版本号为 A2.B2.C2；
当新旧脚本版本号满足以下任何一种条件时，版本号允许升级：
7.
然后在 luatools 里重新选择 core 为 V2012 版本，同样点击生成固件，稍等即可在在 luatools 根目录下的"SOC 量产及远程升级文件\Air8000"目录下，找到 core 版本号为 V2008 且脚本版本号为 001.000.002 的 soc 后缀文件
8.接下来就是针对这两个量产文件，制作一个差分文件，用来远程升级(注：远程升级中 core 为差分，脚本为全量升级)
点击到 luatools 的主界面，依次点击图中蓝框所示意的地方(注：必须使用 luatools_3.0.9 及其以上版本，要不差分包升级的时候可能会出问题)
9.按下图所示选择低版本以及高版本的固件，然后点击开始执行即可，如果不想输出的差分包在 luatools 根目录下，可以自行选择一个输出路径
因为包含了 core 中的改动，所以时间会稍长一些，luatools 可能会出现"假死"情况，不要关闭它，稍等一会即可看到
11.同样，在你选择的目录下看到如下所示，带着脚本的 PROJECT core 版本号 脚本版本号的 bin 后缀的差分文件。
12.至于 iot 平台的配置还是和上文一样的步骤，先在项目底下创建固件-> 上传差分包-> 配置要升级设备的 imei
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
-- 使用合宙iot平台进行升级, 支持自定义参数, 也可以不配置，如果要配置参数可以参考此链接https://docs.openluat.com/osapi/ext/libfota2/
local ota_opts = {}
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())
-- 这个判断是提醒要设置PRODUCT_KEY的,实际生产请删除
if "123" == _G.PRODUCT_KEY then
while 1 do
sys.wait(1000)
log.info("fota", "请修改正确的PRODUCT_KEY")
end
end
log.info("开始检查升级")
libfota2.request(fota_cb, ota_opts)
end
--创建并且启动一个task
--运行这个task的主函数fota_task_func
sys.taskInit(fota_task_func)
升级前：因为 iot 平台没有升级固件，所以请求升级的结果为"已是最新版本"，每隔 3S 会打印当前版本信息，然后会有如下日志：
I/user.已是最新版本 1.设备的固件/脚本版本高于或等于云平台上的版本号 2.用户项目升级配置中未添加该设备 3.云平台升级配置中，是否升级配置为否
I/user.fota 4
E/user.FOTA 失败 原因可能有：
1) 服务器返回 200/206 但报文体为空(0 字节）—— 通常是升级包文件缺失或 URL 指向空文件；
2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效；
3) 已经是最新版本，无需升级
升级中：模块请求升级，下载完升级包以后会进行 MD5 验证升级包有无问题，如果没问题，就会启动重启程序，然后进行升级工作
升级后：升级成功后可以看到当前脚本版本号，已经由原来的 001.000.000 变为了 001.000.001。底层 core 版本号从 2010 变为了 2012
注意：升级完成以后，因为脚本中开机有联网就去请求一次升级的代码，所以，会再去请求一次升级，因为没有更高的版本了，所以会上报"已是最新版本"
6.4.2 场景二：tcp 服务器下发升级指令
通过 tcp 服务器下发升级指令（指令格式使用 json 字符串，包含是否升级参数），控制设备使用 fota 功能模块。此场景下，设备会先连接到 TCP 服务器，等待服务器下发升级指令。在 air_srv_fota.lua 中会有一个参数控制，防止升级过程中重复下载升级包。
合宙测试服务器链接：https://netlab.luatos.com/ ，打开一个 tcp 服务器，
在 tcp_iot_main.lua 中配置 tcp 服务器信息：
升级前：设备连接到 TCP 服务器，等待指令下发：{"fota": "true"}
升级中：模组收到服务器下发的升级指令后，设备开始下载升级包并进行验证
升级后：升级包下载完成后设备重启升级，并循环打印新的版本号信息
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 ota_opts = {}
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, ota_opts)
-- 等待下载升级包结束, 发布消息"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)
升级前：设备会在开机的时候去请求下服务器有没有升级包，定期唤醒检查是否有升级任务
如果有升级包就会去升级。没有升级包的话就会显示如下日志：
I/user.已是最新版本 1.设备的固件/脚本版本高于或等于云平台上的版本号 2.用户项目升级配置中未添加该设备 3.云平台升级配置中，是否升级配置为否
I/user.fota 4
E/user.FOTA 失败 原因可能有：
1) 服务器返回 200/206 但报文体为空(0 字节）—— 通常是升级包文件缺失或 URL 指向空文件；
2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效；
3) 已经是最新版本，无需升级
升级中：如果检测到服务器有新的版本，设备会保持唤醒状态直到升级升级包下载成功，升级包下载成功后会重启并升级，升级流程如下
升级后：升级完成后设备显示新的版本号，并重新去请求升级包，没有新的升级包则会进入 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)