芯片平台与 SDK 概述

fw-AW31N_BLE_SDK 是杰理科技（Jieli Technology）为 AW31N 系列蓝牙芯片提供的通用固件开发包，基于裸机（bare-metal）操作系统，内置完整 BLE 协议栈与两类应用示例（transfer / hid），覆盖从芯片选型、工程组织、编译构建到烧录升级的完整开发链路。

Purpose and Scope

本文档是 AW31N 芯片平台与 SDK 的顶层导读，面向初次接触该 SDK 的开发者与集成工程师，说明：

• AW31N 芯片系列（bd47 平台）的型号、定位与蓝牙认证情况
• SDK 的整体分层架构与模块组织方式
• 应用工程（transfer / hid）与板级配置（board）的关系
• 编译系统（Makefile / Code::Blocks / VS Code）的入口与 target 规则
• 预编译静态库（lib.a）与头文件库（include_lib）的链接模型
• 烧录升级工具链与配置体系

以下内容属于其他独立页面，不在本文展开：具体应用 API 与示例代码（见对应应用页面）、BLE 协议栈内部细节（见协议栈页面）、烧录工具操作步骤（见工具链页面）、版本历史（见 doc 目录与文档中心）。

Overview

AW31N 是杰理科技面向 BLE 透传/数传 与 HID 人机交互 两大场景的蓝牙 SoC 系列。SDK 采用"源码应用层 + 预编译库内核"的发布模式：蓝牙协议栈（controller / host）、CPU 外设驱动、媒体与系统库以静态库（lib.a）形式随仓库发布，开发者只修改和编译应用层（apps/app、apps/demo）与板级配置（board/），从而在保证内核稳定与认证一致性的同时，大幅降低二次开发门槛。

核心设计意图：

1. 裸机调度，无 RTOS 依赖：系统消息队列（msg）与任务调度由 SDK 自带机制提供，适合对资源占用敏感的 BLE 外设类产品。
2. 平台与板级解耦：芯片平台（bd47）决定库文件与 CPU 启动代码；board/ 目录决定引脚、外设与功能开关，二者通过 Makefile 与 board_*_cfg.h 组合。
3. 应用可裁剪：config/ 目录决定编译进固件的库功能，配合 board_*_global_build_cfg.h 的功能开关，可按产品需求裁剪固件体积。
4. 多 IDE 支持：同一套板级工程同时提供 Code::Blocks（.cbp）、Makefile 与 VS Code（tasks.json）三种构建入口，覆盖 Windows / Linux 开发环境。

Architecture

下图展示了 SDK 的分层架构与数据/依赖流向：

flowchart TD
    subgraph sg_App["应用层 apps/demo"]
        AppTransfer["transfer 应用<br/>透传/数传/AT模组"]
        AppHid["hid 应用<br/>键盘/鼠标/遥控器/手柄"]
        Examples["examples/ 示例实现"]
        Include["include/ 应用接口"]
    end

    subgraph sg_Common["公共层 apps/app"]
        Bsp["bsp/ 公共模块<br/>key/ir/msg/uart/vm/update/usb..."]
        Cpu["cpu/ 系统相关"]
        Start["start/ 上电启动入口"]
        Postbuild["postbuild/ 下载工具与脚本"]
    end

    subgraph sg_Lib["内核与驱动层 include_lib"]
        BtController["bt_controller_lib.a<br/>蓝牙控制器"]
        BtProtocol["bt_protocol_lib.a<br/>BLE 协议栈"]
        CpuLib["cpu_lib.a 等预编译库"]
        Headers["头文件<br/>bt/device/fs/msg/update/flash"]
    end

    subgraph sg_Board["板级配置 board/bd47"]
        BoardCfg["board_*_cfg.h 引脚/外设"]
        BuildCfg["board_*_global_build_cfg.h 功能开关"]
        Makefile["Makefile / board_*.cbp"]
    end

    AppTransfer --> Examples
    AppHid --> Examples
    Examples --> Include
    AppTransfer --> Bsp
    AppHid --> Bsp
    Bsp --> Headers
    Headers --> BtController
    Headers --> BtProtocol
    Bsp --> CpuLib
    Start --> CpuLib
    BoardCfg --> AppTransfer
    BoardCfg --> AppHid
    BuildCfg --> AppTransfer
    BuildCfg --> AppHid
    Makefile --> Postbuild
    Postbuild -->|"download.bat / fw_add.exe<br/>isd_download.exe"| Target[("目标板固件 .hex")]

