多媒体技术 Wiki：Application Solution

ESP-WebRTC 方案

概述

WebRTC 被广泛用于实时、 低延迟 通信，最初为点对点 (P2P) 设计，如今是视频会议、流媒体和物联网应用的基础。相比 MQTT 或 WebSocket，WebRTC 对实时媒体传输和 NAT 穿越有更好的优化。ICE（交互式连接建立）是 WebRTC 的关键机制，通过 STUN 和 TURN 服务器实现跨 NAT 和防火墙的可靠连接，ESP-WebRTC 方案对 ICE 的支持进一步简化了 STUN/TURN 配置。

协议对比
特性 / 协议	WebRTC	MQTT	WebSocket
通信模式	点对点 (通过 STUN/TURN/ICE 建立)	基于代理的发布/订阅	客户端-服务器
媒体支持	✅ 音频、视频、数据	❌ 仅消息 (二进制/文本)	❌ 仅消息 (二进制/文本)
延迟	超低延迟 (可能小于 100 ms)	低延迟 (取决于代理，约为 10 至 100 ms)	低延迟 (约为几十毫秒)
可靠性	可靠 + 不可靠通道 (SCTP)	QoS 等级 (0,1,2)	仅 TCP 可靠
NAT 穿越	✅ 内置 STUN/TURN 支持	❌ 仅直接 TCP	❌ 仅直接 TCP
安全性	DTLS/SRTP (强制加密)	TLS (可选，MQTTS)	TLS (可选，WSS)
可扩展性	多方需要 SFU/MCU	使用代理具有很好的可扩展性	服务器集群/负载均衡
最佳用例	实时通话、会议、游戏、P2P 文件共享	IoT 遥测、设备控制、传感器数据	聊天、实时更新、仪表板

应用领域

WebRTC 在嵌入式和物联网系统中可实现 低延迟通信，同时支持 媒体传输，如 IP 摄像头和视频会议，也可通过 WebRTC 数据通道传输任意类型的数据。

用户支持

协议层用户：对于只关注连接层的用户，可使用 esp_peer 提供的轻量级 对等连接实现。其特点包括：

具备完整的 ICE 支持（STUN + TURN）
快速建立优化，优化启动时间
最小依赖，仅需 libsrtp
低资源消耗（约 60 KB/连接）
低延迟（ESP32 与手机之间约 260 ms）
核心协议从零实现，更易扩展

详细文档 esp_peer

最佳实践参考 peer_demo

应用层用户：在协议层的基础上，应用层用户可以基于 ESP-WebRTC 提供的连接能力实现音视频采集、渲染和信令处理，可快速构建原型，仅需替换信令即可。主要组件包括：

esp_capture：从硬件捕获编码的音频/视频
av_render：音视频播放
信令：支持 AppRTC、WHIP、OpenAI

解决方案和演示

openai_demo：ESP32 作为 OpenAI 服务的客户端。
doorbell_demo：使用 AppRTC 信令的智能门铃。
doorbell_local：支持行人 AI 检测的本地门铃，无需信令服务器。
video_call：通过数据通道进行视频通话。
whip_demo：将 ESP32 媒体流推送到 WHIP 服务器。
serverless_mqtt：无需服务器的连接建立。
livekit client：允许连接到 LiveKit 云。
openAI video assistant：通过语音控制启用图像分析。

其他资源

WebRTC 介绍 - 高性能浏览器网络
WebRTC for the Curious - 深入了解 WebRTC 内部机制

ESP-Hosted-MCU 方案

基础功能

概述

ESP-Hosted-MCU 是一种开源解决方案，允许将乐鑫芯片组和模块用作通信从机。该解决方案为主机微处理器或微控制器提供无线连接（Wi-Fi 和蓝牙），使其能够与其他设备进行通信。

ESP-Hosted 主机和从机功能框架请参考 Introduction

从机选型指南

通信接口与吞吐量对比请参考 Decide the communication bus in between host and slave
SDIO 接口从机芯片参数对比

