开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

ESP32 语音智能体固件接入

使用 C SDK 在 ESP32-S3 上接入语音智能体,处理唤醒、外放插话和弱网恢复。

SDK 与开发环境

以 ESP32-S3 和 ESP-IDF v5.5.2 为例。将头文件加入已有固件工程,再按开发板配置 I²S 麦克风和扬声器、引脚、增益和回声消除。下方是源码和接入示例,整机固件由你的工程编译并烧录。

  1. 已有工程若缺 WebSocket 客户端,执行 idf.py add-dependency "espressif/esp_websocket_client"。为接入组件声明 esp_http_client、esp_timer 依赖,使用原生 TLS 示例时加入 esp-tls。
  2. 执行 idf.py set-target esp32s3。配置 Wi-Fi、根证书包和 I²S,再执行 idf.py build。
  3. 用对应板卡的串口执行 idf.py -p PORT flash monitor。首次联调分别确认收音、喇叭播放和联网。

唤醒、取票与连接

  1. 设备接入 Wi-Fi 后可在后台调用 yf_voice_broker_client(&cfg, true) 预热取票服务。唤醒即亮灯并开始收音,已完成的预热句柄可以复用,未完成则由本次唤醒的网络任务直接取票。
  2. 业务服务持有具备 voice.start 权限的 API Key,使用已发布智能体为设备调用 POST /v1/operations/voice.start,mediaProtocol 填 volc-dialogue。设备只收到对应会话的短期票据和返回的媒体地址。相同请求结果未知时保留幂等键核对。
  3. 按回执指定的 WSS URL 连接,用 Authorization: Bearer 传入临时票据。保留 TLS 证书校验。连接打开后按顺序连发 1、100 两条独立二进制消息。50 确认连接,收到匹配当前会话的 150 后才发送缓存音频。启动写入失败时关闭连接,结果未知先核对会话。

ESP32-S3 原生 TLS 示例

原生 esp-tls 客户端读完整个取票响应后,若使用 HTTP/1.1、连接允许复用,且返回的 WSS 主机、端口和 TLS 身份策略一致,可接管同一个句柄。用回执的路径和查询参数发送新的 WebSocket Upgrade,只带媒体票据,校验 101 和 Sec-WebSocket-Accept 后再启动会话。使用 esp_http_client、连接已关闭或目标不同,沿用独立 WSS。

冷连接示例预算为 3 秒。确认 0x8006 后 5 秒内同一链路立即返回原错误,Wi-Fi 或目标变化时清空 link。

运行前

ticket_transport.c · 固件片段

  • 链接 esp-tls 和 esp_timer,配置可信根证书。
  • 每个网络和 HTTPS 目标单独初始化 link,由网络任务独占。
完整代码 · 21 行
ticket_transport.cc
#define YF_VOICE_USE_ESP_TLS
#include "yunfu-esp32-voice.h"

// One zero-initialized link per Wi-Fi connection and HTTPS endpoint.
// cfg is your CA-verified, blocking client configuration. *tls must start as NULL.
static esp_err_t connect_ticket_service(yf_voice_tls_link *link, const char *host,
                                        const esp_tls_cfg_t *cfg, esp_tls_t **tls) {
    return yf_voice_tls_connect(link, host, 443, cfg, 3000, tls);
}

