SDK 总览

fw-AW33N_BLE_SDK 是杰理科技为 AW33N 系列芯片提供的通用蓝牙 SDK 固件开发包，基于裸机操作系统，内置完整的蓝牙 BLE 协议栈与丰富的应用示例，支持 BLE 透传/数传与 HID 人机交互两大应用方向。

Purpose and Scope

本文是 SDK 的总览页，面向刚接触该仓库的开发者，提供进入其他专题页之前所需的全局图景，包括：

• SDK 的定位、支持的芯片平台与蓝牙认证情况；
• 仓库整体目录结构与分层架构（应用层、板级配置、预编译库、构建系统）；
• 两大示例工程（transfer 与 hid）的适用场景与选择指南；
• 环境搭建、编译、烧录与升级的完整流程；
• 功能裁剪与板级配置的入口文件；
• 常见编译问题与排障路径。

以下专题属于独立页面的范围，本文只做指引、不展开：BLE 透传/数传应用细节（见 TRANSFER 应用页）、HID 设备实现细节（见 HID 应用页）、OTA 升级机制（见升级专题页）、各外设驱动（按键、红外、串口、传感器等）的驱动说明。烧录工具与量产脚本的细节请参考文档中心的工具说明。

Overview

SDK 是什么

fw-AW33N_BLE_SDK 是杰理科技（Jieli Tech）面向 AW33N 系列芯片发布的 Release 版本固件开发包。它不同于应用商店类的运行时框架——它是一整套可编译、可烧录的固件工程：源码以裸机（bare-metal）方式运行，无操作系统依赖，蓝牙 BLE 协议栈以预编译静态库（lib.a）形式提供，应用层与板级代码以源码形式开放，开发者通过修改板级配置与功能裁剪配置即可快速产出量产固件。

支持的应用场景

芯片与蓝牙协议支持

蓝牙协议栈已通过蓝牙 SIG 认证（Core v5.4 / v6.0，QDID: DN:Q332415），可直接用于产品化开发、评估、样品及量产。

设计要点（WHY）

• 裸机 + 预编译库：协议栈与底层 CPU 驱动以 lib.a 形式交付，降低源码泄密风险并缩短编译时间；应用层源码开放，保证可定制性。
• 板级目录即工程：每个芯片平台对应一个 board/ 子目录，内含 Makefile、Code::Blocks 工程文件（.cbp）、板级初始化代码与配置头文件——开发者"复制最接近的板级目录"即可开创新工程。
• 功能裁剪配置驱动编译：config/ 目录下的 lib_*_config.c 决定编译进固件的库功能，既控制固件体积，也是"undefined reference"类错误的常见根因。

Architecture

下图展示了 SDK 从顶层构建入口到应用层、板级与预编译库的完整依赖关系：

flowchart TD
    subgraph sg_Top["顶层构建入口"]
        Makefile["顶层 Makefile"]
        Workspace["default.workspace"]
        VSCODE[".vscode/tasks.json"]
    end

    subgraph sg_Demo["示例工程 apps/demo"]
        Transfer["transfer（BLE 透传/数传）"]
        Hid["hid（HID 人机交互）"]
    end

    subgraph sg_App["应用层 apps/app"]
        BSP["bsp 公共模块"]
        Start["start 上电启动入口"]
        Postbuild["postbuild 编译后处理"]
    end

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

    subgraph sg_Lib["预编译资源 apps/include_lib"]
        LibA["lib.a 静态库（bt_controller / bt_protocol / cpu 等）"]
        Headers["头文件（bt / device / fs / msg / update ...）"]
        Tools["烧录与后处理工具"]
    end

    Makefile --> Transfer
    Makefile --> Hid
    Workspace --> BoardMake
    VSCODE --> Makefile
    Transfer --> BSP
    Hid --> BSP
    Transfer --> BoardCfg
    Hid --> BoardCfg
    Transfer --> GlobalCfg
    Hid --> GlobalCfg
    BSP --> Start
    BSP --> Postbuild
    BSP --> Headers
    Transfer --> LibA
    Hid --> LibA
    LibA --> Headers
    Postbuild --> Tools

架构分层说明

这一分层的设计意图是：把"芯片相关"与"产品相关"分离——芯片差异收敛在 board/ 与 include_lib，产品逻辑写在应用层；换芯片型号时只需复制/新增板级目录并替换对应平台的 lib.a，无需改动应用代码。

工程结构详解

仓库根目录布局如下（依据 README 与目录扫描结果整理）：

