远程固件升级服务(第三方服务器)

一、FOTA 概述

FOTA 即远程升级功能，此功能可以让客户在不方便大量线刷升级(设备不在身边/量产 PCB 没引出 USB/需要大批量进行功能升级)的情况下，快速进行单底层固件/单脚本/脚本 + 底层固件的远程更新。

LuatOS 开发模式下，固件分为两部分：core 和 script。

远程升级时：core 为差分升级；script 为全量覆盖升级。

远程升级时：可以仅升级 script；可以仅升级 core；也可以同时升级 core+script。

780EPM 支持合宙 iot 平台升级和自建第三方服务器(HTTP)升级。

二、演示功能概述

上一篇文章讲了使用合宙 IOT 云平台进行 OTA 的完整流程，本文将详细讲述如何使用自建服务器进行远程升级。

三、准备硬件环境

“古人云：‘工欲善其事，必先利其器。’在深入介绍本功能示例之前，我们首先需要确保以下硬件环境的准备工作已经完成。”

3.1 Air780EPM 开发板

本次使用的开发板为 Air780EPM 开发板，如下图所示：

点击链接购买：Air780EPM 开发板淘宝购买链接 ；

此开发板的详细使用说明参考：Air780EPM 开发板资料链接 。

3.2 SIM 卡

请准备一张可正常上网的 SIM 卡，该卡可以是物联网卡或您的个人手机卡。

特别提醒：请确保 SIM 卡未欠费且网络功能正常，以便顺利进行后续操作。

将 SIM 卡插入开发板卡槽中，用 USB 数据线连接开发板与电脑。

四、FOTA 软硬件参考

FOTA 和硬件基本无关，软件 API 参考 https://docs.openluat.com/air780epm/luatos/api/ext/libfota2/

五、准备软件环境

“凡事预则立，不预则废。”在详细阐述本功能示例之前，我们需先精心筹备好以下软件环境。

1. Luatools 工具；

2. 内核固件文件（底层 core 固件文件）：LuatOS-SoC_V2003_Air780EPM；参考项目使用的内核固件；

3. luatos 需要的脚本和资源文件

脚本和资源文件：https://gitee.com/openLuat/LuatOS-Air780EPM/tree/master/demo/fota2

lib 脚本文件：使用 Luatools 烧录时，勾选 添加默认 lib 选项，使用默认 lib 脚本文件；

准备好软件环境之后，接下来查看如何烧录项目文件到 Air780EPM 核心板，将本篇文章中演示使用的项目文件烧录到 Air780EPM 核心板中。

六、第三方服务器 FOTA 简介

FOTA 有多种方式，可以使用合宙的 iot 平台进行升级，也可以使用用户自建平台升级，可以只升级 core，可以只升级用户脚本，也可以 core+ 脚本一起升级，接下来介绍第三方服务器升级。

6.1 云平台配置

每一家的云平台都不一样，但是本质上都一样，都是给模块下发正确的升级文件。建议平台做一些验证，比如 imei 验证、版本号验证，循环请求验证，这样能够有效的避免因为升级包下载不对导致的模块循环升级，不跑代码其他逻辑，引起的假死机现象。

6.2 仅脚本升级简介

如果用户只是新增一些自己的脚本逻辑，没有更新底层，可以选择仅脚本升级。

6.2.1 仅脚本升级示例

在进行脚本改动前，需要在你的电脑上随便生成一个.bin 后缀，大小不为 0 的文件(可以随便往里面写点什么)，然后将这个 bin 文件上传到模块请求的地址去，目的是为了获取升级的 url。

比如我的 bin 文件升级 url 为"http://airtest.openluat.com:2900/download/780EPM_testota.bin"

这个文件里是乱码，没有其他东西，仅仅作为占位符存在，接下来开始修改代码。

