# FOTA升级

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

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

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

```{note}
FOTA差分包和全量包均需配合对应工具使用，详情请参考 [FOTA工具使用教程](../../%E5%BC%80%E5%8F%91%E5%B7%A5%E5%85%B7/FOTA%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B/FOTA%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B.md#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处理器句柄。

- **函数原型**

```c
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下的历史文件<br>*QOSA_TRUE*：删除历史文件<br>*QOSA_FALSE*：不删除历史文件 |

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

### qosa_fota_deinit

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

- **函数原型**

```c
void qosa_fota_deinit(qosa_fota_t *fota)
```

- **参数说明**

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

- **返回值说明**  
  无

### qosa_fota_set_update_urc_num

- **功能描述**  
  设置升级所需的URC（通知）的数量。

- **函数原型**

```c
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包文件大小（用于断点续传/进度）。

- **函数原型**

```c
qosa_int64_t qosa_fota_get_current_file_size(qosa_fota_t *fota)
```

- **参数说明**

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

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

### qosa_fota_verify_image

- **功能描述**  
  对已下载的FOTA包进行完整性/签名校验。

- **函数原型**

```c
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包签名验证配置（是/否）。

- **函数原型**

```c
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签名验证  <br>*QOSA_FOTA_VERIFY_DISABLE*：禁用FOTA签名验证 |

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

### qosa_get_fota_verify_config

- **功能描述**  
  获取FOTA包签名验证配置（是/否）。

- **函数原型**

```c
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包写入要求。

- **函数原型**

```c
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数据包写入。

- **函数原型**

```c
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包名称。

- **函数原型**

```c
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包名称。

- **函数原型**

```c
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选项。

- **函数原型**

```c
qosa_fota_errno_e qosa_fota_set_opt(qosa_fota_opt_cmd_e cmd, void *param)
```

- **参数说明**

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

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

### qosa_fota_flag_set

- **功能描述**  
  设置升级标志。

- **函数原型**

```c
void qosa_fota_flag_set(void)
```

## 枚举定义

### qosa_fota_errno_e

结果码枚举定义如下：

```c
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签名枚举定义如下：

```c
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

枚举定义如下：

```c
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

枚举定义如下：

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

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

# 应用逻辑流程图

## 升级流程

```{image} images/board_T8nBwUG4eh40Qpb7SstcLqzHnsf.jpg
:width: 691px
:height: 950px
:align: center
```

# 示例代码

完整示例代码请查看

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