FOTA升级¶

功能概述¶

FOTA（Firmware Over-The-Air）是远程固件升级能力，支持设备通过蜂窝网络自动下载并更新固件版本。开发者无需现场维护设备，即可远程完成版本升级、问题修复和功能迭代，有效降低运维成本并提升产品可靠性。

当前 FOTA 支持全量升级和差分升级两种模式。其中，全量升级通过下载完整固件包完成更新；差分升级仅传输版本差异数据，可显著减少升级包大小和网络流量消耗。升级过程中支持断点续传和升级状态反馈机制，确保升级过程安全、稳定、可靠。

备注

FOTA差分包和全量包均需配合对应工具使用，详情请参考 FOTA工具使用教程。

该功能适用于大规模物联网设备部署场景，可实现设备全生命周期的软件维护和版本管理。

FOTA升级API¶

头文件¶

qosa_fota.h

函数概览¶

函数	说明
qosa_fota_init()	初始化FOTA并获取FOTA处理器句柄
qosa_fota_deinit()	释放并销毁FOTA相关资源，停止并清理后台工作
qosa_fota_set_update_urc_num()	设置升级所需的URC（通知）的数量
qosa_fota_get_current_file_size()	查询当前已下载的FOTA包文件大小（用于断点续传/进度）
qosa_fota_verify_image()	对已下载的FOTA包进行完整性/签名校验
qosa_set_fota_verify_config()	设置FOTA包签名验证配置（是/否）
qosa_get_fota_verify_config()	获取FOTA包签名验证配置（是/否）
qosa_fota_get_partition_space()	获取分区空间大小，检查是否满足FOTA包写入要求
qosa_fota_write_packet_data()	FOTA数据包写入
qosa_fota_set_packname()	配置FOTA包名称
qosa_fota_get_default_packname()	获取当前配置的FOTA包名称
qosa_fota_set_opt()	配置FOTA选项
qosa_fota_flag_set()	设置升级标志

函数详解¶

qosa_fota_init¶

功能描述
初始化FOTA并获取FOTA处理器句柄。
函数原型

qosa_fota_t *qosa_fota_init(char *fota_name, qosa_bool_t del_old_file)

参数说明

参数名	输入/输出	类型	说明
fota_name	输入	char *	设置FOTA包名称
del_old_file	输入	qosa_bool_t	是否删除UFS下的历史文件 QOSA_TRUE：删除历史文件 QOSA_FALSE：不删除历史文件

返回值说明
*qosa_fota_t **：FOTA处理器句柄
QOSA_NULL：函数执行失败

qosa_fota_deinit¶

功能描述
释放并销毁FOTA相关资源，停止并清理后台工作。
函数原型

void qosa_fota_deinit(qosa_fota_t *fota)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄

返回值说明
无

qosa_fota_set_update_urc_num¶

功能描述
设置升级所需的URC（通知）的数量。
函数原型

qosa_fota_errno_e qosa_fota_set_update_urc_num(qosa_fota_t *fota, qosa_uint8_t update_urc_num)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄
update_urc_num	输入	qosa_uint8_t	设置URC的数量

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_fota_get_current_file_size¶

功能描述
查询当前已下载的FOTA包文件大小（用于断点续传/进度）。
函数原型

qosa_int64_t qosa_fota_get_current_file_size(qosa_fota_t *fota)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄

返回值说明
返回当前文件的大小

qosa_fota_verify_image¶

功能描述
对已下载的FOTA包进行完整性/签名校验。
函数原型

qosa_fota_errno_e qosa_fota_verify_image(qosa_fota_t *fota)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_set_fota_verify_config¶

功能描述
设置FOTA包签名验证配置（是/否）。
函数原型

qosa_fota_errno_e qosa_set_fota_verify_config(qosa_fota_verify_control_e value)

参数说明

参数名	输入/输出	类型	说明
value	输入	qosa_fota_verify_control_e	QOSA_FOTA_VERIFY_ENABLE：启用FOTA签名验证 QOSA_FOTA_VERIFY_DISABLE：禁用FOTA签名验证

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_get_fota_verify_config¶

功能描述
获取FOTA包签名验证配置（是/否）。
函数原型

qosa_fota_verify_control_e qosa_get_fota_verify_config(void)

