杰理AC_中科蓝讯_开发指南

1 · 文档导读与阅读路径

本章说明这份文档的覆盖范围、事实来源与阅读约定。两家厂商的资料体系都偏封闭，先明确边界和「哪些内容以什么为准」比直接跳进技术细节更省时间。

1.1 为什么把两家放在一篇里对照

杰理科技（珠海）与中科蓝讯（深圳）是国内蓝牙音频 SoC 出货主力厂商，产品大量出现在百元内的蓝牙音箱、TWS 耳机、儿童玩具和无线麦克风里。两个生态高度相似：处理器内核 + 片内 NOR + 音频 Codec + 蓝牙射频的四件套架构、面向音箱与对耳的应用形态、封闭但完整的配套工具。差异集中在开发链：工具链、打包格式、烧录器与配置方式各成体系。把两家放在一起对照，可以一次学通共性架构，再按表切换到具体厂商的工具，避免在同一类问题上学两遍。

1.2 覆盖范围

本文档覆盖从认识芯片到量产售后的完整链路：两个家族的系列全景（第 2 章）、开发链与工具对照（第 3 章）、第一个工程的完整流程（第 4 章）、SDK 组织（第 5 章）、启动与 NOR 存储布局（第 6 章，全文重点）、音频通路（第 7 章）、蓝牙协议与连接（第 8 章）、资源与提示音定制（第 9 章）、低功耗与续航（第 10 章）、OTA（第 11 章）、量产烧录与产测（第 12 章）、调试诊断（第 13 章）与故障速查（第 14 章）。

1.3 不覆盖什么

• 不覆盖射频认证的完整流程。SRRC、FCC、CE 认证的实验室流程与费用属于独立主题，本文档只在第 12 章提到产测与认证数据的烧录位置。
• 不逐条翻译 SDK 源码。两家 SDK 闭源程度不同、版本迭代快，本文档讲「结构与机制」，具体函数名与配置项以手头 SDK 版本为准。
• 不覆盖 WiFi 类产品。杰理 AC79 系列的 WiFi 视频与 AIoT 应用自成体系，本文档只把它作为家族成员介绍，不展开 WiFi 开发。
• 不写商业数据。全文不出现单价、市场份额与厂商排名，只保留「出货主力」「入门价位段」这类定性描述。

1.4 事实来源与标注约定

两家的公开资料形态不同，本文档按下列三类出处组织事实，行文中不再重复标注：

凡涉及具体型号参数、容量档位、协议支持清单的内容，如与手头资料不一致，一律以官方 SDK 文档与数据手册为准。本文档不写死寄存器地址、位域与协议 opcode，只写机制、顺序与量级。

1.5 阅读路径建议

按角色分四条路径（见封面读者路径）：首次上手走 2 → 3 → 4 → 5 章顺序跑通工程；从 MCU 平台迁移直接读第 6 章建立存储视角；做资源定制重点读第 9 章；量产与售后从第 12 章进，配合第 14 章速查表。全文图片统一编号，正文引用一律写「第 N 章」；两家并提时用「杰理」「蓝讯」简称，分别指杰理科技 AC 系列与中科蓝讯 AB 系列。

2 · 蓝牙音频 SoC 全景

杰理与蓝讯的芯片不是一颗料，而是覆盖音箱、耳机、数传、玩具等多品类的谱系。两家共用同一套「四件套」架构，真正的差别在工具链与生态组织方式。本章先建立共性架构与存储视角，再给两家逐系速览与横向对照。

2.1 蓝牙音频 SoC 的共性架构

把两家任意一颗蓝牙音频 SoC 拆开，都会看到同样的四件套：处理器内核（附带 DSP 扩展）负责协议栈、解码与应用逻辑；音频 Codec 集成 DAC、ADC、话放与 EQ，直接驱动差分输出的功放；蓝牙射频同时支持经典蓝牙与 BLE 双模；电源管理把锂电池充电、LDO 与电池检测收进芯片。外围只需喇叭、麦克风、天线与少量阻容，一颗芯片就是一台音箱或一副耳机的全部主控。

