SDK 简介与核心特性

fw-AW30N_BLE_SDK 是珠海杰理科技（Jieli）为 AW30N 系列芯片 提供的 BLE 通用 MCU SDK 开发包。AW30N 是集成 BLE 5.4 蓝牙功能的 32bit DSP MCU，本 SDK 提供从蓝牙协议栈、音频编解码、设备驱动到应用示例的完整固件开发能力，主要面向蓝牙遥控器、BLE 对讲机、BLE Dongle、语音玩具、小音箱及通用 MCU 控制等场景。

Purpose and Scope

本页面作为 SDK 的入口级介绍，回答以下问题：

• AW30N 芯片平台是什么，SDK 能做什么；
• SDK 的核心能力矩阵：蓝牙、低功耗、音频、升级、设备驱动；
• SDK 的整体软件架构、工程目录结构与构建系统；
• 关键配置入口（app_config.h、Makefile 宏定义）与常见问题。

属于 SDK 整体介绍范畴的内容（工程结构、编译、烧录、升级、配置说明）在本页给出概要，详细的操作流程属于后续专题页面。各专题页面的对应关系：

• 环境搭建与工具链安装 → 见「环境搭建」页面；
• 快速开始与编译 → 见「快速开始 / 编译指南」页面；
• 烧录与升级（USB/OTA/测试盒） → 见「烧录与升级」页面；
• 具体应用开发（BLE 遥控器 / 对讲机 / Dongle） → 见各应用专题页面。

概述

什么是 AW30N

AW30N 是杰理科技推出的带 BLE 5.4 蓝牙功能的 32bit DSP MCU 系列。芯片以低功耗、音频处理能力和丰富的外设接口为核心卖点，可同时承担"通用 MCU 控制"与"音频/蓝牙应用"两类任务。蓝牙规范认证信息如下：

SDK 的定位

本仓库包含 SDK Release 版本代码及示例工程，配合对应命名规则的预编译库（lib.a）即可编译出完整固件。SDK 采用"应用源码 + 预编译库 + API 头文件"的分发模式：应用层代码完全开源（位于 sdk/apps/），而协议栈、编解码器等核心算法以静态库形式提供（位于 sdk/apps/include_lib/liba/），既保护了核心 IP，又给开发者保留了充分的应用定制空间。

典型应用场景

架构

总体架构图

SDK 采用分层架构：应用层 → SDK 中间件/协议栈 → 预编译库与 API 头文件 → 硬件平台。

flowchart TD
    subgraph sg_App["应用层 (sdk/apps/)"]
        MboxFlash["mbox_flash 应用<br/>(BLE 遥控器 / 对讲机 / 小音箱 / 音频播放)"]
        AppConfig["app_config.h<br/>应用功能开关配置"]
    end

    subgraph sg_Middle["SDK 中间件与协议栈"]
        BLEStack["BLE 5.4 协议栈<br/>(完整 GATT / 简易 GATT)"]
        AudioEngine["音频引擎<br/>(7 种解码 / 4 种编码 / 音效 / MIO)"]
        DeviceLayer["设备驱动层<br/>(FLASH / SD / U 盘 / USB)"]
        UpdateLayer["升级模块<br/>(OTA / USB / U 盘 / SD / 测试盒)"]
        PowerMgmt["电源管理<br/>(SOFT OFF / POWER DOWN)"]
    end

    subgraph sg_Lib["预编译库与头文件 (include_lib/)"]
        LibA["liba/*.a 静态库"]
        Headers["API 头文件<br/>(cpu / decoder / encoder / audio / device / msg / update)"]
    end

    subgraph sg_HW["硬件平台"]
        Chip["AW30N SoC<br/>(32bit DSP MCU + BLE 5.4)"]
    end

    MboxFlash --> AppConfig
    MboxFlash --> BLEStack
    MboxFlash --> AudioEngine
    MboxFlash --> DeviceLayer
    MboxFlash --> UpdateLayer
    MboxFlash --> PowerMgmt
    BLEStack --> Headers
    AudioEngine --> Headers
    DeviceLayer --> Headers
    UpdateLayer --> Headers
    Headers --> LibA
    LibA --> Chip

架构说明

