OTA 升级机制

本页面介绍 fw-AC630N_BT_SDK 中的 OTA（Over-The-Air）固件升级机制：从升级参数在内存中的定义与写入、下载引擎的初始化，到升级结果的上报、校验与用户提示，以及配套的 PC 工具链与配置文件。

Purpose and Scope

本页面覆盖 AC630N 蓝牙 SDK 中与设备端 OTA 升级相关的完整机制，包括：

• 升级参数块 UPDATA_PARM 的内存布局与 CRC16 完整性校验
• apps/common/update/update.c 中的参数写入（updata_parm_set）、结果读取（update_result_get/set）与结果处理（update_result_deal）
• 基于 RCSP 私有协议的无线升级下载引擎初始化（rcsp_user_update.c）
• 各应用工程（apps/hid、apps/spp_and_le 等）中的 update_loader_download_init 启动入口
• 升级类型（SD 卡、U 盘、BLE/SPP 空中升级、双 Bank）与结果码语义
• PC 端工具链（cpu/bd29/tools/ 下的 download_app_ota.bat、ota.bin、isd_config_app_ota.ini）

以下内容属于其他页面，不在本页展开：RCSP 协议本身的帧格式与命令字定义（参见协议栈相关页面）、TWS 对耳同步升级细节（update_tws.c 相关页面）、Boot/uboot 的启动流程（引导程序相关页面）。

概述

OTA 升级机制是嵌入式蓝牙设备（耳机、音箱、键鼠、对讲机等）在量产之后获取固件更新的核心通道。AC630N SDK 的升级链路遵循"参数传递 + 重启切换"的设计思路：

