百度 AI 模组（ESP32-C3）集成开发指南

1 概述

1.1 方案简介

百度 AI 语音模组基于百度 RTC 大模型互动平台打造，是一款面向智能家电、AI 玩具等场景的软硬一体化模组。配套提供具备大模型实时语音交互能力的端侧系统源码开发套件，方案商可在此基础上按产品需求二次定制。

以往方案商接入 AI 语音能力，需要自行完成硬件选型、音频调测和云端对接，开发周期较长。本方案把这些工作提前做完：语音唤醒、降噪与回声消除、配网、联网对话的整条链路已在模组与开发套件中集成并完成调优，端云协同的语音增强让低配置硬件也能获得稳定的识别与交互效果，大幅缩短产品从对接到量产的周期。

交付形态：标准化硬件模组(仅模组不含PCBA) + RTOS 端侧开发套件（全套端侧系统源码）。

适用场景

• 智能家电：中控、厨具、小家电、智能照明等；
• AI 玩具：故事机、AI 闹钟、毛绒玩具、AI 挂件、桌面机器人等。

集成步骤

1. 按第 5 章开通云端资源，并配置智能体的角色、音色和设备控制能力；
2. 将应用凭据填入源码，按产品需要调整会话参数和本地控制逻辑；
3. 编译、烧录，完成样机验证后导入量产。

注：模组/开发板试用、送样申请及接入对接，请联系百度商务。

1.2 模组规格

模组为双芯片方案：ESP32-C3 负责联网、配网与业务逻辑，CI1302 离线语音芯片负责拾音、降噪、回声消除和离线唤醒，两者在模组内部通过串口互联。

模组正面	模组背面	开发板

注：开发板供方案商参考底板设计和调试使用，发货仅含模组，不含开发板。

硬件参数

型号、电气特性、引脚定义等详细参数见模组硬件技术规格书，如有需要请联系百度获取。

1.3 软件能力

云端能力（详见 大模型实时互动功能特性）

设备端能力

1.4 交付物

1.5 系统架构

模组内部分工如下：

ESP32-C3 不处理原始 PCM 音频，只负责转发编码后的音频帧，这样主控的 CPU 和内存可以留给联网和业务逻辑。

2 开发环境搭建

推荐在 Windows 10/11 上用 WSL2 + Ubuntu 22.04 开发；原生 Ubuntu 20.04 及以上同样适用，跳过 2.1 和 2.4 中与 WSL 相关的步骤即可。

ESP-IDF 版本必须是 v5.5.1，其它版本未经验证。官方完整说明见 ESP-IDF v5.5.1 快速入门（Linux），下文是本方案实际使用的步骤，国内网络下可直接照做。

2.1 准备 WSL2（可选）

WSL 新装的发行版默认以 root 登录，建议建一个普通用户，后面串口权限和工具链路径都按普通用户来：

1 sudo adduser <user>
2 sudo usermod -aG sudo <user>

编辑 /etc/wsl.conf，加入：

1 [user]
2 default=<user>

在 Windows PowerShell 里执行 wsl --shutdown，重新打开 Ubuntu，whoami 输出新用户名即可。

源码和 ESP-IDF 都放在 WSL 自己的文件系统里（如 ~/esp），不要放在 /mnt/c、/mnt/d 下，否则可能存在编译问题。

2.2 安装 ESP-IDF v5.5.1

1. 安装依赖：

1 sudo apt-get update
2 sudo apt-get install git wget flex bison gperf python3-pip python3-venv cmake \
3 ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

2. 设置国内镜像（境外网络可跳过）：

1 mkdir -p ~/esp && cd ~/esp
2 git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git
3 ./esp-gitee-tools/jihu-mirror.sh set
4 pip config set global.index-url https://mirrors.aliyun.com/pypi/simple

3. 拉取源码并切到 v5.5.1：

1 cd ~/esp
2 git clone -b v5.5.1 --recursive https://github.com/espressif/esp-idf.git

4. 子模块拉取中断时，进入 esp-idf 目录执行 ../esp-gitee-tools/submodule-update.sh 补齐。
5. 安装工具链：

1 cd ~/esp/esp-idf
2 ../esp-gitee-tools/install.sh        # 未设镜像时用 ./install.sh esp32c3

6. 配置环境变量。在 ~/.bashrc 末尾加一行别名，之后每开一个终端执行一次 get_idf：

1 echo "alias get_idf='. $HOME/esp/esp-idf/export.sh'" >> ~/.bashrc
2 source ~/.bashrc
3 get_idf
4 idf.py --version        # 应输出 ESP-IDF v5.5.1

