烧录与固件升级工具

本文档系统介绍 fw-AC63_BT_SDK 的固件烧录与升级工具链：USB 升级工具（isd_download.exe）、生产烧写工具、无线测试盒、OTA 空中升级，以及驱动这些工具的 isd_config_rule.c 下载配置规则与 download.bat 下载脚本的完整工作流程。

Purpose and Scope

本页覆盖 AC63 系列蓝牙 SoC 从"编译产物"到"目标板运行"之间的所有环节：

• 烧录工具链的组成与分工（USB 升级工具 / 生产烧写工具 / 无线测试盒）；
• 首次烧录（强制升级）的完整操作流程与前置条件；
• 下载配置规则 isd_config_rule.c 生成的 isd_config.ini 的每一项配置含义；
• 按产品形态分发的下载脚本（download.bat / download.c）的执行机制；
• OTA（空中升级）在 SDK 中的支持形态（单备份 / 双备份）。

不在本页范围内的内容（由兄弟页面承载）：

• 编译指南（make 命令、工具链安装）：见 编译指南；
• SDK 功能裁剪配置（lib_*_config.c）：见 配置说明；
• OTA 应用层开发的完整细节（升级包生成、协议流程）：见 OTA 开发文档。

Overview

fw-AC63_BT_SDK 面向杰理（Jieli）AC63 系列蓝牙 SoC（AC632N/AC635N/AC636N/AC638N 等）。这类芯片内部集成 Flash，程序以 .hex 形式通过 USB 或 UART 烧入。与通用 MCU 的 JTAG/SWD 调试器不同，杰理方案采用自研 USB 升级工具 + loader 引导的烧录体系：

1. 编译工具链（JL Toolchain + clang）生成 app.bin、uboot.bin、loader.bin、ota.bin 等固件片段；
2. 下载工具 isd_download.exe 读取 isd_config.ini（由 isd_config_rule.c 编译生成）与这些固件片段；
3. 目标板进入编程模式（按住烧录按键复位上电）后，芯片 ROM 中的引导代码启动 USB/UART 下载协议；
4. 工具按配置将各固件片段布局写入 Flash 的对应区域，完成烧录。

整个烧录体系按使用场景分为三类工具：

三者共享同一套 Flash 分区布局与固件格式（flash.bin、ufw 升级包），但入口与链路不同：开发阶段走有线（USB/UART），产测阶段走无线（BLE/SPP OTA）。

架构总览

下图展示烧录与升级体系在 SDK 中的组件关系与数据流：

flowchart TD
    subgraph sg_Build["编译阶段"]
        TL["JL Toolchain / clang"]
        MAKEFILE["Makefile / Code::Blocks 工程"]
        BINS["app.bin / uboot.bin / loader.bin<br/>ota.bin / p11_code.bin"]
        FWADD["fw_add.exe / ufw_maker.exe<br/>生成 flash.bin / ufw 升级包"]
    end

    subgraph sg_Config["配置阶段"]
        RULE["isd_config_rule.c<br/>（各 CPU tools 目录）"]
        INI["isd_config.ini"]
        BAT["download.bat / download.c<br/>按产品形态分发"]
    end

    subgraph sg_Tools["烧录工具链"]
        ISD["USB 升级工具<br/>isd_download.exe"]
        BURNER["生产烧写工具<br/>（量产/裸片）"]
        TESTBOX["无线测试盒<br/>（OTA/产测）"]
    end

    subgraph sg_Target["目标设备"]
        ROM["芯片 ROM 引导<br/>（编程模式）"]
        LOADER["loader.bin 引导程序"]
        FLASH[("片内 Flash<br/>双备份/单备份分区")]
        APP["用户固件<br/>app.bin 运行"]
    end

    MAKEFILE --> TL
    TL --> BINS
    BINS --> FWADD
    RULE --> INI
    INI --> ISD
    BAT --> ISD
    BINS --> ISD
    ISD -->|"USB / UART"| ROM
    ROM --> LOADER
    LOADER --> FLASH
    BURNER -->|"工装夹具/USB"| FLASH
    TESTBOX -->|"蓝牙 OTA"| APP
    APP --> FLASH

架构要点解读：

