合宙模组FOTA（远程升级）介绍

一. 合宙4G模组远程升级概述

4G模组的远程升级，也称为OTA，也称为FOTA，是物联网应用中最最重要的功能。

通过远程升级，可以极低代价修复设备的缺陷，最大限度减少损失。

本文分别介绍如下集中情况的远程升级：

AT固件的远程升级
LuatOS 的远程升级
LuaOS-Air 的远程升级

二、AT 固件的远程升级

AT版本的远程升级主要是对AT固件版本进行升级，实际方式为通过合宙官方IOT平台升级或者使用自己搭建的服务器进行升级服务。

本节的内容，适合合宙的所有 4G 模组。

合宙IOT平台配置

使用默认项目名配置

客户采购了合宙的4G模块时，如果客户采购人员没有告知这批模块应该放在IOT平台的哪个产品下，

合宙则会以采购人的手机号为账号，默认密码888888，为客户创建一个 IOT 账号，

用这个账号，可以访问合宙的 IOT 平台：合宙IOT平台

创建项目

不同的模组型号，需要创建不同的项目，创建规则如下：

-- 780E，780EX，780EG 模组，需要创建名为 "Air7XXE标准模块" 的项目； -- 780EP,780EPS,780EQ,780ER，700ECQ，700EMQ，700EAQ，需要创建名为 "Air7XXF标准模块" 的项目； -- Air724, 795模组，需要创建名为 "Air72XUX标准模块" 的项目；

需要强调一下，以上项目命名的 X，仅仅就是字母 X，不需要用其他字母替换。

并将此次所采购的所有模块都放在这个项目下，如果模块没在该项目下，

或者需要更换项目，请联系合宙工作人员。

配置流程

以780ET为例，获取AT固件版本，下载到本地后解压并将dfota.bin文件上传到dfota中。

在IOT平台-我的项目页面点击固件列表

创建固件，上传对应文件

上传好文件之后会自动生成固件名称，不需要修改

如果配置“升级全部设备”选项为“是”，则无需配置IMEI，按照上述内容配置即可。如果选择“否”，还需添加IMEI，如下图所示。

AT指令触发升级

手动触发升级

如下模块从V1015升级到V1016的流程

自动升级（默认24小时内自动触发）

自动升级是模块定期向后台发送升级请求，来获取新固件进行更新的，大致流程如下

可以通过AT+UPGRADE=“PERIOD”，60设置自动升级时间，这里设置为60s来作为演示

使用自建项目名配置

客户从合宙采购完模块之后，注册登录合宙IOT平台，在IOT平台我的项目页面新建一个项目，并要求合宙工作人员将这批模块放入新建的项目中（客户本身无权限进行操作）。本示例就以“远程升级模块”为项目名进行远程升级。

该项目下的模块可通过设备列表查看

配置流程

以780ET为例，获取AT固件版本，下载到本地后解压并将dfota.bin文件上传到dfota中。

在IOT平台-我的项目页面点击固件列表

创建固件，上传对应文件

上传好文件之后会自动生成固件名称，不需要修改

如果配置“升级全部设备”选项为“是”，则无需配置IMEI，按照上述内容配置即可。如果选择“否”，还需添加IMEI，如下图所示。

AT指令触发升级

手动触发升级

通过下方图示操作，找到对应项目的项目Key。

复制项目Key，用AT+UPGRADE=“KEY”，ProductKey进行配置，该命令会参数会写入nv，掉电保存，其中ProductKey为对应项目Key。然后再用AT+UPGRADE进行远程升级。

自动升级（默认24小时内自动触发）

自动升级是模块定期向后台发送升级请求，来获取新固件进行更新的，大致流程如下

可以通过AT+UPGRADE=“PERIOD”，60设置自动升级时间，这里设置为60s来作为演示

自定义服务器升级

使用自己的服务器来升级模块和使用iot平台升级最重要的区别是下载固件的来源不同。
其实FOTA的过程是新老版本生成差分包再进行升级的过程，那么这个差分的过程在哪里呢？使用合宙iot平台升级，差分的过程在iot服务器后台，那使用自己的服务器该怎么办呢？答案当然是自己来完成差分的过程，放在服务器等待模块来下载。

差分包生成工具

手动生成差分包的过程使用doc平台工具中的差分工具差分工具

