固件后处理与配置工具

固件后处理与配置工具是 AW33N BLE SDK 中负责"编译产物 → 可烧录固件"的关键环节：构建系统在链接出 sdk.elf 后调用 download.bat / download.sh 等后处理脚本，借助 isd_download.exe、fw_add.exe 等烧录工具完成固件打包与下载，同时通过 AW33N_config_tool（杰理配置工具）把产品配置（如默认配置、提示音等）以 Lua 工程的形式编译成 cfg_tool.c/h、default_cfg.fw 等固化数据，随固件一起烧录。

Purpose and Scope

本页面向"固件后处理与配置工具"这一能力域，覆盖：

• 构建系统（Makefile）如何集成后处理脚本（Windows 的 download.bat 与 Linux 的 download.sh）；
• 后处理/烧录脚本的组成与 isd_download.exe 烧录命令的用法；
• AW33N_config_tool 配置工具工程的目录结构（conf/entry 的 Lua 配置入口与 conf/output 的生成产物）；
• 编译期与后处理共用的配置宏（*_global_build_cfg.h）。

不涉及的部分（属于其他目录页）：芯片底层库、预编译静态库（apps/include_lib/liba/bd57/flash/*.a）的细节请参阅对应章节；BLE 协议栈与各应用（HID 键盘/鼠标/遥控器）行为见各自页面；量产工具的完整 INI 配置说明以杰理官方文档为准（见相关链接）。

概述

在典型的嵌入式 SDK 开发流程中，make 只负责把源码编译链接成 ELF，而"烧录"需要把 ELF 转换为目标板可识别的镜像（app.bin、cfg_tool.bin、cmac.bin），并打包成升级文件（update.ufw）或直接通过 USB/串口下载到 Flash。AW33N SDK 把这一整套流程集中放在 apps/app/post_build/bd57/ 目录，由 Makefile 在链接完成后自动触发，形成"编译 → 后处理 → 下载"的闭环。

同时，产品化的固件还需要携带配置数据（默认配置、蓝牙功耗档位、提示音等）。SDK 引入了一个与工程绑定的配置工具 AW33N_config_tool，它以杰理配置工具工程（.jlxproj）为载体，通过 Lua 脚本描述配置项，最终输出供固件编译期引用的 cfg_tool.c/h 与烧录期使用的 default_cfg.fw。

关键设计意图：

1. 平台自适应：Makefile 通过 OS 变量区分 Windows/Linux，分别选择 download.bat 或 download.sh，并针对 Windows 的 bat 编码问题引入 fixbat.exe 做 UTF-8 → GBK 转换；
2. 配置与代码分离：配置以 Lua 描述、以 C 头文件固化，运行时配置项与固件逻辑解耦，便于工具链统一处理；
3. 产物标准化：后处理统一产出 app.bin、cfg_tool.bin、cmac.bin 与 update.ufw，适配 isd_download.exe 的 NOR Flash 下载流程。

架构

flowchart TD
    subgraph sg_Build["构建系统 (Makefile)"]
        MAKE["make / make clean"]
        LINK["链接 sdk.elf<br/>apps/app/post_build/bd57/sdk.elf"]
    end

    subgraph sg_PostBuild["后处理与烧录 (apps/app/post_build/bd57)"]
        BAT["download.bat (Windows)"]
        SH["download.sh (Linux)"]
        ISD["isd_download.exe"]
        FWADD["fw_add.exe"]
        INI["isd_config_ini.c / INI 配置"]
        UFW["产物: app.bin / cfg_tool.bin /<br/>cmac.bin / update.ufw"]
    end

    subgraph sg_CfgTool["配置工具 (AW33N_config_tool)"]
        PROJ["AW33N_配置工具入口(Config Tools Entry).jlxproj"]
        ENTRY["conf/entry/*.lua<br/>fw_create / fw_edit / ufw_edit /<br/>user_cfg / bluetooth_powerprofile"]
        OUTPUT["conf/output/*<br/>cfg_tool.c / cfg_tool.h /<br/>default_cfg.fw / extra_tones/*.wtg"]
    end

    subgraph sg_Toolchain["工具链与库"]
        FIXBAT["tools/utils/fixbat.exe"]
        CFGLIB["include_lib/liba/bd57/flash/cfg_tool_lib.a"]
        BOARDCfg["board_aw33n_*_global_build_cfg.h"]
    end

    MAKE --> LINK
    LINK -->|"RUN_POST_SCRIPT"| BAT
    LINK -->|"bash download.sh"| SH
    FIXBAT -->|"utf8->gbk 编码修复"| BAT
    BAT --> ISD
    SH --> ISD
    FWADD --> INI
    ISD --> UFW
    PROJ --> ENTRY
    ENTRY --> OUTPUT
    OUTPUT -->|"cfg_tool.bin / default_cfg.fw"| ISD
    BOARDCfg -->|"编译期与后处理共用宏"| MAKE
    CFGLIB -->|"链接进固件"| LINK

架构说明：

• 构建系统层：apps/demo/hid/board/bd57/Makefile 是总入口。它负责设置工具链、编译参数、链接参数，并把 sdk.elf 输出到 apps/app/post_build/bd57/sdk.elf（见 Makefile#L63），链接后触发后处理脚本。
• 后处理与烧录层：download.bat（Windows）与 download.sh（Linux）调用 isd_download.exe 执行 NOR Flash 烧录/打包；fw_add.exe 等工具配合 isd_config_ini.c 描述的 INI 配置工作。
• 配置工具层：AW33N_config_tool 是独立的配置工具工程，Lua 入口脚本定义配置逻辑，输出目录生成固件编译期和烧录期需要的文件。
• 支撑组件：fixbat.exe 解决 Windows 批处理编码问题；cfg_tool_lib.a 在链接期把配置读取能力编入固件；*_global_build_cfg.h 中的宏同时影响编译与后处理行为（见 board_aw33n_demo_global_build_cfg.h#L6）。

主内容

构建系统对后处理的集成

apps/demo/hid/board/bd57/Makefile 在文件头部按平台分别定义后处理脚本。Windows 分支（OS = Windows_NT）如下：

## 后处理脚本
FIXBAT          := ../../../../../tools/utils/fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := ../../../../../apps/app/post_build/bd57/download.bat
RUN_POST_SCRIPT := ..\\..\\..\\..\\..\\apps\\app\\post_build\\bd57\\download.bat

Source: Makefile

Linux 分支则把 FIXBAT 置为 touch（Linux 下不存在 bat 编码问题），并改用 bash 执行 download.sh：

## 后处理脚本
FIXBAT          := touch # Linux下不需要处理 bat 编码问题
POST_SCRIPT     := ../../../../../apps/app/post_build/bd57/download.sh
RUN_POST_SCRIPT := bash $(POST_SCRIPT)

Source: Makefile

设计意图：同一套应用源码（HID 键盘/鼠标/遥控器）需要跨 Windows/Linux 构建。Makefile 用 POST_SCRIPT 描述脚本路径、用 RUN_POST_SCRIPT 描述实际执行方式，把"后处理"抽象成构建流程的固定步骤，同时通过 FIXBAT 屏蔽平台间批处理编码差异。

输出文件被直接定位到后处理目录，保证脚本与 ELF 产物同目录工作：

# 输出文件设置
OUT_ELF   := ../../../../../apps/app/post_build/bd57/sdk.elf
OBJ_FILE  := $(OUT_ELF).objs.txt

Source: Makefile

链接参数中显式包含 cfg_tool_lib.a，说明配置工具生成的代码以静态库形式参与链接（见 Makefile#L361），这是配置数据在固件内生效的载体。

下载/烧录脚本 download.bat 与 download.sh

后处理目录 apps/app/post_build/bd57/ 同时维护 Windows 批处理与 Linux Shell 两个版本。其中 download.bat 的核心烧录命令为：

isd_download.exe -tonorflash -dev bd57 -div8 -wait 300 -uboot uboot.boot -app app.bin -res cfg_tool.bin cmac.bin -output-ufw update.ufw

Source: download.bat

该命令表达的关键信息：

• -tonorflash：目标介质为 NOR Flash；
• -dev bd57：目标芯片平台 BD57；
• -div8：时钟分频参数（与 Flash 读时序相关）；
• -wait 300：下载等待时间（毫秒级参数）；
• -uboot uboot.boot：uboot 引导镜像；
• -app app.bin：应用固件；
• -res cfg_tool.bin cmac.bin：资源区包含配置工具数据块与 cmac（认证/校验）块；
• -output-ufw update.ufw：同时产出用于升级的 UFW 打包文件。

README 将该目录定位为"烧录工具"集：download.bat、fw_add.exe、isd_download.exe 等（见 README.md#L226）。其中 isd_config_ini.c 描述的 INI 配置决定下载脚本的详细行为，官方说明见下载脚本配置文档（README 引用见 README.md#L304）。

AW33N 配置工具（AW33N_config_tool）

配置工具以工程文件 AW33N_配置工具入口(Config Tools Entry).jlxproj 为入口，内部按"输入配置（entry）→ 输出产物（output）"组织：

Source: AW33N_config_tool 目录

设计意图：把"产品配置"从"应用代码"中剥离。Lua 脚本负责描述配置项与生成逻辑，输出 C 代码（cfg_tool.c/h）供固件在编译期直接使用，输出 default_cfg.fw 供烧录期写入 Flash 默认区，同时 extra_tones 以 *.wtg 格式固化提示音——一套配置入口同时服务编译、烧录、音频三个消费方。

编译期与后处理共用的配置宏

各板级目录下的 *_global_build_cfg.h 头文件明确标注其宏"同时影响编译期与后处理期"：

/* Following Macros Affect Periods Of Both Code Compiling And Post-build */

