文档、配置说明与常见问题

本文档汇总 fw-AW30N_BLE_SDK 仓库中的官方文档资源、固件配置机制（app_config.h 功能开关、BLE Profile 制作工具、AW30N 配置工具）以及常见问题解答，帮助开发者快速定位资料、正确配置工程并解决开发中遇到的典型问题。

Purpose and Scope

本页面覆盖以下三块内容：

1. 文档资源：仓库 doc/ 目录下的芯片手册、SDK 手册、硬件设计指南、原理图/规格书、版本信息，以及在线文档中心入口。
2. 配置说明：目标应用功能开关（app_config.h）、GATT 服务配置（BLE Profile 制作工具）、AW30N 配置工具（AW30N_config_tool/）的目录结构与配置产物。
3. 常见问题：README 中沉淀的开发流程、编译、调试三方面的 Q&A。

以下主题属于兄弟页面范畴，本页不做展开，仅给出指引：

• 编译与烧录流程 → 见 README「七、编译指南」「八、烧录与升级」对应章节。
• 应用层业务实现（BLE 遥控器 / 对讲机 / 小音箱等）→ 见应用代码目录 sdk/apps/app/src/mbox_flash/ 相关页面。
• 芯片硬件规格 → 见 doc/ 下的芯片手册与硬件设计指南。

Overview

fw-AW30N_BLE_SDK 是杰理科技为 AW30N 系列芯片提供的 BLE 通用 MCU SDK 开发包，芯片为带 BLE 5.4 蓝牙功能的 32bit DSP MCU，面向蓝牙遥控器、语音玩具、小音箱、通用 MCU 等场景。仓库采用「Release 代码 + 预编译库（lib.a）」的发布形态，因此文档与配置是开发者上手的最短路径：文档决定了"去哪里查资料"，配置决定了"编译出来的固件长什么样"。

配置体系的核心设计意图是把芯片能力与产品形态解耦：同一份 SDK 代码通过 app_config.h 的功能开关裁剪出遥控器、对讲机、小音箱等不同产品；GATT 服务通过 BLE Profile 工具可视化配置；量产参数（蓝牙功率、提示音等）通过 AW30N 配置工具在编译后阶段注入固件。理解这条「源码 → 编译 → 后处理配置 → 固件」的链路，是使用本 SDK 的关键。

Architecture

flowchart TD
    subgraph sg_Docs["文档资源层"]
        README["README.md / README-en.md"]
        DOC["doc/ 目录<br/>（手册/原理图/规格书/版本信息）"]
        ONLINE["在线文档中心<br/>doc.zh-jieli.com/AW30"]
    end

    subgraph sg_Config["配置体系"]
        APP_CFG["app_config.h<br/>功能开关"]
        BLE_TOOL["BLE Profile 制作工具<br/>GATT 服务配置"]
        CFG_TOOL["AW30N 配置工具<br/>AW30N_config_tool/"]
    end

    subgraph sg_Build["构建链路"]
        SRC["应用源码<br/>sdk/apps/app/src/mbox_flash/"]
        MAKE["编译<br/>make / Code::Blocks"]
        POST["post_build 后处理<br/>生成固件 + 配置注入"]
        FW["固件产物<br/>*.fw / *.bin"]
    end

    README --> DOC
    README --> ONLINE
    APP_CFG --> SRC
    BLE_TOOL --> SRC
    SRC --> MAKE
    MAKE --> POST
    CFG_TOOL --> POST
    POST --> FW

上图展示了本页主题的三大支柱及其关系：

• 文档资源层（左侧）：README.md 是仓库的门户，指向 doc/ 目录的离线资料与在线文档中心，同时包含了配置说明与 FAQ 的正文。
• 配置体系（中部）：三个配置入口分别作用于不同阶段——app_config.h 在编译期裁剪功能，BLE Profile 工具生成 GATT 服务代码，AW30N 配置工具在编译后阶段（post_build）修改固件参数。
• 构建链路（右侧）：源码与编译期配置进入构建，配置工具在后处理阶段产出最终固件，形成完整的「配置 → 构建 → 固件」闭环。

配置工具的相关说明文档位于仓库内：AW30N_配置工具使用说明.pdf，入口工程为 AW30N_配置工具入口(Config Tools Entry).jlxproj。

文档资源详解

仓库离线文档（doc/ 目录）

doc/ 目录集中存放了开发所需的全部离线资料，按用途可分为四类：

此外 doc/datasheet/ 存放数据手册、doc/stuff/ 存放杂项资料（如钉钉技术交流群二维码 ding_talk.jpg）。

