后处理与配置工具

AW31N BLE SDK 的编译后处理与配置工具链，负责将 Lua 编写的模块化配置（user_cfg.lua）解析、校验并生成为 C 宏头文件（cfg_tool.h）、默认固件配置（default_cfg.fw）等产物，供 SDK 编译与下载流程使用。

Purpose and Scope

本页面向后处理（post-build）与配置（config）工具这一完整子系统，覆盖：

配置工具目录结构（apps/app/post_build/bd47/AW31N_config_tool/）
配置入口脚本 conf/entry/user_cfg.lua 的模块开关与工具状态
配置生成产物 conf/output/（cfg_tool.c/h、default_cfg.fw、extra_tones/*.wtg）
编译前工具（fw_create.lua）与固件编辑工具（fw_edit.lua / ufw_edit.lua）
后处理下载脚本 download.bat 与工具集 tools/utils/

以下主题不属于本页范围，请参见相应页面：芯片底层驱动（见芯片外设相关页面）、BLE 协议栈实现（见蓝牙协议栈页面）、编译系统与 Makefile 体系（见构建系统页面）。

Overview

AW31N SDK 采用"Lua 配置 → 生成器 → C 宏/固件产物"的配置流水线，把大量硬件与软件开关从散落的 C 代码中抽离到集中式脚本，实现：

配置集中化：所有模块使能、端口分配、功能开关集中在 conf/entry/ 下的 Lua 脚本中，而非分散在各 .c 文件。
生成自动化：配置工具将 Lua 脚本翻译为 cfg_tool.c/h，SDK 编译时通过 #define 宏裁剪功能模块，避免手写宏带来的不一致。
工具状态区分：config_status 区分 develop（开发 SDK 使用）与 release（发布上传使用），防止开发态配置流入发布版本。
界面可裁剪：eq_tool_button_show、fw_create_button_show 等开关决定配置工具入口界面（.jlxproj）中显示哪些功能按钮。

配置工具以 JL 工程文件 AW31N_配置工具入口(Config Tools Entry).jlxproj 为入口，其运行时由 conf/entry/ 下的 Lua 脚本驱动，输出写入 conf/output/，最终由 download.bat 等后处理脚本烧录/下载到芯片。

Architecture

flowchart TD
    subgraph sg_Entry["conf/entry 配置入口"]
        UserCfg["user_cfg.lua<br/>模块开关/版本/状态"]
        FwCreate["fw_create.lua<br/>编译前工具(FW 创建)"]
        FwEdit["fw_edit.lua<br/>FW 编辑"]
        UfwEdit["ufw_edit.lua<br/>UFW 编辑"]
        BtPower["bluetooth_powerprofile.lua<br/>蓝牙功耗"]
        Lang["lang_en.lua<br/>界面语言"]
        AppLog["app_log.md<br/>应用说明"]
    end

    subgraph sg_Tool["配置工具(Config Tools Entry).jlxproj"]
        ToolUI["配置工具界面"]
        CfgState["cfg_tool_state_complete.lua<br/>状态完成检查"]
    end

    subgraph sg_Output["conf/output 生成产物"]
        CfgH["cfg_tool.h / cfg_tool.c"]
        DefCfg["default_cfg.lua / default_cfg.fw"]
        Tones["extra_tones/*.wtg 提示音"]
    end

    subgraph sg_PostBuild["后处理与下载"]
        DownloadBat["download.bat"]
        ToolsUtils["tools/utils/*.exe<br/>make/merge/override-seg"]
        DoMerge["do_merge_libs.bat<br/>库合并"]
    end

    subgraph sg_Sdk["SDK 编译"]
        SdkBuild["SDK 源码编译"]
        Firmware["固件 bin/fw"]
    end

    ToolUI --> UserCfg
    ToolUI --> FwCreate
    ToolUI --> FwEdit
    ToolUI --> UfwEdit
    ToolUI --> BtPower
    ToolUI --> Lang
    ToolUI --> AppLog
    FwCreate --> CfgState
    CfgState --> CfgH
    CfgState --> DefCfg
    CfgState --> Tones
    CfgH --> SdkBuild
    DefCfg --> SdkBuild
    SdkBuild --> Firmware
    Firmware --> DownloadBat
    DownloadBat --> ToolsUtils
    DoMerge --> ToolsUtils

架构说明：配置工具界面（.jlxproj）是交互入口，它读取 conf/entry/ 下各 Lua 脚本渲染配置页；用户保存后由 cfg_tool_state_complete.lua 完成状态校验，并把结果写入 conf/output/ 的 C 头文件与默认固件配置；SDK 编译时通过 cfg_tool.h 的宏裁剪模块；编译出的固件再由 download.bat（配合 tools/utils/ 下的二进制工具）完成后处理与下载。do_merge_libs.bat 负责库合并，属于后处理链条的一环。

配置入口：user_cfg.lua

conf/entry/user_cfg.lua 是用户级配置的总入口，配置工具启动时首先加载它。它定义了脚本版本、产品名、工具状态、界面按钮开关与各功能模块的使能状态：

-------------------- 设置FW版本信息 --------------------
cfg:addKeyInfo("script_version", "AW31N-v0.01-cfg_tool-v0.05");

-------------------- 设置应用名称 --------------------
product_name = "AW31N"; --此名称将显示于配置工具入口界面

-------------------- 设置配置工具开发状态 --------------
    -- develop: 开发状态, 用于开发SDK使用
    -- release: 发布状态, 用于发布上传使用
config_status = "develop";
--config_status = "release";

-------------------- 设置eq工具是否打开 --------------
--eq_tool_button_show = true;
eq_tool_button_show = false;

-------------------- 设置编译前工具是否打开 ----------
fw_create_button_show = true;
--fw_create_button_show = false;

-------------------- 设置模块显示使能 --------------
-- true:  模块配置显示使能;
-- false: 模块配置不显示;
-- 注意: adkey 和 iokey 不能同时为true;
enable_moudles = {
	["isdtool"] = false,
    ["audio"]   = false,
    ["charge"]  = false,
    ["status"]  = false,
    ["tone"]    = false,
    ["bluetooth"]   = true,
    ["ble_config"] = false,
    ["key_msg"] = {enable = false, num = 10},
};

来源：user_cfg.lua

关键字段语义

字段	作用	设计意图
`cfg:addKeyInfo("script_version", ...)`	向配置工具注册脚本版本号	工具界面可展示脚本版本，便于追溯配置与 SDK 版本的匹配关系
`product_name`	应用名称，显示于工具入口界面	区分同一 SDK 下的多产品配置
`config_status`	`develop` / `release` 二选一	开发态允许调试性配置；发布态收紧配置，避免非预期项流入量产固件
`eq_tool_button_show`	是否在入口显示 EQ 工具按钮	默认关闭——EQ 工具仅对音频产品有意义
`fw_create_button_show`	是否显示"编译前工具"按钮	编译前工具（`fw_create.lua`）负责生成初始固件，默认开启
`enable_moudles`	各模块显示使能表	按产品裁剪配置页：`bluetooth` 为当前 AW31N 主力模块（`true`），其余音频/充电/状态/提示音等关闭

模块使能表的约束

enable_moudles 表中每个 key 对应一个配置页模块。注意 Lua 表同时容纳了布尔值（如 ["bluetooth"] = true）与子表（如 ["key_msg"] = {enable = false, num = 10}）两种形态——后者用于带参数的模块（按键消息映射数量 num）。注释明确提示"adkey 和 iokey 不能同时为 true"，这是硬件按键资源互斥的约束，由配置工具校验逻辑保证。

生成产物：conf/output

配置工具完成编辑后，将结果写入 conf/output/ 目录，形成四类产物：

产物	内容	消费方
`cfg_tool.h`	C 宏开关头文件	SDK C 源码编译
`cfg_tool.c`	对应实现（配置表/回调）	SDK C 源码编译
`default_cfg.lua` / `default/default_cfg.fw`	默认配置的 Lua 镜像与固件格式	下载/出厂初始化
`extra_tones/*.wtg`	附加提示音资源（0~3.wtg）	音频/提示音模块
`cfg_tool_state_complete.lua`	状态完成标记脚本	配置工具自身（校验）

cfg_tool.h 是 C 侧消费的核心接口，其头部结构如下：

//*********************************************************************************//
//                                 配置开始                                        //
//*********************************************************************************//
#define ENABLE_THIS_MODULE					1
#define DISABLE_THIS_MODULE					0

