SDK 概览与产品定位

fw-AC63_BT_SDK 是杰理科技（Jieli Technology）为 AC63 系列蓝牙 SoC 提供的通用蓝牙 SDK 固件开发包，基于 Zephyr RTOS，覆盖 SPP + BLE 透传/数传、HID 人机交互、Bluetooth Mesh 物联三大应用方向，配套预编译库（lib.a）、板级工程、编译工具链与烧录/OTA 升级方案。

Purpose and Scope

本文档从整体视角介绍 fw-AC63_BT_SDK 的产品定位、芯片平台、应用矩阵、仓库工程结构与构建体系，帮助开发者快速理解 SDK 全貌并做出正确的工程选型。

本页面属于"概览"类目，仅覆盖 SDK 的整体架构与定位。以下主题由其他页面专门讲解，本页只做指引、不展开：

• 快速开始与环境搭建：工具链安装、工程编译、烧录的逐步操作。
• SPP + BLE 应用开发（apps/spp_and_le/）：透传/数传、AT 指令、FindMy、Dongle 等。
• HID 应用开发（apps/hid/）：键盘、鼠标、遥控器、游戏手柄等参考例程。
• Mesh 应用开发（apps/mesh/）：智能照明、传感器网络、第三方云平台接入。
• 模块配置与裁剪：各 lib_*_config.c 的功能开关细节。

Overview

fw-AC63_BT_SDK 定位为"通用蓝牙 SDK 固件程序"，面向 AC63 系列芯片（AC632N / AC635N / AC636N / AC638N 等）的蓝牙产品研发。仓库 README.md 明确指出其核心特征：

• 基于 Zephyr RTOS：以开源实时操作系统为内核底座，提供任务调度、内存管理等基础能力，同时引用了 Zephyr RTOS 等开源项目。
• 完整蓝牙协议栈：支持 Classic Bluetooth（SPP）与 Bluetooth LE（BLE）双模，并已通过 Core v5.4 蓝牙认证（QDID 222830）。
• 三大应用场景：SPP + BLE 透传/数传、HID 人机交互、Bluetooth Mesh 物联。
• Release 版本代码 + 预编译库：仓库包含 SDK Release 版本源码与示例工程，需配合按命名规则组织的库文件（lib.a）和子仓库进行编译，业务代码开放、底层协议栈以静态库形式交付。

从工程形态看，这是一个"多芯片平台 × 多应用 × 多板级配置"的矩阵式固件仓库：同一套 SDK 通过顶层 Makefile 调度，按 make <chip>_<app> 的形式（如 make ac632n_hid）编译出对应芯片、对应应用的固件，每个板级目录下同时提供 Code::Blocks（.cbp）工程与命令行 Makefile 两种构建入口。

Architecture

SDK 整体采用分层结构：应用层（apps/）→ 公共模块层（apps/common/）→ 预编译库与头文件层（include_lib/ + cpu/*/liba/）→ 芯片平台层（cpu/bd19 ~ br34）→ 硬件。

flowchart TD
    subgraph sg_App["应用层 apps/"]
        AppSpp["apps/spp_and_le<br/>SPP + BLE 透传/数传"]
        AppHid["apps/hid<br/>HID 人机交互"]
        AppMesh["apps/mesh<br/>Bluetooth Mesh 物联"]
    end

    subgraph sg_Common["公共模块层 apps/common/"]
        ComAudio["audio 音频编解码"]
        ComBt["bt_common 蓝牙通用接口"]
        ComDevice["device 外设驱动"]
        ComUpdate["update 固件升级"]
        ComThird["third_party_profile 第三方协议"]
    end

    subgraph sg_Lib["预编译库与头文件层 include_lib/ + cpu/*/liba/"]
        LibBtstack["btstack 协议栈"]
        LibBtctrler["btctrler 控制器"]
        LibMedia["media 媒体库"]
        LibDriver["driver 驱动库"]
    end

    subgraph sg_Platform["芯片平台层 cpu/"]
        P_Bd19["bd19"]
        P_Br23["br23"]
        P_Br25["br25"]
        P_Br34["br34"]
    end

    AppSpp --> ComBt
    AppHid --> ComDevice
    AppMesh --> ComThird
    ComAudio --> LibMedia
    ComBt --> LibBtstack
    ComDevice --> LibDriver
    ComThird --> LibBtstack
    LibBtstack --> P_Bd19
    LibBtctrler --> P_Bd19
    LibMedia --> P_Bd19
    LibDriver --> P_Bd19
    P_Bd19 --> Hw["AC63 芯片硬件"]
    P_Br23 --> Hw
    P_Br25 --> Hw
    P_Br34 --> Hw

