FOTA 开发指导_Rev1.0

修订记录

版本	日期	作者	修订内容
Rev1.0	26-3-26	ljz	创建文档

1 简介

本文档介绍 LTE-EC71X 差分升级接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_fota2/liot_fota2.h 文件声明。

功能限制说明：

仅支持HTTP、FTP、本地文件系统三种升级方式，暂不支持 HTTPS 及 FTPS 加密协议。
FOTA 功能预留空间充足，暂不支持用户自定义修改分区。

1.1 模组升级流程原理

总体流程说明

模组的 FOTA 升级流程主要包括 差分包下载、校验验证、固件还原及系统重启升级 四个阶段。
整体流程如下：

通过 HTTP/FTP/文件系统 下载差分升级包（.par 格式）至模组文件系统；
下载完成后，底层会进行完整性校验，校验不通过则终止升级，校验通过则进入下一步；
模组自动重启并进入 Bootloader 模式，由 Bootloader 执行固件还原与 Flash 擦写操作；
固件还原完成后，系统再次重启，加载新固件并正常运行。

校验机制

校验阶段包含旧固件一致性校验和差分包完整性校验两部分，任一部分校验失败均会导致升级中止，校验逻辑如下：

旧固件一致性校验：对设备当前固件重新计算校验码，并与差分包中记录的校验码比对，以确保旧固件版本匹配；
差分包完整性校验：验证差分包的数据是否完整无损，防止因数据错误导致升级失败。

升级过程

模组接收到升级指令并完成差分包下载、校验后，自动重启，优先由 Bootloader 程序启动；
Bootloader 检查差分包是否存在，并读取 升级标记位；
若差分包存在且标记位为“未升级”，则执行 差分还原算法，按分段方式将新固件内容还原并覆盖至 Flash；
在还原过程中，Bootloader 会执行三个操作：
- 写入升级标记位；
- 更新升级进度信息；
- 循环执行“还原 → 覆盖 → 记录进度”的过程，直到升级完成；
升级完成后，系统再次重启；
根据升级标记位状态：
- 若升级成功，Bootloader 删除差分包文件并更新标记位；
- 然后跳转执行新的应用程序。

2 API 函数概览

FOTA2 功能当前仅提供一个核心升级函数，负责校验升级包信息并写入 FOTA 分区，函数信息如下：

函数	说明
`Liot_FotaUpgrade()`	用于校验文件系统中存储的升级包信息，校验后写入fota分区

3 类型说明

3.1 liot_fota_err_e

FOTA 错误码。

声明

typedef enum
{
    L_FOTA_UPGRADE_SUCCESS             = 0,   /*!< Indicates that the FOTA upgrade was successful.*/
    L_FOTA_UPGRADE_FAIL                = 1,   /*!< General FOTA upgrade failure.*/
    L_FOTA_UPGRADE_CHECK_FAIL          = 2,   /*!< FOTA upgrade check failed.*/
    L_FOTA_UPGRADE_MD5_FAIL            = 3,   /*!< MD5 checksum verification of the FOTA package failed.*/
    L_FOTA_UPGRADE_MATCH_FAIL          = 4,   /*!< FOTA package does not match the device requirements.*/
    L_FOTA_UPGRADE_NO_FILE_FAIL        = 5,   /*!< FOTA file not found or missing.*/
    L_FOTA_UPGRADE_OPENFILE_FAIL       = 6,   /*!< Failed to open the FOTA upgrade file.*/
    L_FOTA_UPGRADE_FILESIZE_FAIL       = 7,   /*!< Invalid or unsupported FOTA file size.*/
    L_FOTA_UPGRADE_LFS_MOUNT_FAIL      = 8,   /*!< Failed to mount LittleFS (LFS) for FOTA.*/
    L_FOTA_UPGRADE_PARAM_FAIL          = 9,   /*!< Invalid input parameters for FOTA upgrade.*/
    L_FOTA_UPGRADE_PROJECT_MATCH_FAIL  = 10,  /*!< Project name in FOTA package does not match the device.*/
    L_FOTA_UPGRADE_BASELINE_MATCH_FAIL = 11,  /*!< Baseline version in FOTA package does not match the device.*/
    L_FOTA_UPGRADE_POINT_NULL_ERR      = 12,  /*!< Null pointer error during FOTA upgrade.*/
    L_FOTA_UPGRADE_FLAG_SET_ERR        = 13,  /*!< Failed to set the upgrade flag during FOTA.*/
} liot_fota_err_e;

