工程结构导航

本文档是 fw-AW33N_BLE_SDK 的工程结构导航页，帮助开发者快速定位 SDK 根目录、应用工程（apps/demo/）、应用与 BSP 代码（apps/app/）、公共 BSP 模块（apps/app/bsp/common/）、板级配置（board/）以及构建系统（Makefile / default.workspace）的组织方式与职责边界，为后续阅读各功能模块文档提供全局地图。

目的与范围

本页面向首次接触该 SDK 的开发者，梳理整个仓库的目录骨架，并解释每个顶层目录/文件在编译链路与运行期中的角色。内容基于仓库实际文件清单与 README.md 中「五、工程结构」相关章节交叉整理。

本页不展开的具体话题由同级页面覆盖：

• 环境搭建（工具链/烧录工具安装）→ 见「环境搭建」
• 如何选择一个应用工程 → 见「应用选择指南」
• 编译与烧录细节 → 见「编译指南」「烧录与升级」
• 具体模块（如 G-Sensor、红外、UART）的内部实现 → 见各自的模块文档

概述

fw-AW33N_BLE_SDK 是杰理科技为 AW33N 系列芯片（bd57 平台：AW332A / AW333A / AW336A / AW336A0 / AW338A）提供的通用蓝牙 SDK 固件开发包，基于裸机操作系统，内置完整 BLE 协议栈（Core v5.4，QDID DN:Q332415），支持 BLE 透传/数传（透传、数传、扫描/广播设备、适配器、AT 模组、定位器等）与 HID 人机交互（媒体控制、遥控器、自拍器、翻页器、3 模鼠标等）两类典型产品形态。

仓库同时包含 SDK Release 代码与示例工程，编译时需要配合对应命名规则的库文件（lib.a）和子仓库。工程结构的核心矛盾在于"一套 SDK、多种产品"：因此顶层目录把通用代码（BSP、公共驱动）与产品应用（demo 工程）分离，板级差异进一步下沉到各工程的 board/ 子目录，从而支持同一份公共代码快速派生不同产品。

架构总览

flowchart TD
    subgraph sg_Root["SDK 根目录"]
        README["README.md / README-en.md<br/>工程说明与文档入口"]
        Makefile["Makefile<br/>Linux 命令行编译入口"]
        Workspace["default.workspace<br/>Code::Blocks 工作区"]
        Script["make_prompt.bat<br/>Windows 辅助脚本"]
        License["LICENSE"]
    end

    subgraph sg_Apps["apps/ 应用目录"]
        DemoTransfer["apps/demo/transfer<br/>BLE 透传/数传应用"]
        DemoHid["apps/demo/hid<br/>HID 人机交互应用"]
        AppCode["apps/app<br/>应用与 BSP 代码"]
    end

    subgraph sg_Bsp["apps/app/bsp/common/ 公共 BSP 模块"]
        BtCommon["bt_common/ble_test_api.c"]
        CodeSwitch["code_switch/"]
        CommonUart["common_uart/"]
        Config["config/lib_power_config.c"]
        Gsensor["gsensor/fmy/"]
        IR["ir/ir_decoder.c + ir_encoder.c"]
    end

    README -->|"说明文档"| DemoTransfer
    README --> DemoHid
    Makefile -->|"Linux 编译"| DemoTransfer
    Makefile --> DemoHid
    Workspace -->|"Windows IDE 编译"| DemoTransfer
    Workspace --> DemoHid
    DemoTransfer --> AppCode
    DemoHid --> AppCode
    AppCode --> BtCommon
    AppCode --> CodeSwitch
    AppCode --> CommonUart
    AppCode --> Config
    AppCode --> Gsensor
    AppCode --> IR

图 1：fw-AW33N_BLE_SDK 顶层工程结构。仓库根目录只保留文档与构建入口；产品代码集中在 apps/ 下。应用工程（apps/demo/transfer、apps/demo/hid）通过 Makefile（Linux）或 default.workspace（Windows Code::Blocks）构建，共享 apps/app/ 下的应用与 BSP 代码；apps/app/bsp/common/ 是跨产品复用的公共驱动集合（蓝牙测试 API、编码开关、UART、电源配置、G-Sensor、红外编解码）。该依赖关系由目录层级与命名推断，具体工程的实际依赖以各应用工程内的构建配置为准。