#define ENABLE								1
#define DISABLE								0

#define NO_CONFIG_PORT						(-1)

//*********************************************************************************//
//                                 配置结束                                        //
//*********************************************************************************//

来源：cfg_tool.h

该文件约定了一组全局语义常量：ENABLE/DISABLE 用作布尔开关，ENABLE_THIS_MODULE/DISABLE_THIS_MODULE 用作整模块裁剪，NO_CONFIG_PORT = (-1) 表示"该外设未配置端口"。C 代码中 #if ENABLE_THIS_MODULE 的写法让编译器在预处理阶段直接剔除未使能模块，兼顾运行效率与代码可读性——这是配置工具生成 C 宏而非运行时配置表的根本原因：零运行时开销。

编译前工具与固件编辑

conf/entry/ 下除 user_cfg.lua 外，还包含驱动配置工具各功能页的脚本：

fw_create.lua（编译前工具）：在首次编译前生成初始固件配置，与 fw_create_button_show = true 呼应——只有该开关打开时，工具界面才显示此入口。它负责建立"从零到可编译"的第一步，产出 default_cfg.fw 等初始文件。
fw_edit.lua / ufw_edit.lua：分别编辑普通固件（FW）与升级固件（UFW），支持在既有固件基础上修改配置项，避免每次改动都全量重建。
bluetooth_powerprofile.lua：蓝牙功耗档位配置页，与 enable_moudles["bluetooth"] = true 对应，是 AW31N（BLE SDK）当前唯一默认开启的模块配置。
lang_en.lua：界面英文语言包，说明工具 UI 支持多语言框架，配置页文案与逻辑分离。
app_log.md：应用说明文档，配置工具将其展示为"应用详细信息"，引导用户在 MD 中维护产品说明。

