配置工具与 OTA 资源

本文档介绍 fw-AC630N_BT_SDK（AC630/1N 系列通用蓝牙 SDK）中的配置工具与 OTA（Over-The-Air）升级资源：包括 isd_config_app_ota.ini 配置文件的格式与含义、uboot/OTA 固件资源的组织方式、烧录与下载脚本的用法，以及 tools/ 目录下的构建工具链。

Purpose and Scope

本页覆盖以下内容：

• OTA 配置文件 cpu/bd29/tools/tool_resource/app_ota/isd_config_app_ota.ini 的完整字段解析（EXTRA_CFG_PARAM、SYS_CFG_PARAM、RESERVED_CONFIG、BURNER_CONFIG）；
• OTA 升级资源的构成（ota.bin、uboot_no_ota.boot、download_app_ota.bat）及其在 flash 分区中的布局；
• tools/ 目录下的构建/合并工具（Makefile.q32s、Makefile.bd29、do_merge_libs.bat）的定位。

以下主题属于其他目录页，不在本页展开：应用工程构建流程（参见应用/示例工程文档）、Zephyr RTOS 子系统、具体蓝牙协议栈实现（SPP/LE、HID、Mesh）。

说明：本文所有字段含义均来自仓库中实际存在的配置文件与资源清单；凡属文件名推断的内容均已明确标注。

Overview

fw-AC630N_BT_SDK 是杰理（Jieli）基于 Zephyr RTOS 的 AC630/1N 系列通用蓝牙固件 SDK，需要与 lib.a 及采用相同命名约定的仓库组合才能构建示例工程（SPP_LE、HID、Mesh）。SDK 同时支持 Codeblock（.cbp 工程）与 Makefile 两种构建方式。

在量产与开发阶段，固件需要两个关键支撑能力：

1. 配置工具：把芯片参数（时钟、SPI flash 接口、串口、产品标识 PID/VID、flash 分区）写入烧录/OTA 镜像。这些参数集中定义在 isd_config_app_ota.ini 中，由杰理的上位机工具（如烧录器/OTA 工具）解析。
2. OTA 资源：提供空中升级所需的引导资源（uboot）、升级镜像（ota.bin）与下载脚本（download_app_ota.bat），配合 flash 分区规划（BTIF/EXIF/VM/PRCT 等区域）实现固件在线升级。

配置数据按「长度 + 配置名字 + 数据」的 TLV（Type-Length-Value）风格存储（见配置文件头部注释），这使得上位机工具可以顺序解析任意长度的配置项，无需依赖固定偏移。

Architecture

flowchart TD
    subgraph sg_Tools["tools/ 构建工具链"]
        Q32S["Makefile.q32s (编译器封装)"]
        BD29["Makefile.bd29 (平台构建)"]
        MERGE["do_merge_libs.bat (库合并)"]
    end

    subgraph sg_Config["配置工具"]
        INI["isd_config_app_ota.ini<br/>配置数据源"]
        EXTRA["[EXTRA_CFG_PARAM]<br/>PID / VID / 入口地址"]
        SYS["[SYS_CFG_PARAM]<br/>SPI / 串口 / 时钟"]
        RESV["[RESERVED_CONFIG]<br/>Flash 分区表"]
        BURN["[BURNER_CONFIG]<br/>烧录参数"]
    end

    subgraph sg_OTA["OTA 资源 (cpu/bd29/tools)"]
        OTA_BIN["ota.bin (升级镜像)"]
        UBOOT["uboot_no_ota.boot<br/>引导程序(无OTA版)"]
        DL_BAT["download_app_ota.bat<br/>下载脚本"]
        UBOOT_DBG["uboot_no_ota.boot_debug<br/>调试引导"]
    end

    subgraph sg_Flash["目标芯片 Flash 分区"]
        BTIF["BTIF (蓝牙信息区)"]
        EXIF["EXIF (扩展信息区)"]
        PRCT["PRCT (代码区)"]
        VM["VM (虚拟管理区)"]
    end

    Q32S --> BD29
    BD29 --> MERGE
    MERGE --> OTA_BIN
    INI --> EXTRA
    INI --> SYS
    INI --> RESV
    INI --> BURN
    DL_BAT --> UBOOT
    DL_BAT --> OTA_BIN
    EXTRA --> PRCT
    RESV --> BTIF
    RESV --> EXIF
    RESV --> VM

