固件 OTA 升级常见问题

固件OTA升级是否一定要制作升级包

必须制作升级包，不可直接用固件版本包中的固件文件作为升级包。

如何制作差分包

不同型号略有差异，参见固件OTA升级包制作指引。

制作差分包失败原因

不同分区结构的固件无法相互OTA升级，所以需要确保制作差分包的2个固件分区一致。官方固件中同一型号的固件分区会保持一致，如果因为特殊情况导致无法OTA会特殊说明。

固件OTA升级异常断电处理

如果断电发生在下载阶段，则下次上电重启后需要重新触发升级，需要重新下载升级包。如果断电发生在升级阶段，可以记录升级标志和上次升级的位置，重新上电后继续上次的位置进行升级直到升级完成并重启。

应用OTA升级异常断电处理

如果断电发生在下载阶段，则下次上电重启后需要重新触发升级，已经下载完的文件不会重新下载，上次下载中断的文件会重新下载。如果断电发生在升级阶段，可以记录升级标志和上次升级的位置，重新上电后继续上次的位置进行升级直到升级完成并重启。

网络不稳定场景处理

如果网络响应超时则升级接口会返回升级失败。需要重新调用升级接口触发升级。针对MiniFota升级方案，则会一直等待直到网络恢复。

什么是最小系统升级

最小系统升级即MiniFota升级方案，结合了差分升级和全包升级2种方式，属于特殊定制的方案。主要针对Flash大小有限没有足够空间存放升级包文件的设备。制作升级包时，会生成两个升级包文件，并需要进行多次自动重启。

MiniFOTA升级方案调用接口直接重启

MiniFota升级方案属于特殊定制的方案，在进行OTA升级功能之前需要先进入最小系统模式，所以在调用完OTA升级接口之后会立即重启设备进入最小系统模式。进入最小系统模式之后会自动进行连网、下载、升级过程，直到最终升级成功。在最小系统模式下不需要用户介入，只需要等待最终升级成功。这个过程可能会有多次设备重启。

为什么用户脚本不能差分升级

用户脚本存放在文件系统分区，而文件系统分区内容在开机运行后会发生变化，无法使用差分算法进行差分升级。

MiniFOTA升级方式如何升级文件系统分区

MiniFOTA升级支持将文件系统分区一起升级，而用户的脚本文件和其他文件也是存在文件系统分区。这样MiniFOTA升级就可以实现固件和用户文件一起进行升级。具体需要制作升级包的时候带上fs分区，可以参见固件OTA升级包制作指引。

应用OTA升级下载是否有完整性校验

OTA功能模块本身没有，客户可以自己加入完整性校验。方法是在下载时传入计算好的MD5校验值，下载到设备后再计算已下载内容的MD5校验值与传入的值进行比对是否一致。

应用OTA升级，文件系统需要预留多少空间

需要预留空间要大于待升级的所有文件占用的空间。注意，一个文件内容即使不够4KB也会占用4KB，一个目录占用8KB。超过空间限制会导致升级失败。

固件OTA 升级是否要预留空间

固件OTA空间由设备底层保证，差分包大小超过空间限制会导致升级失败。

看门狗

设备在升级过程中，是处在特殊模式，没法运行应用程序，所以没法给外部的看门狗电路进行喂狗。这时需要考虑看门狗的超时时间不要低于设备升级成功需要的最大时间。

下载协议

下载协议支持 HTTP、HTTPS和FTP，具体支持情况如下表。

应用OTA升级失败排查处理

可能原因

1.文件系统存储空间不够，需要预留空间要大于待升级的所有文件占用的空间。注意，一个文件内容即使不够4KB也会占用4KB，一个目录占用8KB。超过空间限制会导致升级失败。

2.网络异常导致下载中断，需要重新调用下载接口继续完成剩余的文件下载。

3.异常断电后未清除上次残留的中间文件，需要每次开始执行升级功能前先检测是否残留上次的升级文件，如果有则需要将其删除。

处理

由于异常断电等导致应用OTA升级失败，这时文件系统分区会存有已经下载的升级文件和中间文件。为了不影响下次正常升级，建议删除残留的升级文件。可以在升级之前加入如下代码。

if ql_fs.path_exists("usr/.updater"):
    ql_fs.rmdirs('usr/.updater')

固件OTA升级失败排查

差分升级方案

调用升级接口直接返回-1，且没有升级进度

1.检查网络是否正常，是否插了SIM卡、是否接了天线，是否拨号成功。

2.是否使用HTTPS下载协议，仅部分型号支持HTTPS协议，不支持HTTPS协议的设备使用HTTPS协议的URL会下载失败，需要换成HTTP协议的URL。支持HTTPS协议的情况有ECx00N&EG91xN系列、EC200A系列、ECx00U&EG91xU&ECx00G系列、BG95&BG600L系列且使用差分升级方案时。

3.检查URL正确，可以使用浏览器输入该URL查看是否能下载成功。

调用升级接口直接返回-1，有升级进度

1.版本不匹配，烧录到设备的当前固件版本和制作差分包的旧版本不是同一个版本。需要确保二者一致。

2.前后版本差异过大导致差分包太大超过存储空间，检查制作出的差分包大小是多少。各型号差分包最大size限制如下：

升级接口返回0，设备重启后版本号没变

版本不匹配，烧录到设备的当前固件版本和制作差分包的旧版本不是同一个版本。需要确保二者一致。

MiniFOTA升级方案

设备一直处在升级状态没有反应。

1.检查网络是否正常，是否插了SIM卡、是否接了天线，正常状态时拨号能否成功。

2.检查URL正确，可以使用浏览器输入该URL查看是否能下载成功。

3.是否使用HTTPS下载协议，MiniFOTA升级方案不支持HTTPS下载协议，需要换成HTTP协议的URL。

设备反复重启，无法恢复到正常状态。

抓取debug UART log和catstudio log，给到Quectel工程师分析。

设备重启恢复到正常状态之后，查询版本号还是老版本，未升级成功。

版本不匹配，烧录到设备的当前固件版本和制作差分包的旧版本不是同一个版本。需要确保二者一致。