-- LuaTools需要PROJECT和VERSION这两个信息
PROJECT = "fotademo"
-- iot限制，只能上传xxx.yyy.zzz格式的三位数的版本号，但实际上现在只用了XXX和ZZZ,中间yyy暂未使用
-- 需要注意的是,因为yyy不生效，所以111.222.333版本和111.444.333版本，对iot平台来说都一样，所以建议中间那一位永远写000
VERSION = "001.000.000"

-- 使用合宙iot平台时需要这个参数
PRODUCT_KEY = "123" -- 到 iot.openluat.com 创建项目,获取正确的项目id

sys = require "sys"
libfota2 = require "libfota2"

-- 联网函数, 可自行删减
sys.taskInit(function()
    -- 默认都等到联网成功
    sys.waitUntil("IP_READY")
    log.info("4G网络链接成功")
    sys.publish("net_ready")
end)

-- 循环打印版本号, 方便看版本号变化, 非必须
sys.taskInit(function()
    while 1 do
        sys.wait(5000)
        log.info("降功耗 找合宙")
        -- log.info("fota", "脚本版本号", VERSION)
        log.info("fota", "脚本版本号", VERSION, "core版本号", rtos.version())
    end
end)

-- 升级结果的回调函数
-- 功能:获取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.info("接收报文错误", "检查模块固件或升级包内文件是否正常")
    elseif ret == 5 then
        log.info("版本号书写错误", "iot平台版本号需要使用xxx.yyy.zzz形式")
    else
        log.info("不是上面几种情况 ret为", ret)
    end
end

-- 使用合宙iot平台进行升级,不需要管下面这段代码
-- 使用第三方服务器时打开下面这段代码
local ota_opts = {
    url = "###http://airtest.openluat.com:2900/download/780EPM_testota.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
}
sys.taskInit(function()
    ----这个判断是提醒要设置url的,且不要使用本文中的测试服务器,实际生产请删除
    if not ota_opts.url or string.find(ota_opts.url,"airtest.openluat.com") then
        while 1 do
            sys.wait(1000)
            log.info("fota", "当前URL",ota_opts.url,"请修改正确的url")
        end
    end
    -- 等待网络就行后开始检查升级
    sys.waitUntil("net_ready")
    log.info("开始检查升级")
    sys.wait(500)
    libfota2.request(fota_cb, ota_opts)
end)
-- 演示定时自动升级, 每隔4小时自动检查一次
sys.timerLoopStart(libfota2.request, 4 * 3600000, fota_cb, ota_opts)

-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!

打开 luatools 的项目管理界面，点击生成量产文件，780EPM 的纯脚本升级文件放在 luatools 根目录下的"SOC 量产及远程升级文件\Air780EPM"目录下

因为模块烧录的是 001.000.000 版本，所以我们需要给脚本里的版本号改一下，改为 001.000.001 版本

再在脚本中增加几行打印(为了模拟用户修改脚本的动作)

最后将 url 改成 bin 文件存放的地址:

注：一定要注意 url 前的"###"标志位，如果不加###，模块进行 HTTP 请求时，会在请求头里加上 version、project_key,imei,firmware_name 等参数

然后重新生成一次量产固件

找到这个文件以后，右键重命名成刚刚创建的 bin 文件同名

再将这个 bin 文件放在之前上传到服务器对应地点。可用此服务器作为测试用 http://airtest.openluat.com/download。

6.2.2 示例效果展示

升级中：模块请求升级，下载完升级包以后会进行 MD5 验证升级包有无问题，如果没问题，就会重启程序，然后进行升级工作。

升级后：升级成功后按我们之前的脚本，每隔 5S，打印当前脚本版本号和 core 版本号，可以看出，当前版本号已经由原来的 001.000.000 变为了 001.000.001。

6.3 含 core 升级简介

每一次 core 的升级都会带来一些网络上的优化(例如信号差时的网络稳定性)以及一些 bug 修复，所以在发布新版本以后，用户可以先测试下 core 对自己脚本有无明显影响或性能提升，然后进行远程 FOTA。