各层职责与设计意图：

分层带来的核心收益是可移植性：同一份 apps/hid 源码可以通过选择不同 board/ 子目录编译到 bd19/br23/br25/br34 任一平台，这正是顶层 Makefile 用 make ac632n_hid 这类"芯片 + 应用"目标命名来驱动编译的原因（见 Makefile 的 target 注释）。

产品定位与目标用户

SDK 的产品定位可以概括为：面向 AC63 系列蓝牙芯片的一站式固件开发平台，目标是让方案商与终端厂商"选芯片 → 选应用 → 选板级 → 编译 → 烧录"即可快速产出可量产的蓝牙产品。

目标用户包括：

• 嵌入式固件工程师：基于 apps/ 下的示例工程修改业务逻辑、外设驱动与协议行为。
• 产品方案商：通过 config/ 功能裁剪与 board/ 板级配置，控制固件体积与硬件适配。
• 量产与测试人员：使用 USB 升级工具、生产烧写工具、无线测试盒完成烧录、射频标定与空中升级（OTA）。

与市面上按"芯片型号"分发的 SDK 不同，本 SDK 以应用场景为第一组织维度（应用目录），再以芯片平台为第二维度（board/ 子目录），最后以板级配置为第三维度（board_xxx.cfg.h），形成了三级矩阵结构，最大程度复用应用代码。

支持的芯片平台

仓库 README.md 列出四个芯片平台，均可运行全部三类应用：

蓝牙协议认证方面，SDK 已通过 Bluetooth Core v5.4 认证（QDID 222830），产品基于此 SDK 开发时可复用认证成果，缩短上市周期。每个平台目录（apps/<app>/board/<platform>/）下都包含 Makefile、board_*.cbp、板级初始化代码、board_xxx_cfg.h 与 board_xxx_global_build_cfg.h，形成完整的可编译单元。

应用场景与选型指南

SDK 当前支持三大应用方向，README 的"应用选择指南"章节（README.md）给出了各自适用场景与参考例程：

选型决策流程如下：

flowchart TD
    Start([产品需求]) --> Q1{"需要蓝牙<br/>数据透传?"}
    Q1 -->|"是"| Spp["选择 apps/spp_and_le"]
    Q1 -->|"否"| Q2{"HID 人机<br/>交互设备?"}
    Q2 -->|"是"| Hid["选择 apps/hid"]
    Q2 -->|"否"| Q3{"Mesh 物联<br/>组网?"}
    Q3 -->|"是"| MeshApp["选择 apps/mesh"]
    Q3 -->|"否"| Other["暂不适用<br/>等待后续版本"]
    Spp --> Chip{"选择芯片<br/>平台"}
    Hid --> Chip
    MeshApp --> Chip
    Chip -->|"AC632N"| Bd19["bd19"]
    Chip -->|"AC635N"| Br23["br23"]
    Chip -->|"AC636N"| Br25["br25"]
    Chip -->|"AC638N"| Br34["br34"]
    Bd19 --> Board["进入 board 目录<br/>选择 .cbp 或 Makefile 编译"]
    Br23 --> Board
    Br25 --> Board
    Br34 --> Board