fw-AW33N_BLE_SDK/
├── apps
│   ├── app/                    # 应用层代码
│   │   ├── bsp/                # 公共模块、SDK 配置与输出
│   │   │   ├── common/         # 跨工程共享模块
│   │   │   │   ├── bt_common/        # 蓝牙通用处理（如 ble_test_api.c）
│   │   │   │   ├── codeswitch/       # 旋转编码器驱动
│   │   │   │   ├── common_uart/      # 通用串口适配驱动
│   │   │   │   ├── ir/               # 红外驱动（ir_decoder.c / ir_encoder.c）
│   │   │   │   ├── key/              # 按键驱动
│   │   │   │   ├── mouse_sensor/     # 鼠标传感器驱动
│   │   │   │   ├── gsensor/          # G-sensor（如 fmy 系列）
│   │   │   │   ├── msg/              # 系统消息处理
│   │   │   │   ├── temp_trim/        # 系统温度自适应处理
│   │   │   │   ├── third_party_profile/  # 第三方协议处理
│   │   │   │   ├── update/           # 固件升级处理
│   │   │   │   ├── usb/              # USB 驱动处理
│   │   │   │   ├── vm/               # VM 数据管理
│   │   │   │   └── my_malloc.c       # 系统堆申请处理
│   │   │   ├── cpu/             # CPU、系统相关处理
│   │   │   └── start/           # 上电应用层启动入口
│   │   └── postbuild/           # 编译后配置与下载目录（含各芯片平台 lib.a + 工具脚本）
│   ├── demo/
│   │   ├── hid/                 # HID 应用（键盘/鼠标/遥控器/游戏手柄）
│   │   └── transfer/            # BLE 透传/数传应用
│   └── include_lib/             # 对外头文件与预编译库
│       ├── 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 预定义编译任务）

关键目录职责

构建系统（顶层 Makefile）

顶层 Makefile 是唯一推荐的统一编译入口，它不直接编译任何源码，而是把编译动作委托给各板级目录下的 Makefile：

源码见 Makefile

# 总的 Makefile，用于调用目录下各个子工程对应的 Makefile
# 注意： Linux 下编译方式：
# 1. 从 http://pkgman.jieliapp.com/doc/all 处找到下载链接
# 2. 下载后，解压到 /opt/jieli 目录下，保证
#   /opt/jieli/common/bin/clang 存在（注意目录层次）
# 3. 确认 ulimit -n 的结果足够大（建议大于8096），否则链接可能会因为打开文件太多而失败
#   可以通过 ulimit -n 8096 来设置一个较大的值
# 支持的目标
# make aw33n_transfer
# make aw33n_hid

.PHONY: all clean aw33n_transfer aw33n_hid clean_aw33n_transfer clean_aw33n_hid

all: aw33n_transfer aw33n_hid
	@echo +ALL DONE

clean: clean_aw33n_transfer clean_aw33n_hid
	@echo +CLEAN DONE

aw33n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd57 -f Makefile

clean_aw33n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd57 -f Makefile clean

aw33n_hid:
	$(MAKE) -C apps/demo/hid/board/bd57 -f Makefile

clean_aw33n_hid:
	$(MAKE) -C apps/demo/hid/board/bd57 -f Makefile clean

设计意图："目标名 = 芯片平台 + 应用"（如 aw33n_hid = AW33N 芯片 + hid 应用）。新增应用或芯片时，只需在顶层 Makefile 增加一条委托规则，编译入口保持不变；clean 与 all 则批量透传到所有子工程。

核心流程：从克隆到烧录

下图展示从获取源码到固件落板的完整开发闭环：

flowchart TD
    Start([开始]) --> Clone["git clone 仓库"]
    Clone --> Toolchain{"杰理工具链已安装?"}
    Toolchain -->|"否"| Install["安装工具链<br/>确保 /opt/jieli/common/bin/clang 存在"]
    Install --> Board
    Toolchain -->|"是"| Board["选择应用工程与板级目录<br/>apps/demo/*/board/bd57"]
    Board --> Config["配置引脚/外设/功能开关<br/>board_*_cfg.h / config/lib_*_config.c"]
    Config --> Compile{"编译方式?"}
    Compile -->|"Code::Blocks"| CB["打开 .cbp 工程<br/>Build → Build (Ctrl+F9)"]
    Compile -->|"命令行"| Make["make aw33n_transfer / make aw33n_hid"]
    Compile -->|"VS Code"| VSC["Ctrl+Shift+B 选择任务"]
    CB --> Hex["生成 .hex 固件"]
    Make --> Hex
    VSC --> Hex
    Hex --> Flash["USB 升级工具 isd_download.exe 烧录"]
    Flash --> Test["板级验证 / 串口日志调试"]
    Test --> End([完成])

步骤说明