架构说明：

• 应用层（apps/demo）：transfer 与 hid 是两类完整可编译的产品工程，各自包含 board/（板级配置）、examples/（参考实现）、include/（接口）与 config/（库裁剪）。
• 公共层（apps/app）：跨工程共享的模块与 SDK 配置，bsp/common/ 下按功能划分驱动（按键 key/、红外 ir/、旋转编码器 codeswitch/、鼠标传感器 mouse_sensor/、串口 common_uart/、USB、VM 存储、OTA 升级 update/ 等）；start/ 是上电后的应用层启动入口。
• 内核与驱动层（include_lib）：所有库实现以静态库发布，头文件按子系统分组（蓝牙控制器、蓝牙协议栈、设备驱动、文件系统、消息队列、升级、CPU、Flash）。
• 板级配置（board/bd47）：每个应用目录下按芯片平台划分板级子目录，把"芯片平台"与"具体产品板"组合成可编译单元。

芯片平台：bd47

SDK 当前支持的芯片平台为 bd47，具体型号与适用应用如下：

蓝牙协议支持情况：

来源：README.md

设计要点： 同一平台（bd47）覆盖多款型号，意味着硬件差异被收敛到板级配置层（引脚复用、外设使能、Flash 大小），而库文件与协议栈保持同一套，SDK 的"平台"概念是芯片家族维度，而非单个型号维度。选型时先确定芯片系列，再在 board/bd47/ 下选择或新建对应板级配置即可。

SDK 目录结构

fw-AW31N_BLE_SDK/
├── apps
│   ├── app/                # 应用层代码
│   │   ├── bsp/            # 公共模块、SDK配置和输出
│   │   │   ├── common/     # 公共模块处理（跨工程共享）
│   │   │   │   ├── bt_common/          # 蓝牙通用处理
│   │   │   │   ├── codeswitch/         # 旋转编码器驱动
│   │   │   │   ├── common_uart/        # 通用串口适配驱动
│   │   │   │   ├── ir/                 # 红外驱动处理
│   │   │   │   ├── key/                # 按键驱动处理
│   │   │   │   ├── mouse_sensor/       # 传感器驱动处理
│   │   │   │   ├── msg/                # 系统消息处理
│   │   │   │   ├── temp_trim/          # 系统温度自适应处理
│   │   │   │   ├── third_party_profile/# 第三方协议处理
│   │   │   │   ├── update/             # 固件升级处理
│   │   │   │   ├── usb/                # usb驱动处理
│   │   │   │   ├── vm/                 # 系统消息处理
│   │   │   │   └── my_malloc.c         # 系统堆申请处理
│   │   │   ├── cpu                      # CPU、系统相关处理文件
│   │   │   └── start                    # 上电应用层启动入口处理
│   │   └── postbuild/                   # 工程编译前配置和下载目录等
│   │       └── bd47/                    # 各芯片平台的 lib.a 库文件 + 工具脚本
│   ├── demo/
│   │   ├── hid/                         # HID 应用（键盘/鼠标/遥控器/游戏手柄）
│   │   └── tranfer/                     # BLE 应用
│   └── include_lib/                     # 头文件（bt协议栈、驱动、媒体、系统、cpu等）
│       ├── bt_controller_include/       # 蓝牙控制器的头文件
│       ├── bt_include/                  # 蓝牙协议栈的头文件
│       ├── device/                      # 外设驱动的头文件
│       ├── fs/                          # 文件系统的头文件
│       ├── msg/                         # 系统消息队列的头文件
│       ├── update/                      # 无线OTA升级的头文件
│       ├── common/                      # 通用公共的头文件
│       ├── cpu/                         # 各芯片平的头文件
│       └── flash/                       # 各芯片平台的 lib.a 库文件
├── doc/                    # SDK发布文档资源：版本发布信息、芯片数据手册、硬件设计资料、使用说明文档等
├── tools/
│   └── make_prompt.bat     # Windows 编译命令行入口
├── Makefile                # 顶层 Makefile（统一编译入口）
├── default.workspace       # Code::Blocks 工作空间
└── .vscode/                # VS Code 配置（tasks.json 预定义编译任务）

