辅助工具与脚本

本文档介绍 fw-AW30N_BLE_SDK 仓库中内置的辅助工具与脚本：包括编译环境入口脚本（make_prompt.bat）、编译后处理脚本（post_build/）、平台适配脚本（download_sh.c）、Makefile 命令行编译体系，以及配套的外部工具（USB 升级工具、生产烧写工具、无线测试盒、音频工具）的用途与使用方式。

Purpose and Scope

本页面覆盖 AW30N SDK 开发过程中仓库内置与官方配套的辅助工具与脚本，说明它们各自承担的职责、调用时机与使用方式，具体包括：

编译入口与命令行脚本：make_prompt.bat、顶层 Makefile、make VERBOSE=1 等
编译后处理脚本目录：apps/app/post_build/
平台适配脚本：download_sh.c（Linux 环境需要重写）
官方配套外部工具：USB 升级工具、生产烧写工具、无线测试盒、音频工具

以下主题属于仓库中其他页面的范畴，本页仅提供方向指引，不展开叙述：

环境搭建与工具链安装：见 README「三、环境搭建」，涉及杰理编译工具链的下载与安装
烧录与升级流程：见 README「八、烧录与升级」，本文仅说明烧录工具的角色定位
工程结构与应用代码：见 README「五、工程结构」「六、应用与示例」

Overview

AW30N 系列是杰理科技推出的带 BLE 5.4 蓝牙功能的 32bit DSP MCU，其 SDK 固件程序由 C 代码、预编译库（lib.a）与配套脚本共同构成。与纯源码工程不同，本 SDK 的构建流程依赖一组脚本与外部工具把"源码 → 固件 → 目标板"的链路串联起来：

编译阶段：通过 Code::Blocks IDE、VS Code 任务或 make_prompt.bat + make 命令行，将应用源码与预编译库链接为固件；
编译后处理阶段：post_build/ 目录下的脚本在编译完成后执行固件打包、格式转换等收尾工作；
烧录/升级阶段：由官方 USB 升级工具、生产烧写工具或无线测试盒将固件写入目标板，或通过手机蓝牙/USB 执行 OTA 升级。

设计意图：SDK 将编译入口（make_prompt.bat）、工具集（tools/utils/）与后处理脚本（post_build/）独立成目录，目的是解耦工具链路径与业务代码——用户在 Code::Blocks 中构建时，IDE 会按 .cbp 工程文件中的配置自动调用这些脚本；在 Linux 命令行下则可以直接驱动 Makefile，仅需重写 download_sh.c 这一下载脚本即可适配不同的烧录硬件环境。

Architecture

flowchart TD
    subgraph sg_User["开发者入口"]
        IDE["Code::Blocks (.cbp)"]
        VSCode["VS Code 任务 (Ctrl+Shift+B)"]
        CMD["命令行 (make_prompt.bat)"]
    end

    subgraph sg_Build["编译体系"]
        Makefile["顶层 Makefile"]
        Toolchain["杰理编译工具链 (clang/pi32)"]
        Utils["tools/utils/ 工具集 (make/rm)"]
    end

    subgraph sg_Post["编译后处理"]
        PostBuild["apps/app/post_build/ 脚本"]
        DownloadSh["download_sh.c 下载脚本"]
    end

    subgraph sg_Ext["外部配套工具"]
        USBUpgrade["USB 升级工具"]
        ProdBurner["生产烧写工具"]
        TestBox["无线测试盒"]
        AudioTools["音频工具 (打包/转换/MIDI)"]
    end

    subgraph sg_Output["产物与目标"]
        Firmware["固件 (lib.a + 应用代码)"]
        Board["目标板 (AW30N)"]
    end

    IDE --> Makefile
    VSCode --> Makefile
    CMD --> Makefile
    Makefile --> Toolchain
    Makefile --> Utils
    Makefile --> PostBuild
    PostBuild --> Firmware
    Firmware --> USBUpgrade
    Firmware --> ProdBurner
    Firmware --> TestBox
    USBUpgrade --> Board
    ProdBurner --> Board
    TestBox --> Board
    DownloadSh --> Board

架构说明：

