本帖最后由 TL_RONGLU 于 2026-8-19 14:31 编辑
⚠️ 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 默认音频配置
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 模拟串口输出调试日志： 将开发板 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 调试工具搜索以下广播名称： 连接设备后，在 GATT 服务列表中找到 Telink SPP Service，然后选择 Client-to-Server 特征。该特征支持 Write Without Response。 3.4 开启语音功能 以 Hex 格式写入： 命令被处理后，设备开始采集音频并检测唤醒词。启动后需要先收集约 1 秒的音频，之后才能产生第一次有效识别结果。 3.5 测试 Marvin 唤醒 靠近麦克风并清晰说出： 识别成功后，默认可观察到以下现象： 1. 调试口输出唤醒序号和识别分数； 2. 白色 LED 点亮约 2 秒； 3. 如果主机已经连接并启用 HID Consumer Report，设备发送一次 Volume Up 按键。 为了避免同一次语音被连续触发，Demo 增加了触发释放条件和约 1.5 秒的最小重复触发间隔。 3.6 关闭语音功能 以 Hex 格式写入： 设备将停止音频采集和关键词检测。关闭后再次说出 “Marvin” 不应产生唤醒事件。 如果启动语音功能的 BLE 连接断开，Demo 也会自动停止音频采集。 4. SPP 控制协议 4.1 命令格式 控制包由 2 个字节组成： Plain Text
┌──────────────┬──────────────┐
│ Magic (0xA5) │ Command │
└──────────────┴──────────────┘ |
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 默认识别参数 | | | | | | | 3200 samples，对应 200 ms 音频 | | | | | | | | |
这里的 200 ms 表示两次推理输入之间新增的音频数据长度，不是由定时器保证的固定推理周期。程序累计收到 3200 个新采样点后，在裸机 main_loop 或 FreeRTOS Audio Task 中同步调用一次 KWD 推理。 在当前测试配置下，串口打印的单次推理耗时参考值如下：
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 协议栈处理、SPP 数据接收、HID Notify | | 音频状态切换、PCM 搬运、KWD 推理和唤醒判断 | | |
FreeRTOS 模式下： • SPP Start、Stop 和 Disconnect 事件通过消息队列发送给 Audio Task； • 唤醒产生的 HID 按键事件通过队列交给 BLE Task 发送； • 裸机和 FreeRTOS 模式使用相同的 SPP 命令和测试步骤。 6.3 默认 RTOS 资源 | | | | | | Audio command queue length | | | |
上述配置主要用于 Demo 验证。移植到实际应用时，需要结合算法耗时、系统任务数量和剩余内存重新评估任务优先级、栈空间及队列长度。 7. 关键配置 主要配置位于 app_config.h 和 audio/audio_capture_cfg.h。 注意： • 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，技术支持以功能验证、问题定位和需求收集为主，不承诺接口兼容性及量产可用性。
| 
发表于 