在线文档与资源入口

仓库还提供 README-en.md 英文版门户，面向英文开发者；中文门户为 README.md。

配置说明

配置入口总览

SDK 的配置体系包含三个相互独立的入口，分别作用于不同阶段：

flowchart LR
    subgraph sg_CompileTime["编译期"]
        A1["app_config.h<br/>（应用功能开关）"]
    end
    subgraph sg_Profile["GATT 配置期"]
        B1["BLE Profile 制作工具<br/>（生成 GATT 服务）"]
    end
    subgraph sg_PostBuild["编译后阶段"]
        C1["AW30N 配置工具<br/>（注入量产参数）"]
    end
    A1 --> X["源码编译"]
    B1 --> X
    X --> Y["固件生成"]
    C1 --> Y

app_config.h —— 应用功能开关

编辑 sdk/apps/app/src/mbox_flash/app_config.h 可配置目标应用的功能开关。这是编译期配置，决定 SDK 编译时包含哪些功能模块（BLE 主/从机、遥控器、对讲机、音频解码、录音、USB 设备等）。设计意图是一份源码、多产品形态：同一套代码通过宏开关裁剪出不同的应用组合，避免为每个产品维护独立分支。

BLE Profile 制作工具 —— GATT 服务配置

通过 BLE Profile 制作工具可以可视化配置 GATT 服务（服务 UUID、特征、属性、数据收发方式等），生成的代码集成到工程中。SDK 同时支持完整 GATT 服务（基于标准 GATT 协议、完整 profile）与简易 GATT 服务（按标准协议裁切、仅支持简单数据收发）两种模式，开发者按产品对协议复杂度的要求选择。

AW30N 配置工具 —— 编译后配置

配置工具位于 sdk/apps/app/post_build/bd49/AW30N_config_tool/，在编译后处理阶段运行，用于修改固件中的量产参数（如蓝牙功率配置、提示音等）。其目录结构如下：

AW30N_config_tool/
├── AW30N_配置工具使用说明.pdf          # 工具使用文档
├── AW30N_配置工具入口(Config Tools Entry).jlxproj   # 工具入口工程
└── conf/
    ├── entry/                         # 配置脚本（编译期/工具配置输入）
    │   ├── app_log.md                 # 应用信息
    │   ├── bluetooth_powerprofile.lua # 蓝牙功率配置脚本
    │   ├── fw_common.lua              # 固件公共配置
    │   ├── fw_create.lua              # 固件创建配置
    │   ├── fw_edit.lua                # 固件编辑配置
    │   ├── ufw_edit.lua               # UFW 升级固件编辑配置
    │   ├── lang_en.lua                # 英文语言包
    │   ├── user_cfg.lua               # 用户自定义配置
    │   └── version.log                # 工具版本日志
    └── output/                        # 工具输出产物（生成代码与默认配置）
        ├── cfg_tool_state_complete.lua
        ├── cfg_tool.c / cfg_tool.h    # 生成的配置访问代码
        ├── default_cfg.lua
        └── default/default_cfg.fw     # 默认固件配置

其中 conf/entry/ 下的 Lua 脚本是配置模板，conf/output/ 是工具生成的产物——cfg_tool.c/h 为固件侧读取配置的访问接口，default_cfg.fw 为默认配置固件。extra_tones/ 目录存放提示音资源（0.wtg、1.wtg、2.wtg）。工具入口 app_log.md 内容如下：

应用信息：AW30N-SDK

Source: app_log.md

该文件在工具运行时被读取，用于在配置界面标识当前 SDK 应用信息，保证配置产物与 SDK 版本匹配。

烧录工具相关配置

• USB 升级工具：首次烧录使用，配置见 ISD 配置说明（ISD_CONFIG.INI）。
• 生产烧写工具：量产/裸片烧写，支持一拖二/一拖八，配置文档见对应工具页面。
• 无线测试盒：空中升级、射频标定、产品测试。

常见问题（FAQ）

README「十、常见问题」章节沉淀了社区高频问题，按主题分为三类：

开发流程相关

• Q: 如何创建一个新的工程？ A: 基于现有的 .cbp 工程和 apps/app/src/ 中的应用代码进行修改，配置对应用例即可。SDK 采用"一个入口工程 + 应用代码目录"的结构，新工程从现有工程派生成本最低。

• Q: 如何切换不同的芯片型号？ A: 在配置中选择对应的芯片型号，SDK 已为全系列预配置了统一的编译入口（AW30N_mbox_flash.cbp 支持 AW30N 全系列）。