这些脚本与 user_cfg.lua 的区别在于职责边界：user_cfg.lua 回答"哪些模块可见、工具处于什么状态"，而各功能脚本回答"模块内部如何配置"。

后处理脚本与工具集

download.bat（后处理下载）

编译完成后，apps/app/post_build/bd47/download.bat 承担固件的后处理与下载职责。它位于每个应用工程的 post_build 目录下，与配置工具同层（bd47 平台目录），属于"编译产物 → 芯片烧录"链路的最后一环。仓库中 patch_release/AW31N_开机&低功耗&VM兼容性修复说明_20250102/.../download.bat 的同名脚本表明，该脚本在补丁包中同样被同步维护，是下载流程的固定组成部分（脚本内部具体命令未在本页展开，请直接查看源文件）。

tools/utils 工具集

tools/utils/ 存放后处理阶段调用的可执行工具（Windows 环境）：

工具	作用推断（依据文件名与 SDK 通用实践）
`make.exe`	后处理阶段的 Make 驱动，供脚本批量执行构建步骤
`merge-archives.exe`	静态库合并，与 `do_merge_libs.bat` 配合
`override-seg.exe`	覆盖/重定位段处理，用于调整固件内存布局
`fixbat.exe`	修复批处理脚本（编码/路径兼容）
`find.exe` / `ls.exe` / `rm.exe` / `mkdir_win.exe` / `true.exe` / `uname.exe`	GNU 工具链的 Windows 移植，为批处理脚本提供类 Unix 文件操作能力
`libiconv2.dll` / `libintl3.dll`	上述工具的运行库依赖
`do_merge_libs.bat`	库合并批处理，调用 `merge-archives.exe` 将分散的静态库合并为单一库