参数

参数	说明
`L_FOTA_UPGRADE_SUCCESS`	执行成功
`L_FOTA_UPGRADE_FAIL`	执行失败
`L_FOTA_UPGRADE_CHECK_FAIL`	FOTA 升级包校验失败
`L_FOTA_UPGRADE_MD5_FAIL`	FOTA 升级包MD5校验失败
`L_FOTA_UPGRADE_MATCH_FAIL`	FOTA 升级匹配文件失败
`L_FOTA_UPGRADE_NO_FILE_FAIL`	无升级包文件
`L_FOTA_UPGRADE_OPENFILE_FAIL`	打开文件失败
`L_FOTA_UPGRADE_FILESIZE_FAIL`	升级包文件长度超过限制
`L_FOTA_UPGRADE_LFS_MOUNT_FAIL`	文件系统加载失败
`L_FOTA_UPGRADE_PARAM_FAIL`	参数错误
`L_FOTA_UPGRADE_PROJECT_MATCH_FAIL`	工程不匹配
`L_FOTA_UPGRADE_BASELINE_MATCH_FAIL`	基线不匹配
`L_FOTA_UPGRADE_POINT_NULL_ERR`	指针为空
`L_FOTA_UPGRADE_FLAG_SET_ERR`	标志位设置错误

3.2 Liot_FotaConfig_t

FOTA 参数配置结构体。用于配置 FOTA 升级的核心参数，包括升级链接、自动重启、超时时间、回调函数。

声明

typedef struct
{
    char *url;                   // 升级链接，支持http、ftp、本地文件系统三种类型
    bool enable;                 // 下载完成后是否自动重启升级：true-自动重启，false-仅下载校验不重启
    uint32_t timeout;            // 超时时间，单位：毫秒（ms）
    liot_fota_callback callback; // FOTA过程状态回调函数，用于实时上报下载进度
} Liot_FotaConfig_t;

参数

参数	说明
url	升级包的获取链接，格式要求严格： 1. 若使用HTTP升级： url需要是 “http://” 或 “HTTP://” 开头 2. 若使用FTP升级 url需要是 “ftp://” 或 “FTP://” 开头格式为：ftp://user:pass@ip:port / 路径 / 包名.par 3. 若使用文件系统升级 url需要是 “FILE:” 开头
enable	是否开启自动重启升级。 true - 下载 + 校验通过后，模组自动重启并执行升级； false - 仅完成下载和校验，需用户手动触发重启（如调用：`liot_power_reset()`）
timeout	下载超时时间（单位：毫秒）。
callback	FOTA过程状态回调函数，用于上报下载进度。

4 API 函数详解

4.1 Liot_FotaUpgrade

FOTA2 升级的核心函数，负责根据传入的配置参数，从指定地址（HTTP/FTP/ 本地文件）获取差分包，执行校验，校验通过后将差分包写入文件系统，并根据enable参数决定是否自动重启升级，在相关业务处理完成，可以调用liot_power_reset()来进行重启。

声明

liot_fota_err_e Liot_FotaUpgrade(Liot_FotaConfig_t *fota_config)

参数

fota_config：

[In] 升级参数配置，详情请参考3.2 章。

返回值

liot_fota_err_e ：执行结果码，请参考第 3.1 章。

5 升级前准备

5.1 差分包制作

差分包是 FOTA 升级的核心文件，由旧固件（当前设备运行版本）和新固件（目标升级版本）通过 FotaToolkit 工具生成，支持底包 + APP 差分升级和单 APP 差分升级两种方式，制作前需完成工具准备和配置修改。

5.1.1 差分工具获取

FotaToolkit 工具：FotaToolKit，下载后直接解压即可使用，无需安装。

固件准备