Source: board_aw33n_demo_global_build_cfg.h

同目录还维护 board_aw33n_mouse_global_build_cfg.h、board_aw33n_mouse_m143_global_build_cfg.h、board_aw33n_rc_global_build_cfg.h 等，分别对应 HID 演示、鼠标、鼠标 M143、遥控器方案。这类宏是"后处理与配置"作用于具体产品形态的入口：构建系统读取这些宏决定烧录/打包行为，应用代码也依赖它们裁剪功能。

核心流程

sequenceDiagram
    participant Dev as 开发者
    participant Make as Makefile
    participant Link as 链接器 (lto-wrapper)
    participant PS as download.bat / download.sh
    participant ISD as isd_download.exe
    participant Tool as AW33N_config_tool
    participant Out as 烧录/升级产物

    Dev->>Make: make (或 make download)
    Make->>Make: 读取 *_global_build_cfg.h 配置宏
    Make->>Link: 编译 + 链接 (含 cfg_tool_lib.a)
    Link-->>Make: sdk.elf → post_build/bd57/
    Make->>PS: 执行 RUN_POST_SCRIPT
    PS->>ISD: isd_download.exe -tonorflash -dev bd57 ...
    Tool-->>PS: cfg_tool.bin / default_cfg.fw / extra_tones
    ISD->>Out: app.bin + cfg_tool.bin + cmac.bin
    ISD->>Out: update.ufw (升级包)
    Out-->>Dev: 烧录/升级完成