架构说明：isd_config_app_ota.ini 是配置工具的单一数据源，上位机工具读取后生成烧录/OTA 镜像；cpu/bd29/tools/ 存放可直接用于烧录与升级的引导、镜像和脚本；tools/ 下则是构建期的编译/合并工具链。最终所有资源都会落到芯片 flash 的固定分区（BTIF/EXIF/PRCT/VM），分区表本身也由 RESERVED_CONFIG 段控制。

OTA 配置文件解析

核心配置文件位于 cpu/bd29/tools/tool_resource/app_ota/isd_config_app_ota.ini。其头部注释明确了存储约定——「配置数据按照 长度+配置名字+数据的方式存储」，即每条配置以长度前缀 + 名称 + 数据的形式串行编码，便于工具解析。

源文件：isd_config_app_ota.ini

[EXTRA_CFG_PARAM] — 扩展配置参数

该段定义产品的顶层标识与入口信息，是 OTA 升级匹配与跳转的基础：

PID 与 VID 是 OTA 升级匹配的关键：上位机工具按 PDCTNAME/PID 选择匹配的产品，按 VID 判断版本新旧（受 UPVR_CTL 约束）。

[SYS_CFG_PARAM] — UBOOT 系统配置

该段配置 uboot 阶段的硬件接口参数，注释明确要求「请勿随意调整顺序」，因为上位机工具按固定顺序解析：

[RESERVED_CONFIG] — Flash 空间分区表

该段是 OTA 下载时 flash 操作的依据。每个区域由 XXXX_ADR（起始地址）、XXXX_LEN（长度）、XXXX_OPT（操作属性）三个字段描述：

• ADR 取值 AUTO 表示由工具自动分配起始地址，0 表示从 0 开始，也支持 BEGIN_END 形式；
• LEN 取值 CODE_LEN 表示区域长度等于代码长度，或直接给出大小（如 24K）；
• OPT 操作符：0=下载代码时擦除指定区域；1=下载代码时不操作指定区域；2=下载代码时给指定区域加上保护。

当前配置声明的区域：

设计意图：PRCT 是唯一会被下载写入并加保护的区域；BTIF/EXIF/VM 在代码更新时保持不动，避免每次升级都擦除蓝牙配对信息（BTIF）和用户参数（VM）。

[BURNER_CONFIG] — 烧录配置

[BURNER_CONFIG]
SIZE=32;

SIZE=32 用于烧录器（burner）工具，表明烧录相关的容量/参数规模（如配置块大小），具体语义由上位机烧录工具解释。

OTA 资源与下载流程

cpu/bd29/tools/ 目录集中存放 AC630N 平台的 OTA/烧录相关资源：

资源清单见目录 cpu/bd29/tools；仓库根 README.md 说明了 SDK 的整体结构、工具链获取方式与示例工程（SPP_LE/HID/Mesh）。

OTA 升级决策流程

sequenceDiagram
    participant Tool as 上位机OTA工具
    participant INI as isd_config_app_ota.ini
    participant UBOOT as uboot (引导)
    participant Flash as 芯片Flash分区
    participant APP as 应用固件

    Tool->>INI: 读取 PID/VID/分区表
    Tool->>Flash: 下载引导资源 (uboot_no_ota.boot)
    Tool->>Flash: 按 RESERVED_CONFIG 规划区域
    Tool->>Flash: 写入代码到 PRCT (OPT=2 加保护)
    Flash-->>UBOOT: 复位启动
    UBOOT->>Flash: 校验 PRCT 代码区
    UBOOT->>APP: 跳转到 ENTRY (0x1e000E0)
    Note over APP: 启动后按 BOOT_FIRST 提示首次启动