• 配置即代码：烧录参数（下载模式、SPI 时序、Flash 布局、芯片 PID/VID 等）不是写死在工具里的，而是由 isd_config_rule.c 在编译期生成 isd_config.ini，工具启动时解析。这保证了"一个工具适配多个芯片平台"——每个 cpu/xx/tools/ 目录下都有一份独立的 isd_config_rule.c。
• loader 两段式引导：芯片 ROM 只负责最基础的 USB/UART 协议握手，真正的 Flash 擦写由 loader.bin 完成。这种设计把 Flash 驱动从 ROM 中解放出来，Flash 型号变更时只需更新 loader 而无需更换芯片。
• 有线/无线双通道：开发期用 isd_download.exe 走 USB/UART 全量烧录；量产与售后用 OTA 走蓝牙增量/全量升级。两条通道最终都写入同一份 Flash 分区布局，因此 flash_params.bin、uboot 等分区参数必须保持一致。

工具链详解

USB 升级工具（isd_download.exe）

USB 升级工具是开发阶段最常用的烧录入口，对应 README 中的"首次烧录"流程。它读取 isd_config.ini（下载规则）与编译产物（app.bin、loader.bin、uboot.bin、ota*.bin、p11_code.bin、flash_params.bin 等），通过 USB 或串口把固件写入目标板。

SDK 在 cpu/bd19/tools/download.c 中显式列出了参与下载的文件清单：

/* files="app.bin ${CPU}loader.* uboot*  ota*.bin p11_code.bin isd_config.ini isd_download.exe fw_add.exe ufw_maker.exe" */
files="app.bin ${CPU}loader.* uboot*  ota*.bin p11_code.bin isd_config.ini flash_params.bin"

Source: download.c

该清单揭示了烧录所需的最小文件集：loader.*（下载引导程序，后缀匹配不同 Flash 型号）、uboot*（启动引导）、ota*.bin（升级包）、p11_code.bin（11 号安全/校准代码段）、isd_config.ini（下载规则）以及 flash_params.bin（Flash 参数）。fw_add.exe 与 ufw_maker.exe 用于在编译阶段把多个 bin 片段合成为 flash.bin 或 ufw 升级包。

首次烧录的标准流程（来自 SDK 使用文档）：

1. 连接硬件：将开发板通过 USB 或 UART 连接到 PC；
2. 进入编程模式：按住开发板上的烧录按键，然后复位或重新上电——此时芯片 ROM 引导代码进入下载握手状态；
3. 打开 USB 升级工具：启动 isd_download.exe；
4. 选择固件：选择编译生成的 .hex 文件；
5. 开始烧录：点击下载按钮，等待烧录完成。

Source: README.md

设计意图：编程模式（按键 + 复位）而非自动检测，是为了让工具在芯片处于任意异常状态（固件跑飞、Flash 全空、分区损坏）时都能强制接管芯片——这就是该工具被称为"强制升级工具"的原因。ROM 中的下载协议不依赖用户固件是否正常运行，因此变砖的板子也能被救回。

下载脚本分发机制（download.bat / download.c）

cpu/<平台>/tools/ 目录下的 download.bat 是编译后一键烧录的入口脚本。它以 download.c 为模板按产品形态分发到不同的下载脚本：

call download/watch/download.bat
#elif defined(CONFIG_SOUNDBOX_CASE_ENABLE)
call download/soundbox/download.bat
#elif defined(CONFIG_EARPHONE_CASE_ENABLE)
call download/earphone/download.bat
#elif defined(CONFIG_HID_CASE_ENABLE) ||defined(CONFIG_SPP_AND_LE_CASE_ENABLE)||defined(CONFIG_MESH_CASE_ENABLE)||defined(CONFIG_DONGLE_CASE_ENABLE)    //数传
call download/data_trans/download.bat

Source: download.c

设计意图：手表（watch）、音箱（soundbox）、耳机（earphone）、数传（data_trans，含 HID/SPP+LE/Mesh/加密狗）四类产品的 Flash 分区布局与升级策略差异很大（例如耳机常用双备份 TWS 结构，音箱用单备份大分区），因此每个形态维护独立的下载脚本，避免在同一个脚本里堆叠大量条件分支。脚本分发由板级编译配置中的 CONFIG_*_CASE_ENABLE 宏决定——这再次体现了"编译期决定烧录行为"的 SDK 设计哲学：板级配置不仅决定固件内容，还决定烧录方式。