• 应用层：唯一的应用工程入口是 AW30N_mbox_flash.cbp（Code::Blocks 工程），对应应用源码目录 sdk/apps/app/src/mbox_flash/。该工程通过 app_config.h 中的宏开关裁剪功能，一份代码覆盖 BLE 蓝牙、小音箱、音频播放等多种产品形态。
• 中间件/协议栈层：BLE 5.4 协议栈（支持完整 GATT 与简易 GATT 两种服务模式）、音频引擎（解码/编码/音效/MIO）、设备驱动框架（FLASH、SDMMC、U 盘、USB）与升级模块共同构成 SDK 的能力核心。
• 预编译库与头文件层：include_lib/ 按 cpu/ decoder/ encoder/ audio/ device/ common/ config/ msg/ update/ liba/ 组织 API 头文件与静态库，是应用层与硬件之间的契约边界。
• 硬件平台：AW30N SoC 提供 BLE 射频、DSP 运算、音频 DAC/ADC/APA（Class-D）等硬件资源，SDK 通过 BSP（apps/app/bsp/）完成板级适配。

这一分层设计的目的：应用开发者只面对稳定的 API 头文件，无需关心协议栈内部实现；核心算法库（解码器、协议栈）由杰理维护升级，通过替换 liba/ 目录下的静态库即可完成 SDK 版本更新，应用代码无需改动。

核心特性详解

SDK 的核心能力可归纳为四大板块：BLE 蓝牙、低功耗、音频处理、固件升级，外加设备与通用 MCU 能力。

flowchart LR
    subgraph sg_BLE["BLE 蓝牙 (5.4 单模)"]
        B1["完整 GATT 服务"]
        B2["简易 GATT 服务"]
        B3["从机遥控器 / 主机 Dongle / 对讲机"]
    end

    subgraph sg_Power["低功耗"]
        P1["未连接广播 290uA+"]
        P2["已连接待机 130uA+"]
        P3["SOFT OFF 关机 2uA+"]
        P4["POWER DOWN 休眠 61uA+"]
    end

    subgraph sg_Audio["音频处理"]
        A1["7 种解码播放"]
        A2["4 种编码录音"]
        A3["变速变调 / echo / 变音 / 啸叫抑制 / PCM_EQ"]
        A4["最多三路并发解码 / 硬件重采样 / MIO"]
    end

    subgraph sg_Upgrade["固件升级"]
        U1["手机蓝牙 OTA / 手机 USB"]
        U2["U 盘 / SD 卡升级"]
        U3["测试盒串口 / 测试盒蓝牙"]
    end

    subgraph sg_Dev["设备与通用 MCU"]
        D1["FLASH / SDMMC / U 盘 存储"]
        D2["USB 从机 (Speaker / MIC / HID / MSD)"]
        D3["LINEIN / 扩音 / 录音"]
    end

BLE 蓝牙特性

• 单模 BLE 5.4：仅支持 BLE（无 BR/EDR），符合 Core v5.4 规范（QDID 223418），适合低功耗、低成本的蓝牙外设产品。
• 完整 GATT 服务：基于标准 GATT 协议实现，具有完整的 GATT profile，支持标准化的服务/特征定义，适合对接手机 App 等标准 BLE 主端设备。
• 简易 GATT 服务：根据标准 GATT 协议进行裁切，仅保留简单数据收发能力，占用资源更少、连接建立更快，适合遥控器等轻量应用。
• 三种应用示例：SDK 新增 BLE 从机遥控器、BLE Dongle 主机、BLE 对讲机 三个完整示例。其中对讲机基于 2.4GHz 私有协议，Dongle 通过 USB 与 PC 交互。

低功耗特性

低功耗是 AW30N 的核心卖点，SDK 提供多级功耗状态：

设计意图：遥控器类产品 90% 以上时间处于广播或连接待机状态，这两档功耗直接决定电池续航；SOFT OFF 与 POWER DOWN 则服务于玩具、音箱类产品的整机待机场景。

音频处理特性

音频是 AW30N 的另一核心能力，覆盖"播放—处理—录音"全链路：

• 解码播放：支持 a/b/e、ump3、f1a/f1b/f1c/f1x、midi、标准 mp3、wav、opus 共 7 种格式；支持从系统 FLASH、资源 FLASH、SDMMC、U 盘等设备解码，最多同时三路解码。
• 编码录音：支持标准 mp2、a、ump2、opus 共 4 种格式。
• 音效处理：变速变调、echo、变音、啸叫抑制、PCM_EQ 等，可满足玩具/音箱产品的趣味性与声学需求。
• MIO 解码：支持解码 MIO 功能，用于多路混音/边解边播场景。
• 音频硬件接口：
  • AUDIO_DAC：单声道单端输出，支持 8K~96k 共 12 种采样率；
  • AUDIO_APA（Class-D 直驱喇叭）：单声道差分输出，支持 32K~48k 共 3 种采样率；
  • AUDIO_ADC：单声道单端/差分输入，支持 8K~48k 共 9 种采样率；
  • 支持硬件重采样，简化多采样率音源之间的切换。

固件升级特性

