音频、升级与其他库

本文档介绍 fw-AW31N_BLE_SDK 中与音频（Audio）、固件升级（Update/OTA） 以及其他预编译库相关的头文件、配置、模块、工具与使用方式，帮助开发者理解 SDK 的库系统构成并快速定位音频、升级相关代码入口。

Purpose and Scope

本页面向 AW31N 系列 BLE SDK 的"库"主题，集中说明三类内容：

  • 音频库：apps/include_lib/audio/ 下的类型定义头文件、apps/include_lib/device/usb/device/uac_audio.h（USB Audio Class）、板级音频配置 audio_v1.lua，以及 apps/demo/transfer/examples/dongle/dg_audio_demo.c 参考实现。
  • 升级库：apps/include_lib/update/（无线 OTA 升级头文件）、apps/app/bsp/common/update/（固件升级处理模块）、烧录/升级工具链，以及 patch_release/ 补丁发布目录。
  • 其他库：apps/include_lib/liba/bd**/flash/ 下的预编译静态库（如 bt_controller_lib.a、bt_protocol_lib.a、cpu_lib.a 等）及其配套头文件目录（bt_include、bt_controller_include、device、fs、msg、common、cpu、flash）。

以下主题属于其他目录页范围，不在本页展开：BLE 透传/数传应用（transfer）、HID 人机交互应用、板级引脚/外设的详细接线说明、编译环境搭建步骤。本文档聚焦"库"的构成与使用边界。

Overview

fw-AW31N_BLE_SDK 是杰理科技为 AW31N 系列芯片提供的通用蓝牙 SDK 固件开发包。SDK 基于裸机操作系统，采用"源码 + 预编译库（*.a）+ 头文件"的经典发布形态：业务逻辑以源码形式提供在 apps/app 与 apps/demo，蓝牙协议栈、CPU 驱动、媒体处理等以静态库形式发布在 apps/include_lib/liba/bd**/flash/，对外接口通过 apps/include_lib 下按功能划分的头文件目录暴露。

这一设计决定了音频与升级能力的接入方式：

  • 音频：应用层通过包含 audio_typedef.h 等头文件获得类型与接口声明，具体实现位于预编译库中；板级音频参数（采样率、音量、通路等）由配置工具生成的 audio_v1.lua 脚本维护，在编译期由 AW31N_config_tool 读取并生成配置。
  • 升级：SDK 提供两套升级路径——有线烧录（USB 升级工具、生产烧写工具）与空中升级（无线测试盒 / BLE OTA）。OTA 相关的接口头文件位于 apps/include_lib/update/，升级处理逻辑位于 apps/app/bsp/common/update/。SDK 还通过 patch_release/ 目录发布增量补丁（例如 AW31N_开机&低功耗&VM兼容性修复说明_20250102/AW31N_sdk_v1.1.0_update_patch），说明升级机制同时支持整包与补丁两种形态。
  • 其他库：bt_controller_lib.a（蓝牙控制器）、bt_protocol_lib.a（蓝牙协议栈）、cpu_lib.a（CPU/系统驱动）等预编译库是 SDK 功能的核心载体，配合 bt_controller_include/、bt_include/、cpu/ 等头文件使用，并通过板级全局编译配置（board_xxx_global_build_cfg.h）进行功能裁剪。

Architecture

下图展示音频、升级与其他库在 SDK 中的整体位置及相互关系（节点名均来自仓库实际路径）：

flowchart TD
    subgraph sg_App["应用层 apps/demo"]
        Transfer["transfer 透传/数传"]
        Hid["hid 人机交互"]
        AudioDemo["dg_audio_demo.c 音频示例"]
    end

    subgraph sg_Include["头文件层 apps/include_lib"]
        AudioH["audio/audio_typedef.h"]
        UacH["device/usb/device/uac_audio.h"]
        UpdateH["update/ OTA 头文件"]
        BtH["bt_include / bt_controller_include"]
        OtherH["device / fs / msg / common / cpu / flash"]
    end

    subgraph sg_Lib["预编译库 liba/bd47/flash"]
        BtLib["bt_controller_lib.a"]
        BtProto["bt_protocol_lib.a"]
        CpuLib["cpu_lib.a"]
    end

    subgraph sg_Update["升级处理 apps/app/bsp/common/update"]
        UpdateMod["固件升级处理模块"]
    end

    subgraph sg_Config["板级与库配置"]
        BoardCfg["board_xxx_cfg.h 引脚/外设"]
        BuildCfg["board_xxx_global_build_cfg.h 功能开关"]
        AudioLua["audio_v1.lua 音频配置"]
        ConfigTool["AW31N_config_tool 配置工具"]
    end

    subgraph sg_Tools["烧录与升级工具"]
        UsbTool["USB 升级工具"]
        ProdTool["生产烧写工具"]
        TestBox["无线测试盒 空中升级"]
    end

    Transfer --> BtH
    Hid --> BtH
    AudioDemo --> AudioH
    AudioDemo --> UacH
    AudioH --> BtLib
    UacH --> BtLib
    BtH --> BtLib
    BtH --> BtProto
    OtherH --> CpuLib
    UpdateH --> UpdateMod
    UpdateMod --> BtLib
    UpdateMod --> CpuLib
    ConfigTool --> AudioLua
    BoardCfg --> Transfer
    BuildCfg --> Transfer
    BuildCfg --> Hid
    UsbTool --> UpdateMod
    TestBox --> UpdateMod
    ProdTool --> UpdateMod