// Call after reading the ticket response. Parse media_host/port from its validated wss:// URL.
// Both requests use the same TLS identity and trust settings. *media_tls starts as NULL.
static esp_err_t connect_media(yf_voice_tls_link *media_link, const char *ticket_host, int ticket_port,
                               esp_tls_t **ticket_tls, bool http1_reusable, const char *media_host,
                               int media_port, const esp_tls_cfg_t *cfg, esp_tls_t **media_tls) {
    if (!media_tls || *media_tls) return ESP_ERR_INVALID_ARG;
    *media_tls = yf_voice_tls_take_for_wss(ticket_tls, ticket_host, ticket_port,
                                           media_host, media_port, http1_reusable);
    if (*media_tls) return ESP_OK;
    return yf_voice_tls_connect(media_link, media_host, media_port, cfg, 3000, media_tls);
}
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    链接 esp-tls 和 esp_timer,配置可信根证书。 每个网络和 HTTPS 目标单独初始化 link,由网络任务独占。

  2. 在项目中使用

    ticket_transport.c · 固件片段

  3. 核对结果

    复用成功后由媒体任务独占并最终销毁句柄。冷连接时取票任务仍负责清理原句柄。Upgrade 失败时关闭该连接;已发送 StartSession 而结果未知时先核对会话。取票 POST 结果未知时沿用原幂等键核对。

预期结果:复用成功后由媒体任务独占并最终销毁句柄。冷连接时取票任务仍负责清理原句柄。Upgrade 失败时关闭该连接;已发送 StartSession 而结果未知时先核对会话。取票 POST 结果未知时沿用原幂等键核对。

收音、缓存与媒体发送

使用 16 kHz 单声道 PCM16 小端音频。每帧 20 ms(320 个样本,640 字节)。32 帧占 20 KiB,可容纳 640 ms。256 帧占 160 KiB,可容纳 5.12 秒。模块有 PSRAM 时可在唤醒前分配。开口后保留音节和句中停顿,缓存紧张时只回收开口前确认的非人声。

运行前

media_uplink.c · 固件片段

  • 传入已建立的 WebSocket 句柄和当前 session_id。
  • 使用兼容二进制协议的默认 PCM 格式。只有 150 声明能力时才启用板端 VAD 提示。
完整代码 · 51 行
media_uplink.cc
#include "yunfu-esp32-voice.h"
#include "esp_timer.h"
#include "esp_websocket_client.h"

typedef struct {
    esp_websocket_client_handle_t ws;
    uint8_t packet[16 + 256 + sizeof(yf_voice_frame)];
    size_t prefix;
    const char *session_id;
    yf_voice_activity (*detect_edge)(const int16_t *pcm); // Optional board VAD, advanced by samples.
    uint8_t control[16 + 256 + 64];
} uplink;

static int write_start_frame(void *ws, const uint8_t *frame, size_t length) {
    return esp_websocket_client_send_bin((esp_websocket_client_handle_t)ws, (const char *)frame,
                                         (int)length, pdMS_TO_TICKS(1000));
}

static bool on_media_open(uplink *tx, const char *session_id) {
    tx->session_id = session_id;
    tx->prefix = yf_voice_pcm_prefix(tx->packet, sizeof(tx->packet), session_id);
    return tx->prefix && yf_voice_start_dialogue(tx->control, sizeof(tx->control), session_id,
                                                 write_start_frame, tx->ws);
}

static yf_voice_send_result send_pcm(void *arg, const int16_t *pcm) {
    uplink *tx = (uplink *)arg;
    if (!tx->prefix) return YF_SEND_UNKNOWN;
    memcpy(tx->packet + tx->prefix, pcm, sizeof(yf_voice_frame));
    int size = (int)(tx->prefix + sizeof(yf_voice_frame));
    int sent = esp_websocket_client_send_bin(tx->ws, (const char *)tx->packet,
                                               size, pdMS_TO_TICKS(20));
    if (sent != size) return YF_SEND_UNKNOWN;
    if (!tx->detect_edge) return YF_SENT;
    yf_voice_activity edge = tx->detect_edge(pcm);
    if (edge == YF_ACTIVITY_NONE) return YF_SENT;
    size_t n = yf_voice_activity_packet(tx->control, sizeof(tx->control), tx->session_id, edge);
    if (!n) return YF_SEND_UNKNOWN;
    sent = esp_websocket_client_send_bin(tx->ws, (const char *)tx->control, (int)n, pdMS_TO_TICKS(20));
    return sent == (int)n ? YF_SENT : YF_SEND_UNKNOWN;
}