2.3 串口权限

1 sudo usermod -aG dialout $USER

重新登录后生效；WSL 下需要在 PowerShell 执行一次 wsl --shutdown。

2.4 把串口接进 WSL

WSL2 默认看不到 USB 设备，需要用 usbipd 把开发板的串口转接进来，原理和完整说明见微软文档 连接 USB 设备。

方式一：图形工具（推荐）

在 Windows 上下载 wsl-usb-manager.exe（见 1.4），以管理员身份运行，在「Connected」列表里选中开发板的串口（开发板用的是 CH343 串口芯片，设备名为 USB-Enhanced-SERIAL CH343 (COMxx)），点右下角「Attach」。

方式二：命令行

在 Windows 上以管理员身份打开 PowerShell：

1winget install --interactive --exact dorssel.usbipd-win   # 首次安装
2usbipd list                                              # 找到开发板的 BUSID
3usbipd bind --busid <BUSID>                              # 首次需要，管理员权限
4usbipd attach --wsl --busid <BUSID>                      # 每次插拔后都要执行

在 Ubuntu 里执行 ls /dev/ttyUSB* /dev/ttyACM*，能看到设备即可。设备名一般是 /dev/ttyUSB0 或 /dev/ttyACM0，下文命令中的 <串口> 请替换为实际看到的设备名。

设备 attach 到 WSL 后，Windows 侧的串口工具就打不开它了；要在 Windows 上用串口，先 detach。

3 获取源码与目录结构

3.1 获取源码

下载源码包（地址见 1.4），解压到 WSL 文件系统内：

1 cd ~/esp
2 wget https://brtc-agent.bj.bcebos.com/chip_module/esp32c3/source/baidu_ai_module_esp32c3_v2.1.6_20261103.tar.gz
3 tar -xzf baidu_ai_module_esp32c3_v2.1.6_20261103.tar.gz
4 cd baidu_ai_module_esp32c3_v2.1.6_20261103

源码包按 baidu_ai_module_esp32c3_<版本>_<日期> 命名，下文以 <工程目录> 指代解压出的这个目录。

3.2 目录结构

1<工程目录>/
2├── main/
3│   ├── main.c                  # 系统初始化与主循环
4│   ├── baidu_aiagent/          # AI 对话应用层（二次开发主要改这里）
5│   ├── boards/WT01C302/        # 板级引脚与初始化
6│   ├── audio_codec/            # 语音芯片适配
7│   ├── network/                # Wi-Fi 与 BluFi 配网
8│   ├── chat_notify/            # 本地提示音调度
9│   ├── led/                    # 状态灯
10│   └── tone_res/               # 提示音与会话配置文件，打包进 res 分区
11├── components/
12│   ├── aiagent_sdk/            # 百度端侧 AI 交互 SDK
13│   ├── iot_sdk/                # 百度设备接入 SDK
14│   ├── ci1302_protocol/        # 语音芯片通信、唤醒词固件打包
15│   ├── audio_player/           # 播放队列
16│   ├── qmsd_audio/             # opus / mp3 编解码
17│   ├── qmsd_network/           # Wi-Fi 与 BluFi
18│   ├── qmsd_vmm/               # 运行期配置持久化（NVS）
19│   └── ...                     # 其它基础组件
20├── partitions.csv              # 分区表
21├── sdkconfig.defaults*         # 默认配置
22└── version.txt                 # 固件版本号

3.3 改哪里、不改哪里

components/aiagent_sdk/core/ 是 SDK 的平台无关内核（状态机、协议、交互模式），一般不需要改。

4 编译与烧录

4.1 首次编译

1 get_idf
2 cd ~/esp/<工程目录>
3 idf.py set-target esp32c3
4 idf.py menuconfig

在 menuconfig 中进入 Board Configuration -> Board Model，选择 WT01C302，按 S 保存后退出。

然后编译：

1 idf.py -DAIAGENT_CONN_MODE=USERSERVER build

-DAIAGENT_CONN_MODE=USERSERVER 指定设备经百度托管的业务服务接入，是本模组的标准接入方式。该参数会写入 CMake 缓存，之后直接 idf.py build 即可；但执行过 idf.py fullclean、set-target 或删除 build/ 目录后，需要重新带上。

编译成功后，build/ 下会生成：

4.2 烧录与查看日志

开发板接好 USB 并完成 2.4 的串口转接后：

1 idf.py -p <串口> flash monitor

