WT99C202-S2 入门指南

📖 项目简介

本 SDK 专为 WT99C202-AI 和 WT99C302-AI 开发板设计，基于 ESP32C2/ESP32C3 主控芯片、CI1302 语音识别芯片及硅思平台，构建一套完整的本地语音唤醒与云端实时语音对话系统。该方案集成 Wi-Fi 配网、语音识别、WebSocket 实时通信、TTS 音频播放、OTA 升级 ESP32C2/ESP32C3 以及更换特定版本的唤醒词和本地命令词等核心功能，适用于智能语音助手、语音交互设备等应用场景的开发

⭐️ 核心特性

• 🎤 本地语音唤醒与识别（基于 CI1302）
• 🌐 WebSocket 实时云端语音对话
• 📶 支持 blufi 蓝牙配网
• 🔊 本地音频播放
• 🔄 远程 OTA 升级
• 💾 本地配置与音频资源存储
• 🔔 多种提示音音色同步与更新
• ⏹️ 本地打断机制支持按键和语音打断
• 🎚️ 支持语音控制音量、退出对话等功能
• 🎯 支持语音芯片本地命令词识别
• 🔄 支持 OTA 更新语音芯片特定模型的唤醒词和命令词

🔧 功能概述

• Wi-Fi 配网：支持一键配置、AP/STA 模式切换、网络重置功能
• CI1302 驱动支持：高效 UART 通信协议、支持语音唤醒与指令识别
• 云端对话：基于 WebSocket 协议与 AI 云端进行实时交互，支持流式语音传输
• 本地播放：支持本地 TTS 音频播放、多种音频格式兼容
• OTA 升级：远程固件更新机制，确保设备功能持续迭代优化
• 按键控制：支持语音唤醒、对话打断、会话退出、Wi-Fi 重置等操作
• LED 指示：实时反映设备运行状态（网络连接、对话进行、待机模式等）
• 语音控制：支持通过语音指令调节音量、退出当前对话等本地控制功能
• 本地打断：对话过程中支持本地打断机制，显著提升用户交互体验
• 本地命令词：ci1302 识别到命令词后，会通知到 esp32c2/esp32c3 处理，可在aiha_local_asr_detected_cb中添加自定义操作

🛠️ 开发环境

基础依赖

• ESP-IDF v5.5
• ESP-ADF v2.7
• QMSD ESP32 SDK（项目内已集成）

环境验证步骤

1. 确保 idf.py 可正常编译 ESP-IDF 示例项目 get-started/hello_world
2. 编译 ESP-ADF 示例项目如 player/pipeline_spiffs_mp3 以验证 ADF 配置正确性
3. ADF_PATH 环境导入，配置修改 CMakeLists.txt：

if(NOT DEFINED ENV{ADF_PATH})
    set(ENV{ADF_PATH} "/home/sorz/environment/esp-adf(安装的adf环境目录)")
endif()

4. 编译本工程

📁 项目结构

├── main/                   # 主程序
│   ├── asr_ota_file/       # 1302唤醒词更新组件
│   ├── chat/               # 语音聊天控制逻辑
│   ├── network/            # 网络管理、OTA
│   ├── tone_res/           # 本地提示音资源
│   └── debug/              # 调试相关
├── components/             # 自定义组件
│   ├── ci1302_protocol/    # CI1302 驱动与协议及语音芯片OTA组件
│   ├── audio_player/       # 音频播放支持
│   ├── aiha_server/        # WebSocket 交互组件
│   ├── WT99C202_C302/      # 硬件抽象层
│   └── storage_nvs/        # NVS 本地存储管理
├── qmsd_esp32_sdk/         # QMSD 平台 SDK
└── docs/                   # 文档

🚀 使用指南

启动流程

1. 设备上电启动，会播报开机欢迎语
2. 若检测到未配置 Wi-Fi 网络，设备将自动进入配网模式（请使用"硅思 AIHA 智能硬件"小程序进行配网）
3. 配网成功后，设备进入待机状态，等待语音唤醒指令
4. 用户说出预设唤醒词你好小明后，设备进入语音对话模式
5. 用户可根据需要选择语音指令或按键操作进行交互控制

按键功能说明

• 短按一次：退出当前语音会话，返回待机状态
• 连续短按 6 次：清除已保存的 Wi-Fi 配置信息并重启设备

配置说明

• 音量控制范围：0-100 级，配置信息自动保存至 NVS 存储
• Wi-Fi 网络配置：连接信息自动保存至 NVS 存储，支持断电记忆

编译流程

• 设置 idf 和 adf 环境变量，建议使用 ESP-IDF 5.5 与 ESP-ADF 2.7 版本，以确保最佳的兼容性和稳定性
• 设置芯片型号，根据开发板设置对应的目标,如 WT99C202 就先使用 "idf.py set-target esp32c2" 设置对应芯片型号，WT99C302 就使用 "idf.py set-target esp32c3"
• WT99C202 开发板默认为 26M 晶振，串口波特率为 74880；WT99C302 为 40M 晶振，波特率为 115200

唤醒词及命令词

• 将唤醒词、命令词所需的固件嵌入 esp32c2/esp32c3 固件，设备上电后会自行检测和 OTA

如何烧录出厂固件

准备工作

WT99C202-AI-S2 开发板在进行固件烧录时软硬件如下：

• 硬件设备：
  • WT99C202-AI-S2 开发板 x 1
  • USB转Uart 串口板 x 1
  • 焊接 线 x 5
  • 个人电脑 x 1
• 软件设备：
  • 出厂固件 x 1
  • 乐鑫烧录上位机工具 x 1
  • 启英泰伦烧录工具 PACK_UPDATE_TOOL x 1

ESP32-C2 固件烧录

烧录前需要确保已引线出来，接线参考如下图所示

打开烧录上位机工具，双击 .exe 文件后进入工具的入口界面，切换 ChipType 为 ESP32C2 如下图所示

点击确定，进入烧录主页面，填入烧录固件和对应的烧录地址，并勾选文件前的复选框

点击 START 即可进行烧录

CI1302 固件烧录

打开 PACK_UPDATE_TOOL.exe，选择 CI130X 系列，CI1302 芯片，点击固件升级，
按页面操作即可进入下载模式，界面如图所示：

进入烧录主页面，填入烧录固件并勾选文件前的复选框，即可进行烧录

⚠️ 注意事项

性能与稳定性

• 云端对话存在轻微延迟现象，主要受网络传输速度和 VAD（语音活动检测）控制策略影响
• 建议在稳定的 Wi-Fi 网络环境下运行设备，以确保最佳性能表现
• 当前版本（硬件 1V1，软件 V1.0.0）的电池检测状态仅供参考，不接电池或充电时的电量不准确，也可注释 battery_manage_init 来免除电量提示

开发建议

• 所有设备运行日志建议通过串口监视器进行查看，便于问题排查和调试
• 硬件连接需确保麦克风、扬声器、按键等组件完整接入
• 若对 idf 不够了解，请尽量不要去修改 components_adf 内的内容，以免编译不通过

🆘 常见问题 FAQ

📚 技术支持与资料

• ESP-IDF 官方文档
• ESP-ADF 官方文档
• 语音芯片 OTA 流程请参考main/asr_ota_file/readme.md
• 原理图、使用指南见工程下 docs 目录