// At wake: yf_voice_wake(&input, storage, frame_capacity);
// Each 20 ms: yf_voice_capture(&input, pcm);
// With device VAD, use yf_voice_capture_with_vad(&input, pcm, confirmed_quiet_for_this_frame);
// Keep the admitted session_id alive until teardown. Zero-initialize tx for every connection.
// Use the returned WSS URL with the default raw PCM format.
// After WSS opens, call on_media_open(&tx, session_id) once from the media task.
// On failure close this transport; reconcile an uncertain StartSession before retrying.
// On validated 150: enable detect_edge only if yunfu_input_activity is true. Then yf_voice_ready(&input);
// On ready and each 20 ms tick (including silence): yf_voice_pump(&input, esp_timer_get_time(), send_pcm, &tx);
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    传入已建立的 WebSocket 句柄和当前 session_id。 使用兼容二进制协议的默认 PCM 格式。只有 150 声明能力时才启用板端 VAD 提示。

  2. 在项目中使用

    media_uplink.c · 固件片段

  3. 核对结果

    媒体就绪后按帧发送,跟不上时显式判断回压或断线。已提交结果未知的帧不自动重放。

预期结果:媒体就绪后按帧发送,跟不上时显式判断回压或断线。已提交结果未知的帧不自动重放。

播放、打断与回执

  1. 收到 yunfu.audio.started 后,先用 yf_voice_playback_start(&out, generation, rate) 打开本轮播放,队列和 DMA 回调带上这一代编号。WebSocket 分片按完整消息重组,收到 352 后将有效 PCM 写入现有环形队列,并调用 yf_voice_playback_receive 登记样本。队列已满时分批写入;已丢弃音频则调用 yf_voice_playback_discard。使用 16 kHz 播放时可协商 output_sample_rate=16000。
  2. 在每个 DMA 补给周期调用 yf_voice_playback_allow_dma(&out, generation, queued, capacity, now_ms, underrun),允许后再从原队列提交。queued 和 capacity 都用单声道样本数,不含已提交给 DMA 的样本。now_ms 为单调毫秒时钟,每次真实耗尽仅标记一次 underrun。首播目标 20 ms,耗尽后每次加 20 ms,上限 80 ms 或环形队列容量。连续播放每满一秒降低一级。未攒满也会在目标时限后放行。
  3. 收到本轮正常结束事件时调用 yf_voice_playback_end,立即放行短尾音。yf_voice_playback_consume 只登记 I²S 实际播出的原始样本,等待或填充静音不计入回执。
  4. 收到 yunfu.interrupted 时调用 yf_voice_playback_discard,清空 interrupted_generation 及更早的队列和 DMA。延迟到达的旧代播放回调按代号忽略。
  5. 实际播放完成并且音频连续时,用事件 9000 发送 yunfu.playback.complete,写入当前 generation、实际 playedMs、telephone-media-clock、continuous:true 和 final:true。收到末包、DMA 入队或播放被提前清除时不可确认播完。
  6. 断线清理旧连接的输入、播放和 VAD 状态。票据只消费一次。按回执能力恢复或核对、结束原会话后再明确开始新会话。

外放时插话

  1. 采音侧用对齐的扬声器参考做回声消除,并独立检测用户开口。网络任务在对应 PCM 成功发出后再转发本地判停,扬声器降音由采音侧触发。
  2. 每次连接都重新读取 150 的 yunfu_scoped_interrupt。只有它和当前 yunfu.audio.started 的 interruptible 都为 true,固件才可主动降音和按代打断。其余情况继续上传 PCM,收到 yunfu.interrupted 后按 interrupted_generation 清理旧音频。
  3. 固件自行判定普通插话时,先降低旧播报音量并持续收音。确认是用户插话且不足 3 秒,在用户说完时停掉旧播报。持续满 3 秒仍在说话时停播并继续收音。只有“嗯”等附和或扬声器回声时恢复原音量。新回复只走同一个播放器。
  4. 使用 yf_voice_interrupt_packet 发当前 generation 和真实停播截点。先从 I²S 读取实际已播样本并编码,再调用 yf_voice_playback_discard。截点未知时传 NULL,只按代次打断。普通播完使用 yf_voice_playback_complete_packet。旧代和异步 DMA 回调按 generation 丢弃。