生产烧写工具与无线测试盒

• 生产烧写工具（Burner）：面向量产产线，支持一拖二/一拖多同时烧录，可对裸片（未贴片）或贴片后的芯片通过工装夹具编程。与 USB 升级工具的区别在于批量、自动化、以及支持 Flash 全片写入（含出厂校准参数区）。
• 无线测试盒（TestBox）：通过蓝牙与设备建立连接后执行空中升级（OTA）、射频标定（RF 校准）与整机功能测试，是产测阶段的"无线烧录器"。

三者共用同一套 Flash 布局定义，因此 isd_config_rule.c 中的分区参数（FLASH_SIZE、AREA_ALIGN 等）对三条链路同时生效。

下载配置规则（isd_config_rule.c）深入解析

cpu/<平台>/tools/isd_config_rule.c 是烧录体系的"配置即代码"核心：它在编译期被预处理器展开，生成 isd_config.ini，供 isd_download.exe 解析。所有配置项都以 CONFIG_* 宏定义，支持在板级 board_*_global_build_cfg.h 或编译命令行中被覆盖（#ifndef 保护），因此每个板级工程可以定制自己的烧录参数而无需修改公共代码。

下载模式与串口参数

#ifndef CONFIG_DOWNLOAD_MODEL
#define CONFIG_DOWNLOAD_MODEL                   USB                   //下载模式选择，可选配置USB\SERIAL
#endif

#ifndef CONFIG_DEVICE_NAME
#define CONFIG_DEVICE_NAME                      JlVirtualJtagSerial   //串口通讯的设备名(配置串口通讯时使用)
#endif

#ifndef CONFIG_SERIAL_BAUD_RATE
#define CONFIG_SERIAL_BAUD_RATE                 1000000               //串口通讯的波特率(配置串口通讯时使用)
#endif

#ifndef CONFIG_SERIAL_INIT_BAUD_RATE
#define CONFIG_SERIAL_INIT_BAUD_RATE            9600                  //串口通信初始化时通讯的波特率(配置串口通讯时使用)
#endif

#ifndef CONFIG_LOADER_BAUD_RATE
#define CONFIG_LOADER_BAUD_RATE                 1000000               //写入loader文件时通讯的波特率(配置串口通讯时使用)
#endif

#ifndef CONFIG_BREFORE_LOADER_WAIT_TIME
#define CONFIG_BREFORE_LOADER_WAIT_TIME         150                   //写入loader前延时时间(配置串口通讯时使用)
#endif

Source: isd_config_rule.c

设计意图：默认走 USB 下载模型（JlVirtualJtagSerial 是工具虚拟出的 JTAG 串口设备）；切到 SERIAL 模型时，一组串口参数生效，其中初始化波特率（9600）与 loader 写入波特率（1000000）分离——先用低波特率稳定握手，再切换到高速率传输大文件，这是串口升级的经典"慢启动、快传输"策略。CONFIG_BREFORE_LOADER_WAIT_TIME（150ms）为 loader 写入前的延时，用于等待目标板电源/时钟稳定。

SPI Flash 时序与端口

#ifndef CONFIG_SPI_DATA_WIDTH
#define CONFIG_SPI_DATA_WIDTH                   2                     //data_width[0 1 2 3 4] 3的时候uboot自动识别2或者4线
#endif

#ifndef CONFIG_SPI_CLK_DIV
#define CONFIG_SPI_CLK_DIV                      3                     //clk [0-255]
#endif

//mode:
//    0 RD_OUTPUT,      1 cmd    1 addr
//    1 RD_I/O,         1 cmd    x addr
//    2 RD_I/O_CONTINUE] no_send_cmd x add
#ifndef CONFIG_SPI_MODE
#define CONFIG_SPI_MODE                         0
#endif
//port:
//    0  优先选A端口  CS:PD3  CLK:PD0  D0:PD1  D1:PD2  D2:PB7  D3:PD5
//    1  优先选B端口  CS:PA13 CLK:PD0  D0:PD1  D1:PA14 D2:PA15 D3:PD5
#ifndef CONFIG_SPI_PORT
#define CONFIG_SPI_PORT                         0
#endif

Source: isd_config_rule.c