Model	SRAM	GPIO	Feature
ESP32	520 KB	34	2.4 GHz Wi-Fi-and-Bluetooth
ESP32-C5	384 KB	22	2.4 and 5 GHz dual-band Wi-Fi 6, Bluetooth LE 5, Zigbee 3.0 and Thread 1.3
ESP32-C6	512 KB	30	2.4 GHz Wi-Fi 4/Wi-Fi 6 and Bluetooth LE

更多说明请参考 ESP-Hosted-MCU，主从机依赖组件和相关配置可根据使用的通信接口查看对应说明文件。

ESP-Hosted 加载流程

组件初始化：esp_hosted_init()

添加 wifi remote 通道：add_esp_wifi_remote_channels()

初始化 SDIO 驱动并创建相关任务：bus_init_internal()

初始化 RPC 相关接口：rpc_core_init()

主应用程序中调用 esp_wifi_init()

执行远程初始化：esp_wifi_remote_init()

执行 RPC 相关初始化：rpc_wifi_init()

典型示例：主机通过从机完成网络配置

主机发送流程

Wi-Fi 默认配置：WIFI_INIT_CONFIG_DEFAULT
Wi-Fi 初始化：rpc_wifi_init()
RPC 任务处理：rpc_tx_thread()
获取响应返回值：rpc_rsp_callback()
注册并接收 Slave 事件（如 WIFI_EVENT_STA_START 事件）：rpc_event_callback()

从机处理流程

接收并执行 RPC 命令：esp_rpc_command_dispatcher()
根据传入参数配置 Wi-Fi：req_wifi_init()
处理 Wi-Fi 事件并发送至消息返回队列：event_handler_wifi()
任务处理并触发事件回调：pserial_task()
发送事件到主机：rpc_evt_handler()

从机固件升级

主机通过调用 esp_hosted_slave_ota() 实现从机固件升级：esp_hosted_slave_ota
初期开发时建议在从机中预留 UART 下载接口，便于调试与升级，后续可考虑通过 Wi-Fi 进行升级
相关示例参考： host_performs_slave_ota

其他

Hosted 系统调用接口：g_hosted_osi_funcs
Hosted 任务创建：hosted_thread_create
SDIO 驱动初始化：hosted_sdio_init

网络拆分功能

概述

网络拆分（Network-Split）功能允许主机 MCU 和 ESP32 从机共享一个 IP 地址，并在它们之间分配流量。当主机休眠时，从机可以继续处理选定的网络活动（例如 MQTT、DNS）。

基于端口的数据转发
共享 IP 地址
支持特定端口数据包过滤
支持特定数据包唤醒，如 MQTT 消息中包含 “wakeup-host”
可支持主从机同时调用 esp_wifi_xx() 等相关接口完成网络连接

更多说明请参考 Network Split Feature for ESP-Hosted MCU

主机深度休眠从机维持 MQTT 保活功能

概述

该功能允许主机 MCU 进入低功耗状态，同时保持从机的网络连接，从而提高电池供电设备的能效。

主机进入深度睡眠或者掉电时，从机仍保持网络连接
从机可通过特定数据包唤醒主机，或者执行特定命令
睡眠唤醒期间网络数据包无缝切换
需要与网络拆分功能配合使用

更多说明请参考 Host Power Save (ESP-Hosted MCU)

FAQ

Q: 为什么主从机通信失败？

A: 可按以下步骤排查：

检查主从机 ESP-Hosted 组件版本是否一致

检查主从机配置是否一致，如通信接口（SDIO 或 SPI），通信速率等

检查硬件连接是否正常，如 IO 引脚、电源等，可进一步参考硬件指南

Q: 为什么配置的 CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM 无法生效？

A: 从 esp_wifi_remote 0.8.0 版本开始，配置项名称已更改为 CONFIG_WIFI_RMT_STATIC_RX_BUFFER_NUM。请在 (Top) > Component config > Wi-Fi Remote > Wi-Fi configuration 中进行配置。旧的 CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM 配置项已不再支持。

Q: 为什么出现编译失败？