流程要点：

1. 开发者执行 make，Makefile 先依据 OS 选择 Windows/Linux 分支，并读取板级 *_global_build_cfg.h 确定编译与后处理宏；
2. 编译链接完成后，sdk.elf 输出到 apps/app/post_build/bd57/，与下载脚本、配置工具产物同目录；
3. 链接期已包含 cfg_tool_lib.a，固件具备读取配置数据的能力；
4. RUN_POST_SCRIPT 触发 download.bat（Windows，先经 fixbat.exe 修正编码）或 bash download.sh（Linux）；
5. 脚本调用 isd_download.exe，把 uboot.boot、app.bin、cfg_tool.bin、cmac.bin 组装，产出 update.ufw 并执行下载；
6. 其中 cfg_tool.bin 来自配置工具输出，实现"配置即资源"的固化。

使用示例

示例 1：Windows 下完整后处理命令

download.bat 中的核心烧录命令，可直接在命令行复现（需保证 isd_download.exe 在 PATH 或同目录）：

isd_download.exe -tonorflash -dev bd57 -div8 -wait 300 -uboot uboot.boot -app app.bin -res cfg_tool.bin cmac.bin -output-ufw update.ufw

Source: download.bat

示例 2：Makefile 中切换后处理脚本

开发者若要在 Linux 上构建并下载，无需改动脚本本身——Makefile 已按平台选择执行器：

FIXBAT          := touch # Linux下不需要处理 bat 编码问题
POST_SCRIPT     := ../../../../../apps/app/post_build/bd57/download.sh
RUN_POST_SCRIPT := bash $(POST_SCRIPT)

Source: Makefile

示例 3：确认链接期携带配置能力

若需确认固件是否包含配置工具支持，检查链接参数中是否出现 cfg_tool_lib.a：

../../../../../apps/include_lib/liba/bd57/flash/cfg_tool_lib.a

Source: Makefile

配置选项

Makefile 后处理相关变量

isd_download.exe 烧录参数（来自 download.bat 实际调用）

说明：以上参数取自 download.bat 中的实际调用；完整参数集与 INI 配置语义请参考杰理下载脚本配置文档。

API 参考

isd_download.exe <options>

后处理烧录工具的命令行入口，负责把多个镜像组装为 NOR Flash 布局并执行下载/打包。参数说明见上方配置表。返回码语义由工具自身定义，建议在脚本中检查退出码以判断烧录成败。

fixbat.exe <input.bat>

Windows 批处理编码修复工具，将 UTF-8 编码的 bat 脚本转换为 GBK，避免中文路径/注释在 cmd 下乱码。由 FIXBAT 变量在构建流程中调用（见 Makefile#L31）。

配置工具工程 AW33N_配置工具入口(Config Tools Entry).jlxproj

