应用选择与工程总览

本页介绍杰理 AC63 系列蓝牙 SDK（fw-AC63_BT_SDK）的三大应用工程（SPP + BLE、HID、Mesh）、芯片平台与板级配置体系、顶层编译入口，以及如何根据产品需求选择正确的工程并完成编译烧录。

Purpose and Scope

本文档是 SDK 应用层的"入口地图"，覆盖以下内容：

• 三大应用工程 apps/spp_and_le、apps/hid、apps/mesh 的适用场景与关键特性
• 芯片平台（bd19 / br23 / br25 / br34）与板级配置目录的对应关系
• 顶层 Makefile 的编译目标（target）与工程路由逻辑
• 应用工程内部结构（board/、examples/、include/、config/）
• 配置体系（板级配置头文件、库裁剪配置）与常见编译/烧录问题

不在本页范围内：具体模块的 API 细节、蓝牙协议栈实现、OTA 升级流程、Mesh 协议细节等，请参见文档中心的对应模块页面（如 SPP_LE 开发文档、HID 开发文档、Mesh 开发文档）。

Overview

fw-AC63_BT_SDK 是杰理科技为 AC63 系列芯片提供的通用蓝牙 SDK 固件开发包，基于 Zephyr RTOS 实时操作系统，内置完整蓝牙协议栈（已通过蓝牙 SIG Core v5.4 认证，QDID 222830）。SDK 采用"应用工程 × 芯片平台 × 板级配置"三层组织方式：