软件栈的形态也是同构的：最底层是外设驱动与时钟电源管理，其上是蓝牙协议栈与音频中间件（都以库形式提供），再上是 RTOS 与任务调度，最上层是产品应用。系统默认创建的核心任务通常包括蓝牙协议栈任务、音频处理任务、用户接口（按键与指示灯）任务和低功耗管理任务，应用层通过消息机制与它们协作。两家 OS 的任务 API 名称不同，但「抢占式优先级调度 + 消息队列」的骨架一致 —— 这意味着排障思路可以互通：先分清问题出在哪个任务层级，再决定用什么工具去看它。

2.2 片内 NOR 为什么是主线

两家芯片普遍把 NOR Flash 直接做进封装，容量按档位从几兆比特到几十兆比特不等（以具体型号数据手册为准）。这颗片内 NOR 同时承载四类数据：固件代码（XIP 原地执行）、音频与 UI 资源、VM 键值参数、蓝牙地址与射频校准数据。它决定了 SDK 怎么组织分区、升级怎么做双备份、产线怎么写个性化数据，也决定了「空间不够时先砍什么」。第 6 章将逐层展开这张地图。

2.3 杰理 AC 系列逐系速览

杰理的系列命名与平台代号并行：型号名（如 AC63xx、AC69xx）面向产品，平台代号（如 bd19、br23、br25、br34）面向 SDK 目录与工具链版本。资料在官方文档中心按系列分发，SDK 部分开源于 Gitee 仓库。

新近的 AC63 开源 SDK 基于社区主流 RTOS 框架组织，而音箱与对耳产品线沿用厂商自有 OS 框架，工程结构以手头 SDK 为准。

2.4 中科蓝讯 AB 系列逐系速览

蓝讯是 RISC-V 基金会战略会员，全线采用带 DSP 指令扩展的 32 位 RISC-V 内核，典型主频在 120~125 MHz 档位；片内 NOR 常见 2M / 4M bit 档，RAM 数十至数百 KB，随型号差异明显。产品品类覆盖官网列出的九大类，从音箱、耳机到玩具语音与 AIoT。

2.5 两家横向对照表

下表把选型时最先碰到的维度并排放置。除了内核与工具形态，注意两家 SDK 都采用「应用形态 + 平台层」的分层组织，这点在第 5 章展开。

读这张表的正确姿势是「按行决策」：先定产品形态（决定走哪条产品线），再看蓝牙版本与 Codec 档位（决定认证与音质目标能否达成），然后核对片内 NOR 容量档（决定资源与多语言预算），最后才看工具与烧录形态（决定团队学习成本与产线改造量）。把决策顺序固定下来，可以避免「先看主频再看功能」这类 MCU 选型习惯带来的错配 —— 蓝牙音频 SoC 的主频差异远小于生态与工具差异的影响。

2.6 存储视角：一颗 NOR 上的四类数据

全文的差异化主线从这里开始。把片内 NOR 想象成一栋楼，四类住户的关系是：

把这四类数据的「位置、写入者、生命周期」记牢，后面的分区规划、OTA、产测都会顺理成章。反过来，所有诡异的量产问题（地址重复、校准丢失、参数被冲掉）几乎都是这四类数据的边界没划清。

再补一个时间维度：代码区的生命周期以「版本」计，随 OTA 整体替换；资源区的生命周期介于版本与产品之间，可能单独升级语言包与提示音；参数区的生命周期与产品同寿，被用户与算法持续改写；个性化段则在产线一次性写入后终身不变。四类数据的写入频率从「几乎不改」到「持续改写」依次递增，这就是为什么磨损均衡只对参数区是硬需求、而对代码区完全不需要 —— 存储视角的价值，就在于把「谁会写、写多勤」想清楚，再决定空间与机制怎么给。