SDK 内置多种升级通道，覆盖开发调试、产线测试与用户端 OTA：

软件架构与工程结构

SDK 顶层目录结构如下（摘自仓库 README 的工程结构说明）：

fw-AW30N/
├── sdk/                           # SDK 主目录
│   ├── apps/                      # 应用层代码
│   │   ├── app/                   #   应用入口源码
│   │   │   ├── src/               #     应用源码
│   │   │   │   └── mbox_flash/    #       BLE 蓝牙/小音箱/音频播放应用
│   │   │   ├── bsp/               #     板级支持包（BSP）
│   │   │   └── post_build/        #     编译后处理脚本与工具
│   │   └── include_lib/           #   头文件与预编译库
│   │       ├── cpu/               #     CPU 平台头文件
│   │       ├── decoder/           #     解码器 API 头文件
│   │       ├── encoder/           #     编码器 API 头文件
│   │       ├── audio/             #     音频 API 头文件
│   │       ├── device/            #     设备驱动头文件
│   │       ├── common/            #     公共头文件
│   │       ├── config/            #     配置头文件
│   │       ├── msg/               #     消息机制
│   │       ├── update/            #     固件升级
│   │       └── liba/              #     预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档（芯片手册、SDK 手册、原理图等）
└── README.md                      # 本文件

Source: README.md

几个关键设计点：

• 单一应用工程：AW30N_mbox_flash.cbp 是唯一的 Code::Blocks 工程入口，make 亦编译同一目标，因此 Windows（IDE）与 Linux（命令行）共用一份应用源码与构建配置。
• 源码与库分离：apps/app/src/ 提供全部应用源码，apps/include_lib/ 提供 API 头文件与预编译静态库。新增芯片型号或 SDK 版本升级通常只需替换 liba/ 与头文件。
• BSP 板级适配：apps/app/bsp/ 承载开发板的引脚、时钟、外设初始化，换板只需改 BSP 层。

构建系统与编译流程

顶层 Makefile 负责整个 SDK 的编译，针对 Windows 与 Linux 分别配置工具链路径：

# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
CXX   := clang.exe
LD    := lto-wrapper.exe
AR    := llvm-ar.exe
MKDIR := mkdir_win -p
RM    := rm -rf

SYS_LIB_DIR := C:/JL/pi32/libc
SYS_INC_DIR := C:/JL/pi32/include/libc
EXT_CFLAGS  := # Windows 下不需要 -D__SHELL__
export PATH:=$(TOOL_DIR);$(PATH)

## 后处理脚本
FIXBAT          := tools\\utils\\fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := apps/app/post_build/bd49/download.bat
RUN_POST_SCRIPT := apps\\app\\post_build\\bd49\\download.bat
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/pi32/bin
CC    := clang
CXX   := clang
LD    := lto-wrapper
AR    := lto-ar
MKDIR := mkdir -p
RM    := rm -rf
...
EXT_CFLAGS  := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
export PATH:=$(TOOL_DIR):$(PATH)

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

Source: sdk/Makefile

可见构建系统的设计意图：

• 统一使用 clang 交叉编译器（目标 pi32 架构），链接器为 LLVM 生态的 lto-wrapper（LTO 链接）；
• Windows 工具链默认安装在 C:/JL/pi32，Linux 默认在 /opt/jieli/pi32；
• 编译产物输出到 apps/app/post_build/bd49/sdk.elf，后处理脚本（download.bat / download.sh）负责生成最终固件并触发下载。

关键编译参数与宏定义（节选）：

# 编译参数设置
CFLAGS := \
	-target pi32 \
	-integrated-as \
	-fno-builtin \
	-mllvm -pi32-memreg-opt \
	-mllvm -pi32-mem-offset-adj-opt \
	-Oz \
	-flto \
	-g \
	-O0 \
	-Os \
	-Wcast-align \
	-Werror \
	-Werror=implicit-function-declaration \
	-Werror=return-type \
	-Wno-format

# 宏定义
DEFINES := \
	-D__FPGA=0 \
	-DCONFIG_CPU_BD49=1 \
	-DAPP_BT_BLE=1 \
	-DSUPPORT_MS_EXTENSIONS \
	-DD_IS_FLASH_SYSTEM \
	-DD_SFC_DEVICE_EN \
	-DHAS_SRC_EN=1 \
	-DHAS_MIO_PLAYER \
	-DHAS_MP3_ST_DECODER \
	-DHAS_WAV_DECODER \
	-DHAS_F1A_DECODER \
	-DHAS_MAX_F1A_NUMBER=2 \
	-DHAS_UMP3_DECODER

Source: sdk/Makefile