关键设计意图

1. 构建入口与代码分离：根目录的 Makefile 与 default.workspace 只是入口，真正的源码在 apps/，这使同一仓库可同时支持 Windows（Code::Blocks）与 Linux（Makefile + clang 工具链）两种开发方式。
2. 通用/产品两级划分：apps/demo/* 是面向具体产品的示例工程（每个产品一个目录），apps/app/bsp/common/ 是通用板级支持包。新增产品时优先新增 demo 工程并复用 common 模块，而不是复制公共驱动。
3. 平台差异下沉到 board/：每个应用目录下的 board/ 按芯片平台（如 bd57）组织，板级配置（引脚、外设、时钟等）与应用逻辑隔离，便于同一应用快速切换到不同芯片型号。

目录结构详解

根目录（SDK 根）

仓库根目录仅包含 6 个条目（经仓库文件清单验证）：

根目录刻意保持精简：所有源码均位于 apps/ 下，构建配置由 Makefile/default.workspace 统一编排，文档入口统一指向 README.md（其中包含指向文档中心与版本历史的链接）。

apps/ 应用目录

按 README「四、快速开始」的说明，应用工程按产品形态划分为两个 demo 目录：

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

• apps/demo/transfer/：BLE 透传/数传类应用（透传、数据采集、扫描/广播设备、适配器、AT 模组、定位器等）。
• apps/demo/hid/：HID 人机交互类应用（媒体播放控制、遥控器、自拍器、翻页器、鼠标等）。
• apps/app/：应用与 BSP 代码所在目录（见下节）。

说明：本页未逐一展开 apps/demo/* 工程内部文件；apps/app/bsp/common/ 模块清单来自仓库实际文件扫描，apps/demo 的划分来自 README。若需每个 demo 工程内部目录树的权威说明，请直接阅读 README「五、工程结构」章节正文。

apps/app/bsp/common/ 公共 BSP 模块

该目录是跨产品复用的板级支持包（BSP），按功能模块分子目录。以下是仓库中实际存在的模块（文件清单验证）：

flowchart TD
    subgraph sg_Common["apps/app/bsp/common/"]
        BT["bt_common/<br/>ble_test_api.c — 蓝牙测试 API"]
        CS["code_switch/<br/>code_switch.c/.h — 编码开关驱动"]
        CU["common_uart/<br/>common_uart_control.c/.h — 通用 UART 控制"]
        CF["config/<br/>lib_power_config.c — 电源管理配置"]
        GS["gsensor/fmy/<br/>G-Sensor 驱动层<br/>gsensor_api / gSensor_manage /<br/>msa310 / SC7A20 / Motion_api"]
        IR["ir/<br/>ir_decoder.c / ir_encoder.c — 红外编解码"]
    end
    Common["公共 BSP 层"] --> BT
    Common --> CS
    Common --> CU
    Common --> CF
    Common --> GS
    Common --> IR

图 2：apps/app/bsp/common/ 公共模块地图。各模块职责说明：

设计意图：把多产品共享的驱动（串口、红外、传感器、电源、编码开关、蓝牙测试）抽到 common 层，避免每个 demo 工程重复实现；产品特有逻辑只留在各自 demo 工程内。新增传感器型号时，只需在 gsensor/fmy/ 下补充驱动并接入 gSensor_manage 管理框架即可。

board/ 板级配置

每个应用目录下都有 board/ 子目录，按芯片平台划分。README 中给出的示例：

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

• bd57/ 对应 AW33N 系列芯片平台（AW332A / AW333A / AW336A / AW336A0 / AW338A）。
• 板级配置内包含产品应用配置与 demo 板级配置两类（README 注明 3 个产品应用 + 1 个 demo 板级配置）。

设计意图：芯片型号与具体开发板的差异（引脚复用、外设开关、时钟）被隔离在 board/ 下，应用代码通过统一的板级抽象访问硬件；切换芯片或开发板时通常只改 board/ 而不改应用逻辑，这也是"一套 SDK、多种产品"能成立的关键。

构建系统

SDK 同时支持 Windows 与 Linux 两种构建路径，入口文件都位于根目录：

• Windows：default.workspace（Code::Blocks IDE 工程），推荐 IDE 方式编译。
• Linux：Makefile 命令行编译，依赖杰理工具链（/opt/jieli/common/bin/clang）。

flowchart TD
    Start([开始]) --> Clone["git clone 获取 SDK"]
    Clone --> Env{"安装杰理工具链?"}
    Env -->|"未安装"| Install["安装工具链<br/>验证: clang --version"]
    Env -->|"已安装"| Choose["选择应用工程<br/>transfer 或 hid"]
    Install --> Choose
    Choose --> Board["选择 board 板级配置<br/>如 bd57"]
    Board --> Build{"构建方式?"}
    Build -->|"Linux"| Make["Makefile + clang 编译"]
    Build -->|"Windows"| CB["Code::Blocks 打开 default.workspace"]
    Make --> Out["生成固件"]
    CB --> Out
    Out --> Burn["烧录与升级<br/>USB 升级工具 / 生产烧写工具 / 无线测试盒"]

图 3：构建与烧录主流程。关键约束：SDK Release 代码需要配合对应命名规则的库文件（lib.a）与子仓库才能完整编译（README「一、概述」明确说明），因此克隆后若编译报缺库/缺头文件，应优先检查是否已拉取配套子仓库与库文件。

使用示例

以下示例均提取自仓库 README 原文。

示例 1：克隆仓库并选择应用工程

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 人机交互设备等应用

Source: README.md

按产品形态选择 transfer（透传/数传类）或 hid（人机交互类）工程后，即可进入该目录下的 board/ 选择芯片平台配置。

示例 2：选择芯片型号和板级配置

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

Source: README.md

board/bd57/ 内包含 AW33N 系列的产品应用板级配置与 demo 板级配置，开发者按实际开发板选择对应配置。

示例 3：验证编译工具链

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

Source: README.md

工具链安装（Linux 解压到 /opt/jieli 且 clang 可执行）是 Makefile 编译路径的前置条件；Windows 下则通过 Code::Blocks 打开 default.workspace 编译。

配置选项

工程层面的"配置"分散在构建入口与板级目录中，主要配置入口如下：

说明：各应用工程的详细编译选项（宏开关、优化等级、内存布局等）位于各工程目录内的具体构建/配置文件中，本页不逐一展开，详见「配置说明」页面与 README「九、配置说明」章节。

故障模式与注意事项

依据 README 与仓库结构，以下问题最容易在"入门阶段"出现：

1. 缺库/缺子仓库导致编译失败：SDK Release 代码依赖配套的 lib.a 与子仓库。若编译报找不到库或头文件，优先检查子仓库是否拉取、库文件命名是否与工程匹配，而非修改源码。
2. 工具链路径不对：Linux 下要求 /opt/jieli/common/bin/clang 存在；Windows 下需使用 Code::Blocks 而非其他 IDE，否则 default.workspace 无法正确解析。
3. 选错应用工程：透传/数传类需求应进 apps/demo/transfer，HID 类需求应进 apps/demo/hid；两者 BSP 复用但应用逻辑差异较大，混用会导致功能不符合预期。
4. 选错板级配置：同一平台 bd57 下有多个产品板级配置与 demo 配置，需按实际开发板选择；选错可能导致外设（UART/红外/G-Sensor）初始化失败。

扩展点

结合 apps/app/bsp/common/ 的模块化设计，常见的扩展方式：

• 新增传感器型号：在 gsensor/fmy/ 下添加传感器驱动源文件，接入 gSensor_manage 管理框架（现有 msa310、SC7A20 可作模板）。
• 新增红外协议：扩展 ir/ir_decoder.c / ir_encoder.c，在编解码层追加协议分支。
• 新增产品应用：在 apps/demo/ 下新建工程目录，复用 apps/app/bsp/common/ 公共模块，并在根目录 Makefile / default.workspace 中登记新的构建目标。
• 切换芯片平台：在应用工程的 board/ 下新增平台目录（参考 bd57/），保持应用代码与板级配置分离。

相关链接

• README.md（仓库主文档）
• README-en.md（英文版）
• Makefile（构建入口）
• default.workspace（Code::Blocks 工作区）
• 公共 BSP 模块：apps/app/bsp/common/（bt_common · code_switch · common_uart · config · gsensor · ir）
• 官方文档中心：https://doc.zh-jieli.com/AW33/zh-cn/master/index.html
• 同级导航：环境搭建 · 应用选择指南 · 编译指南 · 烧录与升级 · 配置说明