下载生成的差分文件

本次我们从V1015升级到V1016需要准备各自的bin远程升级文件，上传完成后等待差分完成，下载得到的差分文件，这里将名字改为dfota_final_AirM2M_AirM2M_V1016.bin。

配置流程

把生成的固件放到服务器上，然后通过AT+UPGRADE=“URL”,""指令设置对应的URL链接。
配置完差分包URL地址成功后，AT+UPGRADE 主动触发升级。
升级流程如下，这里选择了USB的另外一个端口，可以上报模块的升级过程：

恭喜你成功从V1015版本通过自己服务器搭建FOTA服务的方式升级到了更新的V1016版本！

介绍如何用Air780E开发板，如何做update升级。

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

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

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

支持合宙iot平台升级和自建第三方服务器升级

二. 材料准备

[EVB_Air780E]开发板一套，包括天线SIM卡，USB线。
PC电脑，以及登录官方IOT后台 https://iot.openluat.com/
固件和DEMO下载地址 LuatOS软件包

三. 合宙iot平台升级core+script过程

1. iot平台创建产品

登录合宙iot平台
如果没有账户，注册一个账户
我的项目->新建产品
复制PRODUCT_KEY

2. 模块端脚本修改，生成升级包

core	旧版本core	新版本core
例子	LuatOS-SoC_V1103_EC618.soc	LuatOS-SoC_V1103_EC618.soc
要求	1、大于等于旧版本core版本号	2、新旧版本core支持的功能相同

script main.lua	旧版本（模块端本地烧录的）	新版本（生成的量产文件，远程升级包）	要求
PROJECT （项目名称）	fotademo	fotademo	新旧版本保持一致
VERSION （软件版本号）	1.0.1	1.0.2	大于等于旧版本VERSION
PRODUCT_KEY （项目密钥）	3TNamWSWhGQKS7pXWyIjoBZWC4xFRMCU	3TNamWSWhGQKS7pXWyIjoBZWC4xFRMCU	和iot平台创建的产品 ProductKey保持一致

3. 按照新版本的需求，修改main.lua

如下图所示，PROJECT和PRODUCT_KEY保持不变，PRODUCT_KEY需和服务器保持一致，VERSION修改为1.0.2。

注意事项： 1、固件版本 V1103 及以上, 配合 libfota.lua 2、main.lua 内填写版本号要符合 x.y.z 形式, 其中 x/y/z 均为数值, 不限于个位数 3、若fota使用合宙iot平台, 版本号中的 y 会被忽略, 推荐写0, 务必留意

4. 使用Luatools生成bin文件差分包

注意：只有Luatools版本2.1.89以上支持生成bin文件差分包，低版本仅支持生成sota文件 * 只升级脚本，差分包制作流程如下： 固件和DEMO下载地址 LuatOS软件包，这里下载的是LuatOS-SoC@EC618 V1103项目下面的core_V1103.zip软件包。下载对应软件包后按如下步骤生成对应的差分包。

在Luatools目录下的SOC量产及远程升级文件下，找到EC618文件夹，打开后缀名为.bin的文件fotademo_1103.1.2_LuatOS-SoC_EC618.bin，这个就是文件差分包。

需要升级底层CORE，差分包制作流程如下： 1）生成新版本的量产固件，如下所示： 2）根据新旧固件生成对应差分文件，如下所示： a、点击选项及工具选项，选择升级包制作工具 b、选择对应文件，点击开始执行生成对应差分文件 3）生成的对应差分文件见下图所示：

### 5.在合宙iot平台配置升级包

进入iot平台创建的产品，打开我的项目->固件列表->创建固件，如下图所示 undefined

点击确定之后，升级配置完成，如下图所示

添加需要升级的模块imei，如下图所示

6. 模块开机，完成升级

烧录旧版本的模块开机后，连接升级服务器，下载差分升级包，自动重启，重启过程中完成固件升级，整个过程的关键日志如下图所示

7.云平台查看升级日志

登录云平台，选择对应设备升级的产品->固件升级->升级日志->输入对应的imei并选择日期->搜索

可以看到设备在此日期下的空中升级日志。正常升级成功的情况下，短时间内会有两次升级请求，第一次请求升级获取到升级包之后，设备重启升级成功会再次向云平台请求是否有更高版本的固件可以升级。直到升级结果为 “已是最新版本” 服务器没有更高版本的固件为止。