即将推出的方向还包括 IoT（IPv6 / 6LoWPAN） 与 2.4G 私有无线，说明 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 库文件 + 工具脚本
├── include_lib/                   # 头文件（bt协议栈、驱动、媒体、系统等）
├── doc/                           # 文档资源（datasheet、架构、FAQ 等）
├── tools/                         # 编译工具与脚本（make_prompt.bat 等）
├── Makefile                       # 顶层 Makefile（统一编译入口）
├── default.workspace              # Code::Blocks 工作空间
└── .vscode/                       # VS Code 配置（tasks.json 预定义编译任务）

关键目录定位：

构建系统与编译流程

SDK 的构建体系以顶层 Makefile 为统一入口，内部委托给各板级目录下的子 Makefile。目标命名规则为 <芯片系列>_<应用名>，例如 ac632n_spp_and_le、ac635n_hid、ac636n_mesh。顶层 Makefile 的实现如下：

# 总的 Makefile，用于调用目录下各个子工程对应的 Makefile
# 支持的目标
# make ac638n_spp_and_le
# make ac632n_spp_and_le
# make ac631n_spp_and_le
# make ac636n_spp_and_le
# make ac637n_spp_and_le
# make ac635n_spp_and_le
# make ac638n_hid
# ...

Sources:

• Makefile

每个目标实际是一条 $(MAKE) -C 委托命令，把编译工作交给对应平台目录下的 Makefile，例如：

ac632n_spp_and_le:
	$(MAKE) -C apps/spp_and_le/board/bd19 -f Makefile

clean_ac632n_spp_and_le:
	$(MAKE) -C apps/spp_and_le/board/bd19 -f Makefile clean

Source: Makefile

这种"顶层调度 + 板级执行"的设计，把芯片差异完全隔离在 board/ 目录内：顶层只关心"哪个芯片 + 哪个应用"，具体的工具链参数、链接脚本、库文件选择由板级 Makefile 负责，从而让 make all 可以一次构建全部 18 个目标组合。

完整编译与烧录流程：

flowchart TD
    Start([开始]) --> Clone["git clone 仓库"]
    Clone --> Choose["选择应用工程<br/>apps/spp_and_le | apps/hid | apps/mesh"]
    Choose --> Board["选择芯片平台与板级目录<br/>apps/*/board/bd19~br34"]
    Board --> Cfg["配置板级参数<br/>board_xxx_cfg.h / global_build_cfg.h"]
    Cfg --> Build{"编译方式?"}
    Build -->|"Windows"| Cb["Code::Blocks 打开 .cbp<br/>Build → Ctrl+F9"]
    Build -->|"Linux"| Make["make ac632n_hid 等<br/>（需杰理工具链 /opt/jieli）"]
    Cb --> Hex["生成 .hex 固件"]
    Make --> Hex
    Hex --> Flash["USB 升级工具烧录<br/>isd_download.exe 选择 .hex"]
    Flash --> Test["上电测试 / 后续 OTA 升级"]

编译目标速查表

在 SDK 根目录执行（数据来自 README.md）：

Linux 下编译前需要把杰理工具链解压到 /opt/jieli 并保证 /opt/jieli/common/bin/clang 存在，同时建议 ulimit -n 8096 提高文件描述符上限（链接阶段会打开大量文件）。

配置体系

SDK 提供两级配置入口，分别控制"功能裁剪"与"硬件适配"。

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

每个应用工程目录下有一组 lib_*_config.c 文件（示例为 apps/hid/config/，见 README.md）：

设计意图：这些配置决定编译时链接哪些库功能，通过裁剪可以显著减小固件体积——例如纯数据透传产品可以裁掉媒体模块，Mesh 产品可以不启用音频。如果裁剪后出现 undefined reference to ...，说明对应模块未被包含，需要回头检查这些配置。

板级配置（apps/<app>/board/<platform>/）

每个板级目录下两个关键头文件：

• board_xxx_cfg.h：引脚映射（UART / SPI / I2C / GPIO 外设分配）、外设使能、时钟配置（CPU 频率、外设时钟源）。
• board_xxx_global_build_cfg.h：功能开关（按需启用/禁用特定功能）、内存配置（堆栈大小、缓冲池大小）。