图中各层职责：

  • 应用层（apps/demo/transfer、apps/demo/hid）通过 apps/demo/*/examples/ 下的参考实现（如 dg_audio_demo.c）演示如何调用库接口。
  • 头文件层（apps/include_lib）是应用与预编译库之间的契约：audio/、update/、bt_include/、device/ 等目录分别声明音频、OTA、蓝牙协议栈和外设驱动接口。
  • 预编译库层（apps/include_lib/liba/bd47/flash/）承载实际实现，按芯片平台（bd47）命名目录，包含 bt_controller_lib.a、bt_protocol_lib.a、cpu_lib.a 等。
  • 升级模块（apps/app/bsp/common/update/）与应用层的升级入口对接，配合 apps/include_lib/update/ 的 OTA 接口实现固件写入。
  • 配置与工具层负责把板级差异（引脚、外设、音频参数、功能开关）转化为编译期配置，并借助外部烧录工具完成固件落地。

音频库

音频能力在 SDK 中以"头文件声明 + 预编译库实现 + 板级配置"的方式提供。仓库中与音频直接相关的文件包括：

文件作用
apps/include_lib/audio/audio_typedef.h音频公共类型定义，应用层包含该头文件获得音频接口的类型与常量
apps/include_lib/device/usb/device/uac_audio.hUSB Audio Class（UAC）设备头文件，用于 USB 音频设备形态
apps/demo/transfer/examples/dongle/dg_audio_demo.c音频示例应用（dongle 形态），演示音频接口的调用方式
apps/app/post_build/bd47/AW31N_config_tool/conf/source/board_common/audio_v1.lua音频通用配置脚本（board_common 平台级）
apps/app/post_build/bd47/AW31N_config_tool/conf/source/board/audio_v1.lua音频板级配置脚本（具体板型）

说明：上述头文件的具体接口签名位于预编译库所对应的头文件中，本次源码探索未能读取其完整内容（探索预算已用尽）；以下基于文件路径、目录结构与 README 描述进行说明，涉及实现细节处已如实标注。

音频类型定义与 USB 音频

apps/include_lib/audio/audio_typedef.h 是音频子系统的类型总入口，供所有调用音频库的应用包含。uac_audio.h 位于 USB 设备驱动目录（apps/include_lib/device/usb/device/），说明 AW31N 支持将芯片作为 USB 音频设备（UAC）使用——这通常用于 dongle/适配器类产品，通过 USB 连接主机、通过 BLE 连接外设，实现音频数据的双向转发。

音频板级配置（audio_v1.lua）

音频参数不直接写在 C 代码中，而是由 AW31N_config_tool（配置工具）读取 conf/source/ 下的 Lua 脚本生成。仓库中存在两份 audio_v1.lua：

  • conf/source/board_common/audio_v1.lua：所有板型共享的音频默认配置；
  • conf/source/board/audio_v1.lua：针对具体板型的音频覆盖配置。

这种"common + board"的配置分层与板级 C 配置（board_xxx_cfg.h 与 board_xxx_global_build_cfg.h）的设计意图一致：把平台共性与板级差异分离，减少重复配置、便于派生新板型。

音频示例应用

apps/demo/transfer/examples/dongle/dg_audio_demo.c 位于 transfer 应用的 dongle 示例目录，是音频接口调用的直接参考。dongle 形态下，芯片一端连接 USB 主机、一端运行 BLE 协议栈，音频示例展示了如何在数传工程中接入音频通路。

音频调用流程

flowchart LR
    subgraph sg_AudioApp["应用层"]
        Demo["dg_audio_demo.c"]
    end
    subgraph sg_AudioHdr["头文件契约"]
        AT["audio_typedef.h"]
        UAC["uac_audio.h"]
    end
    subgraph sg_AudioCfg["配置层"]
        LUA["audio_v1.lua"]
        TOOL["AW31N_config_tool"]
    end
    subgraph sg_AudioLib["预编译库"]
        LIB["音频/媒体 lib.a"]
    end
    subgraph sg_AudioHW["硬件形态"]
        DAC["DAC / Codec"]
        USB["USB Audio (UAC)"]
    end

    TOOL --> LUA
    Demo --> AT
    Demo --> UAC
    Demo --> LIB
    AT --> LIB
    UAC --> LIB
    LUA --> LIB
    LIB --> DAC
    LIB --> USB

流程要点：应用包含 audio_typedef.h 等头文件获得接口声明 → 调用预编译音频库中的实现 → 音频库依据 audio_v1.lua 生成的配置驱动 DAC/Codec 或 USB Audio 通路。配置变更（如采样率、音量）通过修改 Lua 脚本并重新执行配置工具完成，应用代码无需改动——这是配置与代码解耦的设计选择，便于非软件人员调整音频参数。

升级库

升级（固件升级/OTA）是 BLE 产品量产与售后维护的关键能力。SDK 将其拆分为"接口头文件 + 处理模块 + 外部工具"三部分。

模块与文件结构

位置作用
apps/include_lib/update/无线 OTA 升级的头文件（接口声明，供应用调用）
apps/app/bsp/common/update/固件升级处理模块（apps/app/bsp/common/ 下的公共模块之一）
patch_release/SDK 补丁发布目录，包含增量补丁包与说明文档
apps/app/post_build/bd47/编译产物与烧录工具目录（download.bat、fw_add.exe、isd_download.exe 等）

在 apps/app/bsp/common/ 目录下，update/ 与 bt_common/（蓝牙通用处理）、msg/（系统消息）、vm/（掉电保存/系统消息）、usb/、key/、ir/ 等模块并列，说明升级模块是公共业务层的一部分，通过系统消息机制与应用主循环协作。

升级工具链

README 列出了三类官方工具，对应不同的使用阶段：

工具用途阶段
USB 升级工具将固件烧录到目标板（支持强制升级）开发调试 / 售后
生产烧写工具量产/裸片烧写生产
无线测试盒空中升级（OTA）/ 射频标定 / 产品测试产测 / 售后

工具与 SDK 的对接点在 apps/app/bsp/common/update/ 模块：有线工具通过 USB/串口把固件写入 Flash，无线测试盒则通过 BLE 空中通道传输固件数据，由 update 模块接收、校验并写入。

升级流程

flowchart TD
    Start(["编译固件"]) --> Build["make aw31n_xxx / Code::Blocks"]
    Build --> Hex["生成 .hex 固件"]
    Hex --> Choice{"选择升级方式"}
    Choice -->|"USB 有线"| Usb["USB 升级工具 / 生产烧写工具"]
    Choice -->|"空中升级"| Ota["无线测试盒 / BLE OTA"]
    Usb --> UpdateMod["目标板 update 模块"]
    Ota --> UpdateMod
    UpdateMod --> Flash["写入 Flash 固件区"]
    Flash --> Verify{"校验通过?"}
    Verify -->|"是"| Ok["升级成功，重启运行新固件"]
    Verify -->|"否"| Fail["升级失败，使用强制升级恢复"]
    Ok --> End([结束])
    Fail --> End

补丁机制（patch_release）

仓库根目录的 patch_release/ 用于发布增量修复，例如：

  • AW31N_开机&低功耗&VM兼容性修复说明_20250102/AW31N_sdk_v1.1.0_update_patch/sdk/...

该补丁包结构完整复刻了 SDK 目录（apps/app/post_build/bd47/AW31N_config_tool/conf/source/board_common/audio_v1.lua 等），开发者可将补丁内容合并到工程对应路径后重新编译。补丁名称中的关键词（开机、低功耗、VM 兼容性）提示了升级模块与低功耗管理、VM（掉电保存）存储之间存在紧密耦合——OTA 升级涉及 Flash 分区与 VM 数据区，若处理不当可能引发兼容性问题，这正是补丁机制存在的原因之一。

升级核心交互时序

sequenceDiagram
    participant Dev as 开发者
    participant Build as 编译链（Makefile）
    participant Tool as 升级工具
    participant Target as 目标板
    participant UpdateMod as update 模块
    participant Flash as Flash

    Dev->>Build: 选择 target 编译
    Build-->>Dev: 生成 .hex 固件
    Dev->>Tool: 选择固件与升级方式
    Tool->>Target: 传输固件（USB / BLE 空中通道）
    Target->>UpdateMod: 接收固件数据
    UpdateMod->>Flash: 写入固件区
    Flash-->>UpdateMod: 写入完成
    UpdateMod-->>Tool: 上报升级结果
    Tool-->>Dev: 完成 / 失败提示

说明：update 模块内部的具体协议（分包、校验算法、Flash 分区布局）位于预编译库与 apps/app/bsp/common/update/ 实现中，本次探索未读取到其源码细节；以上流程依据 README 工具说明与目录结构归纳，属可信的架构级描述而非逐行实现。

其他库（预编译库与头文件）

预编译静态库

SDK 的核心功能以静态库形式发布在 apps/include_lib/liba/bd**/flash/（bd47 平台），README 明确列出的库包括：