杰理配置工具（JL Config Tool）工程文件，在 GUI 中打开后即可编辑固件配置。其行为由 conf/entry/*.lua 驱动，产物输出到 conf/output/（见 AW33N_config_tool 目录）。各 Lua 入口的具体函数签名需在工具运行时加载，本仓库未包含其调用约定文档，具体实现细节请直接查看对应 Lua 源文件。

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

平台差异导致的失败

• bat 编码乱码：Windows 下若跳过 fixbat.exe（FIXBAT），中文注释或带中文的路径可能以 UTF-8 写入 bat，导致 cmd 解析乱码、命令执行失败。Makefile 在 Windows 分支强制使用 fixbat.exe 正是为此（见 Makefile#L31）。
• Linux 工具链缺失：Makefile 头部注释明确要求从 http://pkgman.jieliapp.com/doc/all 下载工具链并解压到 /opt/jieli，保证 /opt/jieli/common/bin/clang 存在，否则 CC/LD 找不到会直接报错（见 Makefile#L6-L11）。
• 文件描述符不足：注释提示 ulimit -n 需大于 8096，否则链接阶段（LTO）可能因打开文件过多失败——这是 LTO + 大静态库集合下的典型 Linux 边界条件。

烧录阶段失败

• USB 升级工具连接异常：README 明确警告"烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式"（见 README.md#L303）。isd_download.exe 的 -wait 300 参数即用于容忍设备枚举/就绪延迟；连接失败时应优先检查设备枚举与编程模式，而非脚本本身。
• 资源区不完整：-res 同时指定 cfg_tool.bin 与 cmac.bin，若配置工具未先运行导致 cfg_tool.bin 缺失，烧录会失败或产出不含配置的固件。因此配置工具产物应视为后处理的前置依赖。

并发与一致性

• 后处理脚本与配置工具共享 conf/output/ 目录：若在配置工具运行时同时执行 make download，可能读到半写状态的 cfg_tool.bin/default_cfg.fw。建议以 cfg_tool_state_complete.lua 作为配置完成标记，保证"先配置、后烧录"的顺序（该文件即配置工具生成的完成状态文件，见 conf/output 目录）。
• 多个 make 实例并发构建同一 OUT_ELF（sdk.elf）会产生写冲突；SDK 未在 Makefile 中内置锁，量产构建环境应串行化后处理步骤。

性能与运维注意事项

• LTO 全程序优化：CFLAGS 同时出现 -flto、-Oz、-Os 与 -O0（最终优化级由链接阶段决定），并配合 --plugin-opt=save-temps 保留中间文件，便于排查"优化后符号丢失"类问题。全量链接耗时较长，增量开发建议只重新链接而非清理重建（make clean 会清除全部临时文件）。
• 产物管理：sdk.elf、app.bin、cfg_tool.bin、update.ufw 均落在 apps/app/post_build/bd57/ 下，该目录同时是脚本、配置工具与 ELF 的汇聚点。CI 中应把该目录作为固件产物目录整体归档。
• 编码与换行：Windows 侧维护 download.bat 时须经 fixbat.exe 处理；若在 Linux 上编辑后提交，注意行尾（CRLF）与编码一致性，避免批处理执行异常。

扩展点

• 新增芯片平台：仿照 bd57 目录新建 apps/app/post_build/bdXX/，提供对应的 download.bat/download.sh、uboot.boot、fw_add.exe/isd_download.exe 变体，并在板级 Makefile 中替换 POST_SCRIPT 与 -dev 参数即可接入同一构建流程。
• 新增产品方案：复制 board_aw33n_*_global_build_cfg.h，调整其中的编译/后处理宏，并在 apps/demo/hid/board/bd57/ 下新增板级文件与 Makefile，实现"一套后处理框架，多产品配置"。
• 扩展配置项：在 AW33N_config_tool/conf/entry/ 中新增 Lua 脚本（或在 user_cfg.lua 中追加配置项），重新运行配置工具后即刷新 cfg_tool.c/h 与 default_cfg.fw；提示音类资源放入 extra_tones/（*.wtg）即可随资源区烧录。
• 定制烧录流程：修改 download.bat/download.sh 中 isd_download.exe 参数（如去掉 -output-ufw 只做直烧，或调整 -wait），可适配产线/调试两种场景。

相关链接

• apps/demo/hid/board/bd57/Makefile — 构建与后处理集成的源头
• apps/app/post_build/bd57/download.bat — 烧录脚本核心命令
• apps/app/post_build/bd57/AW33N_config_tool — 配置工具工程（entry Lua 与 output 产物）
• apps/demo/hid/board/bd57/board_aw33n_demo_global_build_cfg.h — 编译期与后处理共用宏
• README.md — 仓库目录结构说明（烧录工具定位）
• 杰理官方：下载脚本配置文档 — isd_config_ini.c INI 配置详解
• 相关页面：构建系统与工具链（编译流程）、预编译静态库（apps/include_lib/liba/bd57/flash/）、HID 应用示例（键盘/鼠标/遥控器）