要点：CONFIG_SPI_DATA_WIDTH 控制 loader 与 Flash 之间的数据线宽度（1/2/4 线）；值为 3 时由 uboot 自动识别 2 线或 4 线 Flash——这使同一份固件能兼容不同封装/不同厂商的 Flash。CONFIG_SPI_PORT 在硬件允许时优先选择 A 或 B 端口引脚组，用于适配不同的 PCB 走线。这些参数直接写入 loader 的 Flash 驱动，是"换 Flash 不换烧录器"的关键。

芯片标识与 Flash 布局（[EXTRA_CFG_PARAM]）

[EXTRA_CFG_PARAM]
#if CONFIG_DOUBLE_BANK_ENABLE
BR22_TWS_DB = YES;		//dual bank flash framework enable
FLASH_SIZE = CONFIG_FLASH_SIZE;		//flash_size cfg
BR22_TWS_VERSION = 0; //default fw version
#if CONFIG_DB_UPDATE_DATA_GENERATE_EN
DB_UPDATE_DATA = YES; //generate db_update_data.bin
#endif
#else
NEW_FLASH_FS = YES;		//enable single bank flash framework
#endif 			//CONFIG_DOUBLE_BANK_ENABLE

#if CONFIG_ONLY_GRENERATE_ALIGN_4K_CODE
FORCE_4K_ALIGN = YES; // force aligin with 4k bytes
SPECIAL_OPT = 0;	  // only generate one flash.bin
#endif

#if ALIGN_UNIT_256B
AREA_ALIGN = ALIGN_UNIT_256B; //using n*256B unit for boundary alignment
#endif

CHIP_NAME = CONFIG_CHIP_NAME;
PID = CONFIG_PID;
VID = CONFIG_VID;
ENTRY = CONFIG_ENTRY_ADDRESS;

Source: isd_config_rule.c

要点：

• 双备份框架（BR22_TWS_DB = YES）：当板级使能 CONFIG_DOUBLE_BANK_ENABLE 时，Flash 划分为 A/B 两个 bank，配合 BR22_TWS_VERSION 固件版本号实现"备份升级"——升级失败自动回滚到旧 bank，这是耳机类产品 OTA 安全性的基础。
• 单备份框架（NEW_FLASH_FS = YES）：音箱/数传类产品使用单备份大分区，Flash 利用率高，但 OTA 需要整包替换。
• 对齐与安全：FORCE_4K_ALIGN 强制 4KB 对齐（便于 OTA 按扇区擦写）、AREA_ALIGN = ALIGN_UNIT_256B 以 256B 为最小对齐单元——对齐策略直接决定升级包能否按小粒度差分下载。
• 芯片身份：CHIP_NAME / PID / VID / ENTRY（程序入口地址，默认 0x1e00120）用于工具校验目标芯片与固件匹配，防止烧错固件导致硬件损坏。源码注释特别提醒"匹配的芯片版本请勿随意改动"。

串口交互与调试输出

#ifndef CONFIG_SERIAL_SEND_KEY
#define CONFIG_SERIAL_SEND_KEY                  YES                   //SERIAL_SEND_KEY：串口交互时数据是否需要进行加密(有效值：YES)
#endif

//uboot and ota.bin串口tx
#ifndef CONFIG_UBOOT_DEBUG_PIN
#define CONFIG_UBOOT_DEBUG_PIN                  PA05
#endif

//uboot and ota.bin串口波特率[EXTRA_CFG_PARAM]
#ifndef CONFIG_UBOOT_DEBUG_BAUD_RATE
#define CONFIG_UBOOT_DEBUG_BAUD_RATE            1000000
#endif

Source: isd_config_rule.c

CONFIG_SERIAL_SEND_KEY 决定串口下载交互数据是否加密（量产防抄板）；CONFIG_UBOOT_DEBUG_PIN / CONFIG_UBOOT_DEBUG_BAUD_RATE 指定 uboot 与 ota.bin 的调试串口 TX 引脚与波特率，供开发者观察引导阶段的运行日志。

OTA 升级（空中升级）

SDK 同时支持单备份与双备份两种蓝牙 OTA 升级形态（见 README 8.2 节）：

### 8.2 OTA 升级

支持单备份和双备份蓝牙 OTA 升级，详见：OTA 开发文档