A: ESP-IDF 中的某些结构体定义发生了变化，为适配新版本而更新的组件定义与旧版本 ESP-IDF 不兼容。建议将 ESP-IDF 升级到兼容版本，或使用匹配的组件版本。

Q: 如下 log： === ESP-Hosted Version Warning === 表示什么意思？

A: 该警告表示主机（如 ESP32-P4）和从机（如 ESP32-C6）使用的 ESP-Hosted 组件版本不一致。强烈建议主从机使用相同版本，避免因版本差异导致的通信异常。

Q: 如下 log： Identified slave [esp32c6] != Expected [esp32] 表示什么意思？

A: 该错误表示实际检测到的从机芯片型号（esp32-c6）与配置中指定的型号（esp32）不符。请在 (Top) > Component config > Wi-Fi Remote > choose slave target 中重新选择正确的从机芯片型号。

Q: 为什么 ESP32-P4 + ESP32-C5 开启 Wi-Fi 和 BLE 后，报内存不足？

A: ESP32-C5 内部内存仅有 384 KB，内存资源相对紧张，容易出现内存分配失败。可在 slave 中通过以下配置进一步优化内存使用：

CONFIG_ESP_SDIO_RX_Q_SIZE=10
CONFIG_ESP_WIFI_IRAM_OPT=n
CONFIG_ESP_WIFI_EXTRA_IRAM_OPT=n
CONFIG_ESP_WIFI_RX_IRAM_OPT=n
CONFIG_ESP_WIFI_SLP_IRAM_OPT=n
CONFIG_LWIP_IRAM_OPTIMIZATION=n
CONFIG_LWIP_EXTRA_IRAM_OPTIMIZATION=n
CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH=y

Q: 如何加速获取 IP？

A: Host 和 Slave 均可以采用如下配置：

CONFIG_COMPILER_OPTIMIZATION_PERF=y
CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y
CONFIG_LOG_DEFAULT_LEVEL_ERROR=y
CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS=y
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
CONFIG_LWIP_DHCP_RESTORE_LAST_IP=y
CONFIG_SPIRAM_MEMTEST=n
使用 bootloader_hooks 或 bootloader_override 提前复位从机，以便减少主机等待时间。

默认在 bootloader 阶段初始化 hosted。如需快速启动，可屏蔽 esp_hosted_init()，并在应用程序 esp_wifi_init() 之前调用 esp_hosted_init()。

Q: ESP-IDF 版本与 hosted/remote 版本对应关系

A: - ESP32-C6：推荐使用 esp_hosted ≥ 2.4.2，esp_wifi_remote ≥ 1.0.0，ESP-IDF ≥ v5.3.2 - ESP32-C5：推荐使用 esp_hosted ≥ 2.4.2，esp_wifi_remote ≥ 1.0.0，ESP-IDF ≥ v5.5

可以使用如下方式拉取组件，或者直接使用最新组件。 如果主机更新了组件版本，且版本差异较大，建议从机也一并更新。

espressif/esp_hosted:
  version: ^2.4
  rules:
  - if: target in [esp32p4]
espressif/esp_wifi_remote:
  version: ^1.0
  rules:
  - if: target in [esp32p4]

Q: 蓝牙使用注意事项

A：与具备蓝牙功能的芯片（如 ESP32C6）使用有所不同，通过 esp_hosted 组件进行通信时，需要通过如下修改来支持蓝牙功能。

相关配置

#
# BT config
# - ESP32 co-processor only supports BLE 4.2
#
CONFIG_BT_ENABLED=y
CONFIG_BT_CONTROLLER_DISABLED=y
CONFIG_BT_BLUEDROID_ENABLED=y
CONFIG_BT_BLE_50_FEATURES_SUPPORTED=y
CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y

#
# ESP-Hosted and Wi-Fi Remote config
#
CONFIG_ESP_HOSTED_SDIO_HOST_INTERFACE=y
CONFIG_ESP_WIFI_REMOTE_ENABLED=y
CONFIG_SLAVE_IDF_TARGET_ESP32C6=y

