【Telink BLE SDK｜音频开发】基于AI的语音唤醒Demo

TL_RONGLU

⚠️ IMPORTANT       本 Demo 为语音唤醒功能的早期体验版本，暂未纳入 SDK 正式发布范围，仅供客户进行功能评估和原型验证。       当前版本未经过完整的兼容性、稳定性及量产测试，请勿直接用于量产项目。

1. Demo 简介

acl_audio_demo 在 BLE ACL 多连接示例的基础上集成了音频采集和本地关键词检测（Keyword Detection，KWD）功能，用于演示从麦克风采集语音、在芯片端识别唤醒词，以及通过 BLE 控制语音功能的完整流程。

当前版本提供以下功能：

• 使用 DMIC 采集单声道 PCM 音频；

• 在芯片端识别唤醒词 “Marvin”；

• 通过 BLE Telink SPP 服务开启或关闭语音功能；

• 唤醒成功后点亮 LED；

• 唤醒成功后发送 HID Consumer Control Volume Up 按键；

• 支持裸机主循环和 FreeRTOS 两种运行模式。

NOTE 本文中的 SPP 指 Telink 自定义的 BLE GATT SPP Service，不是 Bluetooth Classic SPP。

2. 适用范围

当前音频采集代码支持以下芯片：

• TL721X

• TL321X

本体验版建议使用 TL721X EVK 测试。当前仓库已经为 TL721X 集成 acl_audio_demo CMake target；TL321X 已包含音频适配代码，具体工程配置请以对应芯片工程为准。

其他芯片暂未完成音频功能验证，不建议直接移植测试。

2.1 默认音频配置

项目	默认配置
麦克风类型	DMIC
采样率	16 kHz
数据格式	Signed 16-bit PCM
声道	单声道（Mono Left）
单帧长度	10 ms / 160 samples
DMA 通道	DMA2
Audio FIFO	FIFO0
DMIC DATA	PA2
DMIC CLK1	PA3
DMIC CLK2	PA4
DMIC 数字增益	-6 dB

WARNING       PA2、PA3、PA4 是 Demo 的默认配置。烧录前请根据开发板原理图确认麦克风类型、供电和引脚连接。不同 EVK 或客户硬件可能需要修改引脚和麦克风增益。

3. 快速体验

3.1 编译和烧录

选择 TL721X 的 acl_audio_demo 工程进行编译，并将生成的固件烧录到开发板。

与体验流程相关的默认配置如下：

Plain Text #define AUDIO_CAPTURE_AUTO_START  0 #define AUDIO_KWD_ENABLE          1 #define FREERTOS_ENABLE           0

默认情况下，设备上电后不会立即启动音频采集，需要通过 BLE SPP 命令开启语音功能。

如果需要先排查麦克风和 Audio DMA，可临时设置：

Plain Text #define AUDIO_CAPTURE_AUTO_START  1

此时设备上电后将自动开始音频采集和唤醒词检测，不需要发送 SPP Start 命令。

3.2 调试日志

Demo 默认通过 GPIO 模拟串口输出调试日志：

项目	默认配置
TX 引脚	PB6
波特率	1000000
串口格式	8-N-1，无流控

将开发板 PB6 连接到 USB-UART 模块的 RX，并将两者 GND 相连。启动后可通过日志确认 KWD 初始化、单次推理耗时及 Marvin 唤醒结果。

Plain Text [KWD] library init result=0 [KWD] inferTime=150000 us [APP] wakeup seq=1 score=950

其中 inferTime 的单位为微秒，score=950 表示识别分数为 0.950。日志内容和耗时数据仅用于功能调试，不作为正式性能指标。

NOTE       PB6 对应当前 TL721X EVK 的板级配置。使用其他开发板时，请以对应 Board Header 中的 TLKAPI_DEBUG_GPIO_PIN 为准。

3.3 连接设备

固件运行后，使用 BLE 调试工具搜索以下广播名称：

Plain Text audio_demo

连接设备后，在 GATT 服务列表中找到 Telink SPP Service，然后选择 Client-to-Server 特征。该特征支持 Write Without Response。

3.4 开启语音功能

以 Hex 格式写入：

Plain Text A5 01

命令被处理后，设备开始采集音频并检测唤醒词。启动后需要先收集约 1 秒的音频，之后才能产生第一次有效识别结果。

3.5 测试 Marvin 唤醒

靠近麦克风并清晰说出：

Plain Text Marvin

识别成功后，默认可观察到以下现象：

1. 调试口输出唤醒序号和识别分数；

2. 白色 LED 点亮约 2 秒；

3. 如果主机已经连接并启用 HID Consumer Report，设备发送一次 Volume Up 按键。

为了避免同一次语音被连续触发，Demo 增加了触发释放条件和约 1.5 秒的最小重复触发间隔。

