7.8 OTA 远程升级组件

学习阁2026/7/19大约 6 分钟常用组件组件OTA固件升级IoT

7.8 OTA 远程升级组件

📚 本节导读

学习时长：约 30 分钟
难度级别：⭐⭐⭐☆☆
前置知识：第 7.2 节网络协议栈、Flash 分区概念

🎯 学习目标

理解 OTA 差分升级的原理和优势
掌握 cmiot API 的使用方法
了解三种下载方案（general/cms/ctwing）
学会配置 OTA 组件和打包固件
能够排查常见升级错误

一、OTA 概述

OTA（Over The Air，远程升级） 通过无线网络实现固件升级。OneOS OTA 组件位于 components/ota/cmiot/，README.md 提供了完整的 API 说明和打包命令，Kconfig 配置位于同目录。核心源文件 source/ 下包含 cmiot 升级逻辑和 LUSUN/Wosun 差分算法实现。采用差分升级方式，可极大降低升级包大小。

1.1 系统架构

┌─────────────────────────────────────────┐
│              OTA 云平台                   │
│  版本管理 │ 差分包制作 │ 推送策略         │
└──────────────────┬──────────────────────┘
                   │ HTTP / CoAP
┌──────────────────┴──────────────────────┐
│           OneOS 设备端                    │
│  ┌────────────────┐ ┌────────────────┐  │
│  │   BootLoader   │ │   App (固件)    │  │
│  │  - 固件还原     │ │  - 更新检测     │  │
│  │  - 固件升级     │ │  - 固件下载     │  │
│  │  - 安全校验     │ │  - 版本校验     │  │
│  └────────────────┘ └────────────────┘  │
└─────────────────────────────────────────┘

1.2 差分算法支持

算法	RAM 要求	适用场景
LUSUN	较小	资源受限设备（默认）
Wosun LOW	> 200KB	中等资源设备
Wosun HIGH	> 512KB	高资源设备
Luckpand	按需	多文件差分升级

1.3 芯片支持情况

STM32F091 / STM32F103 / STM32F407 / STM32F429 / STM32F469 / STM32F767 / STM32F769 / STM32L475 / STM32F496 等均支持 LUSUN 差分算法。

二、核心 API

2.1 API 列表

API	说明	调用方式
`cmiot_get_network_type()`	获取网络类型	无需调用（OTA 自动调用）
`cmiot_get_uniqueid()`	获取设备 MID（最大 30 字节）	无需调用
`cmiot_app_name()`	获取 APP 分区名	无需调用
`cmiot_download_name()`	获取 DOWNLOAD 分区名	无需调用
`cmiot_printf()`	日志输出接口	无需调用（可重写）
`cmiot_msleep()`	延时接口	无需调用（可重写）
`cmiot_reboot_device()`	重启设备	无需调用（可重写）
`cmiot_upgrade()`	开始检测并下载固件包	用户调用
`cmiot_report_upgrade()`	上报升级结果	用户调用
`cmiot_upgrade_slave()`	从设备开始检测下载	多设备方案
`cmiot_report_upgrade_slave()`	从设备上报升级结果	多设备方案

2.2 核心函数详解

/* 开始检测下载固件包 */
cmiot_int8 cmiot_upgrade(void);

返回值	含义
`E_CMIOT_SUCCESS`	有包且下载成功
`E_CMIOT_FAILURE`	下载失败
`E_CMIOT_NOT_INITTED`	OTA 组件初始化失败（内存不够）
`E_CMIOT_LAST_VERSION`	没有新的固件包

/* 上报升级结果 */
cmiot_int8 cmiot_report_upgrade(void);

返回值	含义
`E_CMIOT_SUCCESS`	有升级结果且上报成功
`E_CMIOT_FAILURE`	有升级结果但上报失败
`E_CMIOT_NO_UPGRADE`	没有升级结果
`E_CMIOT_NOT_INITTED`	OTA 组件初始化失败

三、下载方案

3.1 三种方案对比

方案	下载方式	适用场景
general	HTTP / CoAP 直连 OTA 平台	直接对接 OTA 平台
cms	通过 CMS 中转	已使用 CMS 平台的设备
ctwing	通过 Ctwing 转发（仅 CoAP）	使用 Ctwing 平台的设备

3.2 设备类型

类型	说明
单设备	独立设备，自行检测和下载升级
多设备-主设备	负责检测下载，协调从设备升级
多设备-从设备	接收主设备指令，执行升级

四、Kconfig 配置

4.1 Boot 配置

(Top) → Drivers → Boot → CORTEX-M Boot → Board boot configure
    (0x08000000) text section addr      # APP 代码起始地址
    (0x00080000) text section size      # APP 代码区大小
    (0x20000000) data section addr      # 数据区起始地址
    (0x00008000) data section size      # 数据区大小