1. 升级的入口多种多样：SD 卡/U 盘本地升级、BLE 或 SPP 空中升级（RCSP 协议）、TWS 对耳升级等；
2. 所有入口最终都通过 updata_parm_set() 把升级意图写入位于固定地址 UPDATA_FLAG_ADDR 的 UPDATA_PARM 结构体，并附带 CRC16 校验；
3. 设备复位后由 Boot（uboot/loader）读取该参数块，判断是否需要进入升级流程、从哪个通道取固件（如 /*.UFW 文件或空中下载的数据）；
4. 升级完成后 Boot 把结果码写回 UPDATA_PARM，应用固件通过 update_result_get() 读取并做成功/失败提示，最后软关机或复位。

这种"共用一块内存参数、以 CRC 保障一致性、以重启作为状态切换点"的设计，把不同升级通道统一到了同一条升级路径上，是理解整个机制的关键。

架构

flowchart TD
    subgraph sg_Entry["升级入口层"]
        SD["SD 卡 / U 盘升级<br/>CONFIG_SD_UPDATE_ENABLE<br/>CONFIG_USB_UPDATE_ENABLE"]
        RCSP["RCSP 空中升级<br/>rcsp_user_update.c<br/>BLE_APP_UPDATA / SPP_APP_UPDATA"]
        TWS["TWS 对耳升级<br/>update_tws.c"]
    end

    subgraph sg_Core["核心升级模块 apps/common/update/update.c"]
        SetParm["updata_parm_set()<br/>写入 UPDATA_PARM + CRC16"]
        GetResult["update_result_get()<br/>读取结果 + CRC16 校验"]
        Deal["update_result_deal()<br/>语音/LED 提示 + 软关机"]
        LoaderInit["update_loader_download_init()<br/>下载引擎初始化"]
    end

    subgraph sg_Flag["参数交换区"]
        Parm["UPDATA_PARM @ UPDATA_FLAG_ADDR<br/>type / result / file_patch / parm_priv / ota_addr / crc"]
    end

    subgraph sg_Boot["Boot 引导层"]
        Boot["uboot / loader<br/>读取参数块 → 执行升级 → 写回结果"]
        Flash["内部 Flash / OTA 分区"]
    end

    subgraph sg_Tools["PC 工具链 cpu/bd29/tools"]
        Bat["download_app_ota.bat"]
        Ini["isd_config_app_ota.ini"]
        Bin["ota.bin / uboot_no_ota.boot"]
    end

    SD --> SetParm
    RCSP --> SetParm
    TWS --> SetParm
    SetParm --> Parm
    Parm --> Boot
    Boot --> Flash
    Boot --> Parm
    Parm --> GetResult
    GetResult --> Deal
    RCSP --> LoaderInit
    LoaderInit --> Flash
    Bat --> Ini
    Ini --> Bin

架构说明：

• 升级入口层：SD 卡、U 盘、RCSP 空中升级（BLE/SPP）、TWS 对耳升级都是"发起者"。它们各自有独立的握手/文件读取逻辑，但最终都会收敛到 updata_parm_set() 写入参数块。
• 核心升级模块（update.c）：负责参数块的读写与结果处理。它不关心固件从哪里来，只负责"把升级意图可靠地交给 Boot"和"把升级结果可靠地带回应用"。
• 参数交换区：UPDATA_PARM 位于固定地址 UPDATA_FLAG_ADDR，是应用与 Boot 之间唯一的契约。parm_crc 字段用 CRC16 保护除校验值本身以外的全部字段，防止半写状态被误判。
• Boot 引导层：uboot/loader 在复位后读取参数块，依据 parm_type 决定升级通道，完成固件写入后写回 parm_result（如 UPDATA_SUCC）。
• PC 工具链：download_app_ota.bat + isd_config_app_ota.ini 负责把编译产物打包成 Boot 可直接识别的 OTA 固件（ota.bin），并生成无 OTA 的 uboot 镜像。

核心实现详解

UPDATA_PARM 参数块：应用与 Boot 的契约

所有升级通道共用同一个参数结构 UPDATA_PARM，存放在宏 UPDATA_FLAG_ADDR 指向的固定内存地址（定义于 update.h）。参数块包含升级类型、结果码、固件文件路径、私有参数、OTA 地址以及 CRC16 校验值。

UPDATA_PARM *p = UPDATA_FLAG_ADDR;
u16 crc_cal;
crc_cal = CRC16(((u8 *)p) + 2, sizeof(UPDATA_PARM) - 2);	//2 : crc_val
if (crc_cal && crc_cal == p->parm_crc) {
    ret =  p->parm_result;
}

Source: update.c

设计意图：CRC16 从 parm_crc 之后开始计算，即保护除校验值本身之外的所有字段。读取方只有在校验通过时才信任 parm_result，否则视为无效（返回 UPDATA_NON）。这一机制保证了"写入一半时断电"等场景不会让设备误判升级结果。

升级参数写入：updata_parm_set()

所有升级入口调用 updata_parm_set(UPDATA_TYPE up_type, void *priv, u32 len) 将升级意图登记到参数块。核心逻辑如下：

void updata_parm_set(UPDATA_TYPE up_type, void *priv, u32 len)
{
    UPDATA_PARM *p = UPDATA_FLAG_ADDR;
    u8 addr[6];
#ifdef UPDATE_LED_REMIND
    led_update_start();
#endif
    memset((u8 *)p, 0x00, sizeof(UPDATA_PARM));
    p->parm_type = (u16)up_type;
    p->parm_result = (u16)UPDATA_READY;
    memcpy(p->file_patch, updata_file_name, strlen(updata_file_name));
    if (priv) {
        memcpy(p->parm_priv, priv, len);
    } else {
        memset(p->parm_priv, 0x00, sizeof(p->parm_priv));
        if (up_type == BLE_TEST_UPDATA) {
            extern int le_controller_get_mac(void *addr);
            le_controller_get_mac(addr);
            memcpy(p->parm_priv, addr, 6);
        }
    }
#if (USE_SDFILE_NEW == 1)
    p->magic = UPDATE_PARAM_MAGIC;
    p->ota_addr = loader_start_addr;
#endif
    p->parm_crc = CRC16(((u8 *)p) + 2, sizeof(UPDATA_PARM) - 2);	//2 : crc_val
    ...
}

Source: update.c

要点说明：

• parm_result 先置为 UPDATA_READY，表示"升级已登记、等待 Boot 执行"；
• file_patch 写入全局升级文件名 updata_file_name[] = "/*.UFW"，即升级文件必须是短文件名（8+3）结构、支持两层目录、扩展名为 .UFW（见 update.c 第 52-54 行）；
• 当 priv 为空且类型为 BLE_TEST_UPDATA 时，自动读取 BLE 控制器 MAC 地址写入 parm_priv，供 Boot 侧过滤目标设备；
• USE_SDFILE_NEW == 1 时写入 UPDATE_PARAM_MAGIC 魔数与 loader_start_addr（由 set_loader_start_addr() 设置），Boot 据此知道 OTA 固件应写入的 Flash 地址；
• 最后统一计算 CRC16 封口，保证参数块的一致性。

升级结果读写：update_result_get() / update_result_set()

升级结束后 Boot 会调用（或等效于）update_result_set() 把结果码写回参数块，应用侧通过 update_result_get() 读取：

void update_result_set(u16 result)
{
    UPDATA_PARM *p = UPDATA_FLAG_ADDR;
    memset(p, 0x00, sizeof(UPDATA_PARM));
    p->parm_result = result;
    p->parm_crc = CRC16(((u8 *)p) + 2, sizeof(UPDATA_PARM) - 2);
}

Source: update.c

update_result_get() 在返回结果的同时把 g_updata_flag 置为"结果码 + magic<<16"，并立即清零参数块（memset(p, 0x00, sizeof(UPDATA_PARM))），避免同一次开机重复消费升级结果。clr_update_ram_info() 则是显式清空参数块的辅助函数。

首启判断与结果处理

升级完成后第一次上电，应用通过 device_is_first_start() 判断是否需要走"升级结果提示"流程：

bool device_is_first_start()
{
    log_info("g_updata_flag=0x%x\n", g_updata_flag);
    if ((g_updata_flag & DEVICE_FIRST_START) || (g_updata_flag & DEVICE_UPDATE_KEY_ERR) || (g_updata_flag == UPDATA_SUCC)) {
        return true;
    }
    return false;
}

Source: update.c

其中 DEVICE_UPDATE_KEY_ERR = BIT(30)（升级密钥错误）、DEVICE_FIRST_START = BIT(31)（首次启动）定义于 update.c 第 50-51 行。

update_result_deal() 是结果提示的主流程：根据结果码播放提示音（TONE_SIN_NORMAL）、控制 LED 闪烁（PWM_LED0_LED1_FAST_FLASH），并在循环中持续喂狗（wdt_clear）防止看门狗复位，约 5 个周期后 break 退出并调用 enter_sys_soft_poweroff() 软关机：

while (1) {
    clear_wdt();
    key_voice_cnt++;
    if (result == UPDATA_SUCC) {
        app_audio_set_volume(APP_AUDIO_STATE_WTONE, get_max_sys_vol() / 2, 1);
        tone_play(TONE_SIN_NORMAL, 1);
        os_time_dly(25);
    } else {
        log_info("!!!!!!!!!!!!!!!updata waring !!!!!!!!!!!=0x%x\n", result);
        tone_play(TONE_SIN_NORMAL, 1);
        os_time_dly(25);
    }
    if (key_voice_cnt > 5) {
        key_voice_cnt = 0;
        puts("enter_sys_soft_poweroff\n");
        break;
    }
}

Source: update.c

设计意图：升级失败时不直接死循环或立即关机，而是通过有限次数的提示（约 5 次）让用户感知结果，随后进入软关机，避免设备因升级异常长期驻留在异常状态。LED 提示通过 UPDATE_LED_REMIND 宏开关，语音提示通过 UPDATE_VOICE_REMIND 宏开关，二者均可裁剪以减小固件体积。

下载引擎与升级入口

系统级初始化入口

每个应用工程（apps/hid/misc.c、apps/spp_and_le/misc.c 等）在系统初始化阶段调用 update_loader_download_init() 注册下载引擎；bt_lmp_update_loader_download_init() 则用于 LMP 层的更新。这保证了在任何升级通道被触发之前，下载引擎已经就绪：

void update_loader_download_init(void)
{
    // 注册升级下载引擎，供 RCSP / 本地升级共用
    // 具体实现在 lib 层（update_loader_download 库）
}

Source: misc.c (apps/hid) 与 misc.c (apps/spp_and_le)

RCSP 空中升级下载初始化

RCSP（Real-time Control and Status Protocol）是杰理私有协议，手机 App 通过 BLE 或 SPP 与设备建立连接后即可发起固件升级。rcsp_user_update.c 根据当前连接类型选择不同的下载模式并注册结果回调：

if (RCSP_BLE == get_curr_device_type()) {
    rcsp_update_loader_download_init(BLE_APP_UPDATA, rcsp_loader_download_result_handle);
} else if (RCSP_SPP == get_curr_device_type()) {
    rcsp_update_loader_download_init(SPP_APP_UPDATA, rcsp_loader_download_result_handle);
}

Source: rcsp_user_update.c

对于支持双 Bank 镜像的设备，则注册块级固件接收回调并采用 DUAL_BANK_UPDATA 模式，实现"下载新 Bank、失败回滚旧 Bank"的 A/B 升级：

register_receive_fw_update_block_handle(rcsp_update_handle);
rcsp_update_loader_download_init(DUAL_BANK_UPDATA, rcsp_loader_download_result_handle);

Source: rcsp_user_update.c

设计意图：rcsp_update_loader_download_init(mode, callback) 把"下载模式"与"结果处理回调"解耦——下载引擎只负责按模式接收/写入数据块，回调 rcsp_loader_download_result_handle 负责把最终结果（成功/失败）通过 update_result_set() 等机制落盘，供重启后应用侧感知。

升级类型汇总

SD 升级时 updata_parm_set() 会把 sdmmc_get_update_parm() 返回的升级参数追加拷贝到参数块之后的 UPDATE_PRIV_PARAM_LEN 区域；U 盘升级则将该区域清零（见 update.c 第 218-238 行）。

核心流程

一次典型的 RCSP BLE 空中升级从 App 发起到设备重启完成，时序如下：

sequenceDiagram
    participant App as 手机 App (RCSP)
    participant Engine as 下载引擎<br/>rcsp_user_update.c
    participant Core as update.c 核心模块
    participant Parm as UPDATA_PARM @ UPDATA_FLAG_ADDR
    participant Boot as Boot / uboot
    participant Flash as 内部 Flash

    App->>Engine: BLE 连接 + RCSP 升级握手
    Engine->>Engine: rcsp_update_loader_download_init(BLE_APP_UPDATA, cb)
    Engine->>Flash: 按数据块写入 OTA 分区 (loader_start_addr)
    Engine-->>App: 下载完成应答
    Engine->>Core: 回调 rcsp_loader_download_result_handle
    Core->>Parm: updata_parm_set(BLE_APP_UPDATA) + CRC16
    Core->>Device: 复位/软关机
    Device->>Boot: 重启
    Boot->>Parm: 校验 CRC16，读取 parm_type / ota_addr
    Boot->>Flash: 从 OTA 分区搬运固件到运行区
    Boot->>Parm: update_result_set(UPDATA_SUCC) 写回结果
    Device->>Core: 二次上电
    Core->>Parm: update_result_get() 读取并清零参数块
    Core->>Core: device_is_first_start() == true
    Core->>User: 提示音 / LED 提示 (UPDATA_SUCC)
    Core->>Device: enter_sys_soft_poweroff() 软关机

SD 卡本地升级的流程与上图类似，区别在于：入口变为"插入含 /*.UFW 文件的 SD 卡并触发按键/事件"，updata_parm_set(SD0_UPDATA/SD1_UPDATA) 写入参数块后同样依靠重启进入 Boot 执行，固件来源从 OTA 分区变为 SD 卡文件系统。

配置选项

OTA 升级机制通过编译期宏控制功能裁剪，相关配置分散在 app_config.h、lib_config 及各工程头文件中：

注意：UPDATA_PARM 中 file_patch、parm_priv 的容量以及 UPDATE_PARAM_MAGIC 的值由 update.h 定义，修改时需保证与 Boot 侧（uboot）完全一致，否则会出现"应用写入、Boot 无法识别"的兼容性问题。

API 参考

u16 update_result_get(void)

读取上次升级结果，校验 CRC16 通过后返回 parm_result，并将参数块清零防止重复消费。返回 UPDATA_NON 表示无升级记录或校验失败。

参数： 无

返回：

• UPDATA_SUCC：升级成功
• 其他错误码：升级失败的具体原因
• UPDATA_NON：无有效升级记录

副作用： 清零 UPDATA_FLAG_ADDR 处的整个参数块；设置全局 g_updata_flag。

Source: update.c

void update_result_set(u16 result)

把升级结果码写入参数块并重新计算 CRC16。通常由 Boot 侧在升级完成后调用（应用侧也可用于测试注入）。

参数：

• result (u16)：结果码，如 UPDATA_SUCC

返回： 无

Source: update.c

void updata_parm_set(UPDATA_TYPE up_type, void *priv, u32 len)

登记一次升级：清空参数块、写入升级类型与 UPDATA_READY 状态、复制文件路径与私有参数、写入 magic/ota_addr、计算 CRC16。所有升级入口（SD/USB/RCSP/BLE 产测）的统一汇聚点。

参数：

• up_type (UPDATA_TYPE)：升级类型（SD0_UPDATA、SD1_UPDATA、USB_UPDATA、BLE_APP_UPDATA、SPP_APP_UPDATA、DUAL_BANK_UPDATA、BLE_TEST_UPDATA）
• priv (void*)：私有参数指针；为 NULL 时若类型为 BLE_TEST_UPDATA 则自动写入 BLE MAC
• len (u32)：priv 的长度

返回： 无

Source: update.c

bool device_is_first_start(void)

判断当前是否为升级完成后的首次启动（DEVICE_FIRST_START、DEVICE_UPDATE_KEY_ERR 或 UPDATA_SUCC 任一命中即返回 true），用于决定是否播放升级结果提示。

返回： true 表示需要走升级结果处理流程。

Source: update.c

int update_result_deal(void)

升级结果提示主流程：按结果播放提示音/闪烁 LED，循环喂狗约 5 次后软关机。返回 1 表示已处理，0 表示无升级结果可处理（UPDATA_NON）。

返回： int（1=已处理；0=无结果）

Source: update.c

void set_loader_start_addr(u32 addr)

设置 OTA 固件在 Flash 中的下载起始地址，写入 loader_start_addr 静态变量，供 updata_parm_set() 填到参数块的 ota_addr 字段。

参数：

• addr (u32)：OTA 分区起始地址

Source: update.c

void update_loader_download_init(void) / void bt_lmp_update_loader_download_init(void)

各应用工程系统初始化阶段调用，注册下载引擎（普通应用升级 / LMP 层升级）。

参数： 无

Source: misc.c (apps/spp_and_le)

rcsp_update_loader_download_init(mode, result_cb)

RCSP 模块按连接类型初始化下载引擎并注册结果回调，模式为 BLE_APP_UPDATA / SPP_APP_UPDATA / DUAL_BANK_UPDATA，回调为 rcsp_loader_download_result_handle。

Source: rcsp_user_update.c

失败模式、边界情况与并发

参数块半写与 CRC 防护

UPDATA_PARM 在写入过程中若发生断电/复位，parm_crc 与内容不一致。update_result_get() 的 CRC16 校验会直接判为无效并返回 UPDATA_NON，从而避免把"未完成的写入"当作"升级成功/失败"。这是整个机制的第一道安全防线。

升级结果重复消费防护

update_result_get() 在读取后立即 memset 清零参数块，保证同一次开机只消费一次结果；即使应用异常重启，也不会重复播放成功提示。clr_update_ram_info() 提供显式清空手段。

看门狗与长时间等待

update_result_deal() 的结果提示循环依赖 clear_wdt()（wdt_clear）持续喂狗。若该循环因音量获取、tone_play 阻塞等原因卡死，看门狗会触发复位——这是有意的"最后兜底"，避免设备永久驻留在提示状态。循环在 key_voice_cnt > 5 时退出并软关机，因此提示时间是有上限的。

升级密钥错误与首次启动

DEVICE_UPDATE_KEY_ERR (BIT(30)) 用于标识升级密钥校验失败（防伪/防刷机场景），DEVICE_FIRST_START (BIT(31)) 标识出厂首次启动。二者与 UPDATA_SUCC 一样都会触发 device_is_first_start() 返回 true，但结果码不同，提示逻辑可据此区分"成功"与"异常"。

多入口竞争

SD/USB 本地升级与 RCSP 空中升级若在相近时刻被触发，最终都写入同一个 UPDATA_PARM。updata_parm_set() 先 memset 再写入，因此"后写者胜"；不存在并发读写保护，设计上要求上层（App/协议栈）在同一时刻只允许一个升级通道处于活动状态。

文件系统与路径约束

升级文件路径固定为 "/*.UFW"（短文件名 8+3、最多两层目录）。若用户把固件放在深层目录或使用长文件名，Boot 侧 FATFS 将无法找到文件，升级会静默失败并在结果码中体现。SD 升级依赖 CONFIG_FATFS_ENBALE，未使能时 sdmmc_get_update_parm() 返回空，私有参数区会被清零。

性能与运维注意事项

• 升级时机关闭外设：DEV_UPDATE_SUPPORT_JUMP 使能时，升级前需调用 save_spi_port()、sd1_unmount()、usb_sie_close_all() 并跳转 MaskROM，避免 Flash 操作与 SD/USB 访问冲突。
• 分区一致性：ota_addr（loader_start_addr）必须与 isd_config_app_ota.ini 中规划的 OTA 分区地址一致，否则固件会被写入错误区域导致变砖风险。
• 空中升级吞吐：RCSP 空中升级按数据块写入，吞吐受 BLE/SPP 链路 MTU 与 Flash 擦写速度制约；DUAL_BANK_UPDATA 模式通过写入备份 Bank 降低失败风险，代价是占用双倍 Flash 空间。
• 产线工具：cpu/bd29/tools/download_app_ota.bat 配合 isd_config_app_ota.ini 生成 ota.bin；uboot_no_ota.boot 为不带 OTA 功能的 uboot 镜像（量产默认烧录，可省 Flash 空间）。
• 日志标签：升级模块使用 LOG_TAG "[UPDATE]"（update.c 第 22 行），排障时通过串口日志过滤 [UPDATE]、device_is_first_start、update_result_deal 即可快速定位升级链路状态。

工具链与构建产物

相关链接

• update.c（核心升级模块）
• rcsp_user_update.c（RCSP 空中升级下载）
• misc.c（apps/hid，升级引擎初始化入口）
• misc.c（apps/spp_and_le，升级引擎初始化入口）
• lib_update_config.c（apps/hid，升级库配置）
• download_app_ota.bat（PC 端 OTA 下载脚本）
• isd_config_app_ota.ini（OTA 配置）

提示：RCSP 协议的帧格式/命令字细节属于协议栈其他页面；TWS 对耳同步升级（update_tws.c）与 Boot 引导细节请参见对应目录页。