Source: README.md

• 单备份 OTA：固件区只有一份 app.bin，升级时整包下载并替换，配合 NEW_FLASH_FS = YES 的单备份 Flash 框架；
• 双备份 OTA：A/B bank 交替运行与升级，配合 BR22_TWS_DB = YES，升级中断或校验失败时回滚到另一 bank，几乎不可能变砖。

OTA 升级链路（无线测试盒/手机 App → 蓝牙 → 设备）与有线烧录链路（USB 升级工具 → USB/UART → 设备）在 Flash 分区层汇合：fw_add.exe/ufw_maker.exe 生成的 ufw 升级包与 flash.bin 遵循同一套分区与对齐规则（AREA_ALIGN、FORCE_4K_ALIGN），保证两种升级方式产出的 Flash 布局完全一致。

核心流程：一次完整烧录

sequenceDiagram
    participant Dev as 开发者
    participant CB as Code::Blocks / Makefile
    participant RULE as isd_config_rule.c
    participant ISD as isd_download.exe
    participant ROM as 芯片 ROM 引导
    participant LDR as loader.bin
    participant FL as 片内 Flash

    Dev->>CB: 编译（Ctrl+F9 / make）
    CB->>CB: 生成 app.bin / uboot / loader / isd_config.ini
    RULE->>ISD: 编译期生成 isd_config.ini
    Dev->>Dev: 按住烧录键 + 复位，进入编程模式
    Dev->>ISD: 启动 isd_download.exe，选择 .hex
    ISD->>ROM: USB/UART 握手（枚举 JlVirtualJtagSerial）
    ROM-->>ISD: 握手成功
    ISD->>LDR: 按 isd_config.ini 写入 loader.bin（低速握手）
    LDR-->>ISD: loader 就绪（切换高速率）
    ISD->>FL: 按分区布局写入 app.bin / uboot / 参数区
    FL-->>ISD: 校验回读
    ISD-->>Dev: 烧录完成提示
    Dev->>Dev: 复位退出编程模式，固件启动

流程要点：

1. 编译期：isd_config_rule.c 与板级宏（CONFIG_*_CASE_ENABLE、CONFIG_DOUBLE_BANK_ENABLE 等）共同决定 isd_config.ini 内容——烧录行为在编译时就已确定；
2. 握手期：编程模式下芯片 ROM 枚举为 JlVirtualJtagSerial（USB 虚拟串口），工具以此识别目标板；
3. loader 阶段：先写入 loader.bin（串口模型下用 9600 波特率初始化，再切换 1M 波特率），loader 承担后续 Flash 驱动工作；
4. 写入阶段：按 [EXTRA_CFG_PARAM] 中的 FLASH_SIZE、AREA_ALIGN、双/单备份开关将各 bin 片段布局写入 Flash；
5. 校验阶段：工具回读校验，失败则报错并可重试，成功后才提示完成。

配置选项速查表

以下配置项定义于 isd_config_rule.c，均可用 #ifndef 覆盖机制在板级配置中定制：

isd_config.ini 最终输出项（[EXTRA_CFG_PARAM] 段）：CHIP_NAME、PID、VID、ENTRY、DOWNLOAD_MODEL、FLASH_SIZE、BR22_TWS_DB、BR22_TWS_VERSION、NEW_FLASH_FS、DB_UPDATE_DATA、FORCE_4K_ALIGN、SPECIAL_OPT、AREA_ALIGN 等，其中双/单备份开关（BR22_TWS_DB vs NEW_FLASH_FS）由板级 CONFIG_DOUBLE_BANK_ENABLE 互斥决定。

使用示例

示例一：编译后烧录（Code::Blocks 流程）

# 1. 进入对应的板级目录
cd apps/hid/board/bd19/

# 2. 双击打开 .cbp 工程文件（如 AC632N_hid.cbp）
# 3. 在 Code::Blocks 中点击 Build → Build (Ctrl+F9)
# 4. 编译成功后，使用 USB 升级工具烧录生成的 .hex 文件

Source: README.md

示例二：首次烧录五步法