板级配置与功能裁剪的分工是：前者解决"这块板子的硬件怎么接、跑多快"，后者解决"这个产品需要哪些软件功能"，二者共同决定最终固件的行为与体积。

使用示例

克隆仓库并快速编译

以下命令来自 README 的"快速开始"章节，展示从克隆到编译的完整路径：

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

# 2. 进入对应的板级目录（以 HID 应用 + bd19 平台为例）
cd apps/hid/board/bd19/

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

Source: README.md

Linux 命令行编译

# Windows 用户可双击 tools/make_prompt.bat 打开命令行环境

# Linux 用户：确保文件描述符限制足够大（链接阶段需要）
ulimit -n 8096

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

# 编译完成后，在对应 board 目录下找到生成的 .hex 文件
# 清理单个工程
make clean_ac632n_hid

Sources:

• README.md
• README.md

失败模式、边界情况与并发注意

基于 README "常见编译错误" 与"烧录与升级"章节（README.md），SDK 开发中典型的问题与对策如下：

并发/多任务注意事项：SDK 基于 Zephyr RTOS，蓝牙协议栈与业务逻辑运行在多任务环境下，应用层访问共享资源（如外设、缓冲池）时需遵循 Zephyr 的同步原语（互斥锁、信号量）约定；板级配置中的内存分配（堆栈大小、缓冲池大小）直接影响多任务运行稳定性，调整外设数量时需同步评估内存预算。边界情况：Mesh 组网规模、BLE 连接数量等受 lib_btstack_config.c 与 lib_btctrler_config.c 中的资源上限配置约束，超出上限的行为（如连接被拒绝）属于预期裁剪结果，不应视为 bug。

性能与运维注意事项

• 固件体积控制：通过 apps/<app>/config/ 功能裁剪与 board_xxx_global_build_cfg.h 内存配置协同优化，裁剪不需要的协议与媒体模块是减小 .hex 的主要手段。
• 烧录与量产：首次烧录使用 USB 升级工具（isd_download.exe）；量产使用生产烧写工具；空中升级与射频标定使用无线测试盒。OTA 支持单备份与双备份两种模式（详见 OTA 开发文档）。
• 编译性能：Linux 下可并行编译，如 make ac632n_spp_and_le -j\nproc`，但需先保证 ulimit -n` 足够大，否则链接阶段会因打开文件过多而失败。
• 开发环境：Windows 推荐 Code::Blocks（仓库自带 default.workspace 工作空间与各板级 .cbp 工程）；仓库还预配置了 VS Code 任务（Ctrl+Shift+B 选择编译目标），适合跨平台开发。

扩展点

SDK 的扩展主要发生在以下位置：

• 新增业务功能：在 apps/<app>/examples/ 中参考现有例程，或在 apps/common/ 增加公共模块，供三个应用工程共享。
• 接入第三方平台：apps/common/third_party_profile/ 已内置 SigMesh、涂鸦、腾讯连连、HiLink 等协议，新平台接入遵循同样的 Profile 组织方式。
• 适配新板子：在 apps/<app>/board/<platform>/ 下复制一个板级目录，修改 board_xxx_cfg.h（引脚/外设/时钟）与 board_xxx_global_build_cfg.h（功能/内存），再在顶层 Makefile 登记新 target。
• 关键词唤醒：apps/common/jl_kws/ 提供杰理关键词唤醒模块，可扩展语音交互类产品。
• 即将推出的扩展方向：IoT（IPv6 / 6LoWPAN）与 2.4G 私有无线应用，说明底层已为更广的无线协议预留空间。

相关链接

• README.md — SDK 主文档（中文）
• README-en.md — SDK 主文档（英文）
• Makefile — 顶层编译入口与全部 target 列表
• 杰理 AC63 文档中心
• SDK 版本历史
• 相关主题页：快速开始与环境搭建（工具链、烧录工具安装）、SPP + BLE 应用开发、HID 应用开发、Mesh 应用开发、模块配置与裁剪（本页仅给出整体指引，细节见对应页面）。