2.7 家族谱系总览图

下图按产品定位把两家的代表系列归组放置，便于快速定位「我手头这颗芯片属于哪条产品线」。

2.8 选型时先问的五个问题

蓝牙音频项目的选型顺序与通用 MCU 不同，建议按这五个问题过滤：

• 产品形态是什么 —— 音箱、对耳、头戴还是玩具？决定走音箱线还是对耳线，进而决定 SDK 应用形态。
• 提示音与语音包有多大 —— 多语言提示音会吃掉大量资源区，先算这笔账再定容量档。
• 要不要 BLE 通道 —— APP 控制、OTA 走 BLE 的方案对双模能力有硬要求。
• 产线条件如何 —— 有没有烧录治具与 RF 测试位，决定第 12 章的工位设计。
• 供货与授权路径 —— 两家都走方案商 / 代理商体系，先确认 SDK 获取渠道再定料。

2.9 术语差异速查

两家文档与社区用语略有差异，对照记忆可以减少检索阻力：

3 · 两个生态的开发链对比

两家芯片的共性架构一致，但开发链各成体系：SDK 获取方式、工具链、打包格式、烧录器与产测工具都不同。本章按「环境 → 编译 → 打包 → 烧录 → 产测」五步把两条链并排讲清，并给出闭源边界 —— 哪些能改，哪些是黑盒。

3.1 两条开发链总览

下图是全文的工具地图，后续各节按列展开。注意一个规律：两家的流程完全同构，差异只在每一格里的工具名与文件格式。学会一条链之后，另一条按列对照即可切换。

这张图还有第二个用法：当团队里同时存在两个生态的项目时，把这张图贴在工位上，按列分配责任人 —— 「环境与编译」归开发、「打包与配置」归研发与产品共管、「烧录」归产线工程师、「产测」归品质。蓝牙音频项目的很多摩擦来自职责错位：研发以为打包是产线的事，产线以为配置是研发的事，结果固件版本与配置版本在交接环节脱钩。按列定责，是从开发链地图直接得到的组织收益。

3.2 SDK 获取与授权形态

两家的 SDK 都不对散客直接开放，但开放程度不同：

3.3 编译工具链与 IDE

两家都用 Code::Blocks 作为 Windows 侧 IDE，这是蓝牙音频圈的一个有趣共识 —— 低成本工具 + 自有交叉工具链的组合。差异在工具链本体与工程组织：

3.4 固件与资源打包工具

这一步最容易被新手册略过，却是两家差异最大的地方：编译产物不能直接烧，要经过打包与配置。打包环节同时承担三件事：把链接产物与资源、参数段组装成可烧录的整体；把产品化配置（蓝牙名、提示音、按键定义）注入；生成升级与校验所需的校验码与版本信息。理解了这三件事，就能理解为什么「改了配置忘了重新打包」是新手第一大坑 —— 配置不在编译产物里，而在打包环节注入。

• 杰理一侧：编译得到固件文件后，用固件打包工具生成可烧录的固件包；音频与 UI 资源用资源打包工具（packres 类工具）单独打包，可选随固件合并或独立烧写；系统参数由配置工具生成。固件相关 PC 工具在文档中心「工具最新版本」页面统一分发。
• 蓝讯一侧：编译产物经 Downloader 配套流程生成 dcf 固件文件；Setting 文件夹里的配置文件用可视化界面修改，覆盖蓝牙配置、板级配置、按键配置与资源配置四大类 —— 不写代码也能完成大部分产品化定制，这是蓝讯链路对新手最友好的设计。

打包产物的清单管理是这一步的纪律：一次交付 = 固件文件 + 配置文件（或配置生成的参数段）+ 资源文件 + 版本说明，四样缺一不可。只归档固件不归档配置，一周后就没人说得清「这版固件配的是哪个蓝牙名、哪套提示音」；只归档固件不归档资源，换台电脑重新打包就会出现资源不一致。把「一次打包 = 四件套归档」定成团队规则，第 13 章里一半的环境类问题会直接消失。