返回值说明
QOSA_FOTA_VERIFY_ENABLE：签名验证已启用
QOSA_FOTA_VERIFY_DISABLE：签名验证已禁用

qosa_fota_get_partition_space¶

功能描述
获取分区空间大小，检查是否满足FOTA包写入要求。
函数原型

qosa_int64_t qosa_fota_get_partition_space(qosa_fota_t *fota)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄

返回值说明
qosa_int64_t类型，成功时表示实际空间的大小
失败返回 -1

qosa_fota_write_packet_data¶

功能描述
FOTA数据包写入。
函数原型

qosa_fota_errno_e qosa_fota_write_packet_data(qosa_fota_t *fota, qosa_uint8_t *payload, qosa_size_t payload_len)

参数说明

参数名	输入/输出	类型	说明
fota	输入	qosa_fota_t *	与初始化操作相对应的FOTA句柄
payload	输入	qosa_uint8_t *	升级数据内容
payload_len	输入	qosa_size_t	升级数据长度

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_fota_set_packname¶

功能描述
配置FOTA包名称。
函数原型

qosa_fota_errno_e qosa_fota_set_packname(char *packetname, int length)

参数说明

参数名	输入/输出	类型	说明
packetname	输入	char *	FOTA包名称
length	输入	int	FOTA包名称的长度

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_fota_get_default_packname¶

功能描述
获取当前的FOTA包名称。
函数原型

qosa_fota_errno_e qosa_fota_get_default_packname(char *packetname, int *length)

参数说明

参数名	输入/输出	类型	说明
packetname	输出	char *	当前的FOTA包名称
length	输出	int *	当前FOTA包名称的长度

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_fota_set_opt¶

功能描述
配置FOTA选项。
函数原型

qosa_fota_errno_e qosa_fota_set_opt(qosa_fota_opt_cmd_e cmd, void *param)

参数说明

参数名	输入/输出	类型	说明
cmd	输入	qosa_fota_opt_cmd_e	FOTA选项： QOSA_FOTA_OPT_CMD_SET_FOTA_MODE 代表配置FOTA升级方式
param	输入	void *	具体指令：例：当cmd为：QOSA_FOTA_OPT_CMD_SET_FOTA_MODE 时， QOSA_FOTA_DFOTA_MODE 代表差分升级 QOSA_FOTA_FULL_MODE 代表全量升级

返回值说明
QOSA_FOTA_OK：函数执行成功
其他值：函数执行失败

qosa_fota_flag_set¶

功能描述
设置升级标志。
函数原型

void qosa_fota_flag_set(void)

枚举定义¶

qosa_fota_errno_e¶

结果码枚举定义如下：

typedef enum{    
    QOSA_FOTA_OK = 0, 
    QOSA_FOTA_OPEN_ERROR = -1,  
    QOSA_FOTA_WRITE_ERROR = -2,
    QOSA_FOTA_READ_ERROR = -3,
    QOSA_FOTA_ERASE_ERROR = -4,
    QOSA_FOTA_COMPARE_ERROR = -5,
    QOSA_FOTA_SEEK_ERROR = -6,
    QOSA_FOTA_UPDATE_ERROR = -7,
    QOSA_FOTA_PARAM_ERROR = -8,
    QOSA_FOTA_IMAGE_VERIFY_ERROR = -9,
    QOSA_FOTA_CODE_GENERAL_ERROR = -10,
    QOSA_FOTA_NOT_EXIST_ERROR = -11,
    QOSA_FOTA_OUT_OF_MEMORY = -12,
    QOSA_FOTA_PARTITION_ERROR = -13,
    QOSA_FOTA_CLOSE_ERROR = -14,
    QOSA_FOTA_RENAME_ERROR = -15,
    QOSA_FOTA_BUF_NOT_ENOUGH = -16,
    QOSA_FOTA_FLASH_READ_ERROR = -17,
    QOSA_FOTA_FLASH_WRITE_ERROR = -18,
    QOSA_FOTA_FLASH_ERASE_ERROR = -19,
    QOSA_FOTA_VERIFY_NOT_ENABLE = -20,
    QOSA_FOTA_NOT_SUPPORT_ERROR = -21,
} qosa_fota_errno_e;