1. 连接硬件：将开发板通过 USB 或 UART 连接到 PC
2. 进入编程模式：按住开发板上的烧录按键，然后复位或重新上电
3. 打开 USB 升级工具：启动 isd_download.exe
4. 选择固件：选择编译生成的 .hex 文件
5. 开始烧录：点击下载按钮，等待烧录完成

Source: README.md

示例三：定制下载模式为串口（板级覆盖）

在板级编译配置中（如 board_xxx_global_build_cfg.h）预定义宏即可覆盖默认值：

#define CONFIG_DOWNLOAD_MODEL        SERIAL   // 切换为串口下载模型
#define CONFIG_DEVICE_NAME           COM3     // 指定串口设备
#define CONFIG_SERIAL_BAUD_RATE      1000000  // 传输波特率 1M
#define CONFIG_SERIAL_INIT_BAUD_RATE 9600     // 初始化握手波特率

Source: isd_config_rule.c（基于其 #ifndef 覆盖机制）

示例四：按产品形态分发下载脚本

download.c 中的条件分发决定了实际执行的下载脚本，板级使能对应 CONFIG_*_CASE_ENABLE 宏即可切换：

call download/watch/download.bat
#elif defined(CONFIG_SOUNDBOX_CASE_ENABLE)
call download/soundbox/download.bat
#elif defined(CONFIG_EARPHONE_CASE_ENABLE)
call download/earphone/download.bat
#elif defined(CONFIG_HID_CASE_ENABLE) ||defined(CONFIG_SPP_AND_LE_CASE_ENABLE)||defined(CONFIG_MESH_CASE_ENABLE)||defined(CONFIG_DONGLE_CASE_ENABLE)    //数传
call download/data_trans/download.bat

Source: download.c

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

并发/一致性要点：烧录是"独占设备"操作——isd_download.exe 同一时刻只允许一个实例连接同一目标板；量产场景下应使用生产烧写工具的一拖多分组而非多开 USB 升级工具。双备份 OTA 依赖 BR22_TWS_VERSION 版本号仲裁，升级包与当前 bank 版本必须递增，否则会被视为无效升级。CONFIG_SERIAL_SEND_KEY 加密开启后，串口抓包无法直接分析协议，调试排障时注意区分。

性能与运维注意事项

• 传输速率：USB 模型下工具虚拟串口速率不受限；串口模型默认 1M 波特率，约为 100 KB/s，4MB Flash 全量烧录约需 40 秒，产线效率敏感时优先选用 USB 或生产烧写工具。
• Flash 对齐：FORCE_4K_ALIGN / AREA_ALIGN 直接影响 OTA 差分包大小与擦写次数，量产固件应保持 4KB 对齐以延长 Flash 寿命。
• 固件版本纪律：BR22_TWS_VERSION、升级包版本号、flash_params.bin 必须随每次发布同步更新，避免旧板误升新包。
• 工具更新：cpu/*/tools/下载目录工具更新.jlxproj 通过 fwadd、isddownload、ufwmaker 三个软件包管理工具链版本，升级工具时三者应保持一致版本，避免 fw_add.exe 生成的镜像格式与 isd_download.exe 不兼容。

扩展点

1. 新增产品形态：在 download.c 中增加 #elif defined(CONFIG_XXX_CASE_ENABLE) 分支并新建 download/xxx/download.bat，即可为新产品定制烧录流程。
2. 适配新 Flash：通过 CONFIG_SPI_DATA_WIDTH（自动识别 2/4 线）、CONFIG_SPI_CLK_DIV、CONFIG_SPI_MODE 与配套 loader.* 文件，无需修改烧录工具本体。
3. 板级覆盖配置：所有 CONFIG_* 均可用 #ifndef 机制在板级配置中覆盖，实现"一套工具、多种烧录策略"。
4. 产测集成：无线测试盒的 OTA 与射频标定可嵌入产线自动化脚本，与生产烧写工具形成"贴片前有线烧写 + 贴片后无线产测"的两段式产线。

相关链接

• 编译指南（工具链安装、make 命令）：2.3-编译指南
• SDK 功能裁剪与板级配置：2.5-配置说明
• 官方工具文档：USB 升级工具（强制升级）使用文档、下载脚本 INI 配置说明、生产烧写工具文档、无线测试盒文档
• 关键源文件：isd_config_rule.c（各 cpu/*/tools/ 下均有对应版本）、download.c、download.bat、README.md