升级匹配与版本控制

配置文件注释中还定义了 OTA 匹配与版本策略的语义，由上位机工具执行：

• PDCTNAME：产品名，用于升级时匹配产品；
• BOOT_FIRST：1=代码更新后提示 APP 是第一次启动；0=不提示；
• UPVR_CTL：0=不允许高版本升级低版本；1=允许。

这些字段与 PID/VID 共同构成 OTA 的安全边界：先匹配产品，再比较版本，最后决定是否允许降级。

构建工具链

tools/ 目录下的文件属于构建期工具，与 OTA 资源配合产出最终固件：

相关链接：Makefile.q32s、Makefile.bd29、do_merge_libs.bat

构建流程为：Makefile.q32s 提供编译器封装 → Makefile.bd29 执行平台构建 → do_merge_libs.bat 合并 SDK 库与工程代码 → 产出应用固件，最终通过 download_app_ota.bat/烧录器配合 isd_config_app_ota.ini 写入芯片。

使用示例

配置 OTA 镜像参数

以下是从仓库中提取的实际配置片段，展示了如何通过 EXTRA_CFG_PARAM 声明产品标识与入口地址，并通过 SYS_CFG_PARAM 固定 SPI flash 接口与 uboot 串口：

[EXTRA_CFG_PARAM]
NEW_FLASH_FS=YES;
CHIP_NAME=AC630N;//8
ENTRY=0x1e000E0;//程序入口地址
PID=AC630N_HID;//长度16byte,示例：芯片封装_应用方向_方案名称
VID=0.01;

源文件：isd_config_app_ota.ini

规划 Flash 分区

修改 RESERVED_CONFIG 段即可调整升级时各区域的擦除/保护行为。例如将 BTIF 设为 OPT=1 可保证升级不破坏蓝牙配对信息，PRCT 使用 OPT=2 为代码区加保护：

[RESERVED_CONFIG]
BTIF_ADR=AUTO;
BTIF_LEN=0x1000;
BTIF_OPT=1;

PRCT_ADR=0;
PRCT_LEN=CODE_LEN;
PRCT_OPT=2;

VM_ADR=0;
VM_LEN=24K;
VM_OPT=1;

源文件：isd_config_app_ota.ini

执行 OTA 下载

在 Windows 环境下，直接运行 cpu/bd29/tools/download_app_ota.bat 即可触发上位机 OTA 下载流程（脚本内容为调用下载工具，实际命令以仓库脚本为准）：

:: cpu/bd29/tools/download_app_ota.bat
:: 调用上位机下载工具，将 ota.bin + uboot 写入目标芯片

源文件：download_app_ota.bat

配置选项汇总

失败模式与边界情况

• 分区顺序依赖：SYS_CFG_PARAM 注释明确「请勿随意调整顺序」，上位机工具按固定顺序解析配置，调整字段顺序会导致参数错位。
• PID/VID 匹配失败：升级工具按 PID 匹配产品、按 VID 比较版本；若 UPVR_CTL=0，高版本固件无法回退到低版本，误写版本号可能导致无法升级。
• 代码区保护冲突：PRCT_OPT=2 在下载时给代码区加保护，若代码长度超过 CODE_LEN（固定值而非 CODE_LEN）或入口地址 ENTRY 与分区不匹配，可能造成写入失败或启动异常。
• SPI 参数错误：SPI=data_width,clk,mode 配置错误时 uboot 无法识别 flash（data_width=3 时才自动识别 2/4 线），将导致引导失败。
• 无 OTA 引导回退：仓库同时提供 uboot_no_ota.boot，当 OTA 升级反复失败时可烧录无 OTA 引导恢复，但该引导不支持在线升级，需配合串口/烧录器。

相关链接

• README.md（SDK 总览与工具链获取）
• isd_config_app_ota.ini（OTA 配置文件）
• download_app_ota.bat（OTA 下载脚本）
• tools/compiler/Makefile.q32s
• tools/platform/Makefile.bd29
• tools/utils/do_merge_libs.bat