本文介绍如何基于乐鑫 ESP32 使用 NERTC SDK 实现音视频通信。

• 适用芯片：ESP32-S3, ESP32-C3, ESP32-P4
• Demo 工程：demo/esp32
• 基于：开源项目 xiaozhi-esp32（MIT 协议）

方案概览

text┌────────────────────────────────────────────┐
│              demo/esp32                     │
│  ┌──────────────────────────────────────┐  │
│  │         Application Layer            │  │
│  │  application.cc  device_state_machine│  │
│  ├──────────────────────────────────────┤  │
│  │     NERTC Protocol Adapter Layer     │  │
│  │  nertc_protocol.cc                   │  │
│  │  nertc_external_network.cc           │  │
│  │  nertc_external_osal.cc              │  │
│  ├──────────────────────────────────────┤  │
│  │         NERTC SDK (src/nertc_sdk)    │  │
│  │  Signal (MQTT) │ Media (RTP/Opus)    │  │
│  ├──────────────────────────────────────┤  │
│  │         Platform HAL                 │  │
│  │  ESP-IDF: Wi-Fi, BLE, I2S, GPIO     │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  boards/  ← 开发板定义                       │
│    lichuang-s3/                             │
│    m5stack-core-s3/                         │
│    esp-box3/                                │
│    ... (持续增加)                            │
└────────────────────────────────────────────┘

开发环境

系统要求

环境	版本/说明
ESP-IDF	v5.5.2（推荐，已充分验证）
Python	3.8+
系统	macOS, Linux, Windows（推荐 Linux/macOS）
工具链	xtensa-esp-elf（ESP-IDF 自带）

安装 ESP-IDF

bash# 克隆 ESP-IDF v5.5.2
git clone -b v5.5.2 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v5.5.2

# 安装工具链
cd ~/esp/esp-idf-v5.5.2
./install.sh esp32s3 esp32c3 esp32p4

获取 Demo 工程

bashgit clone https://github.com/netease-im/nertc-iot-demo.git
cd esp32/nertc_demo

工程结构

textdemo/esp32/
├── main/                         # 主程序
│   ├── application.cc            # 应用主逻辑（设备状态机）
│   ├── application_nertc.cc      # NERTC 模式下的应用扩展
│   ├── device_state_machine.cc   # 设备状态机（待机→激活→监听→说话）
│   ├── boards/                   # 开发板定义（每个板子一个目录）
│   ├── protocols/                # 通信协议适配
│   │   ├── nertc_protocol.cc     # NERTC SDK 适配层
│   │   ├── nertc_external_network.cc  # 外部网络注入
│   │   └── nertc_external_osal.cc     # 外部 OS 抽象层注入
│   └── CMakeLists.txt
├── partitions/                   # 分区表
├── components/                   # 本地组件
├── managed_components/           # ESP-IDF 组件管理器依赖
├── local_config/                 # 本地配置（Wi-Fi、AppKey、设备ID）
├── scripts/                      # 辅助脚本
└── CMakeLists.txt                # 顶层 CMake

编译开关

Demo 通过 CONFIG_CONNECTION_TYPE_NERTC 宏区分 NERTC / 开源协议模式：

c#if CONFIG_CONNECTION_TYPE_NERTC
  // 使用 NERTC SDK 进行音频传输和 AI 对话
  nertc_protocol_.Initialize(...);
#else
  // 使用开源 WebSocket / MQTT 协议
  websocket_protocol_.Initialize(...);
#endif

所有 NERTC 专属代码都在 #if CONFIG_CONNECTION_TYPE_NERTC 块中，与开源项目小智代码完全隔离。

配置

编辑 create_local_config/config.json.s3，填入您的 App Key。如果不需要小程序配网，将 blufi_wifi 改为 false 即可。

编译和烧录

配置与编译

bashcd demo/esp32

# 1. 激活 ESP-IDF 环境
. ~/esp/esp-idf-v5.5.2/export.sh

# 2. 设置芯片型号
idf.py set-target esp32s3