4.2 OTA 组件配置

(Top) → Components → OTA → Fota by CMIOT
    [*] Enable fota by cmiot
        The supported device type (single device)  --->
        The supported download solution (general)  --->
        The supported network protocol (Http)  --->
        The supported algorithm (Lusun)  --->
    (200)   The network timeout              # 网络超时(ms)
    (3)     Segment size index               # 分块大小索引

4.3 平台相关配置

(cmiot_cd)          Oem                  # OEM 标识
(F103RE)            Model                # 设备型号
(1593394730)        Product id           # 产品 ID
(e7f48e3ea...)     Product secret       # 产品密钥
(box)               Device type          # 设备类型
(STM32F1)           Platform             # 平台名称
(5.0)               Firmware version     # 固件版本号

注意：Firmware version 改变后编译会生成对应版本的软件包，可在 OTA 平台上传制作差分包。

五、固件打包命令

5.1 打包命令格式

# 单 axf 文件打包
cmiot_pack.bat <fromelf路径> <压缩软件路径> oneos_config.h <axf文件路径>

# 单 bin 文件打包
cmiot_pack.bat <压缩软件路径> oneos_config.h <bin文件路径>

# 多 bin 文件打包
cmiot_pack.bat <压缩软件路径> oneos_config.h <bin文件夹路径>

5.2 打包示例

# 使用 fromelf + WinRAR 打包
..\..\components\ota\cmiot\source\pack\cmiot_pack.bat ^
    "D:\Keil_v5\ARM\ARMCC\bin\fromelf.exe" ^
    "C:\Program Files\WinRAR\WinRAR.exe" ^
    oneos_config.h ^
    build\keil\Obj\oneos.axf

# 使用 WinRAR 打包 bin 文件
..\..\components\ota\cmiot\source\pack\cmiot_pack.bat ^
    "C:\Program Files\WinRAR\WinRAR.exe" ^
    oneos_config.h ^
    ..\..\out\stm32l475-atk-pandora\oneos.bin

注意：压缩软件支持 WinRAR.exe 和 7z.exe。路径需替换为个人电脑实际路径。

六、使用示例

#include <cmiot_user.h>

/* 单设备 OTA 升级示例 */
void ota_upgrade_task(void)
{
    cmiot_int8 ret;

    /* 检测并下载固件包 */
    ret = cmiot_upgrade();
    if (ret == E_CMIOT_SUCCESS) {
        os_kprintf("Firmware downloaded, rebooting...\r\n");
        cmiot_reboot_device();  /* 下载成功，重启升级 */
    } else if (ret == E_CMIOT_LAST_VERSION) {
        os_kprintf("Already the latest version\r\n");
    } else {
        os_kprintf("Upgrade failed: %d\r\n", ret);
    }

    /* 上报升级结果 */
    ret = cmiot_report_upgrade();
    if (ret == E_CMIOT_SUCCESS) {
        os_kprintf("Upgrade result reported\r\n");
    }
}

七、常见错误码

错误码	含义	排查建议
1001	项目 ID 与平台不一致	检查 Product id 配置
1002	项目不存在	检查 Oem/Model/Device type/Platform 配置
1005	Flash 操作失败	检查 Flash 驱动和硬件
1008	MID 长度错误	MID 需 4-31 个字符
1010	设备访问上限	单日访问量达到上限
1015	用户访问上限	所属用户单日访问量达到上限
2001	签名不对	检查 Product secret，擦除 Flash 下载分区
2101	没有新版本	当前已是最新版本
2103	设备未注册	擦除 Flash 下载分区

八、FAQ

Q：OTA 组件资源占用大吗？
A：FLASH 占用 9KB 以内，RAM 占用 3KB 以内（含 RW、ZI、堆、栈）。

Q：cmiot_upgrade() 该怎么调用？
A：OTA 组件只提供机制，策略由用户决定。可以每天检测一次，也可以每周检测一次；可以下载完就重启升级，也可以等业务完成再重启。

Q：调用超时怎么办？
A：在 menuconfig 中修改 The network timeout，适当增大超时时间。

Q：下载中断后需要重新下载吗？
A：不需要，支持断点续传，会从中断处继续下载。

📝 本节小结

本节介绍了 OneOS OTA 远程升级组件：

差分升级：支持 LUSUN/Wosun/Luckpand 三种算法，大幅减小升级包
三种方案：general（直连）/ cms（CMS 中转）/ ctwing（Ctwing 转发）
核心 API：cmiot_upgrade() 检测下载，cmiot_report_upgrade() 上报结果
配置要点：Boot 分区、设备类型、下载方案、差分算法、平台参数
断点续传：下载中断后从断点继续，无需重新下载