3.5 烧录工具

烧录工具在第 12 章量产部分还会展开，这里先给开发期视角：

3.6 产测工具：测试盒与上位机

开发期「能响」不代表产线「合格」。杰理的蓝牙测试盒（一拖二）承担 RF 产测主力：频偏校准、发射功率、灵敏度与 MIC 测试都可以在工位完成，并可配合一拖八烧录器做电流与性能测试。蓝讯的对应角色是 BT_Tool 类上位机配合烧录器完成产测项，具体测试项组合随 SDK 交付包定义。两家的产测结果都建议回写到个性化数据段（第 12 章），让每台机器留下可追溯的产测记录。

3.7 闭源程度与二次开发边界

拿到 SDK 后的第一件事是划清「能改什么」。两家都以「应用层开放 + 协议栈闭库」为基本盘：

实操纪律：先改应用层与配置，不动库。遇到行为与预期不符，先怀疑自己的配置项，再怀疑库 —— 两家的库经过大规模出货验证，问题的概率分布 strongly 偏向配置错误。

3.8 工具版本管理建议

蓝牙音频项目周期长、工具链更新快，建议把「工具版本」当资产管理：SDK 版本号、工具链版本、打包与烧录工具版本、配置工具版本四项写进项目 README；固件归档时连同当次的打包配置与 Setting 一起入库。杰理用户可用包管理器统一升级工具并用 .jlxproj 关联版本；蓝讯用户则应固定 dcf 与 Setting 的配对关系，避免「新固件配旧配置」的隐性错配。版本错位是社区高频踩坑点，第 13 章的排查表会反复回到这一条。

4 · 第一个工程

本章给出一条完整走通的最小流程：编译固件、烧录、上电、测音。目标不是理解每个配置项，而是建立「改动 → 编译 → 打包 → 烧录 → 验证」的肌肉记忆，并识别三个成功标志与三个假成功。

4.1 准备工作

开工前确认四件事：开发板或样机（两家都有官方开发板可申请，蓝讯随 SDK 交付）、烧录通道（杰理 USB 下载线或一拖八烧录器，蓝讯 Xlink 或串口线）、日志观察通道（USB 转串口模块，115200 起试）、以及一台用于回连测试的手机。硬件准备里最容易被忽略的是喇叭或耳机的负载：没有正常负载时部分方案的功放保护逻辑会让输出静默，看起来像「没声音的故障」。

4.2 七步流程总览

下图把全流程拆成七步加一张验收卡。第一行从左到右走到 STEP 4，第二行从右到左接续 STEP 5，蛇形阅读。

4.3 第 1~2 步：取 SDK 与搭环境

获取 SDK 时同步确认三样东西：SDK 版本号、配套工具版本、板级对应关系。安装按第 3 章工具链表格执行，特别注意两点：工程与工具链路径都放在无中文、无空格的目录下；装完先用默认工程编译一次再改任何东西。杰理用户此时可以顺手把包管理器配好，后续工具升级走统一入口。

4.4 第 3~4 步：选应用与编译

应用形态决定工程模板：音箱产品进 soundbox 类应用，对耳产品进 earbuds 类应用，数传类产品走数传模板。第一次编译的原则是零改动 —— 不改板级、不改配置、不改资源，直接全量编译。这一步的意义在于建立基准线：之后任何编译失败都能确定是自己改出来的。若默认工程都编译不过，先核对工具链版本与 SDK 是否配套，再检查路径与环境变量，不要急着改代码。

4.5 第 5 步：配置与打包