6.3.1 含 core 升级测试 demo

和 6.2 章节仅脚本升级的 demo 一样。

-- LuaTools需要PROJECT和VERSION这两个信息
PROJECT = "fotademo"
-- iot限制，只能上传xxx.yyy.zzz格式的三位数的版本号，但实际上现在只用了XXX和ZZZ,中间yyy暂未使用
-- 需要注意的是,因为yyy不生效，所以111.222.333版本和111.444.333版本，对iot平台来说都一样，所以建议中间那一位永远写000
VERSION = "001.000.000"

-- 使用合宙iot平台时需要这个参数
PRODUCT_KEY = "123" -- 到 iot.openluat.com 创建项目,获取正确的项目id

sys = require "sys"
libfota2 = require "libfota2"

-- 联网函数, 可自行删减
sys.taskInit(function()
    -- 默认都等到联网成功
    sys.waitUntil("IP_READY")
    log.info("4G网络链接成功")
    sys.publish("net_ready")
end)

-- 循环打印版本号, 方便看版本号变化, 非必须
sys.taskInit(function()
    while 1 do
        sys.wait(5000)
        log.info("降功耗 找合宙")
        -- log.info("fota", "脚本版本号", VERSION)
        log.info("fota", "脚本版本号", VERSION, "core版本号", rtos.version())
    end
end)

-- 升级结果的回调函数
-- 功能:获取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.info("接收报文错误", "检查模块固件或升级包内文件是否正常")
    elseif ret == 5 then
        log.info("版本号书写错误", "iot平台版本号需要使用xxx.yyy.zzz形式")
    else
        log.info("不是上面几种情况 ret为", ret)
    end
end

-- 使用合宙iot平台进行升级,不需要管下面这段代码
-- 使用第三方服务器时打开下面这段代码
local ota_opts = {
    url = "###http://airtest.openluat.com:2900/download/780EPM_testota.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
}
sys.taskInit(function()
    ----这个判断是提醒要设置url的,且不要使用本文中的测试服务器,实际生产请删除
    if not ota_opts.url or string.find(ota_opts.url,"airtest.openluat.com") then
        while 1 do
            sys.wait(1000)
            log.info("fota", "当前URL",ota_opts.url,"请修改正确的url")
        end
    end
    -- 等待网络就行后开始检查升级
    sys.waitUntil("net_ready")
    log.info("开始检查升级")
    sys.wait(500)
    libfota2.request(fota_cb, ota_opts)
end)
-- 演示定时自动升级, 每隔4小时自动检查一次
sys.timerLoopStart(libfota2.request, 4 * 3600000, fota_cb, ota_opts)

-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!

按照生成量产固件的步骤，001.000.000 版本脚本搭配 V2003 版本固件生成量产文件如下图：

需要注意的是：生成了这个版本以后，再去脚本中改动脚本版本号为 001.000.001(只要前后两位有一位大于 1，一位大于 0 即可(当然第一位大于 1 的时候，整个版本号自然大于 001.000.000)，如 002.000.200；001.000.001；030.000.311 等)

脚本版本号分为 A.B.C 三段；

因为历史原因，中间这一段 B 没有任何意义，但是必须存在；

假设旧的脚本版本号为 A1.B1.C1，新的脚本版本号为 A2.B2.C2；

当新旧脚本版本号满足以下任何一种条件时，版本号允许升级：

1、A2 等于 A1，同时 C2 大于 C1；

2、A2 大于 A1，同时 C2 大于或者等于 C1；

3、B1 B2 无意义

然后在 luatools 里重新选择 core 为 V2004 版本，同样点击生成固件，稍等即可在 luatools 根目录下的"SOC 量产及远程升级文件\Air780EPM"目录下，找到 core 版本号为 V2004 且脚本版本号为 001.000.001 的 soc 后缀文件。