flash 会把 bootloader、分区表、应用固件、res 分区和唤醒词固件一次写入。只改了 C 代码时可以用 idf.py -p <串口> app-flash 只写应用分区，速度更快。退出 monitor 按 Ctrl+]。

4.3 首次上电

1. 上电后播放开机提示音；
2. 设备未配网时提示「设备未绑定」并进入蓝牙配网，配网方法见 6.5；
3. 配网成功后自动重启并连上网络；
4. 完成第 5 章云端开通和 6.1 填写凭据、重新烧录后，说出唤醒词「你好小明」，听到应答提示音即可对话。

5 云端开通与配置

设备端的对话能力由百度智能云提供。当前阶段采用线上与线下结合的方式开通：账户和应用在控制台自行创建，License 资源由百度线下下发。

5.1 开通应用与 License

1. 注册并登录 百度智能云控制台，进入「实时音视频 RTC」；
2. 把账户的用户 ID 提供给百度商务，同时确认采购的模组型号和需要开通的能力（如是否需要儿歌、故事等内容资源），百度据此下发对应的资源。用户 ID 在控制台右上角头像菜单中查看；

3. 百度按「一批一码」方式向该账户下发 License 资源，下发后可在「大模型实时互动 → 资源列表」中看到；

   

4. 在「互动应用」中创建应用，并记下列表中的应用 ID（即 AppID）；

   

5. 回到资源列表，点「绑定应用」，在弹窗中给该应用填写「新增资源」数量，即分给这个应用的 License 数（也可以在互动应用列表中点「绑定资源」进入）。绑定后不可撤回，按实际需要填写。最后点「下载 License」拿到 License Key。

5.2 配置智能体

在互动应用详情的「智能体配置」和「TTS 文字转语音」中配置：

设备连接云端智能体时，默认使用这里配置的角色、音色和 Function Call 模板，端侧不填也能直接用。需要按设备单独指定时，也可以在端侧配置文件里写明对应参数（见 6.2），端侧的值优先。

人设和函数描述写得好不好，直接影响对话效果和指令识别率，撰写方法参考官方最佳实践：

• 人设 Prompt 撰写最佳实践
• Function 撰写最佳实践

6 端侧配置与二次开发

6.1 填写应用凭据

打开 components/aiagent_sdk/config/aiagent_credentials.h，把 5.1 中拿到的值填进去：

1 #define AIAGENT_APPID           "<您的 AppID>"
2 #define AIAGENT_LICENSE_KEY     "<您的 License Key>"

两者必须属于同一个应用。同一款产品的所有设备共用这一组凭据，烧录时不需要逐台区分。

设备 ID（deviceId）由固件自动读取 Wi-Fi MAC 地址生成（12 位大写十六进制，不带冒号），无需在控制台登记，也不用手工配置。

该文件里的其它宏（服务地址、鉴权方式等）已按百度托管服务配好，请勿修改。

6.2 调整会话参数

会话参数集中在 main/tone_res/ai_agent_config.json。设备每次建立会话时，把文件内容原样上报给云端，文件里写什么，云端就按什么执行。

常用字段：

以下字段与模组的音频链路配套，已调优，不要修改：audiocodec、aoco、audio_bitrate、aopt、dfda、cloud_3A_url、tts_enable_fast_send、tts_fast_send_ratio、tts_fast_send_second。cloud_3A_url 的调整见 6.7。

注意事项：

• 文件大小不能超过 2 KB；
• 文件打包在 res 分区里，修改后要重新编译，并用 idf.py flash 烧录（app-flash 不会更新 res 分区）；
• 文件格式错误或超出大小时，设备不会上报任何会话参数，日志中会出现 cfg file invalid 或 cfg file open fail。

6.3 更换提示音、唤醒词及指令词

提示音

提示音放在 main/tone_res/ 下，按文件名对应各个场景（如 wakeup.mp3 为唤醒应答、open_start.mp3 为开机）。直接用同名文件替换即可，格式保持与原文件一致：MP3、16 kHz、单声道，码率 40 kbps 左右。

tone_res/ 整体打包进 320 KB 的 res 分区，替换后注意总大小。修改后重新编译并用 idf.py flash 烧录。

唤醒词

模组内置「你好小明」和「小爱小爱」两套唤醒词，出厂默认「你好小明」。切换方法：