需提前准备两个固件文件，固件在LSDK/gccout目录下，如果是底包+APP的升级方式，使用binpkg格式的固件，若单APP差分升级，使用bin格式的固件：

旧固件文件（Old File）：设备当前运行的固件版本。
目标固件文件（Delta File）：用于升级的目标固件版本。

5.1.2 确认APP分区大小

底包分离方案需要额外修改工具的配置文件，首先需要确认LSDK/components/basePkg/[模组型号]/partition_info.txt中当前APP的大小，（如 F6B_A 型号为LSDK/components/basePkg/F6B_A/partition_info.txt），查找appsdk分区的Size字段，记录其十六进制大小（如 0x0CB000）。

5.1.3 修改 FotaToolkit 配置文件

进入 FotaToolkit 根目录，打开配置文件：./config/[模组型号].json（如 EC718PM 型号为ec718pm.json）；
找到attr:“APP”（APP 分区）对应的size字段，该字段表示规划存储的加载最大尺寸，将其值修改为比实际 APP 分区适当大的数值（十进制），没有对其或需要在分区边界内的需求，例如实际 APP 大小为 831448，可修改为 933888；
使能APP升级
保存配置文件，修改后需关闭文件再重新打开工具，确保配置生效。

5.1.4 底包+APP差分升级

适用于底包和 APP 应用代码均有修改的场景，生成的差分包包含底包和 APP 的差异数据，操作步骤如下：

打开 FotaToolkit 工具，切换至 Generator 标签页；
Config File：点击选择按钮，选择对应模组型号的配置文件（如ec718pm.json）；
Delta File：选择差分包的保存路径和名称，后缀为.par（如C:/FOTA/test.par）；
Old File：选择准备好的旧固件文件（binpkg格式）；
New File：选择准备好的新固件文件（binpkg格式）；
FLASH 配置：Load Addr 包类型选择BINPKG（默认）；
所有参数配置完成后，点击Start按钮，工具开始生成差分包；
工具日志窗口显示>>>>>>>>>>>SUCC<<<<<<<<<<<，表示差分包制作成功；若显示错误，根据日志提示排查（如配置错误、固件格式错误）。

5.1.5 单APP差分升级

适用于仅 APP 应用代码修改，底包无任何变化的场景，生成的差分包仅包含 APP 的差异数据，体积更小，操作步骤如下：

打开 FotaToolkit 工具，切换至 Generator 标签页；
Config File：点击选择按钮，选择对应模组型号的配置文件（如ec718pm.json）；
Delta File：选择差分包的保存路径和名称，后缀为.par（如C:/FOTA/test.par）；
Old File：选择准备好的旧固件文件（bin格式）；
New File：选择准备好的新固件文件（bin格式）；
FLASH 配置：Load Addr 包类型选择 APP；
所有参数配置完成后，点击Start按钮，工具开始生成差分包；
工具日志窗口显示>>>>>>>>>>>SUCC<<<<<<<<<<<，表示差分包制作成功；若显示错误，根据日志提示排查（如配置错误、固件格式错误）。

5.2 HTTP及FTP的环境搭建

用户在进行HTTP或FTP的FOTA测试时，需要使用自己的服务器进行远程升级，为了方便前期用户设备调测，这里给出利尔达 X 平台测试服务器的环境搭建流程和使用指导。

5.2.1 平台登陆

登陆利尔达 X 平台：https://account.xiot.senthink.com/，如下图所示，点击“控制台”进入功能模块窗口界面。

图 2.1 Lierda X平台网络调试助手

开通后进入该功能模块，点击“网络调试助手”，创建所需要测试协议对应的服务器。

5.2.2 上传FOTA包

按照 2.1 章节开通“网络调试助手”后，进入该功能模块，选择左侧的“文件下载”，点击“添加文件”，上传已制作好的差分包。

图2.2 上传差分包

Lierda X平台针对每个用户上传差分包对应的下载地址是固定的，只是根据用户差分包的名称不同而有所区别。如差分包的名称为fota_test3.par，完整下载地址为：http://xiot.oss.senthink.com/upload-http-ftp/5D6A3E7E/fota_test3.par。用户在进行初始程序编译时需要写入该地址：