简介：这份PDF资料面向从事Airoha洛达AB1568蓝牙耳机固件与应用开发的工程师，系统梳理该芯片平台从底层启动到上层功能实现的完整知识脉络，帮助开发者快速建立工程认知、定位关键代码入口。内容围绕headset工程展开，涵盖上电后执行函数、mk文件中的宏定义、app活动行为开启、ANC模式切换、LED呼吸灯样式修改、充电参数监测、超时时间设置、事件发送与删除、Airoha API使用、回调注册、自动关机、配对时间、开机提示电量、清除配对列表、链路丢失重连、UI Shell框架、SideTone与音频路径设置、DUT模式测RF、硬件复位及PEQ设定等模块，目录层次清晰，便于按主题查阅。资源包为1个PDF文件，约9.58MB，单文件结构适合随身查阅与打印对照。目前已有374人学习，适合需要系统掌握AB1568开发要点、补齐功能模块实现思路的初中级开发者参考。
1. 拿到 AB1568 的 headset 工程，先别急着改代码
三连击电源键，提示音响了，ANC 却没反应——这是我在 AB1568 头戴耳机项目上遇到的第一个翻车现场。按键映射对了，宏也开了，问题出在 ANC 参数根本没写进固件。Airoha AB1568 蓝牙耳机应用开发这件事，难的不是写代码，而是搞清楚这套 SDK 里「代码、配置、NVkey、固件」四层东西各自管什么。这份 headset 工程分析资料，从 bootloader 上电流程一路讲到 FOTA 更新 NVkey，覆盖 ANC 切换、LED 呼吸灯、充电监测、UI Shell 事件框架、产测模式等三十多个技术点，适合正在用 AB1568x 做头戴耳机、又不想在 SDK 里瞎摸的固件工程师。下面按我实际拆工程的顺序，把能抄的部分和会踩的坑都摊开。
2. 上电流程与编译宏：先搞清楚代码从哪跑起来
2.1 bootloader 到 app main 的两级跳
AB1568 上电后不是直接进你的应用代码。第一段跑的是apps目录下 bootloader 的main函数，这里有个条件编译的坑：BL_FOTA_ENABLE宏必须在 GCC 目录下的 mk 文件里定义，bl_fota_process函数才会被编进去。没定义，FOTA 相关逻辑直接消失，编译不报错，运行时才发现升级流程走不通。
bootloader 跑完才跳到apps下对应工程（earbuds或headset）的main函数，然后apps_inits初始化各种应用模块。我一般排查启动问题时，先在这两个main里各打一条 log，确认跳转顺序没被改乱。
2.2 宏到底在哪个 mk 文件里定义
这是新手最容易卡住的地方。GCC 目录下有一堆 mk 文件，代码里的宏定义在哪个文件，取决于你编译的是哪个工程。别猜，用命令查：
# 列出所有可编译工程及其调用的 mk 文件 ./build.sh list输出里能看到每个工程对应的 mk 文件。当前头戴耳机（AB1568x 芯片）是基于ab1565_ab1568_evk开发板工程改的，编译ab1568_evk的headset_ref_desgin工程时，调用的是feature_68_evk.mk。打开这个文件，宏定义都在里面，要加新宏也往这里加。
提示：改宏之前先跑一遍
./build.sh list确认工程名，不同板子对应的 mk 文件不一样，改错了编译能过但行为不对，这种玄学问题最难查。
2.3 活动行为是怎么被拉起来的
apps_inits里包含了所有活动行为的初始化。ui_shell_start_activity函数负责在活动堆里申请空闲 item，app_preproc_activity_proc是主进程，管理和调配其它子进程，比如app_home_screen_idle_activity_proc。开机后系统会拉起很多进程，每个进程有自己的事件组。系统产生事件时把事件抛出去，所有进程都能监听到，事件属于谁谁处理。
这套机制类似一个个 UI 界面：当前处于某个活动进程，发生的事件就由该进程处理。比如在 home_screen 状态下，能处理的事件集合是固定的。理解这一点，后面加按键、加 ANC 切换才不会把事件挂错进程。
3. ANC 模式切换：从按键到滤波器的完整链路
3.1 音频通路与四种 ANC 模式
AB1568 的音频通路分 Line-in 和 BT 两种。ANC 用 FF 麦（前馈）和 FB 麦（反馈）实现，Configtool 上有三种参数：ANC（含 FF 和 FB）、FBC（FB 的补偿）、Passthrough（通透）。硬件上是 4 个麦克风用于降噪，1 个主麦负责说话，2 个振动喇叭加 2 个声音喇叭。音频降噪用 FF 和 FB，通话降噪用 talk 麦加 FF。
目标场景很明确：在 home_screen 状态下用按键切换 ANC 模式。按键事件先进_proc_key_event_group处理，这里需要MTK_ANC_ENABLE宏开启，feature_68_evk.mk里默认已开。所有 ANC 事件行为最终都调app_home_screen_process_anc_and_pass_through函数。
按键行为key_action有四个值，对应 Configtool 的 UI 行为：
| key_action 值 | 行为含义 |
|---|---|
KEY_PASS_THROUGH | 通透模式开/关 |
KEY_ANC | ANC 开/关 |
KEY_SWITCH_ANC_AND_PASSTHROUGH | 全关→通透→ANC |
KEY_BETWEEN_ANC_PASSTHROUGH | 通透开与 ANC 开之间切换 |
按键行为到key_action的映射在customerized_key_config.c里配。
3.2 参数没写进去，按键就是白按
我第一次配完三连击 POWER，提示音响了，ANC 毫无效果。用 Configtool 打开工程的download文件夹，发现 ANC 模式里根本没有调整过的参数——代码链路是通的，但滤波器参数是空的。
解决路径是把声学调好的 ANC 参数（nvr 文件）导入工程，或者直接在 tool 上调整。操作顺序是：先 Write NV，再 Reset，把 FF、FB、FBC、AiroThru 参数写进耳机。写完再循环三连击，能听出不同模式的降噪差异，才算真正使能成功。
ANC 执行代码的逻辑是：KEY_SWITCH_ANC_AND_PASSTHROUGH改变target_anc_type和target_filter_id两个变量，再传入app_anc_service_enable执行。看切换 log 时过滤anc_result，能看到三个模式循环。ANC 默认滤波器AUDIO_ANC_CONTROL_ANC_FILTER_DEFAULT是值为 1 的枚举，PassThrough 默认滤波器AUDIO_ANC_CONTROL_PASS_THRU_FILTER_DEFAULT是值为 9 的枚举。
3.3 四组滤波器与 NVkey 的对应关系
Configtool 里把下面的 R 和上面的 L 重叠看，就是 4 组滤波器，每组都是 FF+FB+FBC 三件套：
- Filter 1：FF1(L/R) + FB1(L/R) + FBC1(L/R)
- Filter 2：FF2(L/R) + FB2(L/R) + FBC2(L/R)
- Filter 3：FF3(L/R) + FB3(L/R) + FBC3(L/R)
- Filter 4：FF4(L/R) + FB4(L/R) + FBC4(L/R)
点保存，参数落到download文件。但要让参数进代码，得走另一条路：先 clean 再 build 生成最新download，用 Configtool 打开后导入声学 NVR 文件，再用 Special_Export 导出变更。导出会生成 4 个文件；如果用 Save 方式存成 download 文件则生成 3 个，其中 syskey 和 bin 文件是一致的，部分 NVkey 被存进filesystem.bin。
3.4 把 ANC 参数固化进代码
量产编译时，XML 和 bin 文件要一起参与。编译ab1568_evk时用到三个 nvkey.xml：xml 1 有 7 个 KeyID，xml 2 有 4 个，xml 3 有剩下的所有 KeyID。把 Special_Export 导出的syskey.xml里变更的参数逐个更新到这三个文件——syskey.xml 里有的 keyID，nvkey.xml 里不一定有，没有就添加，有就替换。注意 ANC 参数的 keyID 在0xEE00~0xEEFF区间，这部分在 nvkey.xml 里原本没有，得手动补。同时替换filesystem.bin，重新编译生成 download，用 Configtool 打开确认 ANC 参数已变成 nvr 文件的配置，才算固化成功。
3.5 Component Gain 的 NVR 解析
ANC Default Setting 里的 Component Gain 校准值需要手动解析。比如0xE1E5 = 10FF 1400 D8DC D8DC，高字节在前低字节在后。FF 对应10FF，解析时前后位反转成FF10，十六进制转十进制再减 65536，得到 -240，即 -2.4dB。FB 对应1400，反转成0014，转十进制得 20，即 0.2dB。这个反转规则不记住，看 NVR 就是看天书。
4. 事件框架与系统配置：UI Shell 是绕不开的地基
4.1 ui_shell_send_event 与事件生命周期
UI Shell 框架是整个应用的事件总线。发事件用ui_shell_send_event，删事件用ui_shell_remove_event，接收事件消息在ui_shell_init_input_msg里初始化。这三个函数构成事件从产生到消费的闭环。
发事件时要注意事件组归属，发错组等于石沉大海。我一般在新加功能时，先在目标 activity 的 handler 里打 log 确认事件到了，再往下写业务逻辑。删事件主要用于超时场景，比如配对超时后把挂起的事件撤掉，避免回调在对象已销毁后触发。
4.2 超时、自动关机与配对时间
超时时间设置、自动关机配置、配对时间设置是三个容易混的配置项。超时时间管的是事件等待上限；自动关机是空闲多久后断电，属于节能管理；配对时间是开机后可被搜索的窗口期。三者数值互相影响——配对时间设太长，自动关机还没触发就先被连上了；自动关机设太短，用户还没配对完就关机。
常见做法是配对窗口 3 到 5 分钟，自动关机 10 到 15 分钟，超时事件按业务单独设。具体值看产品定位，但改完一定要实测「开机不操作→自动关机」和「开机配对超时→回 idle」两条路径。
4.3 开机提示电量与清除配对列表
开机提示电量要在电量监测机制就绪之后触发，顺序错了会播报错误电量。清除配对列表是隐私保护和重置配对的必要功能，实现时注意同时清 flash 里的配对信息和内存里的链路状态，只清一边会出现「显示已清除但还能连上」的怪现象。
4.4 链路丢失重连与 SideTone
链路丢失重连的逻辑要区分「主动断开」和「异常掉链」，前者不该重连，后者才触发。SideTone（侧音）设置影响通话时听到自己声音的量，参数过大会啸叫，过小用户觉得闷，一般在音频路径设置里和 PEQ 一起调。
4.5 音频路径、PEQ 与通话降噪
音频路径设置决定声音从哪个源进、经过哪些处理、从哪个喇叭出。PEQ 设定方法按频段调增益，通话降噪涉及 iGO 算法和 ENC。这几块参数耦合度高，改 PEQ 可能影响 ANC 效果，调 ENC 可能改变 SideTone 听感，建议一次只动一个变量并留好回退版本。
5. 避坑与排查：五个让我返工的现场
5.1 按键有提示音但 ANC 无效
现象：三连击 POWER 有提示音，降噪无变化。原因：ANC 参数没写入固件，download文件夹里滤波器参数为空。解决：导入 nvr 文件，Write NV 后 Reset，再验证模式切换。
5.2 改了宏但行为没变
现象：在代码里加了宏定义，编译通过，运行行为没变。原因：宏加错了 mk 文件，实际编译用的是另一个 feature 文件。解决：./build.sh list确认工程对应的 mk 文件，宏加到正确位置。
5.3 FOTA 流程编译后消失
现象：FOTA 相关函数编译后找不到。原因：BL_FOTA_ENABLE没在 GCC 目录 mk 文件里定义，bl_fota_process没被编进去。解决：在对应 mk 文件补宏定义后重新编译。
5.4 ANC 参数固化后仍是旧值
现象：按流程更新了 nvkey.xml，编译下载后 ANC 还是旧参数。原因：0xEE00~0xEEFF区间的 keyID 在 nvkey.xml 里原本不存在，只替换没添加。解决：对照 syskey.xml 把缺失 keyID 补进 nvkey.xml，同时替换filesystem.bin。
5.5 事件发了但没人处理
现象：ui_shell_send_event调用成功，目标 activity 没反应。原因：事件组归属错误，或目标 activity 当前不在活动栈顶。解决：确认事件组 ID 与目标进程匹配，检查 activity 是否已ui_shell_start_activity拉起。
6. 产测与调试通道：DUT、AT 命令和 USB log 怎么配合用
产测阶段最耗时的不是功能本身，是验证通道搭不起来。AB1568 提供了几条并行的调试路径，用对了能省大量时间。
DUT 模式测 RF 是射频验证的入口，进入 DUT 后配合 RACE 和 RAW 指令下发测试项。AT+CMD 命令是另一条通道，AT 转 Race 指令有固定格式，转换时注意参数顺序和校验位。USB 口通信用来打 log，产测时把 log 级别调高，能直接看到指令执行结果。
设置设备信息、读取耳机现有 NVkey、理解 SDK 的 NVKEY 机制，这三件事在产测前必须做完。NVKEY 是配置的持久化载体，NVKEY_Setting.c里的函数负责写该文件中的 NVkey。FOTA 更新 NVkey 的路径是：Special_Export 导出变更，再通过 FOTA 下发，不用整包重刷。
AP 测试和硬件复位功能属于产线兜底手段，硬件复位要确认复位后 NVkey 不丢。我一般会在产测前跑一遍完整链路：DUT 进 RF 测试 → AT 命令读设备信息 → USB 抓 log 确认无异常 → FOTA 推一次 NVkey 变更 → 复位后复查参数。这套流程走顺了，量产阶段的问题基本能在样机阶段暴露。
从那以后我每次改 ANC 或 NVkey 相关配置，都强制走一遍「clean → build → Configtool 打开 download 确认参数 → 下载实测」四步，不再相信「编译过了应该没问题」。希望帮到你。
本文还有配套的精品资源，点击获取