IDE/编辑器入口（左侧）：Code::Blocks、VS Code 与命令行三种方式殊途同归，最终都驱动 Makefile 完成构建，保证不同平台上构建行为一致；
编译体系（中部）：顶层 Makefile 是构建核心，依赖杰理编译工具链（/opt/jieli/pi32/bin/clang）与 tools/utils/ 中的通用工具（make、rm 等）；
编译后处理（中右）：post_build/ 脚本在链接完成后对固件进行打包等收尾，download_sh.c 负责把固件下载到目标板；
外部工具（右侧）：固件产物通过官方烧录/测试工具进入目标板；音频工具（音频文件转换、MIDI、打包）属于独立的 PC 端辅助工具，经百度网盘发布。

主要工具与脚本详解

编译命令行入口脚本：`make_prompt.bat`

make_prompt.bat 位于 sdk/tools/ 目录，是 Windows 下命令行编译的环境入口。其作用是一次性配置好命令行环境（PATH、工具链变量等），使开发者可以直接在弹起的命令行窗口中执行 make 系列命令，而无需手动设置环境变量。

README 中给出的标准用法如下：

# Windows 用户
双击 sdk/make_prompt.bat 打开命令行环境

# 编译
make -j4

# 显示编译详情
make VERBOSE=1 -j4

Source: README.md

设计意图：-j4 启用四路并行编译以缩短构建时间；VERBOSE=1 输出详细编译命令，便于排查头文件路径、链接选项等问题。二者组合使用可在"快速构建"与"诊断构建"之间灵活切换。

顶层 Makefile 与工具集 `tools/utils/`

tools/utils/ 存放构建所需的通用工具（make、rm 等），避免依赖系统自带版本导致的跨平台差异。顶层 Makefile 负责编排编译、链接与后处理全流程，是 IDE 构建与命令行构建的共同后端。

编译后处理脚本：`apps/app/post_build/`

post_build/ 目录存放编译后处理脚本与工具。在应用链接完成之后、固件交付烧录之前，这些脚本负责固件的格式整理、打包等收尾工作。它被 Makefile 在构建流程末尾自动调用，对开发者通常是透明的。

说明：由于本页面的源文件探索预算有限，未能逐一读取 post_build/ 与 tools/utils/ 目录内各脚本的具体实现，其内部细节以仓库实际文件为准。

平台适配脚本：`download_sh.c`

download_sh.c 是固件下载脚本的源文件，负责把编译产物下载到目标板。README 明确提示：

Linux 系统使用 Makefile 命令行编译时，需要重写 download_sh.c 脚本适配 Linux 环境。

Source: README.md

设计意图：Windows 下 Code::Blocks 内置的下载插件与烧录链路在 Linux 下不可用，因此 SDK 把下载动作抽象为 download_sh.c 脚本，让 Linux 用户自行实现烧录器适配逻辑，从而保持 Makefile 主流程不变。

核心流程：编译 → 后处理 → 烧录

一次完整的"代码到目标板"流程如下，展示了各脚本与工具的调用顺序：

sequenceDiagram
    participant Dev as 开发者
    participant Entry as 编译入口 (make_prompt.bat / IDE)
    participant Make as 顶层 Makefile
    participant TC as 杰理工具链 (clang)
    participant PB as post_build/ 脚本
    participant Tool as 烧录/升级工具
    participant Board as 目标板 (AW30N)

    Dev->>Entry: 启动编译（双击 bat 或 Ctrl+Shift+B）
    Entry->>Make: 调用 make -j4
    Make->>TC: 编译/链接应用源码与 lib.a
    TC-->>Make: 生成固件
    Make->>PB: 触发编译后处理
    PB-->>Make: 返回打包后的固件
    Make-->>Entry: 编译完成提示
    Dev->>Tool: 选择 USB 升级工具 / 测试盒 / 生产烧写
    Tool->>Board: 写入固件（或通过 download_sh.c 下载）
    Board-->>Tool: 烧录结果
    Tool-->>Dev: 显示升级状态

各步骤说明：

入口选择：Windows 用户双击 sdk/make_prompt.bat 获得命令行环境，或在 Code::Blocks / VS Code 中直接构建；Linux 用户直接执行 make；
编译编排：Makefile 并行编译（-j4），可选 VERBOSE=1 输出详细信息；
固件生成：应用源码与命名规则对应的预编译库 lib.a 链接生成固件（SDK 仓库本身不含库文件，需配套下载）；
后处理：post_build/ 脚本完成固件打包等收尾，使产物符合烧录工具要求；
烧录/升级：通过 USB 升级工具（开发调试）、无线测试盒（空中升级/射频标定）或生产烧写工具（量产裸片）写入目标板；Linux 下可重写 download_sh.c 自定义下载链路；
手机升级：支持手机蓝牙 OTA 与手机 USB 升级，作为无烧录器时的替代路径。