接下来就是针对这两个量产文件，制作一个差分文件，用来远程升级(注：远程升级中 core 为差分，脚本为全量升级)

点击到 luatools 的主界面，依次点击图中蓝框所示意的地方(注：必须使用 luatools_3.0.9 及其以上版本，要不差分包升级的时候可能会出问题)。

按下图所示选择低版本以及高版本的固件，然后点击开始执行即可，如果不想输出的差分包在 luatools 根目录下，可以自行选择一个输出路径。

注意：新旧版本固件都要选择后缀为.soc 的量产文件。

因为包含了 core 中的改动，所以时间会稍长一些，luatools 可能会出现"假死"情况，不要关闭它，稍等一会即可看到

同样，在你选择的目录下(没选择的在 luatools 根目录下)看到如下所示，带着脚本的 PROJECT core 版本号 脚本版本号的 bin 后缀的差分文件。

依然是将这个文件改名为 780EPM_testota.bin 上传到对应位置

将升级文件上传完成以后，为了防止模块当前固件不是最早的版本，可以点击 luatools 主界面右边的"下载固件"选择最早的 001.000.000 版本，按住 boot 重启模块，然后点击下载，将最早的固件下载进模块里

6.3.2 示例效果展示

升级前：模块打印当前脚本版本号和 core 版本号

升级中下载差分包，校验差分包完成后就会重启模块进入真正的升级逻辑。

因为升级包带 core，所以从重启命令执行下去，到最终升级完成，模块重新开机打印了第一条开机日志，中间隔了快一分钟，如果 core 中代码改动较多，两分钟三分钟都是正常的。

升级后：打印脚本版本号为 001.000.001 core 版本号为 V2004 即证明升级成功。

七、常见问题

7.1 为什么升级后我的模块没有任何反应了，像是变砖一样

有多种可能，可以看以下几种情况

7.1.1 检查脚本

首先先检查下用户自己的脚本，有可能是引起重启/死机的代码写在了最前面，例如新加的某个值或者函数为 nil 但是还是去做了些加减乘除或者判断大小的逻辑。可以直接本地烧录下新版本的 core+ 脚本验证，如果有 fskv 等用到 flash 的代码，可能需要仔细检查才能排除问题，比如下载的时候勾选如下图所示的两个选项。

7.1.2 检查 core

如果是仅脚本升级，但是没注意使用了新 core 中才有的接口，就有可能引起循环重启，如果重启在代码最开头，模块可能来不及打印任何日志就重启了，可以直接本地烧录下新版本的 core+ 脚本验证，如果有 fskv 等用到 flash 的代码，可能需要仔细检查。

7.2 检查过脚本和 core，没问题，为什么会循环升级 6 次以后禁止升级

检查下升级包是否正常，有时候因为人员误操作，经常会出现旧脚本 + 新 core 或者新脚本 + 旧 core 的意外组合，

例如：

本来应该如下表描述的一样

	脚本版本号	core版本号
旧版本	001.000.000	V2003
新版本	001.000.005	v2004

操作人员失误后变成了如下

	脚本版本号	core版本号
误操作旧版本(1)	001.000.005	V2003
误操作旧版本(2)	001.000.000	V2004
误操作新版本(1)	001.000.000	V2004
误操作新版本(2)	001.000.005	V2003

然后误操作旧版本(1) 和误操作新版本(1)进行差分，这样虽然脚本版本号旧版本大于了新版本，但是 core 的旧版本小于新版本，所以升级平台依旧认为是依次有效的升级，下发了升级包。

升级完成后，模块内部脚本版本号变成了 001.000.000 core 版本号为 V2004 ，下次模块请求升级的时候，当前固件上报的脚本版本号(001.000.000)依旧小于云平台存储的脚本版本号(001.000.005)，然后继续下发升级包，就这么循环升级，直到流量耗尽，建议可以做一个类似合宙 iot 平台的禁止升级规则

7.3 我想在服务器发送特定的字符串如"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)