# 3. 启用 NERTC 模式（通过 menuconfig）
idf.py menuconfig
# 路径：Demo Configuration → Connection Type → 选择 NERTC

# 4. 编译
idf.py build

烧录

bash# 1. 烧录固件（替换为实际串口）
idf.py -p /dev/cu.usbmodemXXX flash

# 2. 烧入配置文件
python3 config.py -p /dev/cu.usbmodemXXX --build --flash

# 如果需要小程序配网，加上 --blufi
python3 config.py -p /dev/cu.usbmodemXXX --build --flash --blufi

仅查看日志

bashidf.py -p /dev/cu.usbmodemXXX monitor

退出监控

按 Ctrl+] 退出串口监控。

对接网易小派

烧录完成后，可以通过微信小程序 网易小派 AI 完成配网和 AI 对话体验。详情请参考 对接网易小派。

串口日志解读

正常的启动流程日志类似：

textI (1234) NERTC: Initializing NERTC SDK...
I (1345) NERTC: Engine created successfully
I (1456) NERTC: Engine initialized, mode: AI_MODE
I (1567) NERTC: Joining channel: my-channel
I (1678) NERTC: OnJoin: cid=123456, uid=789, code=0
I (1789) NERTC: Successfully created AI session
I (1890) NERTC: Starting AI conversation...
I (1901) NERTC: Start AI success
I (2000) NERTC: OnAiData type=event data=audio.agent.speech_started
I (2100) NERTC: OnAudioEncodedData: Received audio from uid=xxx

音频方案配置

本地 AEC

c// SDK 配置

// 初始化时配置音频采集参数
sdk_config.audio_config.sample_rate = 16000;
sdk_config.audio_config.frame_duration = 20;
sdk_config.audio_config.channels = 1;

// 使用 OPUS 编码发送
nertc_push_audio_encoded_frame(engine_, channel, audio_config, payload, &encoded_frame);

与开源项目小智的关系

ESP32 Demo 工程（demo/esp32）基于开源项目 xiaozhi-esp32（MIT 协议）改造而来。

改造内容：

• 新增 CONFIG_CONNECTION_TYPE_NERTC 编译选项，可切换 NERTC / 开源协议
• 新增 protocols/nertc_protocol.*，将 NERTC SDK 适配到小智的设备状态机框架
• 新增 protocols/nertc_external_network.* 和 nertc_external_osal.*，提供 MQTT / TCP / 线程注入
• 所有 NERTC 专属代码通过 #if CONFIG_CONNECTION_TYPE_NERTC 隔离，与上游代码共存

保留不变：

• boards/ 目录下的所有开发板定义
• application.cc 的设备状态机框架
• 音频采集、播放、显示的驱动层
• 离线唤醒词（ESP-SR）

我们衷心感谢小智开源项目及其社区贡献者！🎉

常见问题

编译问题

Q: idf.py set-target esp32s3 报错 A: 确保已激活 ESP-IDF 环境：. ~/esp/esp-idf-v5.5.2/export.sh

运行问题

Q: 烧录后串口无输出 A: 1) 检查串口线连接；2) 确认波特率为 115200；3) 按住 BOOT 键再按 RESET 键进入下载模式

Q: Wi-Fi 连接失败 A: 1) 确认 Wi-Fi 为 2.4 GHz（ESP32 不支持 5 GHz）；2) 检查 SSID 和密码是否正确；3) 确认设备在 Wi-Fi 信号覆盖范围内

Q: MAC 地址未激活 A: 确保设备 MAC 地址已在网易云信服务端完成激活。

音频问题

Q: 说话没有应答 A: 1) 检查麦克风连接；2) 确认音频采样率和帧时长配置正确；3) 查看 OnAiData 日志确认 AI 是否收到音频

Q: 声音断断续续 A: 1) 检查 Wi-Fi 信号质量；2) 降低音频码率；3) 检查设备 CPU 占用

参考资源

• Demo 工程 README（中文）
• ESP-IDF 编程指南
• 开源项目小智