说明：tools/utils 下为编译后的二进制可执行文件，其内部实现不在源码仓库中；上表依据文件命名与调用方脚本（do_merge_libs.bat）推断职责，具体行为以工具输出为准。tools/make_prompt.bat 位于仓库根级 tools/ 下，与 make_prompt.bat（根目录）对应，负责构建提示环境。

Core Flow：配置 → 生成 → 编译 → 后处理

sequenceDiagram
    participant Dev as 开发者
    participant UI as 配置工具入口(.jlxproj)
    participant Lua as conf/entry Lua 脚本
    participant Gen as cfg_tool_state_complete.lua
    participant Out as conf/output 产物
    participant Sdk as SDK 编译
    participant PB as download.bat + tools/utils

    Dev->>UI: 打开配置工具入口
    UI->>Lua: 加载 user_cfg.lua 等入口脚本
    Lua-->>UI: 渲染配置页(bluetooth/ble_config/key_msg…)
    Dev->>UI: 编辑模块配置
    UI->>Gen: 保存并触发状态完成校验
    Gen->>Out: 生成 cfg_tool.h/c、default_cfg.fw、tones
    Sdk->>Out: 编译时读取 cfg_tool.h 宏裁剪模块
    Sdk-->>Dev: 产出固件 bin/fw
    Dev->>PB: 运行 download.bat 下载
    PB->>Sdk: 定位固件产物
    PB-->>Dev: 烧录完成

流程要点：

配置装载：工具入口加载 conf/entry/ 下所有 Lua，user_cfg.lua 决定可见模块集合与工具状态。
状态完成校验：cfg_tool_state_complete.lua 在保存时校验配置完整性（如 adkey/iokey 互斥、端口冲突），通过后才允许生成输出。
产物生成：cfg_tool.h 中的 ENABLE_THIS_MODULE 系列宏直接决定 SDK 编译时的代码裁剪粒度。
后处理下载：download.bat 借助 tools/utils/ 下的工具完成固件处理与烧录；多库工程先经 do_merge_libs.bat 合并再链接。

该顺序保证配置变更永远先于编译生效，且任何一步失败都不会产生"配置与固件不一致"的中间态。

Configuration Options（配置选项汇总）

user_cfg.lua 顶层选项

选项	类型	默认值	说明
`script_version`	string	`"AW31N-v0.01-cfg_tool-v0.05"`	通过 `cfg:addKeyInfo` 注册的脚本版本号，随配置工具界面展示
`product_name`	string	`"AW31N"`	应用名称，显示于配置工具入口界面
`config_status`	string	`"develop"`	工具状态；`develop` 用于 SDK 开发，`release` 用于发布上传
`eq_tool_button_show`	bool	`false`	EQ 工具按钮是否显示（音频产品可开启）
`fw_create_button_show`	bool	`true`	编译前工具按钮是否显示
`enable_moudles`	table	见下	模块显示使能表

enable_moudles 模块表

模块 key	类型	默认值	说明
`isdtool`	bool	`false`	ISD 录音工具模块
`audio`	bool	`false`	音频参数模块
`charge`	bool	`false`	充电管理模块
`status`	bool	`false`	状态指示模块
`tone`	bool	`false`	提示音模块
`bluetooth`	bool	`true`	蓝牙配置模块（AW31N 默认开启）
`ble_config`	bool	`false`	BLE 专项配置模块
`key_msg`	table	`{enable=false, num=10}`	按键消息映射，`num` 为映射条数上限

cfg_tool.h 宏常量