设备升级失败等情况，可对照以下表格寻求解决方案。

响应码	响应信息	问题以及解决办法	云平台日志结果
3	无效的设备	检查请求键名(imei小写)正确性	无
17	无权限	设备会上报imei、固件名、项目key。服务器会以此查出设备、固件、项目三条记录，如果这三者不在同一个用户名下，就会认为无权限。设备不在项目key对应的账户下，可寻找合宙技术支持查询该设备在哪个账户下，核实情况后可修改设备归属	无权限
21	21	不允许从1.0.2升到1.0.3	21
25	无效的项目	productkey不一致，检查是否存在拼写错误，检查模块是否在本人账户下，若不在本人账户下，请联系合宙工作人员处理	未找到项目
26	无效的固件	固件名称错误，项目中没有对应的固件。用户自己修改了固件名称，可对照升级日志中设备当前固件名与升级配置中固件名是否相同（固件名称，固件功能要完全一致，只是版本号不同）。	找不到固件
27	已是最新版本	1、设备固件版本高于云平台 2、固件版本设备脚本版本高于云平台版本 3、用户项目升级配置中未添加该设备 4、云平台升级配置中，是否升级配置为否	已是最新版本设备不在配置的升级设备列表中
40	循环升级	云平台进入设备列表搜索被禁止的imei，解除禁止升级就好了。云平台防止模块在升级失败后，反复请求升级导致流量耗尽，在模块一天请求升级六次后会禁止模块升级。可在平台解除。	检测到循环升级 (已禁止升级，请到设备列表解除)
43	请等待	云平台生成差分升级包需要等待，一到三分钟后云平台生成完成差分包便可以请求成功。	正在生成版本，请等待
44	基础版本缺失	平台未收录设备固件（多为定制固件，可寻找合宙技术支持人员添加，需提供定制固件邮件）	基础CORE版本缺失

四. 自建第三方服务器升级过程

使用自建第三方服务器升级：

注意：只有Luatools版本2.1.89以上支持生成bin文件差分包，低版本仅支持生成sota文件

手动生成core差分包+script全量包。例如core版本有1001、1002、1003，现在要统一升级到1004，则需要按照如下步骤操作：

1、手动生成：从1001到1004的core差分包+script全量包、从1002到1004的core差分包+script全量包、从1003到1004的core差分包+script全量包

2、模块请求升级时，服务器根据模块中的core版本返回对应的升级包文件

手动生成差分包的过程如下：

用合宙提供的luatools中的soc差分工具生成差分包 undefined

操作步骤：

1、准备：模块中使用的旧版本core升级文件

此文件指的是模块中旧版本core中的.soc文件（从合宙官方渠道下载），例如以LuatOS-SoC_V1103_EC618.soc为例

2. 使用Luatools分别生成新旧版本的升级包

如下图所示

在Luatools目录下SOC量产及远程升级文件下的EC618下，生了一个后缀名为.soc的文件fotademo_1.0.2_LuatOS-SoC_V1103_EC618.soc，这个就是新版本的升级包

3、生成差分包

使用luatools生成升级文件，无论core是否需要升级，升级文件必须包含core，因为差分会用到使用luatools内的soc差分工具生成即可生成对应差分包如下图所示：

注意：差分包不能超过480k

4、差分包上传到自建服务器

lua固件默认支持HTTP获取升级包

启动远程升级功能，demo/fota/mian.lua文件做如下修改，注释掉使用合宙iot平台进行升级，打开使用自建服务器进行升级部分代码，填写对应的ota_url 。

注意：服务器端需要有判断版本号的能力。

-- 使用合宙iot平台进行升级
--libfota.request(fota_cb)
--sys.timerLoopStart(libfota.request, 3600000, fota_cb)

-- 使用自建服务器进行升级
 local ota_url = "http://myserv.com/myapi/version=" .. _G.VERSION .. "&imei=" .. mobile.imei()
 libfota.request(fota_cb, ota_url)
 sys.timerLoopStart(libfota.request, 3600000, fota_cb, ota_url)

5、使用其他协议实现自建服务器远程升级

可参考脚本库中配置。无论使用哪种协议，远程升级的关键是获取正确的升级固件包。