第一次打包建议只做两个改动：把蓝牙名称改成自己的产品名、把一条默认提示音换成自己准备的音频。这两个改动恰好覆盖「配置项修改」与「资源打包」两条路径。杰理侧用配置工具改参数、用资源打包工具处理音频；蓝讯侧在 Downloader 的 Setting 配置里改蓝牙参数与资源配置。打包产物（固件包或 dcf）按日期归档，开始积累你的固件版本库。

4.6 第 6~7 步：烧录与上电

烧录前确认板级供电正常，烧录通道按第 3.5 节接好。烧录完成的判定以工具提示为准（杰理一拖八会有通道状态灯与屏幕提示，蓝讯 Downloader 有烧录进度与结果提示）。烧完上电，观察顺序是：先听提示音，再看回连，最后看日志。上电无声时先查负载与供电，不要直接怀疑固件。

烧录环节还有两条产线视角的预演建议：其一，从第一个工程开始就打开读回校验，养成「烧录必校验」的习惯，产线工具的校验配置与此一脉相承；其二，把开发期烧录用的接线方式记录进项目文档（引脚、串阻、供电方式），售后与产线复现你的烧录环境时不用重新摸索。这两条成本极低，却能在量产前排除掉一大类「开发机能烧、产线机不能烧」的环境差异问题。

4.7 三个成功标志

三个标志分别覆盖「音频通路」「蓝牙链路」「软件基础」三条主干，任何一个不成立都说明对应主干有问题，按第 13 章四步法定位。

4.8 三个假成功

比失败更危险的是「看起来成功了」的三种状态：

对假成功的防御手段只有一个：每一步都以可观察的证据为准 —— 提示音用耳朵确认内容对不对，回连用日志确认 profile 建立顺序，烧录用读回校验确认数据一致。证据链习惯从第一个工程就建立起来。

4.9 上手首日建议

第一天的时间分配建议是：两成时间搭环境、三成时间走通七步、五成时间用来回退与重放 —— 故意改坏一个配置（比如把蓝牙名改回默认）再修好，故意烧一版旧固件再升级回来。蓝牙音频开发的很多能力来自「知道改了什么会坏」，第一天建立这个手感，比急着改业务代码划算得多。走通之后，就进入第 5 章的 SDK 结构与第 6 章的存储布局，开始回答「为什么」的问题。

5 · 工程结构与 SDK 组织

两家的 SDK 结构高度相似：应用形态层、协议栈与系统层、平台层，加上环绕的工具与资源目录。看懂这棵树，才知道「改一块新板要动哪里」「改一个功能会牵连什么」。

5.1 一棵目录树看懂 SDK

把两家 SDK 的目录抽象出来，都是五层结构：应用在上、平台在下、库与工具环绕。下图是这棵树的抽象视图，两层文字分别是「这层放什么」与「开发时怎么对待它」。

5.2 apps：应用形态层

apps 目录按产品形态组织应用，这是二次开发的主战场。杰理 SDK 的典型形态是 soundbox（蓝牙音箱，含 U 盘 / SD 卡播放、混音、FM 等音箱功能全集）与 earbuds（TWS 对耳，含对耳组队、入盒检测、主从切换逻辑）；数传与 HID 类应用面向 BLE 数传、键盘鼠标类产品。蓝讯的 SDK 以耳机 / 音箱工程模板内置，配合 Setting 配置完成产品化。应用形态之间不要混用：对耳逻辑（组队、同步、主从切换）与音箱逻辑（混音、多通道）是两套框架，选错形态等于推倒重来。

应用形态选择的时机也很关键：在需求评审阶段就锁定形态，而不是拿到 SDK 后先随便跑一个再说。形态决定了资源预算的结构（对耳要算对耳链路开销与左右耳资源一致性，音箱要算多通道与本地播放）、产线工位的设计（对耳要多一道左右耳配对与标识工序）、以及测试矩阵的规模。中途换形态的代价，通常是资源区重新规划加一轮完整的回归 —— 相当于项目重做一次地基。

5.3 cpu 与平台层