来源：README.md

关键目录职责

来源：README.md

分层解读

• bsp/common：跨工程共享的"中间件"层，把芯片外设能力封装为业务模块（按键、红外、编码器、传感器、消息、存储、升级），让应用代码不直接面对寄存器。
• include_lib：只读的"SDK 契约"层。头文件是开放的，实现以静态库形式交付。开发时通过头文件调用协议栈与驱动 API，但无法修改库内部实现——这是保持 BLE 认证（QDID）一致性的关键设计。
• postbuild：编译后处理与下载环节，包含固件打包（fw_add.exe）与烧写（isd_download.exe）工具，属于构建流水线的一部分。

构建系统与编译流程

顶层 Makefile 目标

顶层 Makefile 是统一编译入口，支持两个应用 target，且 all 默认同时构建两者：

# 支持的目标
# make aw31n_transfer
# make aw31n_hid

.PHONY: all clean aw31n_transfer aw31n_hid clean_aw31n_transfer clean_aw31n_hid

all: aw31n_transfer aw31n_hid
	@echo +ALL DONE

clean: clean_aw31n_transfer clean_aw31n_hid
	@echo +CLEAN DONE

aw31n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd47 -f Makefile

clean_aw31n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd47 -f Makefile clean

aw31n_hid:
	$(MAKE) -C apps/demo/hid/board/bd47 -f Makefile

clean_aw31n_hid:
	$(MAKE) -C apps/demo/hid/board/bd47 -f Makefile clean

来源：Makefile