1. 克隆仓库：git clone https://gitee.com/Jieli-Tech/fw-AW33N_BLE_SDK.git，SDK 依赖 lib.a 与子仓库，需完整克隆。
2. 准备工具链：Windows 推荐 Code::Blocks；Linux 需将工具链解压到 /opt/jieli 并保证 clang 可用，同时建议 ulimit -n 8096（链接阶段需打开大量文件）。
3. 选择工程与板级：按产品形态在 apps/demo/transfer 与 apps/demo/hid 之间选择，再进入对应 board/bd57 目录。
4. 配置裁剪：修改 board_*_cfg.h（引脚、外设、时钟）与 config/lib_*_config.c（库功能开关）——这是控制固件体积与功能集的关键步骤。
5. 编译：三条等价路径（Code::Blocks / Makefile / VS Code 任务），产物为 .hex 固件。
6. 烧录：目标板进入编程模式（按住烧录键复位），使用 isd_download.exe 选择 .hex 下载；量产场景使用生产烧写工具与无线测试盒（支持空中升级与射频标定）。

应用选择指南

TRANSFER（apps/demo/transfer）

HID（apps/demo/hid）

使用示例

示例一：克隆仓库并选择工程

以下命令来自 README「快速开始」章节，是进入开发的第一步：

源码见 README.md

git clone https://gitee.com/Jieli-Tech/fw-AW33N_BLE_SDK.git

cd fw-AW33N_BLE_SDK

# 根据产品需求选择应用工程
SDK 根目录
├── apps/demo/transfer    # BLE 透传/数传等应用
└── apps/demo/hid/        # HID 人机交互设备等应用

示例二：命令行编译（Linux/macOS）

源码见 README.md 与 Makefile

# Windows 用户：双击 tools/make_prompt.bat 进入预配置命令行环境

# Linux/macOS：先确保工具链存在且文件描述符足够
ulimit -n 8096

# 编译完整工程（在 SDK 根目录执行）
make aw33n_transfer
# 或
make aw33n_hid

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

# 批量操作
make all      # 编译全部工程
make clean    # 清理全部编译产物
make clean_aw33n_hid   # 清理单个工程

示例三：Code::Blocks 图形化编译（Windows 推荐）

源码见 README.md

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

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

示例四：验证工具链

源码见 README.md

# 验证杰理编译工具链是否安装成功
clang --version

配置选项

SDK 的配置分布在两类文件中：库功能裁剪配置（apps/demo/*/config/）与板级配置（apps/demo/*/board/*/）。

库功能裁剪配置

板级配置

配置原则：功能裁剪配置决定"编译哪些库功能"，板级配置决定"硬件如何连接"。改动配置后若出现 undefined reference to ...，通常是裁剪配置未包含对应模块所致。

失败模式、边界情况与排障

常见编译错误

边界情况与注意事项

• 新工程创建：复制 apps/ 下与芯片型号最接近的板级目录，修改 board_xxx_cfg.h 的引脚与外设配置即可——不要从零搭建目录。
• 新增芯片型号：需在 cpu/ 下创建平台目录并提供对应 liba/ 库文件与 tools/ 烧录工具，再在 apps/demo/*/board/ 下添加板级目录。
• 烧录前置条件：目标板必须进入编程模式（按住烧录键后复位或重新上电），否则 isd_download.exe 无法识别设备。
• 并发编译：make -j 并行编译可显著提速，但 Linux 下需同步调大 ulimit -n，否则并行链接阶段更容易触发"打开文件过多"。

调试技巧

• 串口日志：通过 log_config.c 配置日志输出等级与通道，是定位协议栈与应用行为问题的第一手段。
• GPIO Debug：利用空闲 GPIO 输出调试波形测量时序，适用于外设时序类问题。

性能与运维提示

• 固件体积控制：通过 config/lib_*_config.c 裁剪未用模块（如去掉不需要的 Profile、驱动），是控制 ROM/RAM 占用的主要手段。
• 量产流程：裸片量产使用生产烧写工具；产线测试与空中升级使用无线测试盒（1 拖 2），支持射频标定。
• OTA 升级：支持单备份与双备份蓝牙 OTA，详见升级专题文档；升级相关源码位于 apps/app/bsp/common/update 与 apps/include_lib/update。
• 版本管理：Release 版本通过 Tag 管理，切换版本前核对 版本历史 与 doc/ 目录下的发布说明。

扩展点

• 应用层扩展：在 apps/app/bsp/common 下新增公共模块，或在 apps/demo/*/examples 中新增示例应用；msg 系统消息机制为模块间通信提供统一入口。
• 外设扩展：按键（key）、红外（ir）、旋转编码器（code_switch）、G-sensor（gsensor）、通用串口（common_uart）等公共驱动可直接复用，按 board_xxx_cfg.h 映射引脚即可接入新硬件。
• 第三方协议：定位器（Findmy & Find Hub）等第三方协议通过 third_party_profile 目录接入。
• 新芯片/新板：按"复制最近板级目录"的方式扩展，构建系统（顶层 Makefile + 板级 Makefile）无需改动。

Related Links

• README.md（SDK 总说明）
• Makefile（顶层编译入口）
• TRANSFER 开发文档
• HID 开发文档
• SDK 架构文档（模块架构说明）
• OTA 升级文档
• SDK 版本历史
• 在线文档中心
• 问题反馈（Gitee Issues）