1. 应用层（apps/）：按产品形态划分的三大应用工程——spp_and_le（数据透传/数传）、hid（人机交互设备）、mesh（物联网组网），外加 common/ 公共模块。
2. 平台层（cpu/）：按芯片平台提供预编译静态库（liba/*.a）与烧录工具脚本。
3. 板级层（board/）：每个应用工程下的板级配置目录，包含引脚定义、外设初始化、编译选项与功能开关。

选择工程的本质是回答三个问题：做什么产品（应用）→ 用哪颗芯片（平台）→ 用哪块开发板/硬件（板级配置）。三者确定后，即可通过统一的顶层 Makefile 或 Code::Blocks 工程完成编译。

仓库还预配置了 VS Code 编译任务（.vscode/tasks.json），按下 Ctrl+Shift+B 即可选择编译目标。

Architecture

flowchart TD
    subgraph sg_Top["顶层构建入口"]
        MK["Makefile<br/>统一编译入口"]
        WS["default.workspace<br/>Code::Blocks 工作空间"]
        VS[".vscode/tasks.json<br/>VS Code 任务"]
    end

    subgraph sg_Apps["应用层 apps/"]
        SPP["spp_and_le<br/>SPP + BLE 透传/数传"]
        HID["hid<br/>HID 人机交互"]
        MESH["mesh<br/>Bluetooth Mesh 物联"]
        COMMON["common<br/>公共模块（跨工程共享）"]
    end

    subgraph sg_Board["板级配置 board/"]
        B19["bd19<br/>AC632N 系列"]
        B23["br23<br/>AC635N 系列"]
        B25["br25<br/>AC636N 系列"]
        B34["br34<br/>AC638N 系列"]
    end

    subgraph sg_Cpu["平台层 cpu/"]
        LIBA["liba/*.a<br/>预编译静态库"]
        CTOOLS["tools/<br/>烧录工具脚本"]
    end

    MK --> SPP
    MK --> HID
    MK --> MESH
    WS --> SPP
    WS --> HID
    WS --> MESH
    VS --> SPP
    VS --> HID
    VS --> MESH
    SPP --> B19
    SPP --> B23
    SPP --> B25
    SPP --> B34
    HID --> B19
    HID --> B23
    HID --> B25
    HID --> B34
    MESH --> B19
    MESH --> B23
    MESH --> B25
    MESH --> B34
    B19 --> LIBA
    B23 --> LIBA
    B25 --> LIBA
    B34 --> LIBA
    B19 --> CTOOLS
    B23 --> CTOOLS
    B25 --> CTOOLS
    B34 --> CTOOLS
    COMMON -.-> SPP
    COMMON -.-> HID
    COMMON -.-> MESH

架构说明：

• 顶层构建入口：Makefile 将每个 make <芯片>_<应用> 目标路由到对应应用工程的板级目录（如 make ac632n_hid 进入 apps/hid/board/bd19 执行该目录下的 Makefile）；Code::Blocks 工作空间与 VS Code 任务则提供 IDE 侧的编译入口。三种入口最终都会落到同一个板级 Makefile 上。
• 应用层：spp_and_le、hid、mesh 三个工程各自独立，互不编译依赖；common/ 下的音频、设备驱动、升级、第三方协议等模块通过 include 路径被各工程共享（虚线表示共享引用）。
• 板级配置：每个应用工程下都有按芯片平台划分的 board/<平台>/ 目录，一个平台目录内可包含多个板级配置（如 bd19 下有 32 个板级配置），每个板级目录自成一套可编译工程。
• 平台层：cpu/<平台>/liba/ 存放该平台预编译的 .a 静态库（btctrler、btstack、media、driver 等），板级链接时按 config/ 下的裁剪配置决定链接哪些库功能；cpu/<平台>/tools/ 提供 isd_download.exe、fw_add.exe 等烧录与固件加工工具。

应用工程详解

SPP + BLE（apps/spp_and_le/）

经典蓝牙 SPP 与 BLE 双模透传/数传应用，是最通用的数据类工程：

选择依据：产品需要"设备与手机/主机之间传输数据"（透传、数传、定位信标、外设 Dongle）时，首选本工程。

HID（apps/hid/）

人机交互设备应用，面向按键/指针/遥控类产品：

选择依据：产品需要向主机（PC/手机/电视）上报按键、指针或媒体控制指令时，首选本工程；examples/ 目录下提供了可直接参考或修改的参考实现。

Mesh（apps/mesh/）

Bluetooth Mesh 物联网组网应用：

选择依据：产品需要多节点组网、低功耗物联或接入国内主流智能家居平台（天猫精灵/涂鸦/腾讯连连）时，首选本工程；第三方协议实现位于 apps/common/third_party_profile/。

即将推出的应用

芯片平台与板级配置

SDK 支持的芯片平台与可用的应用工程矩阵如下（来自 README.md）：

每个应用目录下的 board/ 子目录按芯片平台划分，每个板级目录是一套完整可编译的工程：

apps/hid/board/
├── bd19/   # AC632N 系列 (32个板级配置)
├── br23/   # AC635N 系列
├── br25/   # AC636N 系列
└── br34/   # AC638N 系列

源码出处：README.md

每个板级目录下包含的文件及作用：

设计意图：将"应用逻辑"与"硬件差异"解耦——同一份应用代码（如 HID 键盘逻辑）通过不同的板级目录适配不同芯片与不同 PCB，新增硬件只需复制最接近的板级配置并修改引脚/外设即可，无需改动应用层。

应用选择决策流程

flowchart TD
    Start([产品需求]) --> Q1{"需要什么无线功能?"}
    Q1 -->|"数据透传 / 数传 / FindMy / Dongle"| SPP["apps/spp_and_le"]
    Q1 -->|"键盘 / 鼠标 / 遥控器 / 手柄"| HID["apps/hid"]
    Q1 -->|"智能照明 / 传感器网络 / 平台接入"| MESH["apps/mesh"]
    SPP --> Q2{"选择芯片平台"}
    HID --> Q2
    MESH --> Q2
    Q2 -->|"AC632N"| B19["board/bd19"]
    Q2 -->|"AC635N"| B23["board/br23"]
    Q2 -->|"AC636N"| B25["board/br25"]
    Q2 -->|"AC638N"| B34["board/br34"]
    B19 --> Q3{"选择编译方式"}
    B23 --> Q3
    B25 --> Q3
    B34 --> Q3
    Q3 -->|"Code::Blocks"| CB["打开 .cbp 工程<br/>Ctrl+F9 编译"]
    Q3 -->|"命令行"| MK["make ac63xx_&lt;app&gt;"]
    CB --> HEX["生成 .hex 固件"]
    MK --> HEX
    HEX --> FLASH["USB 升级工具烧录 / OTA 升级"]

流程说明：第一步根据产品形态确定应用工程；第二步根据硬件选型确定芯片平台；第三步选择编译入口。make 目标的命名规则为 ac63xx_<app>（芯片缩写 + 下划线 + 应用名），例如 ac632n_hid、ac636n_mesh。

工程结构总览

SDK 根目录的关键结构（来自 README.md）：

fw-AC63_BT_SDK/
├── apps/                          # 应用层代码
│   ├── common/                    # 公共模块（跨工程共享）
│   │   ├── audio/                 #   音频编解码、音量控制
│   │   ├── bt_common/             #   蓝牙通用接口
│   │   ├── cJSON/                 #   JSON 解析库
│   │   ├── debug/                 #   调试工具
│   │   ├── device/                #   外设驱动（按键、USB、传感器等）
│   │   ├── jl_kws/                #   杰理关键词唤醒
│   │   ├── music/                 #   音乐播放
│   │   ├── update/                #   固件升级
│   │   └── third_party_profile/   #   第三方协议（SigMesh、涂鸦、腾讯连连、HiLink）
│   ├── spp_and_le/                # 📌 SPP + BLE 应用
│   ├── hid/                       # 📌 HID 应用（键盘/鼠标/遥控器/游戏手柄）
│   └── mesh/                      # 📌 Mesh 应用
├── cpu/                           # CPU 相关代码与库文件
│   ├── bd19/ → br34/              #   各芯片平台的 lib.a 库文件 + 工具脚本
│   ├── .../
│   └── br34/
├── include_lib/                   # 头文件（bt协议栈、驱动、媒体、系统等）
├── doc/                           # 文档资源（datasheet、架构、FAQ）
├── tools/                         # 编译工具与脚本（make_prompt.bat 等）
├── Makefile                       # 顶层 Makefile（统一编译入口）
├── default.workspace              # Code::Blocks 工作空间
└── .vscode/                       # VS Code 配置（tasks.json 预定义编译任务）

顶层 Makefile 与编译目标

顶层 Makefile 是统一的编译入口，开头的注释完整列出了所有受支持的 target，并在 .PHONY 中显式声明。其路由逻辑是：每个 make <target> 调用对应应用工程板级目录下的 Makefile，例如：

ac638n_spp_and_le:
	$(MAKE) -C apps/spp_and_le/board/br34 -f Makefile

clean_ac638n_spp_and_le:
	$(MAKE) -C apps/spp_and_le/board/br34 -f Makefile clean

源码出处：Makefile

同时 all 目标会顺序编译全部 18 个 target，clean 目标清理全部产物：

all: ac638n_spp_and_le ac632n_spp_and_le ac631n_spp_and_le ac636n_spp_and_le ac637n_spp_and_le ac635n_spp_and_le ac638n_hid ac632n_hid ac631n_hid ac636n_hid ac637n_hid ac635n_hid ac638n_mesh ac632n_mesh ac631n_mesh ac636n_mesh ac637n_mesh ac635n_mesh
	@echo +ALL DONE

源码出处：Makefile

编译命令速查表

以下命令在 SDK 根目录下执行（来自 README.md）：

清理单个工程使用 clean_<target> 前缀，例如 make clean_ac632n_spp_and_le。

快速开始示例

# 1. 克隆仓库
git clone https://github.com/Jieli-Tech/fw-AC63_BT_SDK.git
cd fw-AC63_BT_SDK

# 2. 根据产品需求选择应用工程
#    apps/spp_and_le/    # SPP + BLE 透传/数传应用
#    apps/hid/           # HID 人机交互设备应用
#    apps/mesh/          # Bluetooth Mesh 物联应用

# 3. 命令行编译（Linux/Windows make_prompt 环境）
make ac632n_spp_and_le

# 4. 并行编译加速
make ac632n_spp_and_le -j`nproc`

# 5. 编译产物为 board 目录下的 .hex 文件，使用 USB 升级工具烧录

源码出处：README.md

设计意图：顶层 Makefile 采用"薄路由层"设计——自身不包含任何编译规则，只负责把目标名映射为板级目录路径并递归调用；这样新增芯片平台或板级配置时，只需在顶层追加一行路由，编译逻辑全部收敛在板级 Makefile 中。

配置选项

功能裁剪配置（apps/<app>/config/）

每个应用工程的 config/ 目录通过以下文件灵活裁剪 SDK 功能，减小固件体积（来自 README.md）：

apps/hid/config/
├── lib_btctrler_config.c    # 蓝牙控制器配置
├── lib_btstack_config.c     # 蓝牙协议栈配置
├── lib_driver_config.c      # 驱动模块配置
├── lib_media_config.c       # 媒体模块配置
├── lib_profile_config.c     # 蓝牙 Profile 配置
├── lib_system_config.c      # 系统模块配置
├── lib_update_config.c      # 升级模块配置
└── log_config.c             # 日志输出配置

板级配置头文件

board_xxx_cfg.h 包含：

• 引脚映射：UART / SPI / I2C / GPIO 等外设的引脚分配
• 外设使能：开启或关闭特定外设模块
• 时钟配置：CPU 频率、外设时钟源

board_xxx_global_build_cfg.h 包含：

• 功能开关：按需启用/禁用特定功能
• 内存配置：堆栈大小、缓冲池大小

源码出处：README.md

设计意图：配置采用"两层分离"——config/ 控制"编译哪些库功能"（决定链接的库符号与固件体积），board_*.h 控制"硬件怎么用"（引脚/外设/时钟）。产品量产裁剪时优先调整 config/，硬件改版时只动 board_*.h，两者互不干扰。

失败模式与常见问题

编译阶段

以下编译错误与解决办法来自 README.md：

边界情况：

• Windows 下 make 不是有效命令：需先运行 tools/make_prompt.bat 进入预配置命令行环境，该脚本已设置好所有环境变量和 make 路径。
• 首次链接失败：仓库包含多个平台库，链接时打开文件数量巨大，Linux 用户务必在编译前调大 ulimit -n，否则可能间歇性报 Too many open files。
• 裁剪配置导致链接错误：config/ 裁剪的是"库功能"，若应用代码仍引用被裁剪符号，会出现 undefined reference——这是 SDK 中最常见的"功能开关与应用代码不一致"问题，定位时优先检查 lib_*_config.c 与 board_*_global_build_cfg.h 的开关是否匹配。

烧录阶段

• 烧录前检查：确保 USB 升级工具正确连接且目标板已进入编程模式（按住烧录按键后复位/重新上电）。
• INI 配置：下载脚本行为由 cpu/<平台>/tools/isd_config_rule.c 生成的 INI 控制，详细说明见 下载脚本配置文档。
• OTA 升级：支持单备份和双备份蓝牙 OTA 升级，详见 OTA 开发文档。

性能与运维注意事项

• 并行编译：使用 -j 参数可显著加速，如 make ac632n_spp_and_le -j4；多核机器可配合 -j 与 nproc（Linux）。
• 固件体积控制：量产阶段通过 config/ 裁剪未用模块（蓝牙 Profile、媒体、升级等）来减小 .hex 体积；裁剪原则是"从完整示例逐步关闭功能"，而不是从零开启，避免漏配导致链接失败。
• 日志调试：通过 log_config.c 配置日志输出等级和通道；时序类问题可利用空闲 GPIO 输出调试波形测量（GPIO Debug 手法）。
• 完整编译：make all 会顺序编译全部 18 个目标，耗时较长，适合 CI 或发布前全量验证；日常开发只编译所需 target 即可。

扩展点

SDK 的设计为二次开发预留了清晰的扩展路径（来自 README.md）：

• 创建自己的工程：复制 apps/ 下对应应用的 board/ 目录中与芯片型号最接近的板级配置，修改 board_xxx_cfg.h 中的引脚和外设配置即可，无需改动应用层代码。
• 添加新的芯片型号支持：在 cpu/ 下创建对应的平台目录，提供 liba/ 库文件和 tools/ 烧录工具，然后在 apps/*/board/ 下添加对应的板级目录，并在顶层 Makefile 追加路由目标。
• 参考示例应用：apps/*/examples/ 提供了各应用的参考实现（HID 鼠标/键盘/手柄、Mesh 灯/风扇等），可直接复制为新产品起点。
• 第三方协议接入：涂鸦、腾讯连连、天猫精灵等平台接入实现在 apps/common/third_party_profile/，新增平台协议在该目录扩展。

相关链接

• README.md（中文总览） — 本文档的主要信息源
• Makefile（编译目标定义） — 全部受支持 target 的路由定义
• README-en.md（英文总览）
• 杰理 AC63 文档中心 — 在线开发文档
• SDK 架构文档（本地） — 模块架构说明
• FAQ 文档（本地） — 常见问题集合
• SDK 版本历史 — 版本发布记录
• 问题反馈（Gitee Issues）

从选择到烧录的完整流程

以下时序图概括了从"选择工程"到"固件上板"的完整开发路径，可作为新项目的操作清单：

sequenceDiagram
    participant Dev as 开发者
    participant App as 应用工程 apps/<app>
    participant Board as 板级目录 board/<platform>
    participant Make as 顶层 Makefile
    participant Cpu as 平台库 cpu/<platform>/liba
    participant Hex as .hex 固件
    participant Tool as USB 升级工具

    Dev->>App: 1. 按产品形态选择应用<br/>(spp_and_le / hid / mesh)
    Dev->>Board: 2. 按芯片选择板级配置<br/>并修改 board_xxx_cfg.h
    Dev->>Make: 3. 执行 make ac63xx_&lt;app&gt;
    Make->>Board: 4. 路由到板级 Makefile
    Board->>Cpu: 5. 按 config/ 裁剪配置链接 lib.a
    Cpu-->>Board: 6. 生成固件
    Board-->>Hex: 7. 产出 .hex
    Dev->>Tool: 8. 目标板进入编程模式<br/>选择 .hex 烧录
    Tool-->>Dev: 9. 烧录完成，复位运行

关键点回顾：

1. 应用选择决定功能边界：透传类选 spp_and_le，人机交互选 hid，物联组网选 mesh；三者代码互不共享编译产物，但都依赖 apps/common/ 公共模块。
2. 芯片平台决定库与工具：板级目录引用的 liba/*.a 与烧录工具都来自 cpu/<platform>/，平台选错会导致链接失败或烧录异常。
3. 配置分层决定固件形态：config/ 控制功能裁剪与体积，board_*.h 控制硬件适配；两者结合即可完成从评估板到量产板的迁移。
4. 编译入口可多选：顶层 Makefile（命令行）、Code::Blocks .cbp 工程（Windows GUI）、VS Code 任务（Ctrl+Shift+B）最终都落到同一个板级 Makefile，产物一致。

总结

本文档从"做什么产品 → 用哪颗芯片 → 用哪块板子 → 怎么编译烧录"四个维度梳理了 AC63 BT SDK 的应用选择与工程组织方式：三大应用工程覆盖透传、人机交互、物联组网三大场景；四个芯片平台通过板级目录实现应用与硬件的解耦；顶层 Makefile 提供统一的 18 个编译目标；config/ 与 board_*.h 构成"功能裁剪 + 硬件适配"的双层配置体系。新项目落地时，遵循"复制最接近的板级配置 → 修改引脚与外设 → 裁剪库功能 → 编译烧录"的路径即可快速启动开发。