1. idf.py menuconfig，进入 Component config -> CI1302 OTA 配置；
2. 在「唤醒词选择」中勾选要打包的唤醒词，在「默认唤醒词」中选定一个；
3. 重新编译，执行 idf.py -p <串口> ci130x-ota-flash（只写唤醒词固件分区）；
4. 重启设备，ESP32 启动时检测到新固件，会自动升级语音芯片，完成后即使用新唤醒词。

语音芯片唤醒词固件的打包、分区与升级机制，可参考 components/ci1302_protocol/docs/。

需要定制专属唤醒、指令词时，现阶段请联系百度技术进行训练。

6.4 实现自定义设备控制

设备控制走 Function Call：用户说「把风扇调到三档」，云端根据控制台中的函数模板识别出函数名和参数，下发给设备，设备执行后回执结果，云端再组织一句话播报给用户。

第一步，在控制台的 Function Call 模板中声明函数，例如：

第二步，在 main/baidu_aiagent/aiagent_scene_esp32.c 的 scene_on_function_call() 中加分支：

1 static void scene_fc_set_fan_speed(const char *session_id, const char *params)
2 {
3     cJSON *root = cJSON_Parse(params);
4     cJSON *level = NULL;
5     bool ok = false;
6
7     if (root != NULL) {
8         level = cJSON_GetObjectItem(root, "level");
9         if (cJSON_IsNumber(level) && level->valueint >= 1 && level->valueint <= 3) {
10             ok = (my_fan_set_level(level->valueint) == 0);   /* 您的业务实现 */
11         }
12         cJSON_Delete(root);
13     }
14     scene_fc_reply(session_id, ok, ok ? NULL : "档位设置失败");
15 }
16
17 static int scene_on_function_call(const char *session_id, const char *name,
18                                   const char *params)
19 {
20     /* ... 已有分支 ... */
21
22     if (strcmp(name, "set_fan_speed") == 0) {
23         scene_fc_set_fan_speed(session_id, params);
24         return 1;
25     }
26 
27     return 0;
28 }

要点：

• params 是云端下发的 JSON 字符串，字段名与控制台模板中声明的参数一致；
• 返回 1 表示已处理；返回 0 交给 SDK 内置逻辑处理（例如对话模式切换）；
• 每次调用都要通过 scene_fc_reply() 回执，否则云端会一直等待结果；
• 该回调运行在网络接收线程上，不能阻塞。耗时操作（如串口等待外设应答）请投递到您自己的任务中执行，执行完再回执；
• 模组已内置 adjust_volume（音量）、set_custom_effect / set_preset_effect（灯效）、conversation_exit（退出对话）四个函数，自定义函数不要与它们重名。

6.5 蓝牙配网

模组使用乐鑫 BluFi 协议配网，协议说明见 BluFi 官方文档。

配网流程

1. 设备未保存 Wi-Fi 信息时，上电自动进入配网，蓝牙广播名为 QM-<MAC>；
2. 用户打开配网小程序（或 App），连接设备并下发 Wi-Fi 名称和密码（仅支持 2.4 GHz）；
3. 设备连接成功后保存配置并自动重启；连接失败时播报对应原因（密码错误、找不到网络等），并继续等待配网。

联调阶段可以直接用乐鑫官方的 EspBlufi App（Android / iOS）。

重新配网：连续按 AI 键 4 次，设备清除已保存的 Wi-Fi 信息并重启，重新进入配网。

定制

• 广播名：修改 main/network/qmsd_network.c 中 wifi_cfg_via_blufi_task() 里的设备名前缀；
• 自有配网客户端：在您的小程序或 App 中按 BluFi 协议实现配网，设备端不用改。

6.6 固件升级

建议优先接入您已有的 IoT 平台与升级服务。模组提供了升级执行模块，您的平台只需把升级指令送到设备，调用一个接口即可：

1 #include "aiagent_ota.h"
2 /* url 必须是 https:// 的地址；version 仅用于日志；task_id 为您平台的任务号 */
3 int aiagent_ota_start(const char *url, const char *version, const char *task_id);

调用后立即返回，升级在后台线程执行：结束当前对话 → 播放「开始升级」提示音 → 下载固件写入备用分区 → 播放结果提示音 → 重启。下载中途失败时备用分区不会被启用，重启后仍运行原固件。

接入时还需要处理一处：升级结果的上报。aiagent_ota.c 在重启前调用 aiagent_iot_device_report_ota_result() 上报结果，这个函数在当前接入方式下是空实现，请替换为向您自己平台上报。

固件大小不能超过单个应用分区（1752 KB），可通过 idf.py size 查看。