3.6 关闭语音功能

以 Hex 格式写入：

Plain Text A5 00

设备将停止音频采集和关键词检测。关闭后再次说出 “Marvin” 不应产生唤醒事件。

如果启动语音功能的 BLE 连接断开，Demo 也会自动停止音频采集。

4. SPP 控制协议

4.1 命令格式

控制包由 2 个字节组成：

Plain Text ┌──────────────┬──────────────┐ │ Magic (0xA5) │ Command      │ └──────────────┴──────────────┘

功能	Hex 数据	说明
Start	A5 01	开启音频采集和 Marvin 检测
Stop	A5 00	关闭音频采集和 Marvin 检测

4.2 使用说明

• 必须发送原始 Hex 数据，不能发送 ASCII 字符串 "A5 01"；

• 写入方式为 Write Without Response；

• 当前版本没有命令执行结果或状态 Notify；

• 数据至少需要包含 2 个字节，多余字节当前会被忽略；

• Magic 不正确或不支持的命令会被忽略；

• 启动语音功能的 BLE 连接会成为本次音频会话的 owner；

• 通常只有 owner 连接可以停止本次音频会话；

• owner 连接断开时，Demo 自动请求停止音频功能；

• 重复发送 Start 或 Stop 不会重复执行相同的状态切换。

5. Marvin 唤醒流程

5.1 数据处理流程

Plain Text DMIC   |   v Audio RX DMA   |   v 10 ms PCM Frame   |   v PCM FIFO   |   v 1-second KWD Window   |   v Accumulate 3200 New Samples   |   v Run KWD Inference Synchronously   |   v Marvin Trigger Decision   |   +--> Debug Log   +--> LED On (about 2 seconds)   +--> HID Consumer Volume Up

5.2 默认识别参数

参数	默认值
KWD 输入采样率	16 kHz
推理窗口	1 秒 / 16000 samples
音频步长（Hop）	3200 samples，对应 200 ms 音频
触发阈值	0.9
释放阈值	0.6
释放条件	连续 3 次低于释放阈值
最小重复触发间隔	1.5 秒

这里的 200 ms 表示两次推理输入之间新增的音频数据长度，不是由定时器保证的固定推理周期。程序累计收到 3200 个新采样点后，在裸机 main_loop 或 FreeRTOS Audio Task 中同步调用一次 KWD 推理。

在当前测试配置下，串口打印的单次推理耗时参考值如下：

运行模式	单次推理耗时（参考值）
裸机	约 150 ms
FreeRTOS	约 190 ms

NOTE       上述数据仅为当前软硬件配置下的实测参考，不是性能规格。推理耗时和相邻两次推理的实际时间间隔会受到芯片型号、系统时钟、编译优化、RTOS 调度、日志配置以及其他业务负载等因素影响。

检测分数第一次达到或超过 0.9 时产生唤醒事件。产生事件后，需要同时满足以下条件才允许下一次唤醒：

1. 连续 3 次推理结果不高于 0.6；

2. 距离上一次唤醒至少 1.5 秒。

唤醒词模型封装在预编译 KWD 算法库中。当前体验版的唤醒词固定为 “Marvin”，暂不提供模型训练和替换流程。

6. FreeRTOS 模式

将以下宏设置为 1，可切换到 FreeRTOS 模式：

Plain Text #define FREERTOS_ENABLE  1

还需要确保 FreeRTOS 源文件参与acl_audio_demo 的编译。根据使用的开发环境，按下面对应的方法配置。

6.1 将 FreeRTOS 加入编译

使用 VS Code Telink 插件

使用 VS Code Telink 插件编译时，需要在 cmake_configs/TL_BLE_SDK_721X_cmake.json 中找到 acl_audio_demo 的工程配置，并在其directories 数组中加入：

Plain Text "directories": [   "3rd-party/freertos-V5",   "algorithm",   "..." ]

上面的配置用于说明 FreeRTOS 源码是如何加入 VS Code CMake 工程的。

使用 Telink IoT Studio

Telink IoT Studio 工程通常已经包含 3rd-party/freertos-V5 目录，但该目录可能针对当前 Demo 设置为 Exclude from Build。需要取消 acl_audio_demo 对该目录的编译排除：

1. 在 Project Explorer 中展开 3rd-party；

2. 右键单击 freertos-V5；

3. 选择 Resource Configurations → Exclude from Build...；

4. 在弹出的配置列表中找到acl_audio_demo；

5. 取消勾选acl_audio_demo，然后确认保存；

6. 清理工程并重新编译 acl_audio_demo。

完成上述配置后，再确认 app_config.h 中 FREERTOS_ENABLE 已设置为 1。

6.2 任务分工

运行单元	主要职责
BLE Task	BLE 协议栈处理、SPP 数据接收、HID Notify
Audio Task	音频状态切换、PCM 搬运、KWD 推理和唤醒判断
LED Task	LED运行闪烁