库文件职责
bt_controller_lib.a蓝牙控制器（射频/基带层）
bt_protocol_lib.a蓝牙协议栈（Host 层，含 BLE 协议）
cpu_lib.aCPU/系统驱动（时钟、外设寄存器等）

库按芯片平台分目录存放（如 bd47），与 apps/app/post_build/bd47/ 的板级工具目录一一对应。这种"平台目录 + 预编译库"的组织方式意味着：更换芯片平台时必须同时更换对应的 lib.a 与头文件，不可混用。

头文件目录

apps/include_lib/ 下按功能划分的头文件目录与预编译库配合使用：

  • bt_controller_include/、bt_include/：蓝牙控制器与协议栈接口；
  • device/：外设驱动接口（含 usb/device/uac_audio.h）；
  • fs/：文件系统接口；
  • msg/：系统消息队列接口；
  • update/：无线 OTA 升级接口；
  • common/：通用公共接口；
  • cpu/：芯片平台相关接口；
  • audio/：音频类型定义（见上文音频库章节）；
  • flash/：Flash 驱动接口。

库裁剪与功能开关

库功能通过板级全局编译配置开关，即 board_xxx_global_build_cfg.h（README 中定义为"全局编译配置（功能开关）"）。该头文件与 board_xxx_cfg.h（引脚、外设配置）配合，决定编译时链接哪些库功能、启用哪些特性。裁剪配置位于 apps/demo/*/config/，README 称其为"库配置：各模块的裁剪配置（决定编译哪些库功能）"——这是控制固件体积与功耗的主要手段。

Usage Examples

以下示例均提取自仓库 README（源码探索预算内实际读取的文件）。

工程结构概览（音频/升级/库所在位置）

apps/
├── app/                      # 应用层代码
│   ├── bsp/
│   │   └── common/
│   │       ├── bt_common/            # 蓝牙通用处理
│   │       ├── update/               # 固件升级处理
│   │       ├── usb/                  # USB 驱动处理
│   │       └── vm/                   # 系统消息处理
│   └── post_build/bd47/              # 各芯片平台的 lib.a 库文件 + 工具脚本
├── demo/
│   ├── hid/                          # HID 应用
│   └── transfer/                     # BLE 应用
└── include_lib/                      # 头文件（bt协议栈、驱动、媒体、系统、cpu等）
    ├── bt_controller_include/        # 蓝牙控制器的头文件
    ├── bt_include/                   # 蓝牙协议栈的头文件
    ├── device/                       # 外设驱动的头文件
    ├── fs/                           # 文件系统的头文件
    ├── msg/                          # 系统消息队列的头文件
    ├── update/                       # 无线OTA升级的头文件
    └── common/                       # 通用公共的头文件

Source: README.md

板级目录与配置

apps/demo/hid/board/
├── bd47/   # AW31N 系列 (3个产品应用和1个demo板级配置)

每个芯片目录下包含：

  • Makefile - 编译脚本
  • board_*.cbp - Code::Blocks 工程文件
  • board_xxx.c - 板级初始化代码
  • board_xxx_cfg.h - 板级配置（引脚、外设等）
  • board_xxx_global_build_cfg.h - 全局编译配置（功能开关）

Source: README.md

编译与烧录入口

# 克隆仓库
git clone https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK.git

# 编译完整工程（Linux/macOS）
make aw31n_hid

# 编译完成后，在对应 board 目录下找到生成的 .hex 文件，使用 USB 升级工具烧录

Source: README.md

Configuration Options

以下配置项均来自仓库实际路径与 README 描述：

配置项类型默认说明
board_xxx_cfg.h头文件依板型板级引脚、外设配置
board_xxx_global_build_cfg.h头文件依板型全局编译配置（功能开关，决定库裁剪）
apps/demo/*/config/目录—各模块的库裁剪配置
audio_v1.lua（board_common）Lua 脚本—音频通用配置（配置工具读取）
audio_v1.lua（board）Lua 脚本—音频板级配置（覆盖通用配置）
Makefile target（如 aw31n_hid）编译目标见 Makefile 注释选择要编译的应用工程
default.workspaceCode::Blocks 工作空间—IDE 工程入口