成员	说明
QOSA_FOTA_OK	FOTA执行成功
QOSA_FOTA_OPEN_ERROR	FOTA文件打开错误
QOSA_FOTA_WRITE_ERROR	FOTA数据写入错误
QOSA_FOTA_READ_ERROR	FOTA数据读取错误
QOSA_FOTA_ERASE_ERROR	FOTA擦除失败
QOSA_FOTA_COMPARE_ERROR	FOTA对比失败
QOSA_FOTA_SEEK_ERROR	FOTA检测错误
QOSA_FOTA_UPDATE_ERROR	升级失败
QOSA_FOTA_PARAM_ERROR	输入参数错误
QOSA_FOTA_IMAGE_VERIFY_ERROR	FOTA包校验失败
QOSA_FOTA_CODE_GENERAL_ERROR	FOTA升级内部错误
QOSA_FOTA_NOT_EXIST_ERROR	文件不存在
QOSA_FOTA_OUT_OF_MEMORY	内存不足
QOSA_FOTA_PARTITION_ERROR	分区错误
QOSA_FOTA_CLOSE_ERROR	关闭失败
QOSA_FOTA_RENAME_ERROR	重命名失败
QOSA_FOTA_BUF_NOT_ENOUGH	缓冲区不足
QOSA_FOTA_FLASH_READ_ERROR	FLASH数据读取失败
QOSA_FOTA_FLASH_WRITE_ERROR	FLASH数据写入失败
QOSA_FOTA_FLASH_ERASE_ERROR	FLASH数据擦除失败
QOSA_FOTA_VERIFY_NOT_ENABLE	FOTA包校验未开启
QOSA_FOTA_NOT_SUPPORT_ERROR	不支持

qosa_fota_verify_control_e¶

FOTA签名枚举定义如下：

typedef enum{
    QOSA_FOTA_VERIFY_NOT_SUPPORT = -1,    
    QOSA_FOTA_VERIFY_DISABLE = 0,
    QOSA_FOTA_VERIFY_ENABLE = 1,
} qosa_fota_verify_control_e;

成员	说明
QOSA_FOTA_VERIFY_NOT_SUPPORT	不支持FOTA签名验证
QOSA_FOTA_VERIFY_DISABLE	禁用FOTA签名验证
QOSA_FOTA_VERIFY_ENABLE	启用FOTA签名验证

qosa_fota_opt_cmd_e¶

枚举定义如下：

typedef enum{
    QOSA_FOTA_OPT_CMD_SET_FOTA_MODE = 0,
} qosa_fota_opt_cmd_e;

成员	说明
QOSA_FOTA_OPT_CMD_SET_FOTA_MODE	设置FOTA升级方式

qosa_fota_mode_e¶

枚举定义如下：

typedef enum{
    QOSA_FOTA_DFOTA_MODE = 0, 
    QOSA_FOTA_FULL_MODE,
} qosa_fota_mode_e;

成员	说明
QOSA_FOTA_DFOTA_MODE	差分升级
QOSA_FOTA_FULL_MODE	全量升级

应用逻辑流程图¶

升级流程¶

../../_images/board_T8nBwUG4eh40Qpb7SstcLqzHnsf.jpg

示例代码¶

完整示例代码请查看

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/fota/http_fota_demo.c

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/fota/ftp_fota_demo.c

FOTA升级¶

功能概述¶

FOTA升级API¶

头文件¶

函数概览¶

函数详解¶

qosa_fota_init¶

qosa_fota_deinit¶

qosa_fota_set_update_urc_num¶

qosa_fota_get_current_file_size¶

qosa_fota_verify_image¶

qosa_set_fota_verify_config¶

qosa_get_fota_verify_config¶

qosa_fota_get_partition_space¶

qosa_fota_write_packet_data¶

qosa_fota_set_packname¶

qosa_fota_get_default_packname¶

qosa_fota_set_opt¶

qosa_fota_flag_set¶

枚举定义¶

qosa_fota_errno_e¶

qosa_fota_verify_control_e¶

qosa_fota_opt_cmd_e¶

qosa_fota_mode_e¶

应用逻辑流程图¶

升级流程¶

示例代码¶

目录

本页