FreeRTOS 模式下：

• SPP Start、Stop 和 Disconnect 事件通过消息队列发送给 Audio Task；

• 唤醒产生的 HID 按键事件通过队列交给 BLE Task 发送；

• 裸机和 FreeRTOS 模式使用相同的 SPP 命令和测试步骤。

6.3 默认 RTOS 资源

资源	默认配置
Audio Task 调度基准周期	10 ms
Audio Task stack depth	1024
Audio command queue length	4
BLE event queue length	4

上述配置主要用于 Demo 验证。移植到实际应用时，需要结合算法耗时、系统任务数量和剩余内存重新评估任务优先级、栈空间及队列长度。

7. 关键配置

主要配置位于 app_config.h 和 audio/audio_capture_cfg.h。

配置宏	默认值	说明
AUDIO_CAPTURE_ENABLE	TL721X/TL321X 为 1	使能音频采集
AUDIO_CAPTURE_AUTO_START	0	上电后是否自动启动音频
AUDIO_KWD_ENABLE	1	使能关键词检测
FREERTOS_ENABLE	0	0：裸机；1：FreeRTOS
BLE_APP_PM_ENABLE	0	BLE 低功耗管理
AUDIO_CAPTURE_USE_DMIC	1	使用数字麦克风
AUDIO_CAPTURE_USE_AMIC	0	使用模拟麦克风

注意：

• AUDIO_KWD_ENABLE=1 依赖 AUDIO_CAPTURE_ENABLE=1；

• DMIC 和 AMIC 必须且只能选择一种；

• DMA2、FIFO0 和麦克风引脚不能与应用中的其他外设冲突；

• 如果改用 AMIC，需要同时确认芯片、Bias 引脚、模拟输入通道和 PGA 增益配置。

8. 常见问题

请依次检查：

1. 是否连接到广播名称为 audio_demo 的设备；

2. 是否写入 Telink SPP Client-to-Server 特征；

3. 写入方式是否为 Write Without Response；

4. 数据是否为 Hex 格式的 A5 01；

5. AUDIO_CAPTURE_ENABLE 和 AUDIO_KWD_ENABLE 是否已使能；

6. DMIC 接线和引脚配置是否正确；

7. 调试日志中 KWD 是否初始化成功。

请检查开发板 LED 的引脚定义和有效电平。Demo 默认使用白色 LED，不同开发板的 LED 配置可能不同。

请确认：

• 设备当前存在 peripheral-role BLE 连接；

• 主机已经完成 HID 服务发现；

• HID Consumer Report 的 CCC 已使能；

• 调试日志中没有 HID Notify 失败信息。

LED 点亮和 HID 按键是两个独立的结果。没有建立合适的 HID 连接时，Marvin 仍可能被正常识别并点亮 LED。

识别效果可能受以下因素影响：

• 麦克风型号、灵敏度及安装方向；

• DMIC 时钟和数据线连接质量；

• 麦克风增益；

• 说话距离、音量和发音差异；

• 环境噪声及回声；

• 实际硬件与 Demo 默认参数的差异。

当前参数主要用于功能演示，尚未针对不同硬件和使用环境进行完整调优。

9. 当前版本限制

CAUTION       以下限制是本体验版的一部分。客户评估时请勿将当前表现视为正式产品指标或量产承诺。

• 本 Demo 未完成全面的功能、稳定性和回归测试；

• 当前主要在 TL721X 平台上提供工程并进行验证；

• 唤醒词暂时固定为 “Marvin”；

• KWD 模型以预编译算法库形式提供；

• 暂不提供模型训练、自定义唤醒词或模型替换流程；

• SPP 命令暂时没有应答和状态查询机制；

• 暂未提供正式的唤醒率、误唤醒率、识别距离、功耗及算法性能指标；

• 暂未针对客户自定义硬件完成适配和参数调优；

• 目录结构、接口、控制协议和算法参数在后续版本中可能调整；

• 不建议将当前代码直接用于量产项目。

10. 问题反馈

欢迎试用并反馈实际效果。为了提高问题定位效率，反馈时建议同时提供以下信息：

• 使用的芯片型号和开发板版本；

• SDK 版本或代码提交号；

• 使用裸机还是 FreeRTOS 模式；

• 麦克风型号、供电及接线方式；

• 是否修改过音频引脚、增益或 KWD 参数；

• 使用的 BLE 调试工具和发送的 SPP 命令；

• 完整的启动日志和 KWD 调试日志；

• 可稳定复现问题的操作步骤；

• 如条件允许，提供现场录音或测试环境说明。

当前版本属于早期体验 Demo，技术支持以功能验证、问题定位和需求收集为主，不承诺接口兼容性及量产可用性。