宏定义揭示了 SDK 的能力裁剪机制：APP_BT_BLE=1 使能 BLE 应用；CONFIG_CPU_BD49=1 指定 CPU 平台；HAS_*_DECODER 系列宏按需挂载解码器（MP3/WAV/F1A/UMP3 等）；HAS_SRC_EN=1 使能硬件重采样；HAS_MIO_PLAYER 使能 MIO 播放。这些宏与 app_config.h 的应用开关共同构成 SDK 的"功能裁剪面"——按产品需求移除不需要的解码器/模块，可显著减小固件体积与 RAM 占用。

编译流程

flowchart TD
    Start([开始]) --> Env{"操作系统?"}
    Env -->|"Windows"| CB["Code::Blocks 打开 .cbp<br/>或 make_prompt.bat + make -j4"]
    Env -->|"Linux"| MK["cd sdk && make -j`nproc`"]
    CB --> TC["杰理 pi32 工具链 clang / lto-wrapper"]
    MK --> TC
    TC --> CF["CFLAGS: -target pi32 -flto -Os/-Oz -Werror"]
    CF --> DF["DEFINES: APP_BT_BLE=1 / CONFIG_CPU_BD49=1 / HAS_*_DECODER"]
    DF --> LINK["链接 include_lib/liba/*.a 静态库"]
    LINK --> OUT["生成 sdk.elf"]
    OUT --> POST["post_build 后处理脚本<br/>(download.bat / download.sh)"]
    POST --> FW["生成最终固件并下载"]

使用示例

Windows 下通过 make_prompt.bat 进入预配置的命令行环境后编译：

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

# 编译
make -j4

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

Source: README.md

Linux 用户需先安装工具链到 /opt/jieli，确保 /opt/jieli/pi32/bin/clang 存在（见 Makefile 头部注释），然后执行：

# Linux 用户（需要自行修改 download_sh.c 文件适配 Linux）
cd sdk
make -j`nproc`

Sources:

• README.md
• sdk/Makefile

配置说明

SDK 的功能裁剪与平台适配分布在三个层次，配置优先级从高到低为：应用宏开关 → 构建宏定义 → 烧录配置。

注：app_config.h 与 BLE Profile 工具属于应用定制入口；Makefile 宏属于 SDK 级裁剪入口；ISD_CONFIG.INI 属于烧录工具配置。三者职责不同，改动前需确认影响范围。

常见问题与失败模式

以下问题均来自仓库 README 的「常见问题」与「常见编译错误」章节，属于开发者最容易踩到的坑：

边界与注意事项：

• 功耗数据（广播 290uA+、待机 130uA+、关机 2uA+、休眠 61uA+）为官方标注的典型值，实际功耗取决于射频参数、广播间隔、外设负载与应用配置；
• POWER DOWN 休眠功耗 61uA+ 官方注明"后续将会大幅度优化"，量产前应关注 SDK 版本更新；
• 简易 GATT 服务是对标准 GATT 的裁切，仅支持简单数据收发，复杂 profile 场景应使用完整 GATT；
• 工具链为 clang 交叉编译（-target pi32），并使用 -Werror 将告警升级为错误，应用代码需严格消除告警；
• 预编译库（liba/）与源码需配套对应命名规则，混用不同 SDK 版本的库可能导致链接错误。

性能与运维提示

• 并行编译：使用 make -j4（或 -j + CPU 核数）可显著缩短编译时间，Windows 下建议配合 make_prompt.bat；
• 固件体积控制：通过 Makefile 的 HAS_*_DECODER 宏裁剪不需要的解码器，通过 app_config.h 关闭不需要的应用模块，可同时减小 FLASH 占用与 RAM 峰值；
• 调试手段：UART 串口日志输出调试信息；BLE 抓包使用 BLE Dongle 进行空中抓包分析；
• 产线烧录：量产使用杰理生产烧写工具（一拖二/一拖八），支持裸片烧写，与开发阶段的 USB 升级工具区分使用。

相关链接

• 仓库 README（概述/核心特性/快速开始）
• sdk/Makefile（构建系统与宏定义）
• sdk/AW30N_mbox_flash.cbp（Code::Blocks 工程入口）
• 在线文档中心：https://doc.zh-jieli.com/AW30/zh-cn/master/index.html
• SDK 版本历史：doc/AW30N_SDK_发布版本信息.pdf
• SDK 手册：doc/AW30N_SDK手册_V1.7.pdf
• 芯片手册：doc/AW30N_芯片手册_V1.1.pdf
• 硬件设计指南：doc/AW30N硬件设计指南V1.2.pdf
• 芯片选型表：doc/杰理科技AW30N系列芯片选型表_20240816.pdf
• 问题反馈：Gitee Issues