设计要点： 顶层 Makefile 只做"目标 → 板级目录"的路由，真正的编译逻辑下沉到 apps/demo/*/board/bd47/Makefile。每个板级目录是一个独立的可编译单元，这允许同一 SDK 源码树同时产出 transfer 与 hid 两套固件，也便于厂商在 board/bd47/ 下新增自有板型而不触碰公共代码。

构建流程

flowchart TD
    Start([开发者]) --> Choose{"选择应用"}
    Choose -->|"make aw31n_transfer"| T["apps/demo/transfer/board/bd47"]
    Choose -->|"make aw31n_hid"| H["apps/demo/hid/board/bd47"]
    Choose -->|"Code::Blocks .cbp"| CB["board_*.cbp 工程"]
    Choose -->|"VS Code Ctrl+Shift+B"| VS["tasks.json 任务"]

    T --> B1["board Makefile<br/>编译应用源码 + 链接 lib.a"]
    H --> B1
    CB --> B1
    VS --> B1

    B1 --> B2["postbuild 工具<br/>fw_add.exe 打包"]
    B2 --> B3["输出 .hex 固件"]
    B3 --> B4{"烧录方式"}
    B4 -->|"USB 升级工具"| U1["USB 强制升级"]
    B4 -->|"生产烧写工具"| U2["量产/裸片烧写"]
    B4 -->|"无线测试盒"| U3["空中升级/射频标定"]
    U1 --> Done([目标板运行])
    U2 --> Done
    U3 --> Done

三种构建入口对比

编译产物 .hex 位于对应板级目录下，通过烧录工具写入目标板。

板级配置体系

每个应用目录下的 board/bd47/ 是"平台 × 板型"的组装点，包含：

来源：README.md

设计意图： 将"硬件差异"与"业务逻辑"分离——board_xxx_cfg.h 描述"这块板上有什么外设、接在哪个引脚"，board_xxx_global_build_cfg.h 描述"这次固件要包含哪些功能"。产品工程师改板级文件即可适配新硬件，应用工程师则专注于 examples/ 中的业务逻辑。

Usage Examples

克隆与快速开始

以下命令序列展示了从克隆仓库到完成一次编译的完整流程：

git clone https://github.com/Jieli-Tech/fw-AW31N_BLE_SDK.git
# 或者
git clone https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK.git

cd fw-AW31N_BLE_SDK

来源：README.md

按产品需求选择工程

SDK 根目录
├── apps/demo/transfer    # BLE 透传/数传等应用
└── apps/demo/hid/        # HID 人机交互设备等应用

来源：README.md

选择芯片型号与板级配置

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

来源：README.md

Code::Blocks 编译（Windows）

# 1. 进入对应的板级目录
cd apps/demo/hid/board/bd47/

# 2. 双击打开 .cbp 工程文件（如 AW31N_hid.cbp）
# 3. 在 Code::Blocks 中点击 Build → Build (Ctrl+F9)
# 4. 编译成功后，使用 USB 升级工具烧录生成的 .hex 文件

来源：README.md

Makefile 命令行编译（Linux/macOS）

# Windows 用户：双击 tools/make_prompt.bat 打开命令行环境
# Linux/macOS 用户：直接进入 SDK 根目录

# 编译完整工程
make aw31n_hid

# 编译完成后，在对应 board 目录下找到生成的 .hex 文件

来源：README.md

验证编译工具链

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

来源：README.md

Configuration Options

SDK 的配置分散在多个层级，按作用域从大到小排列：

配置优先级说明： 库裁剪配置（config/）决定链接进固件的库功能集合；板级全局编译开关（board_*_global_build_cfg.h）进一步裁剪应用侧模块；引脚级差异由 board_xxx_cfg.h 承载。三者共同决定最终固件的体积与功能，是产品化的主要调优点。

来源：README.md、README.md

故障模式与边界情况

以下结论基于 SDK 结构与发布形态推断得出，供集成时注意（实现细节未在本次阅读范围内）：

性能与运维注意事项

• 固件体积控制：内核为预编译库，应用侧可通过 config/ 裁剪 + 板级功能开关（board_*_global_build_cfg.h）减小固件；my_malloc.c 提供系统堆管理，动态内存申请集中在应用层。
• 构建产物定位：make aw31n_transfer / make aw31n_hid 的 .hex 产物位于对应 board/bd47/ 目录下；postbuild/ 中的 fw_add.exe、isd_download.exe 负责固件打包与烧写。
• 烧录与升级：量产场景使用生产烧写工具与无线测试盒（支持空中升级与射频标定）；开发阶段使用 USB 升级工具进行强制升级。
• 文档资源：doc/ 目录内置版本发布信息、芯片数据手册与硬件设计资料；在线文档中心（doc.zh-jieli.com/AW31）提供持续更新的使用说明与版本历史。

Extension Points

• 新增产品板型：在 apps/demo/{transfer,hid}/board/bd47/ 下复制现有板级目录，修改 board_xxx.c / board_xxx_cfg.h / board_xxx_global_build_cfg.h，并配套 Makefile 与 .cbp 工程，即可形成独立编译单元。
• 新增应用逻辑：在 apps/demo/*/examples/ 中编写参考实现，通过 include/ 暴露接口，复用 bsp/common/ 下的公共模块（key、ir、uart、msg、update、vm 等）。
• 第三方协议接入：bsp/common/third_party_profile/ 是第三方协议处理的预留位置，适合接入私有透传协议或行业 Profile。

Related Links

• README.md（SDK 总览与快速开始）
• 顶层 Makefile（编译目标定义）
• README-en.md（英文版说明）
• default.workspace（Code::Blocks 工作空间）
• tools/make_prompt.bat（Windows 编译环境入口）
• 在线文档中心：https://doc.zh-jieli.com/AW31/zh-cn/master/index.html
• SDK 版本历史：https://doc.zh-jieli.com/AW31/zh-cn/master/other/version/index.html

相关子页面导航：transfer 应用细节参见「BLE 透传应用」页面；HID 应用细节参见「HID 人机交互应用」页面；工具链与烧录流程参见「烧录与升级」页面。