平台层存放启动代码、外设驱动与板级配置。杰理按平台代号组织（如 br23、br25、br34 等目录，对应不同芯片批次），板级配置以 board 配置文件与配置宏的形式出现，覆盖时钟、引脚复用、功放使能、LED 与按键定义。蓝讯的板级配置同样以配置文件加可视化工具的形式提供。换一块新板的原则是：只动板级配置，不动平台代码 —— 引脚分配、上下拉、功放控制、充电参数都属于板级范畴。

平台层还有一个容易被忽视的角色：它是硬件差异的隔离层。同一个应用形态跑在不同的平台代号上，应用代码几乎不变，变的是平台层与板级配置。这意味着：换芯片平台时，你的业务代码大概率可以平移，需要重做的是板级配置与驱动相关调用。做产品系列（同形态不同价位档）的团队，应该刻意把业务代码与板级相关的调用隔离成薄薄一层适配层，让「一套业务、多档硬件」成为可能。

5.4 include_lib 与库文件

协议栈、RTOS、编解码库、音频算法都以库文件加头文件的形式提供。杰理把头文件集中在 include_lib 类目录，按「驱动 / 协议栈 / 算法」分组，应用层只 include 头文件调用接口；蓝讯的库随 SDK 交付包提供，接口经头文件暴露。库是黑盒（见 3.7 节边界表），你的排查手段是：读头文件注释与示例工程用法，而不是反汇编。升级 SDK 时注意库与头文件必须成套更新，混搭版本是诡异问题的常见来源。

头文件实际上是两家 SDK 最好的「文档」：接口签名、参数枚举与使用前提都写在注释里，比散落的说明文档更新更及时。建议把常用模块的头文件（音频通路、蓝牙控制、存储接口）通读一遍并做索引笔记，之后实现任何功能前先翻笔记确认「SDK 是不是已经提供了」—— 蓝牙音频 SDK 的功能覆盖面远超新人预期，重复造轮子不仅浪费工时，还常常与 SDK 内部机制冲突。

5.5 资源目录与工具目录

资源目录存放 tone 提示音、字库、UI 图片与 EQ 参数表，通过打包工具变成资源文件后写入 NOR 资源区（流程见第 9 章）。工具目录存放打包脚本、下载脚本与配置工具入口：杰理工程通常把「编译 → 打包 → 下载」串成一键脚本，底层是 isd_download 类下载器；蓝讯的工程以 Downloader 为枢纽，编译产物与 Setting 配置在烧录前组合。把工具目录里的脚本读懂一次，日后每次改版都能省下大量重复劳动。

一键脚本值得再展开一层：脚本的真正价值不是「省几次点击」，而是把流程固化。脚本里写死的参数顺序（先打包资源、再组固件、后校验）就是打包流程的单一事实来源，任何人执行都得到一致结果。团队应该在脚本头部维护版本注释（对应 SDK 版本、工具版本、最后一次验证日期），脚本本身随项目仓库管理。当新人问「固件怎么打出来」，答案应该是一条命令，而不是一份口头流传的操作说明。

5.6 板级配置：换一块板要动哪里

拿到新板（或自己画的新硬件）要跑通，检查点按顺序是：

改完板级配置后先编译烧录一版「只验证硬件」的固件：能开机、提示音正常、按键有响应，再叠加业务改动。一次只动一层，是板级调试的铁律。

5.7 两家 SDK 结构对照

5.8 新手目录操作纪律

最后是四条保命纪律：第一，永远从官方交付的原始 SDK 复制一份再开工，原始包只读保存；第二，改动前先让默认工程编译通过，建立基准；第三，每完成一个可编译的里程碑就打一个固件归档，配一条修改说明；第四，不要在 SDK 目录里手工删除「看不懂」的文件 —— 蓝牙音频 SDK 的目录互相引用，删文件的收益几乎为零，风险极高。做到这四条，你就能在出问题时随时回到任意一个已知良好状态。