#
# Bluetooth Support
#
CONFIG_ESP_HOSTED_ENABLE_BT_BLUEDROID=y
CONFIG_ESP_HOSTED_BLUEDROID_HCI_VHCI=y

代码修改

#if CONFIG_IDF_TARGET_ESP32P4
#include "esp_hosted.h"
#include "esp_hosted_bluedroid.h"
#else
  #if CONFIG_BT_CONTROLLER_ENABLED || !CONFIG_BT_NIMBLE_ENABLED
  #include "esp_bt.h"
  #endif
#endif

esp_err_t esp_blufi_controller_init() {
#if CONFIG_IDF_TARGET_ESP32P4
  // init bt controller
  esp_err_t ret = esp_hosted_bt_controller_init();
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to init bt controller, %s", esp_err_to_name(ret));
    return ret;
  }

    // enable bt controller
  ret = esp_hosted_bt_controller_enable();
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to enable bt controller, ret: %s", esp_err_to_name(ret));
    return ret;
  }

  hosted_hci_bluedroid_open();

  /* get HCI driver operations */
  esp_bluedroid_hci_driver_operations_t operations = {
      .send = hosted_hci_bluedroid_send,
      .check_send_available = hosted_hci_bluedroid_check_send_available,
      .register_host_callback = hosted_hci_bluedroid_register_host_callback,
  };
  ret = esp_bluedroid_attach_hci_driver(&operations);
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to attach hci driver, ret: %s", esp_err_to_name(ret));
  }
  return ret;
#endif
}

esp_err_t esp_blufi_controller_deinit() {
  esp_err_t ret = ESP_OK;
#if CONFIG_IDF_TARGET_ESP32P4
  ret = esp_hosted_bt_controller_disable();
  if (ret) {
      ESP_LOGW("INFO", "failed to disable bt controller, ret: %s", esp_err_to_name(ret));
      return ret;
  }

  ret = esp_hosted_bt_controller_deinit(true);
  if (ret) {
      ESP_LOGW("INFO", "failed to deinit bt controller, ret: %s", esp_err_to_name(ret));
      return ret;
  }
#endif
  return ret;
}

Q: ESP32S3 作为主机使用注意事项

A: 芯片本身支持 Wi-Fi 和蓝牙功能时，需要参考 Troubleshooting 完成通信。

AI Agent 方案

概述

AI Agents 基于 ESP32 平台实现了音视频交互的应用代码。该应用基于 ESP-GMF 架构实现，集成了 AI Agent 设备端开发，为开发者提供了完整的音视频交互解决方案。

应用架构

AI Agents 应用基于 ESP-GMF 架构实现，主要包含以下两个核心模块：

Audio-processor 模块 主要负责音频数据处理，包括：

Playback（播放）
- 支持本地音频文件播放
- 支持网络音频播放
- 支持多种音频格式解码
- 可作为背景音乐或提示音来源
Feeder（流式播放）
- 播放实时流式音频数据（如 WebSocket、HTTP 流、内存缓冲区）
- 常用于 TTS、实时语音下发、在线音频播放等场景
- 可与 Mixer 结合做混音输出
Recorder（录音）
- 音频采集功能
- 支持 3A 算法处理（AEC、ANS、AGC）
- 支持编码输出（PCM、AMR、OPUS、WAV 等）
- 可用于智能语音交互、语音上传等场景
Mixer（混音）
- 将 Playback 和 Feeder 进行混音输出
- 可扩展多个输入通道
- 适用于背景音乐 + 实时语音、提示音叠加等场景

Video-processor 模块 主要负责视频数据处理，包括：

视频采集
视频编解码
视频渲染

功能特性

AI Agents 应用支持多种主流 AI 平台和功能：

火山 RTC 语音通话和视觉处理：火山 RTC 示例
COZE 语音交互和视觉处理：COZE 示例
BRTC 语音通话、视觉处理和音视频对话：BRTC 示例
腾讯云 RTC 语音通话：腾讯云 RTC 示例