编译相关

• Q: Windows 下编译报错 make 不是有效命令？ A: 使用 sdk/make_prompt.bat 进入预配置的命令行环境，该脚本已设置好所有环境变量和 make 的路径。设计意图是把工具链路径差异封装在脚本内，避免开发者手工配置环境。

• Q: 如何加快编译速度？ A: 使用 -j 参数进行并行编译，如 make -j4（数字为并行任务数）。

调试技巧

• 串口日志：可通过 UART 输出调试日志。
• BLE 抓包：可使用 BLE Dongle 进行空中抓包分析，定位 GATT 交互与连接问题。

使用示例

环境验证与编译（命令行方式）

# 验证工具链是否安装成功（应安装到 /opt/jieli，确保 /opt/jieli/pi32/bin/clang 存在）
clang --version

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

# 编译（-j 为并行任务数）
make -j4

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

# 清理
make clean

Source: README.md · README.md

克隆仓库并进入 SDK

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

Source: README.md

配置工具入口工程

使用杰理开发环境（jlxproj）打开配置工具入口工程，即可在图形界面中编辑固件配置：

sdk/apps/app/post_build/bd49/AW30N_config_tool/AW30N_配置工具入口(Config Tools Entry).jlxproj

配置脚本（Lua）与产物（生成代码）的对应关系见上文「AW30N 配置工具」小节：编辑 conf/entry/*.lua 模板后运行工具，产物输出到 conf/output/。

配置选项速查表

更多工具细节请参阅仓库内的 AW30N_配置工具使用说明.pdf。

故障排查与边界情况

常见编译错误对照表

Source: README.md

边界情况与注意事项

• 平台差异：README 明确 Linux 下使用 Makefile 命令行编译需要重写 download_sh.c 脚本适配；macOS 需自行配置交叉编译工具链。Windows 是官方推荐开发环境（Code::Blocks IDE）。
• 工具链版本耦合：仓库发布的是 Release 代码 + 预编译库（lib.a），必须配合对应命名规则的库文件编译，混用不同版本 SDK 的库会导致链接错误。
• 配置产物一致性：AW30N 配置工具输出（cfg_tool.c/h、default_cfg.fw）由 conf/entry/ 脚本生成，修改脚本后需重新运行工具，避免固件读取到过期配置。
• 烧录前置条件：烧录前必须确保 USB 升级工具正确连接且目标板已进入编程模式，否则下载会失败。

并发/时序考虑

SDK 为嵌入式单芯片方案，配置与编译流程本身无并发问题；但 make -j 并行编译会同时产生大量日志，排错时可先使用 VERBOSE=1 单线程复现以定位具体错误文件。

运维与性能注意事项

• 功耗指标是产品选型依据：未连接广播功耗 290uA+、已连接待机功耗 130uA+、关机功耗 2uA+、休眠功耗 61uA+——配置蓝牙功率档位（bluetooth_powerprofile.lua）直接影响实测功耗，量产前需按产品认证要求（如 BQB/SRRC）校准。
• 升级通道多样：支持 U 盘/SD 卡、测试盒串口、测试盒蓝牙、手机蓝牙 OTA、手机 USB 共五种升级路径，量产方案通常选择测试盒通道以兼顾效率与稳定性。
• 多路解码资源：系统支持最多同时三路解码播放，配置功能开关时需评估 CPU/内存余量，避免功能叠加导致资源不足。

扩展点

• 新增产品形态：不修改 SDK 核心，在 apps/app/src/ 下基于现有应用（mbox_flash/）派生新应用，通过 app_config.h 裁剪功能组合。
• 自定义 GATT 服务：通过 BLE Profile 制作工具定义私有服务/特征，实现与 App 的私有协议交互。
• 自定义提示音：向 conf/output/extra_tones/ 增加 .wtg 格式音频资源，并在配置工具中关联事件。
• 用户配置脚本：编辑 conf/entry/user_cfg.lua 可扩展配置工具的自定义参数项，产物自动生成到 cfg_tool.c/h。

Related Links

• README.md（中文门户，含配置说明与 FAQ 原文）
• README-en.md（英文门户）
• AW30N 配置工具使用说明
• 配置工具入口工程
• 配置脚本目录 conf/entry/
• SDK 版本历史（doc/AW30N_SDK_发布版本信息.pdf）
• SDK 手册（doc/AW30N_SDK手册_V1.7.pdf）
• 在线文档中心：https://doc.zh-jieli.com/AW30/zh-cn/master/index.html