如果您没有自己的升级平台、也不打算自建，百度具备相应的设备管理与升级能力，可与百度商务及技术团队沟通，评估接入方案。

6.7 进阶使用

切换交互模式：支持按键说话、唤醒词打断（出厂默认）、插话打断三种模式，插话打断依赖回声消除效果。原理与切换方式见 语音对话模式最佳实践。

接入知识库：在控制台「知识库」上传文档，再到「意图设置」配置意图路由，问题命中意图后才会检索知识库。详见 知识库使用最佳实践。

多语言接入：支持广东话、四川话等 8 种方言和英语、日语等 16 种外语，在 ai_agent_config.json 的 lang 字段中指定语种（如广东话 zh_yue、日语 ja），并在控制台开启多语言、按语种配置角色与音色。详见 多语言接入。

互动记录及语音调测：「互动记录 → 对话记录」保存每轮交互的上下行文本与语音，可按用户、实例 ID 回溯试听，排查音频采集、识别或播放异常时很有帮助。产品的喇叭、麦克风和腔体与开发板不同时，可在「互动记录 → 语音调测」中新增调测设备，对话一轮后下载原声及 3A 处理后的音频，对比定位问题环节。详见 互动记录。

模组默认由语音芯片完成端侧回声消除与降噪。端侧效果欠佳时，可尝试开启云端 3A，参数见 云端音频 3A 最佳实践，改后用语音调测回归验证。

更多场景实现：

• 实时语音翻译：音频实时识别并翻译，支持智能断句和译文播报，推荐的第二版可自动检测双语、双向互译，见 实时语音翻译最佳实践；
• 会议纪要：通话中实时收集识别文本，结束后生成全文摘要、分段摘要、发言人观点和待办事项，见 在线会议纪要最佳实践；
• 英语陪练：【链接待补充】。

更多功能和场景的进阶用法，参考官网 最佳实践。

7 调试

7.1 查看日志

日志从 UART0 输出（TX GPIO21 / RX GPIO20），波特率 2000000。idf.py monitor 会自动按此波特率打开；用其它串口工具时请手动设置，否则会显示乱码。

1 idf.py -p <串口> monitor

日志格式为 级别 (时间戳ms) TAG: 内容，例如 I (5321) LIC: license PASS。排查时先按 TAG 过滤到对应模块。

7.2 常见问题

8 出厂烧录

不同阶段用不同的烧录方式，但写入的都是 8.1 的同一份镜像：

8.1 量产镜像

Flash 容量 4 MB，频率 80 MHz，烧录工具里的 SPI 模式填 DIO（固件运行时由引导程序切到 QIO，烧录时不用改）。各分区地址如下（由 partitions.csv 决定，修改分区表后以 build/flash_args 为准）：

产线建议烧录合并后的整包，避免逐个文件填写地址出错。build/flash_args 是编译时自动生成的烧录参数清单，记录了上表的地址与文件，里面的路径相对 build/ 目录，所以命令要在 build/ 下执行：

1 cd build && esptool.py --chip esp32c3 merge_bin -o factory_<版本号>.bin @flash_args

整包从 0x0 地址写入。每个发布版本保留一份整包及对应的 version.txt，便于追溯。

8.2 小批量自行烧录

模组贴到产品板上之后，用 USB 转串口工具接模组的 UART0（U0TXD / U0RXD）和 GND，上电时把 GPIO9 拉低进入下载模式。这几个信号对应的模组管脚见硬件技术规格书，产品板上建议预留测试点。命令行烧录：

1 esptool.py --chip esp32c3 -p <串口> -b 921600 erase_flash
2 esptool.py --chip esp32c3 -p <串口> -b 921600 write_flash 0x0 factory_<版本号>.bin

先整片擦除再写入，否则残留的 Wi-Fi 配置和音量等设置会带到成品里。esptool 写完会自动校验。

习惯图形界面的话，可以用乐鑫官方的 Flash 下载工具：芯片选 ESP32-C3，地址填 0x0，SPI 参数按 8.1 设置，勾选擦除。

重新上电后听到开机提示音、进入配网提示，就说明烧录成功。

8.3 大批量工厂代烧

交给工厂的材料：

• 整包 factory_<版本号>.bin；
• 烧录参数：芯片 ESP32-C3，地址 0x0，Flash 4 MB / DIO / 80 MHz，先整片擦除，写后校验；
• 判定标准：烧录后逐台产测，以下各项全部通过。

新烧录的设备首次开机会自动升级语音芯片，开机时间稍长，期间不要断电。

附录 参考资料