宏	值	语义
`ENABLE_THIS_MODULE`	`1`	整模块使能开关
`DISABLE_THIS_MODULE`	`0`	整模块裁剪开关
`ENABLE`	`1`	通用布尔使能
`DISABLE`	`0`	通用布尔关闭
`NO_CONFIG_PORT`	`(-1)`	外设未配置端口的哨兵值

API Reference

`cfg:addKeyInfo(key, value)`

配置工具全局注入的注册接口，用于向工具元信息表添加键值对。

参数：

key (string)：元信息键名，如 "script_version"。
value (string)：键对应的值，如版本号字符串。

返回值： 无（Lua 脚本中通常忽略返回值）。

说明： 该 API 由配置工具运行时注入（.jlxproj 宿主），user_cfg.lua 中 cfg:addKeyInfo("script_version", ...) 是仓库内唯一直接调用点，用于版本溯源。更完整的 API 集合（如端口分配、模块注册等）由工具宿主实现，不在 SDK 源码内，需以工具自带的脚本手册为准。

`enable_moudles` 表访问约定

配置工具按表 key 读取各模块的显示使能；值为 table 时读取其 enable 字段（如 key_msg.enable）与扩展参数（如 key_msg.num）。该约定并非显式 API，而是工具与脚本之间的数据契约。

Failure Modes、边界与一致性

adkey/iokey 互斥：user_cfg.lua 注释明确要求 adkey 与 iokey 不能同时为 true。若违反，配置工具应在状态完成校验（cfg_tool_state_complete.lua）阶段拒绝生成产物；SDK 侧无兜底，因此该约束完全依赖工具链路。
develop/release 状态泄漏：若发布时忘记将 config_status 切回 release，开发态配置可能随固件流出。这是纯脚本配置的固有风险，发布流程应把该字段纳入检查清单。
模块表形态不一致：enable_moudles 同时接受 bool 与 table 两种值形态，读取方必须分别处理，否则会把子表当真值导致判断错误——这是 Lua 弱类型带来的典型边界。
二进制工具不可审计：tools/utils/*.exe 为预编译二进制，其行为只能通过调用方脚本间接验证；升级工具集时需回归 do_merge_libs.bat 与下载脚本的全链路。
补丁同步维护：patch_release/ 中存在同名 download.bat，说明后处理脚本在补丁包中独立维护，升级 SDK 时需注意两处脚本的一致性，避免补丁覆盖主线下载流程。
并发/重入：配置工具为交互式单实例 GUI 工作流（.jlxproj），同一时间仅一个用户编辑，conf/output/ 的写入无需并发控制；但若 CI 并行编译多个工程共享同一 tools/utils，需保证工具二进制只读、不被脚本修改。

Extension Points（扩展方式）

新增配置模块：在 enable_moudles 中增加 key 并配套 conf/entry/ 下新增模块脚本（参照 bluetooth_powerprofile.lua 的写法），即可让配置工具渲染新配置页——无需改动工具宿主。
多语言界面：参照 lang_en.lua 增加语言包文件，配置页文案即可本地化。
产品定制：修改 product_name 与模块使能组合，即可在同一 SDK 上派生不同产品线的配置入口。
后处理扩展：在 download.bat 或 tools/ 层追加批处理步骤，调用 tools/utils/ 中的工具（或新增工具）扩展下载/合并/段处理流程。
生成产物扩展：cfg_tool_state_complete.lua 是生成链路的钩子点，可在其中追加自定义产物（如校验和、版本戳）。

配置工具入口工程
用户配置入口 user_cfg.lua
生成头文件 cfg_tool.h
后处理下载脚本 download.bat
库合并工具 do_merge_libs.bat
蓝牙功耗配置页 bluetooth_powerprofile.lua
相关页面：构建系统与编译流程、蓝牙协议栈、芯片外设驱动（均为本 SDK 的其他目录页）