说明：audio_v1.lua 内部的具体字段（采样率、通路、音量等）需在配置工具文档中确认；本次源码探索未读取到 Lua 脚本内容，故未列出字段级配置。

API Reference

音频与升级的对外接口以头文件形式提供，但具体函数签名位于预编译库对应的头文件中，本次源码探索（6 次工具调用预算）未能读取到实现/声明细节，因此不在此处杜撰任何 API 签名。开发者应以仓库中的实际头文件为准：

  • 音频类型：apps/include_lib/audio/audio_typedef.h
  • USB 音频：apps/include_lib/device/usb/device/uac_audio.h
  • OTA 接口：apps/include_lib/update/ 目录

这些文件的路径与说明见上文"音频库""升级库"章节的文件表。

Failure Modes, Edge Cases & Concurrency

基于仓库实际证据（补丁说明与工具文档），升级相关的风险与边界如下：

  • 升级失败与强制升级：README 中 USB 升级工具配套文档名为 forced_upgrade（强制升级），说明协议中存在升级中断/校验失败后的恢复通道——当固件写入不完整或校验失败时，可通过强制升级模式重新烧录，避免设备变砖。设计意图：Flash 写入是幂等且可重入的，升级工具在任意失败点都能重新开始。
  • 低功耗与升级的耦合：补丁 AW31N_开机&低功耗&VM兼容性修复说明 提示，开机流程、低功耗（休眠/唤醒）与 VM（掉电保存）存储的兼容性会直接影响升级可靠性。OTA 升级过程中若系统进入低功耗状态或 VM 数据布局变更，可能导致升级中断或旧数据损坏，因此 SDK 以补丁形式持续修复此类问题。
  • VM 兼容性：vm/ 模块负责系统消息与掉电保存，固件升级会改写 Flash 内容，若新固件改变 VM 分区布局，旧数据可能无法读取——这正是补丁名称中"VM兼容性修复"的由来。
  • 并发/时序：SDK 为裸机架构，升级模块通过系统消息（msg/）与应用主循环协作，升级期间应避免其他模块并发写 Flash；具体互斥机制位于预编译库实现中，源码未暴露。
  • 平台库混用：预编译库按平台目录（bd47）存放，跨平台混用 lib.a 与头文件属于非法配置，会导致链接失败或运行异常。