使用示例

示例一：验证工具链安装

编译前先确认杰理编译工具链可用（Linux 安装路径为 /opt/jieli，要求 clang 存在）：

# 验证工具链是否安装成功
clang --version

Source: README.md

示例二：克隆仓库并进入工程目录

git clone https://gitee.com/Jieli-Tech/AW30N.git
cd AW30N/sdk

Source: README.md

克隆后 sdk/ 根目录即包含 AW30N_mbox_flash.cbp 工程文件与顶层 Makefile，可直接进入编译环节。

示例三：Code::Blocks 图形化编译

1. 双击打开 AW30N_mbox_flash.cbp 工程文件
2. 点击 Build → Build（Ctrl+F9）
3. 编译成功后，使用 USB 升级工具烧录生成的固件

Source: README.md

要点：.cbp 工程文件中已配置好工具链、包含路径与后处理脚本调用，IDE 方式适合不熟悉命令行的开发者；编译前需确保 USB 升级工具正确连接且目标板已进入编程模式。

示例四：VS Code 一键构建

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标。

Source: README.md

VS Code 任务与 Makefile 共用同一构建后端，适合偏好编辑器的开发者，且跨平台体验一致。

Configuration Options

以下配置项来自 README 中环境搭建与编译章节，直接影响脚本与工具的运行方式：

配置项	类型	默认值/要求	说明
操作系统	枚举	Windows / Linux / macOS	Windows 推荐 Code::Blocks；Linux 用 Makefile 命令行；macOS 需自行配置交叉编译工具链
工具链安装路径	路径	`/opt/jieli/pi32/bin/clang`（Linux）	杰理编译工具链需先下载安装；Windows 下随 IDE 配置
并行编译数	整数	`-j4`	`make -j4` 四路并行，可自行调整
编译详细输出	布尔	关闭	`make VERBOSE=1` 开启详细编译信息
Linux 下载脚本	源码	`download_sh.c`	Linux 下需重写该脚本适配本机烧录环境
库文件	文件	与 SDK 版本同命名规则的 `lib.a`	仓库不含库文件，需配套获取后放至 `apps/include_lib/liba/`

Failure Modes、边界情况与并发注意

基于 README 可确认的失败模式与注意事项：

工具链缺失：未安装杰理编译工具链时 clang --version 报错，所有构建方式都会失败。排查顺序：检查 /opt/jieli/pi32/bin/clang 是否存在（Linux）→ 确认 IDE 工具链路径配置；
Linux 下载不可用：download_sh.c 为 Windows 烧录链路设计，Linux 下直接调用会失败，必须重写脚本适配（这是 SDK 官方明确提示的已知限制）；
烧录前置条件：编译前若 USB 升级工具未连接或目标板未进入编程模式，烧录步骤会失败；建议先连接目标板再编译，避免固件就绪后才发现设备不在线；
库文件缺失：SDK 源码需搭配对应命名规则的 lib.a 预编译库才能链接，库文件缺失会在链接阶段报错；
并行编译资源：-j4 会同时启动多个编译任务，内存/CPU 资源紧张的机器可降低并行度（如 -j2），避免构建进程被系统 OOM 杀掉；
并发写目标板：多个烧录工具（USB 升级工具、测试盒）同时连接同一目标板会造成下载冲突，同一时刻应只保留一条烧录链路。

扩展点与运营注意事项

自定义下载链路：download_sh.c 是官方预留的扩展点，Linux 或特殊烧录器用户通过重写该脚本接入自有下载硬件，无需改动 Makefile 主流程；
新增应用工程：在 sdk/ 根目录按既有模式新增 .cbp 工程与对应 apps/app/src/<app_name>/ 源码目录，即可复用现有 Makefile 与 post_build/ 后处理管线；
工具获取渠道：USB 升级工具、无线测试盒需向官方渠道申请（README 提供了淘宝链接与使用文档）；音频工具（打包、音频文件转换、MIDI）通过百度网盘发布（提取码 3jey）；
文档配套：详细的手册类资料位于 doc/ 目录，包括 AW30N_SDK手册_V1.7.pdf、AW30N_SDK_发布版本信息.pdf、芯片手册与硬件设计指南，排查工具问题时优先对照 SDK 手册。