弱网恢复

在三段式智能体中启用「音频断续保护」。一句话中途断流后,网关会等待同一输入轨道恢复。固件保留真实采音顺序,避免用补零制造句末。

设备收到什么固件怎么处理
上行暂时写不进去确认整帧尚未提交时返回 YF_WOULD_BLOCK,SDK 会保留该帧并按顺序补发。部分写入或结果未知时返回 YF_SEND_UNKNOWN。进入 YF_INPUT_LOST 后丢弃本句缓存,提示用户重说。
事件 9000 · yunfu.input.flow读取 input_flow.id、sequence 和 paused,同一流忽略重复或较旧序号。paused 为 true 时暂停上传,收到更新的 false 后从新采音恢复并重置 VAD。暂停期的积压音频不补发。
事件 9000 · yunfu.input.unconfirmed只请用户重说受影响的那句话。保留已确认轮次,避免用已识别的半句话触发业务操作。
Wi-Fi 断开或连接失去响应响应标准 WebSocket Ping。二进制网关每 5 秒探测,连续 15 秒未收到 Pong 或上行二进制消息时释放连接。断开时清理本地收音、待播队列和 DMA。
恢复原会话从 voice.start 回执读取 connectionPolicy。resumeSupported 为 true 且仍在 reconnectWindowMs 内时,保留 compatibility.url 的媒体参数,追加 resume=1,将 reconnectToken 作为 Authorization 请求头的 Bearer 凭据重连。重发事件 1 和 100,核对本次会话的 150 后再上传新音频。无法恢复时由业务服务用 voice.read 核对原会话,再决定是否结束并重新取票。

真机验收

  1. 在同一连接连续对话三轮。分别记录唤醒到事件 150、用户说完到扬声器播出正文第一个字的时间。用同一板卡和网络对比,唤醒提示音与垫词单独记录。
  2. 播放中分别说一声“嗯”、一句不到 3 秒的“改到周六”,再试一句超过 3 秒的话。确认附和后能接着播,有效插话时只有一路回复。记录用户开口、旧声实际停止及本次 generation 的已播样本数。
  3. 说“约周五……改到周六”时,在两段之间让上行暂停约半秒,然后恢复。确认完整语句只触发一次回复,或收到未确认提示后重说。再断开 Wi-Fi 验证恢复窗口内外两种情况,核对会话编号、旧音频是否重播及有无重复取票。

联调与排错

查看二进制协议和完整回执 →

现象核对方式
0x8006 / select() timeout记录时区、域名、解析 IP 和失败阶段。同一 Wi-Fi 下用电脑验证 443。同步核对平台维护窗口。
HTTP 401 / 403检查业务服务权限、票据有效期、来源和会话匹配。
已连接却丢开口分别计时唤醒、取票、WSS 升级和事件 150。检查缓存容量、实际 PCM 规格和 YF_INPUT_LOST。
唤醒后首句慢分别记录唤醒、取票完成、WSS 升级完成、事件 150、首个 352 和扬声器首声。注明媒体是否复用 TLS。扬声器为 24 kHz 时可协商 output_sample_rate=24000,上行保持 16 kHz。
首包已到但听到晚分开记录事件 352、PCM 入队、I²S 实际开始播放。核对播放队列和 DAC 采样率。
打断后出现上一轮声音按 generation 清理 DMA 和待播队列。连续测试两轮、插话、断线和 Wi-Fi 切换。
实现依据 · 仓库内路径
  • sdk/yunfu-esp32-voice.h

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。