固件升级模块-物联网智能视频服务（消费版）-文档中心-腾讯云

功能介绍
本模块用于设备在线升级操作。用户使用本模块实现数据设备固件在线检查升级，本模块提供下载后的升级包，升级包写入设备操作由用户实现。
流程指引
主流程
注册 OTA 固件更新回调 > OTA 模块初始化 > OTA 模块去初始化
升级流程
收到固件更新回调 > 开始将固件数据写 flash > 发送固件更新进度
接口参考
该功能模块提供以下接口：
iv_ota_init：OTA 模块初始化。
iv_ota_exit：OTA 模块去初始化。
iv_ota_firmware_update_cb：固件更新回调。
iv_ota_update_progress：固件升级进度。
iv_ota_get_firmware_save_name_cb：SDK 获取本地存储 OTA 固件完整路径文件名回调。
iv_ota_init
接口描述
OTA 模块初始化。
int iv_ota_init(iv_ota_init_parm_s *pstInitParm) 
参数说明
参数名称
类型
描述
输入/输出
pstInitParm
iv_ota_init_parm_s *
OTA 模块初始化参数
输入
返回值
返回值
描述
IV_ERR_NONE
成功
IV_ERR_*
失败，对应相应错误码
iv_ota_exit
接口描述
OTA 模块去初始化。
int iv_ota_exit(void);
参数说明
无
返回值
返回值
描述
IV_ERR_NONE
成功
IV_ERR_*
失败，对应相应错误码
iv_ota_firmware_update_cb
接口描述
固件更新回调。此接口由 SDK 回调给应用层，携带已经下载固件所保存文件的路径，文件长度信息，所更新的固件保存在内存中，应用层在收到此回调后使用本文件进行升级操作。
int (* iv_ota_firmware_update_cb)(int8_t *pFirmwarePath, uint64_t u32FirmwareLen); 
参数说明
参数名称
类型
描述
输入/输出
pFirmwarePath
int8_t *
固件绝对路径
输入
u32FirmwareLen
uint64_t
固件大小
输入
返回值
返回值
描述
IV_ERR_NONE
成功
IV_ERR_*
失败，对应相应错误码
iv_ota_update_progress
接口描述
固件升级的进度。
int iv_ota_update_progress(int value); 
参数说明
参数名称
类型
描述
输入/输出
value
int
更新进度值：
[-30,30]为 SDK 内存使用。 [-30,0]表示下载过程中的错误，详见 iv_ota_progress_e， [0,30]对应下载进度[0,100]
其他值为用户可自定义使用
输入
返回值
返回值
描述
IV_ERR_NONE
成功
IV_ERR_*
失败，对应相应错误码
iv_ota_get_firmware_save_name_cb
接口描述
1. SDK 在下载固件时从应用层获取固件下载存储在本地的完整路径文件名。如果提供的路径是可用的则会存储在该路径，如果该路径不可用则会通过 iv_ota_update_progress 传输错误到 App 端。
2. 如果应用层不想指定该路径，则无需注册该回调函数，SDK 会根据系统初始化时传入的 cache 路径 iv_sys_init->stSysInitParameters.s8PubCachePath 来合成最后固件存储的完整路径。
3. 如非必要建议不设置该回调。
int32_t (* iv_ota_get_firmware_save_name_cb)(uint8_t firmware_name[IV_OTA_LOCAL_FILE_NAME_MAX_LEN],uint32_t name_buff_len);
参数说明
参数名称
类型
描述
输入/输出
firmware_name
uint8_t*
完整的文件名及其绝对路径 eg:/temp/app_upg.bin
输出
name_buff_len
uint32_t
firmware_name buff 的最大长度，文件路径不可超过该限制
输入
返回值
返回值
描述
IV_ERR_NONE
成功
IV_ERR_*
失败，对应相应错误码
数据结构
该模块提供以下数据结构：
iv_ota_init_parm_s：OTA 模块初始化参数结构体。
iv_ota_progress_e：OTA 模块升级时的进度和错误枚举。
iv_ota_init_parm_s
OTA 模块初始化参数结构体。
typedef struct iv_ota_init_parm_s
{
     /* start update firmware callback */
    void (* iv_ota_firmware_update_cb)(char * firmware_name, uint64_t firmware_len);
    /* get local firmware file full path name of ota downlaod save */
    int32_t (* iv_ota_get_firmware_save_name_cb)(uint8_t firmware_name[IV_OTA_LOCAL_FILE_NAME_MAX_LEN],uint32_t name_buff_len);
}iv_ota_init_parm_s;
参数说明
成员名称
描述
取值
iv_ota_firmware_update_cb
开始更新固件回调
略
iv_ota_get_firmware_save_name_cb
获取下载ota固件存储全路径回调(非必要注册)
略
iv_ota_progress_e
OTA 模块升级时的进度和错误枚举。
typedef enum iv_ota_progress_e{
﻿
    /* custom: <-30 */
    /*
        IV_OTA_ERR_UPGRADE_*
     */
    /* download progress err : sdk set[-30,0) */
    IV_OTA_FILE_SIZE_TOO_SAMLL      = -1,
    IV_OTA_FILE_SIZE_TOO_BIG        = -2,
    IV_OTA_FILE_SAVE_FAIL           = -3,
    IV_OTA_FILE_CREATE_FAIL         = -4,
    IV_OTA_URL_NOT_EXIST            = -5,
    IV_OTA_CONNECT_SERVER_FAIL      = -6,
    IV_OTA_REQUEST_DOWNLOAD_FAIL    = -7,
    IV_OTA_FILE_DOWNLOAD_TIME_OUT   = -8,
    IV_OTA_APP_REJECT_UPGRADE       = -9,
    IV_OTA_MODULE_BUSY              = -10,
    IV_OTA_MODULE_EXIT              = -11,
    /* download progress: sdk set[0,30]->file download[0%,100%] */
    IV_OTA_FILE_DOWNLOAD_0          = 0,
    /* 
        IV_OTA_FILE_DOWNLOAD_progress....
    */
    IV_OTA_FILE_DOWNLOAD_100        = 30,/
    /* custom: >30 */
    /*
        IV_OTA_FILE_UPGRADE_*
     */
}iv_ota_progress_e;
参数说明
成员名称
描述
取值
IV_OTA_ERR_UPGRADE_
其他升级错误
<-30
IV_OTA_FILE_SIZE_TOO_SAMLL
OTA 文件下载不完整，和预期长度不符，过小
-1
IV_OTA_FILE_SIZE_TOO_BIG
OTA 文件下载出错，和预期长度不符，过大
-2
IV_OTA_FILE_SAVE_FAIL
保存本地 OTA 文件失败（需要检查空间是否充裕）
-3
IV_OTA_FILE_CREATE_FAIL
创建 OTA 文件失败（需要检查目录是否可写）
-4
IV_OTA_URL_NOT_EXIST
OTA 文件 URL 不存在（是否预先进行了升级检查，是否有更新的版本可供更新）
-5
IV_OTA_CONNECT_SERVER_FAIL
连接 OTA 文件资源服务器失败
-6
IV_OTA_REQUEST_DOWNLOAD_FAIL
请求下载 OTA 文件失败
-7
IV_OTA_FILE_DOWNLOAD_TIME_OUT
长时间未收到新的数据（socket 读超时）
-8
IV_OTA_APP_REJECT_UPGRADE
应用层拒绝了本次升级
-9
IV_OTA_MODULE_BUSY
OTA 模块忙无法进行升级
-10
IV_OTA_MODULE_EXIT
OTA 模块已经退出无法进行升级
-11
IV_OTA_FILE_DOWNLOAD_0
文件开始下载
0
IV_OTA_FILE_DOWNLOAD_100
文件下载成功
30
IV_OTA_FILE_UPGRADE_
文件升级的进度
>30
代码示例
1. OTA 模块初始化
iv_err_code_e eErrCode = 0;
iv_ota_init_parm_s stUpgradeInitParm;
memset(&stUpgradeInitParm,0,sizeof(iv_ota_init_parm_s));
stUpgradeInitParm.iv_ota_firmware_update_cb = upgrade_firmware_update;
stUpgradeInitParm.iv_ota_get_firmware_save_name_cb = get_firmware_save_name;
﻿
eErrCode = iv_ota_init(&stUpgradeInitParm);
if(eErrCode < 0)
{
        GDB_INFO("fail:%d.\\n",eErrCode);
        return eErrCode;
}
2. OTA 模块去初始化
iv_err_code_e eErrCode = 0;
eErrCode = iv_ota_exit();
if(eErrCode < 0)
{
        GDB_INFO("fail:%d.\\n", eErrCode);
        return eErrCode;
}
﻿
3. OTA 升级
void upgrade_firmware_update(char *pFirmwarePath, uint64_t u32FirmwareLen)
{
        /*read firmware data and write flash*/
        FILE *fpFirmware = NULL;
        fpFirmware = fopen(pFirmwarePath, "rb");
        if(!fpFirmware)
        {
            GDB_ERR("fopen %s fail.\\n", pFirmwarePath);
            iv_ota_update_progress(IV_OTA_PROGRESS_TYPE_FAIL, IV_OTA_FAIL_TYPE_OPEN_FILE);
            return;
        }
﻿
        fseek(fpFirmware, 0, SEEK_END);
        if(u32FirmwareLen != ftell(fpFirmware))
        {
            GDB_ERR("%s real size is wrong, u32FirmwareLen:%lld, fileLen:%ld.\\n", pFirmwarePath, u32FirmwareLen, ftell(fpFirmware));
            iv_ota_update_progress(IV_OTA_PROGRESS_TYPE_FAIL, IV_OTA_FAIL_TYPE_WRONG_SIZE);
            fclose(fpFirmware);
            fpFirmware = NULL;
            return;
        }	
        /*执行升级...*/
        /*发送升级进度*/
        fclose(fpFirmware);
        usleep(600000);
        fpFirmware = NULL;
        /*demo模拟升级进度*/
        iv_ota_update_progress(50);
        usleep(1000000);
        iv_ota_update_progress(100);
        usleep(1000000);
﻿
        return;
}
﻿
参数名称	类型	描述	输入/输出
pstInitParm	iv_ota_init_parm_s *	OTA 模块初始化参数	输入
返回值	描述
IV_ERR_NONE	成功
IV_ERR_*	失败，对应相应错误码
成员名称	描述	取值
iv_ota_firmware_update_cb	开始更新固件回调	略
iv_ota_get_firmware_save_name_cb	获取下载ota固件存储全路径回调(非必要注册)	略
固件升级模块

本页目录：

功能介绍

流程指引

主流程

升级流程

接口参考

iv_ota_init

iv_ota_exit

iv_ota_firmware_update_cb

iv_ota_update_progress

iv_ota_get_firmware_save_name_cb

数据结构

iv_ota_init_parm_s

iv_ota_progress_e

代码示例

1. OTA 模块初始化

2. OTA 模块去初始化

3. OTA 升级