Performance & Operational Notes

  • 固件体积控制：通过 board_xxx_global_build_cfg.h 与 apps/demo/*/config/ 裁剪库功能是控制 ROM/RAM 占用的主要手段，音频、USB、OTA 等模块可按需启用。
  • 裸机实时性：音频与升级处理均在裸机环境执行，音频回调与升级数据接收依赖中断/消息机制，关键路径应避免长时间关中断。
  • 升级通道选择：开发阶段推荐 USB 有线升级（速度快、可强制恢复），量产使用生产烧写工具，售后远程修复使用无线测试盒/OTA。

Extension Points

  • 新增板型：复制 board/ 下现有板级目录，修改 board_xxx_cfg.h（引脚/外设）与 audio_v1.lua（音频参数）即可派生新硬件。
  • 新增应用：参考 apps/demo/transfer/examples/dongle/dg_audio_demo.c 的写法，在 examples 目录新增示例，包含音频/升级相关头文件后调用库接口。
  • 升级通道扩展：apps/app/bsp/common/update/ 是升级处理入口，可在此扩展自定义升级协议（如私有透传通道），头文件契约见 apps/include_lib/update/。
  • 补丁合入：将 patch_release/ 中对应版本的补丁内容合并到工程同名路径后重新编译，是官方推荐的修复合入方式。

Tests

本次源码探索未在仓库中发现针对音频/升级库的单元测试文件（apps/demo/*/examples/ 以示例程序为主，apps/include_lib/ 为头文件与预编译库）。测试与验证主要依赖：

  • 无线测试盒的产测流程（空中升级/射频标定/产品测试）；
  • 各 demo 板级工程的编译与烧录验证。

若需了解更细的验证手段，请参考官方文档中心：AW31 文档中心。