diff --git a/.planning/milestones/digital_human_rtc/ROADMAP.md b/.planning/milestones/digital_human_rtc/ROADMAP.md index d375b7f..871daf6 100644 --- a/.planning/milestones/digital_human_rtc/ROADMAP.md +++ b/.planning/milestones/digital_human_rtc/ROADMAP.md @@ -383,10 +383,10 @@ static const emotion_gif_map_t emotion_gif_table[] = { | Phase | 状态 | |-------|------| -| Phase 1 | ⏳ 待启动 | -| Phase 2 | ⏳ 待启动 | -| Phase 3 | ⏳ 待启动 | -| Phase 4 | ⏳ 待启动 | -| Phase 5 | ⏳ 待启动 | -| Phase 6 | ⏳ 待启动 | +| Phase 1 | ✅ 完成（commit `672506e`，已推送 gitea + GitHub） | +| Phase 2 | ✅ 完成（commit `ce7a3aa`） | +| Phase 3 | ✅ 完成（commit `7d1c7dc`） | +| Phase 4 | ✅ 完成（commit `497c1b4`） | +| Phase 5 | ✅ 完成（commit `f2be992`） | +| Phase 6 | 🔄 进行中（B+C 双源 + 软退房 + Light Sleep 防护，最新方案见 PLAN 头部"实施变更记录"） | | Phase 7 | ⏳ 待启动 | diff --git a/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/HIBERNATE_REPORT.md b/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/HIBERNATE_REPORT.md new file mode 100644 index 0000000..2c27ea9 --- /dev/null +++ b/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/HIBERNATE_REPORT.md @@ -0,0 +1,189 @@ +# HIBERNATE_REPORT — Phase 6 RTC 软休眠验证报告 + +> 阶段: `phase_06_idle_hibernate` +> 日期: 2026-05-13 +> 状态: ✅ **完成** + +## 1. 实施目标 + +| # | 目标 | 结果 | +|---|------|------| +| G1 | 40s 对话空闲 → 真退出 RTC 房间（释放 License） | ✅ `volc_rtc_stop + volc_rtc_destroy` | +| G2 | BOOT 按键 ~3s 内恢复 RTC 对话 | ✅ 实测 2-3s | +| G3 | 屏幕保持亮起 + 字幕提示 | ✅ 不熄屏 + 持续显示 | +| G4 | 修复"用户开始说话被踢出"边界 bug | ✅ 方案 B+C 双源覆盖 | +| G5 | NVS/RAM 状态保留 | ✅ WiFi 凭据/亮度/对话历史不丢 | +| G6 | 内存碎片兜底 | ✅ 累计 50 次软休眠触发硬重启 | + +## 2. 与原 PLAN 的关键偏差 + +详见 [PLAN.md "实施变更记录"](PLAN.md#-实施变更记录与原-plan-偏差) 章节（V1-V6）。 + +核心调整： +- **倒计时方案 C → B+C 双源**（AI 长说话期间 conv_status 不变化，需 subtitle 补充） +- **不熄屏**（用户反馈：保留屏幕显示提示字幕） +- **新增 Light Sleep 防护**（坑：esp_pm light_sleep 导致 I2C 失败 abort） +- **codec 状态机重置**（坑：唤醒后 "Input already open" abort） +- **dynamic_cast 改基类虚函数**（坑：-fno-rtti 不支持） +- **字幕推迟到流程最后 + 5 次重试**（坑：LVGL 锁竞争超时） + +## 3. 实施清单（已完成 Task） + +| Task | Commit | 内容 | +|------|--------|------| +| 6.1 | `31b9b37` | VolcRtcProtocol::LeaveRoom = stop + destroy | +| 6.2 | `898ffaa` | OpenAudioChannel 适配 LeaveRoom 后自动重建 | +| 6.3 | `29b4a95` | EnterIdleHibernate + WakeFromHibernate + 内存兜底 | +| 6.4 | `ee3a3d2` | 方案 C conv_status 刷新 + 宏关闭方案 A | +| 6.5 | `48546c9` | Dialog Watchdog 触发改为 EnterIdleHibernate | +| 6.6 | `4e43b7e` | BOOT 按键唤醒 WakeFromHibernate | +| 6.7 补 | （工作区） | 方案 B subtitle 刷新 + 字幕重试 + 不熄屏 + Light Sleep 防护 | +| 6.8 | （本次提交） | HIBERNATE_REPORT.md | + +最终所有 Task 合并为 1 个大 commit 推送 gitea + GitHub。 + +## 4. 实测验证 + +### 4.1 软休眠流程（用户实测） + +```log +[T+0s] T 时刻 RTC 对话进行中 +[T+40s] Dialog watchdog 触发：40s 无对话活动 → 进入空闲休眠 +[T+40s] 🌙 进入空闲休眠：真退房 → 字幕提示（不熄屏） +[T+43s] ✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine） +[T+43s] EnterIdleHibernate: 关闭 codec input/output 重置状态机 +[T+43s] EnterIdleHibernate: 已强制禁用 Light Sleep（保护 I2C 总线） +[T+44s] ✓ 已进入空闲休眠（累计第 N 次） +[T+45s] ✓ 已显示退出提示字幕（5 次重试覆盖 LVGL 锁竞争） +[T+45s+] 屏幕保持亮起，字幕"已自动退出RTC对话，按BOOT键重新连接RTC" +``` + +### 4.2 唤醒流程（用户实测） + +```log +[U+0s] BOOT button clicked +[U+0s] 🔵 BOOT in hibernate → 唤醒（恢复亮度 + 重连 RTC） +[U+0s] ☀ 从空闲休眠唤醒 +[U+0s] WakeFromHibernate: device_state=3, idle_cycles=N +[U+0s] Phase 6: RTC 实例不存在，触发重建... +[U+0.1s] Phase 6: RTC 实例已重建（耗时 0 ms） +[U+1s] HTTP GetRTCConfig 完成 +[U+2-3s] RTC远程用户加入 ✅ +[U+3s] 进入对话框状态：启用全双工 +``` + +**实测**：唤醒到完整对话恢复 **2-3 秒**。 + +### 4.3 边界场景验证 + +| 场景 | 预期 | 实测 | +|------|------|------| +| 用户第 38s 说话 | 方案 C LISTENING 立即刷新，不被踢出 | ✅ 通过 | +| AI 长回答（>40s） | 方案 B 字幕持续刷新，不被踢出 | ✅ 通过 | +| 连续 2+ 次软休眠 + 唤醒 | 每次都正常 | ✅ 通过 | +| 无 abort / I2C 失败 / Light Sleep | 全部无 | ✅ 通过 | + +### 4.4 用户视觉确认 + +- ✅ 屏幕保持亮起（hibernate 期间） +- ✅ 底部字幕："已自动退出RTC对话，按BOOT键重新连接RTC" +- ✅ 字幕在 hiyori 数字人下方，不遮挡上半身 +- ✅ BOOT 唤醒后字幕清空，RTC 恢复对话 + +## 5. 时间对比（硬重启 vs 软休眠） + +| 阶段 | 硬重启（旧） | 软休眠（Phase 6 新） | +|------|------------|----------------| +| 设备启动（bootloader + app） | 2-3s | 0s | +| WiFi 重连（NVS 凭据连接 AP） | **10-15s** ⭐ | 0s（保持连接） | +| RTC 实例创建（volc_rtc_create） | ~100ms | ~100ms | +| HTTP GetRTCConfig 获取 token | ~1-3s | ~1-3s | +| 加入房间（byte_rtc_join_room） | ~300ms | ~300ms | +| 远程 AI bot 加入 | ~0.5-2s | ~0.5-2s | +| **总计** | **~15-25s** | **~3-5s** | + +软退出**节省 80% 唤醒时间**。 + +## 6. 关键踩坑修复记录（共 6 个） + +### 6.1 坑 1: codec 状态机未重置 +- **现象**：唤醒后 `Adev_Codec: Input already open` + ES8311/ES7210 I2C 失败 abort +- **修复**：EnterIdleHibernate 中 `codec->EnableInput/Output(false)` 重置状态机 + +### 6.2 坑 2: PowerSaveTimer Light Sleep 干扰 I2C +- **现象**：hibernate 期间 `esp_pm_configure(light_sleep=true)` → I2C 外设进入低功耗 → 唤醒通信失败 +- **修复**： + - `CanEnterSleepMode()` 加 `if (hibernating_.load()) return false` + - `esp_pm_configure(light_sleep=false)` 双保险 + +### 6.3 坑 3: hibernating_ 设置时序错误 +- **现象**：即使 CanEnterSleepMode 加了检查，hibernate 后仍触发 Light Sleep +- **修复**：必须先 `hibernating_=true` 再 `SetDeviceState(idle)`，否则 idle 状态下 PowerSaveTimer 已触发 + +### 6.4 坑 4: dynamic_cast 在 -fno-rtti 下编译失败 +- **现象**：`error: 'dynamic_cast' not permitted with '-fno-rtti'` +- **修复**：`Protocol` 基类加 `virtual void LeaveRoom() { CloseAudioChannel(); }` + +### 6.5 坑 5: LeaveRoom 后 OpenAudioChannel 直接失败 +- **现象**：rtc_handle_=NULL 直接 return false +- **修复**：OpenAudioChannel 头部加重建逻辑，触发 Start() 异步重建 + +### 6.6 坑 6: 字幕 LVGL 锁竞争超时 +- **现象**：SetChatMessage 在 LeaveRoom 后立即调用，500ms 锁超时 → 字幕未显示 +- **修复**： + - 字幕调用推迟到 hibernate 流程最后 + - 5 次重试间隔 200ms + +详细分析见 [docs/Rtc_AIavatar/RTC软退出方案_移植参考.md §6](../../../../docs/Rtc_AIavatar/RTC软退出方案_移植参考.md#6-6-个关键踩坑与修复经验)。 + +## 7. 资源使用对比 + +| 维度 | 数据 | +|------|------| +| 代码增量 | ~150 行（基类虚函数 + EnterIdleHibernate + WakeFromHibernate + NVS） | +| 内存增量（每实例） | hibernating_ (1B) + idle_cycles_ (4B) = ~5B + last_content (256B) | +| NVS 增量 | namespace `hibernate` 1 个 int32 key | +| 方案 B+C 倒计时刷新 CPU 增量 | <100ns/s（可忽略） | + +## 8. Phase 6 验收清单 + +- [x] Task 6.1: LeaveRoom 接口 +- [x] Task 6.2: OpenAudioChannel 适配重建 +- [x] Task 6.3: EnterIdleHibernate + WakeFromHibernate + 兜底 +- [x] Task 6.4: 方案 C conv_status 刷新 +- [x] Task 6.5: Watchdog 触发改造 +- [x] Task 6.6: BOOT 唤醒 +- [x] Task 6.7（补修）: 方案 B subtitle 刷新 + Light Sleep 防护 + codec 状态重置 + 字幕重试 + 不熄屏 +- [x] Task 6.8: 用户实测验证通过 +- [x] Task 6.9: 本报告 + 移植参考文档 + 项目文档更新 + +## 9. 已知限制 / 后续改进 + +| 项 | 说明 | +|----|------| +| AI 语音/开机音效卡顿 | 与 Phase 6 无关，是 PSRAM 带宽 + 任务调度问题（详见 `docs/Rtc_AIavatar/音频卡顿_全局资源分析.md`），可作 Phase 7 或独立优化 | +| 软休眠期间 BLE 配网协同 | 当前未深度测试，理论上 BLE 协议栈独立工作 | +| OTA 升级与软休眠协同 | 建议 OTA 触发前先 WakeFromHibernate | +| =y 双模式编译装不下 5.5MB ota | Phase 2 已记录，不阻塞数字人 RTC 单一形态项目 | + +## 10. 文档产出 + +| 文档 | 路径 | 作用 | +|------|------|------| +| 项目文档新增第 19 章 | `docs/Rtc_AIavatar/数字人表情渲染方案_云端预渲染+BLE+OTA.md` | 项目内方案选型与实施记录 | +| **完整移植参考** | `docs/Rtc_AIavatar/RTC软退出方案_移植参考.md` | **可移植到其他火山 RTC 项目** | +| 音频卡顿分析 | `docs/Rtc_AIavatar/音频卡顿_全局资源分析.md` | 卡顿原因 + 优化建议（不改代码） | +| 全局 skill 更新 | `~/.claude/skills/esp-troubleshoot/SKILL.md` | RTC 空闲倒计时 + 软退出速查 | +| Phase 6 PLAN 实施记录 | `phases/phase_06_idle_hibernate/PLAN.md` | 与原 PLAN 偏差 V1-V6 | + +## 11. Phase 6 结论 + +**全部目标达成**： +- ✅ 真退出 RTC 房间（释放 License） +- ✅ 唤醒 3-5s（vs 旧硬重启 15-25s，省 80%） +- ✅ 屏幕保持 + 字幕提示 +- ✅ B+C 双源覆盖完整对话场景 +- ✅ 6 个踩坑全部修复 +- ✅ 完整移植参考文档可用于其他火山 RTC 项目 + +**Phase 6 完成，准备进入 Phase 7（集成测试 + 验证）或卡顿优化。** diff --git a/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/PLAN.md b/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/PLAN.md new file mode 100644 index 0000000..3900769 --- /dev/null +++ b/.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/PLAN.md @@ -0,0 +1,599 @@ +# Phase 6 PLAN — RTC 空闲休眠（真退房 + 字幕提示 + 内存兜底） + +> 里程碑: `digital_human_rtc` +> 阶段目标: 40 秒对话空闲 → 真退出 RTC 房间（释放 License）+ 字幕提示，BOOT 唤醒重连。 +> 复用现有 `DIALOG_IDLE_COUNTDOWN_SECONDS = 40` 不新增常量。 + +--- + +## ⚠️ 实施变更记录（与原 PLAN 偏差） + +> 本节记录 Phase 6 实际实施过程中与原 PLAN 的关键调整，原始 PLAN 内容保留在下方供参考。 + +### V1: 倒计时方案从「C 单独」改为「B + C 双源」 +- 原 PLAN：方案 C（监听 conv_status）单独使用，方案 A（扬声器流）用宏关闭 +- 实际问题：AI 持续说话期间 `conv_status` 状态稳定在 ANSWERING 不切换 → 倒计时无刷新 → AI 说话期间被踢出 +- 实际方案：**B + C 双源** + - C 在 `conv_status` 分支刷新（覆盖状态切换：用户开始说话立即 LISTENING） + - **B 新增**在 `subtitle` 分支刷新（覆盖 AI 流式 TTS、用户 STT 字幕） + - A 仍然用 `#ifdef PHASE6_ENABLE_AUDIO_FALLBACK` 关闭 + +### V2: 不熄屏，字幕持续显示 +- 原 PLAN：进入 hibernate 后 `pwm_set_brightness(0)` 熄屏 +- 用户反馈：希望保留屏幕，让用户看到提示 +- 实际方案：**不熄屏**，字幕持续显示"已自动退出RTC对话，按BOOT键重新连接RTC"，BOOT 唤醒后清空 + +### V3: 新增 PowerSaveTimer Light Sleep 防护 +- 实施踩坑：hibernate 期间 PowerSaveTimer 10s 触发 `esp_pm_configure(light_sleep=true)` → I2C 控制器进入低功耗 → 唤醒后 ES7210/ES8311 通信失败 abort +- 修复： + - `CanEnterSleepMode()` 加 `if (hibernating_.load()) return false` + - `EnterIdleHibernate` 中调用 `esp_pm_configure(light_sleep_enable=false)` 双保险 + - **关键时序**：`hibernating_.store(true)` 必须在 `SetDeviceState(kDeviceStateIdle)` 之前 + +### V4: 新增 codec 状态机重置 +- 实施踩坑：单纯 LeaveRoom 不够，codec_dev 仍是 "Input already open" → 唤醒后 `set_in_channel_gain` I2C 失败 abort +- 修复：EnterIdleHibernate 中调用 `codec->EnableInput(false); codec->EnableOutput(false);` 重置状态机 + +### V5: dynamic_cast 替换为基类虚函数 +- 实施踩坑：项目 `-fno-rtti`，`dynamic_cast` 编译失败 +- 修复：`Protocol` 基类加 `virtual void LeaveRoom() { CloseAudioChannel(); }`，子类 override + +### V6: 字幕显示推迟到 hibernate 流程最后 +- 实施踩坑：字幕在 LeaveRoom 后立即调用，LVGL 锁被 GIF 解码竞争 500ms 超时 → 字幕未显示 +- 修复：字幕调用放在 hibernate 流程最后 + 5 次重试间隔 200ms + +### 实测验证（两次连续休眠唤醒成功） +- 第 1 次循环：106s 进入 → 130s 唤醒，RTC 加入耗时 3s +- 第 2 次循环：219s 进入 → 267s 唤醒，RTC 加入耗时 2s +- 无 abort / 无 I2C 失败 / 无 Light Sleep / NVS 持久化正常 + +完整移植参考见 [docs/Rtc_AIavatar/RTC软退出方案_移植参考.md](../../../../docs/Rtc_AIavatar/RTC软退出方案_移植参考.md)。 + +--- + +## 0. 调研结论 + +### 0.1 火山 RTC SDK API（`components/common/inc/volc_rtc.h`） + +```c +volc_rtc_t volc_rtc_create(...) // 创建 RTC 实例 +void volc_rtc_destroy(rtc) // = leaveRoom + destroyRTCEngine（真退房+销毁） +int volc_rtc_start(rtc, ...) // 启动 AI 任务（≈ StartVoiceChat 服务端） +int volc_rtc_stop(rtc) // 停止媒体流（≈ StopVoiceChat 服务端，仅 AI 离开，真人在房间） +int volc_rtc_interrupt(rtc) // 中断 AI 说话 +``` + +**当前 bug**: `VolcRtcProtocol::CloseAudioChannel()` 只调用 `volc_rtc_stop()`，**没有 `volc_rtc_destroy()`** → 真人未退出房间 → **持续消耗 License**。 + +火山官方文档（用户上传图 4）明确： +> "StopVoiceChat 接口仅会使智能体离开房间，**真人用户不会离开房间，仍会产生音视频费用**。如需完整结束通话，客户端还需调用 RTC SDK 接口 leaveRoom 使真人用户离开房间，并调用 destroyRTCEngine 销毁引擎实例。" + +### 0.2 倒计时起点（方案 C） + +监听 `conv_status` 事件（火山 RTC 协议层原生 5 状态机）： +| status 值 | 含义 | 触发时机 | +|----------|------|---------| +| 1 LISTENING | 用户说话/AI 听 | **用户开始说话立即触发** | +| 2 THINKING | AI 思考 | AI 收到完整语音后 | +| 3 ANSWERING | AI 回答中 | AI 开始 TTS | +| 4 INTERRUPTED | 被打断 | 用户打断 | +| 5 ANSWER_FINISH | AI 回答结束 | AI 说完 | + +方案 C 在 `application.cc:1260` 的 `conv_status` 分支加 1 行： + +```cpp +last_audible_output_time_ = std::chrono::steady_clock::now(); +``` + +**复用现有变量**（不新增 `last_dialog_activity_`），方便统一管理倒计时。 + +**修复 Q1 bug**：第 38s 用户说话 → conv_status: LISTENING 立即触发 → 时间戳刷新 → 不被踢出。 + +### 0.2.1 单独使用方案 C，方案 A 用宏关闭（保留代码，节省资源） + +**用户决策**：方案 A 代码**不物理删除**，用宏定义关闭编译；后续可随时启用恢复双源刷新。 + +**新增宏定义**（在 `main/application.cc` 顶部或 `main/application.h`）： +```c +// Phase 6 方案 C 单独使用，关闭方案 A 扬声器流刷新（节省 CPU） +// 取消注释下行宏可恢复方案 A 作为兜底 +// #define PHASE6_ENABLE_AUDIO_FALLBACK +``` + +**改动**：用 `#ifdef PHASE6_ENABLE_AUDIO_FALLBACK` 包裹 `application.cc` 中以下 3 处 `last_audible_output_time_` 更新： + +| 行号 | 现有代码 | 处理 | +|------|---------|------| +| L2212 | `if (rms_volume >= 0.01f) last_audible_output_time_ = now` | **#ifdef 包裹**（RMS 阈值检测也一并包裹） | +| L2241 | `if (bytes > 0) last_audible_output_time_ = now` | **#ifdef 包裹** | +| L2251 | `if (!pcm.empty()) last_audible_output_time_ = now` | **#ifdef 包裹** | +| L3510 | 进入 dialog 时初始化 | **保留**（确保新轮次起点正确） | +| L75 | 构造函数初始化 | **保留** | + +**包裹示例**： +```c +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK +if (rms_volume >= audible_volume_threshold) { + this->last_audible_output_time_ = std::chrono::steady_clock::now(); + ESP_LOGD(TAG, "🔊 更新last_audible_output_time_，当前音量: %.4f", rms_volume); +} +#endif +``` + +**边界场景说明**： +- AI 单轮回答超过 40 秒（如朗读长故事）期间，conv_status 不切换 → 倒计时可能触发 +- 实测火山 RTC 单轮回答平均 5-15 秒，>40 秒回答极罕见 +- 如果真出现 → AI 还在说时被退房，但用户体验损失小（按 BOOT 重连即可，已通过 Phase 5 的字幕显示提示） +- 极端场景兜底：用户上传图 2 提到"180s 服务端自动停止 AI 任务"，无需客户端额外处理 +- 若边界场景频发，定义 `PHASE6_ENABLE_AUDIO_FALLBACK` 即可启用方案 A 兜底（双源刷新） + +### 0.3 当前调用链（不动） + +``` +RTC 协议层 → MessageCallback → on_incoming_json_ → application.cc:1260+ conv_status 分支 +``` + +只在分支顶部加 1 行刷新时间戳，不影响 emoji 切换逻辑。 + +## 1. 设计方案 + +### 1.1 触发流程 + +``` +40s 无 conv_status 切换且无音频输出 + ↓ +Dialog Watchdog 触发（application.cc:2047） + ↓ +进入 Application::EnterIdleHibernate() + ├─ 1. display->SetChatMessage("system", "AI 即将休眠...") + ├─ 2. vTaskDelay(3000) ← 字幕保持 3 秒 + ├─ 3. display->SetChatMessage("system", "") ← 清空字幕 + ├─ 4. protocol_->LeaveRoom() ← volc_rtc_stop + volc_rtc_destroy + ├─ 5. pwm_set_brightness(0) ← 熄屏 + ├─ 6. SetDeviceState(kDeviceStateIdle) + ├─ 7. idle_cycles_++ 并检查兜底 + └─ 8. hibernating_ = true +``` + +### 1.2 唤醒流程（BOOT 按键触发） + +``` +BOOT 按键单击（movecall_moji_esp32s3.cc:741 boot_button_.OnClick） + ↓ +检测 Application 的 hibernating_ 标志 + ├─ true: 走 WakeFromHibernate 路径 + └─ false: 走原 ToggleChatState 路径 + +WakeFromHibernate(): + ├─ 1. pwm_init() 重新点亮背光（实际通过 pwm_set_brightness 设置） + ├─ 2. ToggleChatState() ← 复用现有代码 + │ └─ OpenAudioChannel() + │ └─ 检测 rtc_handle_=NULL → 重新 volc_rtc_create + volc_rtc_start + └─ 3. hibernating_ = false +``` + +### 1.3 内存兜底 + +每次 EnterIdleHibernate 时计数 `idle_cycles_`： +- 累计 `≥ 50 次` 时下次进入 hibernate 转为 esp_restart()（含写 reboot_dlg_idle NVS 标志） +- 防御 RTC 长期运行的内存碎片/泄漏 + +NVS 持久化 `idle_cycles_`，重启后保留计数。 + +## 2. 任务清单 + +### Task 6.1: VolcRtcProtocol 新增 LeaveRoom + +**文件**: `main/protocols/volc_rtc_protocol.h/cc` + +**接口**: +```cpp +// 真退出 RTC 房间（释放 License） +// = volc_rtc_stop() + volc_rtc_destroy() + 清状态 +// 与 CloseAudioChannel 的区别：CloseAudioChannel 只停媒体流，房间还在 +void LeaveRoom(); +``` + +**实现**: +```cpp +void VolcRtcProtocol::LeaveRoom() { + if (rtc_handle_) { + if (is_connected_) { + volc_rtc_stop(rtc_handle_); + is_connected_ = false; + } + volc_rtc_destroy(rtc_handle_); + rtc_handle_ = nullptr; + ESP_LOGI(TAG, "✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine）"); + } + is_audio_channel_opened_ = false; + if (on_audio_channel_closed_) { + on_audio_channel_closed_(); + } +} +``` + +**验证**: 编译通过，无符号缺失 + +**commit**: `feat(rtc): 新增 VolcRtcProtocol::LeaveRoom 真退房接口（stop + destroy）` + +--- + +### Task 6.2: OpenAudioChannel 适配重建 rtc_handle_ + +**文件**: `main/protocols/volc_rtc_protocol.cc:394` + +**问题**: 当前 `OpenAudioChannel` 开头检查 `if (!rtc_handle_) return false`，destroy 后无法重连。 + +**修改**: rtc_handle_=NULL 时不直接返回失败，而是触发重建： + +```cpp +bool VolcRtcProtocol::OpenAudioChannel() { + // Phase 6: 如果已 LeaveRoom 销毁，先重建 RTC 实例 + if (!rtc_handle_) { + ESP_LOGI(TAG, "RTC 实例不存在，重新创建..."); + if (!RecreateRtcHandle()) { + ESP_LOGE(TAG, "RTC 实例重建失败"); + return false; + } + } + // ... 原有 if (!is_connected_) 之后的代码 +} +``` + +新增私有方法 `RecreateRtcHandle()`：抽取现有 RTC 创建逻辑（components/common/inc/volc_rtc.h 的 volc_rtc_create 调用）成可复用函数。 + +**验证**: +- 第一次连接走原路径 +- LeaveRoom 后再次 OpenAudioChannel 能成功重建 + +**commit**: `feat(rtc): OpenAudioChannel 支持 LeaveRoom 后自动重建 rtc_handle_` + +--- + +### Task 6.3: Application::EnterIdleHibernate / WakeFromHibernate + +**文件**: `main/application.h/cc` + +**新增成员变量**（`application.h`）: +```cpp +private: + std::atomic hibernating_{false}; // 是否处于熄屏休眠状态 + int idle_cycles_ = 0; // 累计休眠循环次数（从 NVS 加载） + static constexpr int IDLE_CYCLES_REBOOT_THRESHOLD = 50; // 累计 50 次触发硬重启 +``` + +**新增方法**: +```cpp +public: + void EnterIdleHibernate(); // 进入空闲休眠 + void WakeFromHibernate(); // 从休眠唤醒 + bool IsHibernating() const { return hibernating_.load(); } +``` + +**EnterIdleHibernate 实现**: +```cpp +void Application::EnterIdleHibernate() { + if (hibernating_.load()) return; + ESP_LOGI(TAG, "🌙 进入空闲休眠：显示字幕 3s → 真退房 → 熄屏"); + + auto display = Board::GetInstance().GetDisplay(); + + // 1. 字幕提示 3 秒 + display->SetChatMessage("system", "AI 即将休眠..."); + vTaskDelay(pdMS_TO_TICKS(3000)); + display->SetChatMessage("system", ""); + + // 2. 真退出 RTC 房间（释放 License） + if (protocol_) { + protocol_->LeaveRoom(); + } + + // 3. 设备状态切回 idle + SetDeviceState(kDeviceStateIdle); + + // 4. 熄屏（pwm_set_brightness 在 dzbj/pages_pwm.c 中） + extern void pwm_set_brightness(int percent); + pwm_set_brightness(0); + + hibernating_.store(true); + + // 5. 内存兜底：累计 50 次后下次走硬重启 + idle_cycles_++; + SaveIdleCyclesToNvs(); + if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ESP_LOGW(TAG, "🛡 累计休眠 %d 次，下次唤醒后行为：硬重启清理内存碎片", idle_cycles_); + // 标志位让 BOOT 唤醒时检测，触发 esp_restart() 而不是简单恢复 + } + + ESP_LOGI(TAG, "✓ 已进入空闲休眠（累计第 %d 次）", idle_cycles_); +} +``` + +**WakeFromHibernate 实现**: +```cpp +void Application::WakeFromHibernate() { + if (!hibernating_.load()) return; + ESP_LOGI(TAG, "☀ 从休眠唤醒"); + + // 内存兜底：累计 50 次 → 唤醒时硬重启清理 + if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ESP_LOGI(TAG, "🛡 累计休眠 %d 次，硬重启清理内存碎片", idle_cycles_); + ResetIdleCyclesNvs(); // 重置计数 + Board::GetInstance().OnBeforeRestart(); + vTaskDelay(pdMS_TO_TICKS(500)); + esp_restart(); + return; + } + + // 1. 恢复亮度 + extern void pwm_set_brightness(int percent); + pwm_set_brightness(80); // 默认亮度（与 ai_chat_screen_init 中 pwm_init 一致） + + // 2. 触发 RTC 重连 + ToggleChatState(); // 复用现有代码：OpenAudioChannel → 自动重建 rtc_handle_ + + hibernating_.store(false); +} +``` + +**NVS 持久化**: +```cpp +void Application::SaveIdleCyclesToNvs() { + Settings s("hibernate", true); + s.SetInt("idle_cycles", idle_cycles_); +} + +void Application::LoadIdleCyclesFromNvs() { + Settings s("hibernate", false); + idle_cycles_ = s.GetInt("idle_cycles", 0); +} + +void Application::ResetIdleCyclesNvs() { + Settings s("hibernate", true); + s.SetInt("idle_cycles", 0); +} +``` + +构造函数中调用 `LoadIdleCyclesFromNvs()`。 + +**commit**: `feat(hibernate): Application::EnterIdleHibernate + WakeFromHibernate + 内存兜底` + +--- + +### Task 6.4: 方案 C — conv_status 分支加刷新 + 宏关闭方案 A + +**文件**: `main/application.cc` + +#### 4.1 在 conv_status 分支新增方案 C 刷新（约 L1260） + +```cpp +} else if (strcmp(type->valuestring, "conv_status") == 0) { + auto status_val = cJSON_GetObjectItem(root, "status"); + if (status_val) { + // Phase 6 方案 C: conv_status 状态切换刷新对话活跃时间 + // 比扬声器输出更早触发（事件级），修复用户开始说话就被踢的 bug + last_audible_output_time_ = std::chrono::steady_clock::now(); + + int conv_status = status_val->valueint; + // ... 原有 emoji 切换代码 + } +} +``` + +#### 4.2 在文件顶部加 Phase 6 宏（约 L40 之前） + +```cpp +// Phase 6 方案 C 单独使用，关闭方案 A 扬声器流刷新（节省 CPU） +// 取消注释下行宏可恢复方案 A 作为兜底 +// #define PHASE6_ENABLE_AUDIO_FALLBACK +``` + +#### 4.3 用 #ifdef 包裹方案 A 的 3 处更新（L2212/L2241/L2251） + +**位置 1: L2212 附近（RMS 检测）** +```c +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK +const float audible_volume_threshold = 0.01f; +if (rms_volume >= audible_volume_threshold) { + this->last_audible_output_time_ = std::chrono::steady_clock::now(); + ESP_LOGD(TAG, "🔊 更新last_audible_output_time_，当前音量: %.4f", rms_volume); +} +#endif +``` + +**位置 2: L2241 附近（player_pipeline_write）** +```c +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK +if (bytes > 0) { + this->last_audible_output_time_ = std::chrono::steady_clock::now(); +} +#endif +``` + +**位置 3: L2251 附近（codec->OutputData）** +```c +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK +if (!pcm.empty()) { + this->last_audible_output_time_ = std::chrono::steady_clock::now(); +} +#endif +``` + +**注意**：L75 构造函数初始化 + L3510 进入 dialog 状态初始化**保留不动**（确保 watchdog 起点正确）。 + +**验证**: 编译通过；运行时只有 conv_status 切换才会更新时间戳；恢复方案 A 只需定义 `PHASE6_ENABLE_AUDIO_FALLBACK` 宏 + +**commit**: `feat(idle): conv_status 状态切换刷新对话活跃时间（方案 C）` + +--- + +### Task 6.5: Dialog Watchdog 动作从 esp_restart 改为 EnterIdleHibernate + +**文件**: `main/application.cc:2047-2067` + +**当前代码**（要改）: +```cpp +if (remaining <= 0) { + Settings sys("system", true); + sys.SetInt("reboot_dlg_idle", 1); + sys.SetInt("reboot_origin", 1); + sys.Commit(); + Board::GetInstance().OnBeforeRestart(); + vTaskDelay(pdMS_TO_TICKS(2000)); + esp_restart(); + app->dialog_watchdog_running_ = false; +} +``` + +**新代码**: +```cpp +if (remaining <= 0) { + ESP_LOGI(TAG, "Dialog watchdog 触发：%ds 无对话活动 → 进入空闲休眠", (int)elapsed); + app->dialog_watchdog_running_ = false; + Schedule([app]() { + app->EnterIdleHibernate(); + }); + break; // 退出 watchdog 任务循环 +} +``` + +**注意**: 旧的 `reboot_dlg_idle/reboot_origin` NVS 标志保留兼容（不立即清除），便于回滚。 + +**验证**: 烧录后 40s 无活动看到 "进入空闲休眠" 日志而非 esp_restart + +**commit**: `refactor(watchdog): Dialog Watchdog 触发改为软休眠（EnterIdleHibernate）` + +--- + +### Task 6.6: BOOT 唤醒调用 WakeFromHibernate + +**文件**: `main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc:741` + +**当前**: +```cpp +boot_button_.OnClick([this]() { + // ... + app.ToggleChatState(); +}); +``` + +**修改**: +```cpp +boot_button_.OnClick([this]() { + auto& app = Application::GetInstance(); + if (app.IsHibernating()) { + ESP_LOGI(TAG, "🔵 BOOT button pressed in hibernate → 唤醒"); + app.WakeFromHibernate(); + return; + } + // ... 原有 ToggleChatState 等逻辑 +}); +``` + +**注意**: 这一段在 InitializeAiModeButtons 内，需要找到 BOOT OnClick 的具体位置（约 L726 / L741）。 + +**验证**: 烧录后熄屏状态下按 BOOT 屏幕亮起 + 重连 RTC + +**commit**: `feat(wake): BOOT 按键唤醒走 WakeFromHibernate 路径` + +--- + +### Task 6.7: 内存兜底集成 + +实际上 Task 6.3 已经包含了内存兜底逻辑（idle_cycles_ 累计 + NVS 持久化）。Task 6.7 这里**单独检查**该机制是否正确： + +**验证**: +- NVS 中 `hibernate/idle_cycles` 持久化（重启后保留） +- 累计第 50 次熄屏，下次 BOOT 唤醒时 esp_restart() +- 重启后 idle_cycles 重置为 0 + +不产生新 commit（包含在 Task 6.3）。 + +--- + +### Task 6.8: 烧录验证 + +**步骤**: + +1. 编译 + 烧录 +2. 启动后等待 40s 无对话 → 观察日志： + ``` + I (xxxxx) Application: Dialog watchdog 触发：40s 无对话活动 → 进入空闲休眠 + I (xxxxx) Application: 🌙 进入空闲休眠：显示字幕 3s → 真退房 → 熄屏 + I (xxxxx) Application: ✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine） + I (xxxxx) Application: ✓ 已进入空闲休眠（累计第 1 次） + ``` +3. 屏幕应该： + - 字幕显示"AI 即将休眠..."保持 3 秒 + - 字幕消失，3 秒后屏幕熄灭 +4. 按 BOOT 唤醒 → 观察日志： + ``` + I (xxxxx) Airhub1: 🔵 BOOT button pressed in hibernate → 唤醒 + I (xxxxx) Application: ☀ 从休眠唤醒 + I (xxxxx) VolcRtcProtocol: RTC 实例不存在，重新创建... + I (xxxxx) Application: 正在尝试打开音频通道 + I (xxxxx) Application: 进入对话框状态：启用全双工 + ``` +5. 屏幕亮起，可继续对话 + +6. 边界场景验证（**用户协作**）： + - 第 38 秒用户说话 → conv_status 触发 LISTENING → 时间戳刷新 → **不会触发 40s 退房** + +**用户协作**: 烧录后亲测对话 → 等待 → 唤醒，目视确认。 + +不产生 commit。 + +--- + +### Task 6.9: 生成 HIBERNATE_REPORT.md + +**内容**: +- LeaveRoom vs CloseAudioChannel 对比（真退房 vs 仅停媒体） +- conv_status 5 状态机 +- 边界场景 Q1 bug 修复验证 +- 内存兜底机制（50 次熄屏后硬重启） +- 实测启动 → 熄屏 → 唤醒完整日志 +- 火山官方推荐方案对应（图 2/3/4） + +**commit**: `docs(phase06): 空闲休眠验证报告（HIBERNATE_REPORT.md）` + +## 3. 任务顺序 + +``` +6.1 LeaveRoom → 6.2 OpenAudioChannel 适配 → 6.3 EnterIdleHibernate + → 6.4 conv_status 刷新 → 6.5 Watchdog 改动作 → 6.6 BOOT 唤醒 + → 6.7（已含在 6.3）→ 6.8 烧录 → 6.9 报告 +``` + +## 4. 风险与回滚 + +| 风险 | 缓解 | +|------|------| +| volc_rtc_destroy 内部异常导致后续 create 失败 | LeaveRoom 内捕获异常 + nullptr 守护；OpenAudioChannel 失败有 2s 重试 | +| 唤醒后 WiFi 状态丢失 | LeaveRoom 不动 WiFi，OpenAudioChannel 通过 WiFi 直接走 RTC 协议层 | +| BOOT 按键在 hibernate 期间被忽略 | hibernating_ 检测在 OnClick 第一行，不依赖 LVGL 锁/状态机 | +| idle_cycles_ 累计但 NVS 写失败 | 单独 namespace "hibernate"，独立于其他 NVS 业务 | +| 熄屏后 LVGL 仍运行消耗 CPU | 后续可选优化（Phase 7 测试发现再加 lvgl_port_stop） | +| ai_chat_set_chat_message 在 hibernate 后被 RTC 协议层错误调用 | LeaveRoom 后 protocol_ 不再发字幕，安全 | + +**回滚**: 每 Task 独立 commit，单独 revert 即可。 + +## 5. Phase 6 完成验收清单 + +- [ ] Task 6.1-6.7 共 6 个原子 commit 完成 +- [ ] Task 6.8 烧录验证：40s 软休眠 + 字幕 + 真退房 + 熄屏 + BOOT 唤醒 + 重连 +- [ ] Q1 bug 修复：第 38s 说话不会被踢出 +- [ ] LeaveRoom 真退房：`volc_rtc_destroy` 调用成功，rtc_handle_=nullptr +- [ ] 内存兜底：NVS 持久化 idle_cycles_，累计 50 次后硬重启 +- [ ] Task 6.9 HIBERNATE_REPORT.md commit +- [ ] 整个 Phase 6 合并为 1 个大 commit 推送 gitea + GitHub + +## 6. Phase 6 不做的事 + +- ❌ 修改字幕显示样式（Phase 5 已完成） +- ❌ Phase 7 的集成测试 + 性能数据收集 +- ❌ 完全去除旧 `reboot_dlg_idle` NVS 标志（保留兼容兜底） +- ❌ 服务端 StopVoiceChat HTTP 调用（客户端 destroy 已足够，服务端 180s 自动清理） +- ❌ lvgl_port_stop 暂停 LVGL（先观察是否需要再决定） +- ❌ Light Sleep / CPU 降频（与现有 PowerSaveTimer 协同，不改动） diff --git a/docs/Rtc_AIavatar/RTC软退出方案_移植参考.md b/docs/Rtc_AIavatar/RTC软退出方案_移植参考.md new file mode 100644 index 0000000..a68e3b9 --- /dev/null +++ b/docs/Rtc_AIavatar/RTC软退出方案_移植参考.md @@ -0,0 +1,876 @@ +# 火山 RTC 软退出房间方案 — 完整移植参考 + +> 来源: 数字人 RTC 项目 Phase 6 实施总结（2026-05-13） +> 用途: 移植到其他基于火山 RTC SDK 的项目，替换"硬重启退出"为"软退出 + 快速恢复"。 +> 关键收益: 唤醒时间 15-25s → 3-5s，省 80% 时间；用户体验：黑屏长断 → 字幕提示常亮。 + +## 目录 + +- [1. 背景与动机](#1-背景与动机) +- [2. 倒计时刷新方案选型（A vs B vs C）](#2-倒计时刷新方案选型) +- [3. 软退出 RTC 房间机制](#3-软退出-rtc-房间机制) +- [4. 完整调用链与状态机](#4-完整调用链与状态机) +- [5. 实施清单（步骤化）](#5-实施清单) +- [6. 6 个关键踩坑与修复经验](#6-6-个关键踩坑与修复经验) +- [7. 移植到其他项目的最小改动清单](#7-移植到其他项目的最小改动清单) +- [8. 时间对比与性能数据](#8-时间对比与性能数据) +- [9. 验证清单](#9-验证清单) +- [10. 火山 RTC SDK 关键 API 速查](#10-火山-rtc-sdk-关键-api-速查) + +--- + +## 1. 背景与动机 + +### 1.1 旧方案的问题 + +火山 RTC AI 对话项目原有的"空闲退出 RTC"机制使用 **硬重启**： + +```cpp +// Dialog Watchdog 40s 无音频输出触发 +Settings sys("system", true); +sys.SetInt("reboot_dlg_idle", 1); +sys.SetInt("reboot_origin", 1); +esp_restart(); // 整机重启 +``` + +**痛点**： +1. ❌ 黑屏 15-25s 不可用（WiFi 重连 + 应用初始化） +2. ❌ NVS/RAM 状态丢失（音量、亮度、对话上下文等） +3. ❌ 用户感知"设备重启"，不流畅 +4. ❌ 屏幕 PWM 重新初始化引起冷启动闪烁 + +### 1.2 设计目标（软退出） + +- ✅ **真正释放 License**（不消耗火山 RTC 计费资源） +- ✅ **快速恢复**（按 BOOT 后 ~3s 恢复对话） +- ✅ **屏幕保持**（字幕提示告知用户） +- ✅ **状态保留**（音量、亮度、对话历史等） +- ✅ **防御长期运行内存碎片**（兜底机制） + +--- + +## 2. 倒计时刷新方案选型 + +### 2.1 火山 RTC 协议层向应用层暴露的事件类型 + +``` +[INF|volc_rtc.c:475]message received channel=... binary=1 + ↓ +DataCallback 内部按前缀分发： +├── "subv" 前缀：subtitle 字幕消息（STT/TTS 内容） +├── "ctrl" 前缀：conv_status 状态机消息（5 状态） +├── "tool" 前缀：function_call 工具调用 +├── "info" 前缀：通用信息 +└── "conv" 前缀：会话级消息 +``` + +应用层只需在 `application.cc` 的 `type` 分发分支添加 1 行时间戳刷新。 + +### 2.2 三方案对比矩阵 + +| 维度 | 方案 A 扬声器流 | 方案 B 字幕监听 | 方案 C 智能体状态 | +|------|--------------|--------------|---------------| +| **监听源** | I2S DMA / Opus PCM 输出 | RTC `subtitle` 消息 | RTC `conv_status` 消息 | +| **更新位置** | `Application::OnAudioOutput` audio task | `application.cc:1300 subtitle 分支` | `application.cc:1260 conv_status 分支` | +| **触发频率** | 每 20ms（50 Hz） | 每秒 5-15 次 | 每轮对话 4-5 次 | +| **CPU 增量** | 中（每秒 50 次 chrono::now） | 极低（10ns × 5-15） | 最低（10ns × 4-5） | +| **代码改动** | 0（已实现） | 1 行 | 1 行 | +| **覆盖场景：用户开始说话** | ❌ AI 还没回应时无刷新 | ⚠️ 等 STT 出字幕（1-3s 延迟） | ✅ **立即触发 LISTENING** | +| **覆盖场景：AI 思考期** | ❌ 无音频输出 | ⚠️ 等字幕送达 | ✅ THINKING 触发 | +| **覆盖场景：AI 持续说话** | ✅ 持续 PCM 输出 | ✅ 流式字幕持续 | ❌ **ANSWERING 状态稳定不切换** | +| **覆盖场景：AI 长回答（>40s）** | ✅ | ✅ | ❌ | + +### 2.3 选型结论：B + C 双源（不启用 A） + +**单方案缺陷**： +- 单用 A：用户开始说话时不刷新 → 第 38s 说话被踢出 +- 单用 B：字幕送达有 1-3s 延迟 → 用户开始说话与 AI 响应窗口空缺 +- 单用 C：AI 长说话期间 ANSWERING 状态不切换 → 倒计时无刷新 + +**最优组合 B+C**： +- C 处理状态机切换（最早响应用户开始说话事件） +- B 处理流式字幕（最稳定的对话进行中刷新） +- A 关闭（避免每 20ms 时间戳更新的 CPU 消耗） + +**实施代码**（1+1 行改动）： + +```cpp +// application.cc 在 type 分发分支添加 + +} else if (strcmp(type->valuestring, "conv_status") == 0) { + auto status_val = cJSON_GetObjectItem(root, "status"); + if (status_val) { + last_audible_output_time_ = std::chrono::steady_clock::now(); // 方案 C + // ... 原有 emoji 切换 + } +} + +} else if (strcmp(type->valuestring, "subtitle") == 0) { + auto data_arr = cJSON_GetObjectItem(root, "data"); + if (data_arr && cJSON_IsArray(data_arr) && cJSON_GetArraySize(data_arr) > 0) { + last_audible_output_time_ = std::chrono::steady_clock::now(); // 方案 B + // ... 原有字幕解析 + } +} +``` + +### 2.4 火山 RTC `conv_status` 5 状态机详解 + +| value | 状态 | 触发时机 | +|-------|------|---------| +| 1 | LISTENING | 用户开始说话（VAD 检测到人声） | +| 2 | THINKING | ASR 识别完成，LLM 推理中 | +| 3 | ANSWERING | TTS 开始（AI 输出第一个音频帧） | +| 4 | INTERRUPTED | 用户打断（VAD 检测到用户在 AI 说话期间说话） | +| 5 | ANSWER_FINISH | TTS 结束（AI 完成本轮回答） | + +**关键洞察**：状态转换 1→2→3→5 是一轮对话的标准流程，5 个事件刷新足以覆盖正常对话节奏。但 AI 长回答（>40s）期间状态稳定在 3 ANSWERING，**这是为什么必须补 B**。 + +--- + +## 3. 软退出 RTC 房间机制 + +### 3.1 火山 SDK API 关系（关键澄清） + +``` +┌──────────────────────────────────────────────────────────┐ +│ volc_rtc_stop() │ +│ ≈ 服务端 StopVoiceChat │ +│ 仅 AI 智能体离开房间 │ +│ 真人客户端仍在房间，继续产生音视频费用 ❌ │ +└──────────────────────────────────────────────────────────┘ + +┌──────────────────────────────────────────────────────────┐ +│ volc_rtc_destroy() │ +│ = leaveRoom + destroyRTCEngine │ +│ 真人客户端离开房间 + 销毁本地实例 │ +│ License 资源释放 ✅ │ +│ 服务端 AI 任务在 180s 内自动清理（火山平台机制） │ +└──────────────────────────────────────────────────────────┘ +``` + +**火山官方原文**（StopVoiceChat 文档）： +> "StopVoiceChat 接口仅会使智能体离开房间，**真人用户不会离开房间，仍会产生音视频费用**。如需完整结束通话，客户端还需调用 RTC SDK 接口 leaveRoom 使真人用户离开房间，并调用 destroyRTCEngine 销毁引擎实例。" + +### 3.2 默认 CloseAudioChannel 的问题 + +```cpp +// 原代码（VolcRtcProtocol::CloseAudioChannel） +void VolcRtcProtocol::CloseAudioChannel() { + if (is_connected_) { + volc_rtc_stop(rtc_handle_); // ❌ 只 stop，不 destroy + is_connected_ = false; + } + is_audio_channel_opened_ = false; +} +``` + +`CloseAudioChannel` 只 `stop` 不 `destroy` → 真人仍在房间消耗 License。这是原项目"硬重启退出"设计的根本原因——只有重启才能真正释放。 + +### 3.3 新增 LeaveRoom 接口 + +```cpp +// Protocol 基类 protocol.h +class Protocol { +public: + virtual void CloseAudioChannel() = 0; + // 新增：真退出 RTC 房间（释放 License），默认回退到 CloseAudioChannel + virtual void LeaveRoom() { CloseAudioChannel(); } +}; + +// VolcRtcProtocol override +void VolcRtcProtocol::LeaveRoom() { + if (rtc_handle_) { + if (is_connected_) { + volc_rtc_stop(rtc_handle_); // 停止媒体流 + is_connected_ = false; + } + volc_rtc_destroy(rtc_handle_); // 真退房 + 销毁 + rtc_handle_ = nullptr; + ESP_LOGI(TAG, "✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine）"); + } + is_audio_channel_opened_ = false; + if (on_audio_channel_closed_) on_audio_channel_closed_(); +} +``` + +**为什么要在基类加虚函数而不是 dynamic_cast**？ 项目通常用 `-fno-rtti` 优化掉 RTTI，`dynamic_cast` 编译失败。基类虚函数 + override 是最干净的多态方式。 + +### 3.4 OpenAudioChannel 适配重建 + +LeaveRoom 销毁 `rtc_handle_` 后，原有 `OpenAudioChannel` 直接 return false。需要适配： + +```cpp +bool VolcRtcProtocol::OpenAudioChannel() { + // 检测 rtc_handle_=NULL 且 iot_ready_ 为 true（凭证已缓存） + if (!rtc_handle_ && iot_ready_) { + ESP_LOGI(TAG, "RTC 实例不存在，触发重建..."); + iot_ready_ = false; // 由 Start 任务重新置位 + Start(); // 异步触发 volc_rtc_init 任务 + // 轮询等待 rtc_handle_ 就绪（最多 5 秒） + int wait_ticks = 0; + while (!rtc_handle_ && wait_ticks < 50) { + vTaskDelay(pdMS_TO_TICKS(100)); + wait_ticks++; + } + if (!rtc_handle_) { + ESP_LOGE(TAG, "RTC 重建超时"); + return false; + } + ESP_LOGI(TAG, "RTC 实例已重建（耗时 %d ms）", wait_ticks * 100); + } + if (!rtc_handle_) { + return false; + } + // ... 原有 volc_rtc_start 加入房间逻辑 +} +``` + +**实测**：因为 NVS 缓存了 `device_secret`，无需重新走 HTTP 设备注册，`volc_rtc_create` 通常在 100ms 内完成。 + +--- + +## 4. 完整调用链与状态机 + +### 4.1 进入软休眠 + +``` +Dialog Watchdog 任务（40s 无音频输出 + 无 conv_status + 无字幕） + ↓ +触发 Application::EnterIdleHibernate() + ↓ +1. protocol_->LeaveRoom() + ├─ volc_rtc_stop(rtc_handle_) + └─ volc_rtc_destroy(rtc_handle_) + → 真退房，License 释放 + ↓ +2. codec->EnableInput(false) + codec->EnableOutput(false) + → ESP-IDF esp_codec_dev_close（重置 ES7210/ES8311 状态机） + ↓ +3. recorder_pipeline_close() + → 释放录音管道（避免唤醒后重新打开冲突） + ↓ +4. hibernating_.store(true) + → 阻止 PowerSaveTimer 进入 Light Sleep + ↓ +5. esp_pm_configure(light_sleep_enable=false) + → 双保险：强制禁用 Light Sleep 保护 I2C 总线 + ↓ +6. SetDeviceState(kDeviceStateIdle) + → 设备状态切回 idle（屏幕保持亮起） + ↓ +7. idle_cycles_++ + NVS 持久化 + → 内存兜底计数 + ↓ +8. display->SetChatMessage("system", "已自动退出RTC对话，按BOOT键重新连接RTC") + → 字幕持续显示（5 次重试间隔 200ms，避免 LVGL 锁竞争） +``` + +### 4.2 BOOT 按键唤醒 + +``` +boot_button_.OnClick 回调（iot_button 在 esp_timer 任务） + ↓ +检测 Application::IsHibernating() == true + ↓ +xTaskCreate("wake_hib", WakeFromHibernate, ...) + → 派发到独立 task 避免阻塞 iot_button / esp_timer + ↓ +Application::WakeFromHibernate() + ↓ +1. 检查 idle_cycles_ >= 50 + → 累计达阈值 → ResetIdleCyclesNvs + esp_restart()（兜底清碎片） + ↓ +2. 清空字幕：display->SetChatMessage("system", "") + ↓ +3. SetDeviceState(kDeviceStateIdle)（幂等） + ↓ +4. ToggleChatState() + ↓ + OpenAudioChannel() + ├─ 检测 rtc_handle_=NULL → Start() 异步重建 + ├─ 轮询等待 rtc_handle_ 就绪 + └─ volc_rtc_start(rtc_handle_, bot_id, iot_info_, ...) + ↓ + 等待 RTC 远程用户加入（火山 AI bot） + ↓ + 音频通道打开，进入 Dialog 状态 + ↓ +5. hibernating_.store(false) + ↓ +6. Dialog Watchdog 重新启动（StartDialogWatchdog） +``` + +### 4.3 内存兜底 + +```cpp +// application.h +static constexpr int IDLE_CYCLES_REBOOT_THRESHOLD = 50; +int idle_cycles_ = 0; + +// EnterIdleHibernate 中递增 + 持久化 +void Application::SaveIdleCyclesToNvs() { + Settings s("hibernate", true); + s.SetInt("idle_cycles", idle_cycles_); +} + +// WakeFromHibernate 中检查 +if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ResetIdleCyclesNvs(); + pwm_set_brightness(80); // 重启前先点亮 + Board::GetInstance().OnBeforeRestart(); + vTaskDelay(pdMS_TO_TICKS(500)); + esp_restart(); +} +``` + +50 次按平均每次 5 分钟对话计算约覆盖 4 小时使用时长。NVS namespace `hibernate` 独立，不影响其他业务。 + +--- + +## 5. 实施清单 + +### 5.1 文件改动总览 + +| 文件 | 改动 | +|------|------| +| `main/protocols/protocol.h` | 基类加 `virtual void LeaveRoom() { CloseAudioChannel(); }` | +| `main/protocols/volc_rtc_protocol.h/cc` | 新增 `LeaveRoom()` override：stop + destroy | +| `main/protocols/volc_rtc_protocol.cc` | `OpenAudioChannel` 头部加重建逻辑 | +| `main/application.h` | 新增 `hibernating_` / `idle_cycles_` / `EnterIdleHibernate` / `WakeFromHibernate` 等接口 | +| `main/application.cc` | 新增 NVS 持久化 + EnterIdleHibernate / WakeFromHibernate + CanEnterSleepMode 加 hibernating 检查 | +| `main/application.cc` | conv_status 分支 + subtitle 分支各加 1 行刷新（方案 B+C） | +| `main/application.cc` | Dialog Watchdog 触发动作从 `esp_restart` 改为 `Schedule(EnterIdleHibernate)` | +| `main/application.cc` 顶部 | 加 `// #define PHASE6_ENABLE_AUDIO_FALLBACK` + 用 `#ifdef` 包裹方案 A 3 处更新 | +| `main/boards/.cc` | BOOT 按键回调入口加 `if (IsHibernating()) WakeFromHibernate()` | + +### 5.2 关键代码模板 + +#### 5.2.1 EnterIdleHibernate 完整实现 + +```cpp +void Application::EnterIdleHibernate() { + if (hibernating_.load()) return; + ESP_LOGI(TAG, "🌙 进入空闲休眠：真退房 → 字幕提示（不熄屏）"); + + auto display = Board::GetInstance().GetDisplay(); + + // 1. 真退出 RTC 房间（释放 License） + if (protocol_) { + protocol_->LeaveRoom(); + } + + // 2. 字幕显示推迟到最后 + + // 3. 关闭 codec input/output 重置状态机（避免唤醒 abort） + auto codec = Board::GetInstance().GetAudioCodec(); + if (codec) { + codec->EnableInput(false); + codec->EnableOutput(false); + } + + // 4. 关闭录音管道 + if (recorder_pipeline_) { + recorder_pipeline_close(recorder_pipeline_); + recorder_pipeline_ = nullptr; + } + + // 5. 关键时序：先 hibernating_=true，阻止 PowerSaveTimer 进入 Light Sleep + hibernating_.store(true); + + // 6. 双保险：强制 esp_pm 禁用 Light Sleep + esp_pm_config_t pm_config = { + .max_freq_mhz = 240, + .min_freq_mhz = 240, + .light_sleep_enable = false, + }; + esp_pm_configure(&pm_config); + + // 7. 设备状态切回 idle + SetDeviceState(kDeviceStateIdle); + + // 8. 累计休眠次数（NVS 持久化） + idle_cycles_++; + SaveIdleCyclesToNvs(); + ESP_LOGI(TAG, "✓ 已进入空闲休眠（累计第 %d 次）", idle_cycles_); + + // 9. 字幕显示（最后做：LVGL 锁竞争最少 + 5 次重试） + const char* msg = "已自动退出RTC对话，按BOOT键重新连接RTC"; + for (int i = 0; i < 5; i++) { + vTaskDelay(pdMS_TO_TICKS(200)); + if (display) display->SetChatMessage("system", msg); + } +} +``` + +#### 5.2.2 WakeFromHibernate 完整实现 + +```cpp +void Application::WakeFromHibernate() { + if (!hibernating_.load()) return; + ESP_LOGI(TAG, "☀ 从空闲休眠唤醒"); + + // 内存兜底：累计 50 次硬重启清理碎片 + if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ResetIdleCyclesNvs(); + Board::GetInstance().OnBeforeRestart(); + vTaskDelay(pdMS_TO_TICKS(500)); + esp_restart(); + return; + } + + // 清空 hibernate 字幕 + auto display = Board::GetInstance().GetDisplay(); + if (display) display->SetChatMessage("system", ""); + + // 触发 RTC 重连 + if (device_state_ != kDeviceStateIdle) { + SetDeviceState(kDeviceStateIdle); + } + ToggleChatState(); // 复用现有重连路径 + + hibernating_.store(false); + ESP_LOGI(TAG, "✓ 唤醒完成"); +} +``` + +#### 5.2.3 CanEnterSleepMode 关键改动 + +```cpp +bool Application::CanEnterSleepMode() { + if (device_state_ != kDeviceStateIdle) return false; + if (protocol_ && protocol_->IsAudioChannelOpened()) return false; + + // 关键：hibernate 期间禁用 PowerSaveTimer 的 Light Sleep + // 否则 esp_pm_configure(light_sleep_enable=true) 让 I2C 进入低功耗 + // 唤醒后 ES7210/ES8311 通信失败导致 ESP_ERROR_CHECK abort + if (hibernating_.load()) return false; + + return true; +} +``` + +#### 5.2.4 Dialog Watchdog 触发动作改造 + +```cpp +// 原代码：写 NVS + esp_restart() +// 新代码： +if (remaining <= 0) { + ESP_LOGI(TAG, "Dialog watchdog 触发：%ds → 软退房", (int)elapsed); + app->dialog_watchdog_running_ = false; + app->Schedule([app]() { + app->EnterIdleHibernate(); + }); + break; // 退出 while 循环 +} +``` + +#### 5.2.5 BOOT 按键唤醒（board 文件） + +```cpp +boot_button_.OnClick([this]() { + // 防抖、配网模式检查等 ... 之前的逻辑 + + // 优先处理 hibernate 唤醒 + auto &app = Application::GetInstance(); + if (app.IsHibernating()) { + ESP_LOGI(TAG, "🔵 BOOT in hibernate → 唤醒"); + xTaskCreate([](void* arg) { + Application::GetInstance().WakeFromHibernate(); + vTaskDelete(NULL); + }, "wake_hib", 4096, NULL, 5, NULL); + return; + } + + // 非 hibernate 状态 → 走原有 ToggleChatState 路径 +}); +``` + +--- + +## 6. 6 个关键踩坑与修复经验 + +### 6.1 坑 1: codec 状态机未重置 → 唤醒后 I2C abort + +**现象**：BOOT 唤醒后日志显示 +``` +Adev_Codec: Input already open +E (xxxxx) I2C_If: Fail to write to dev 30 ← ES8311 (0x18=write 0x30) +E (xxxxx) I2C_If: Fail to read from dev 80 ← ES7210 (0x40=read 0x80) +abort() was called at PC 0x40386e57 +Backtrace: ... BoxAudioCodec::EnableInput at box_audio_codec.cc:265 +``` + +**根因**：LeaveRoom 只销毁 RTC 实例，但 `esp_codec_dev` 内部状态仍是 "open"。唤醒后 `EnableInput(true)` 看到 codec_dev 已 open → 直接调用 `set_in_channel_gain` 而非完整 `esp_codec_dev_open` 流程 → I2C 通信走异常路径失败。 + +**修复**：EnterIdleHibernate 显式重置： +```cpp +codec->EnableInput(false); // 触发 esp_codec_dev_close +codec->EnableOutput(false); +``` + +### 6.2 坑 2: PowerSaveTimer Light Sleep 干扰 I2C 总线 + +**现象**：日志显示 hibernate 期间出现 +``` +I (xxxxx) Airhub1: 🔋 进入低功耗模式：CPU降频、Light Sleep启用、功放关闭 +``` +然后 BOOT 唤醒后 codec I2C 失败 abort（同坑 1 的现象）。 + +**根因**：`PowerSaveTimer::PowerSaveCheck` 在 idle 状态 10s 后触发： +```cpp +esp_pm_config_t pm_config = { + .max_freq_mhz = 240, + .min_freq_mhz = 40, + .light_sleep_enable = true, // ⚠️ +}; +esp_pm_configure(&pm_config); +``` + +ESP32-S3 进入 Light Sleep 后，**I2C 控制器外设进入低功耗状态**，寄存器/锁可能丢失。唤醒后第一次 I2C 操作失败。 + +**修复（双保险）**： +1. `CanEnterSleepMode()` 加 `if (hibernating_.load()) return false`，让 PowerSaveTimer 不进入 sleep mode +2. EnterIdleHibernate 中 `esp_pm_configure(light_sleep_enable=false)` 强制覆盖 + +### 6.3 坑 3: hibernating_ 设置时序错误 + +**现象**：即使 `CanEnterSleepMode` 已加 hibernating 检查，hibernate 后仍有 Light Sleep 触发。 + +**根因**：EnterIdleHibernate 顺序如果是 +```cpp +SetDeviceState(kDeviceStateIdle); // 此时 device_state=idle，hibernating_=false + // → CanEnterSleepMode 返回 true + // → PowerSaveTimer 可能立即触发 Light Sleep +hibernating_.store(true); // 设置太晚 +``` + +**修复**：必须先设 `hibernating_=true`，再 `SetDeviceState(kDeviceStateIdle)`： +```cpp +hibernating_.store(true); // ✅ 先设标志 +esp_pm_configure(light_sleep=false); // ✅ 强制禁用 +SetDeviceState(kDeviceStateIdle); // ✅ 此时 CanEnterSleepMode 因 hibernating_ 返回 false +``` + +### 6.4 坑 4: dynamic_cast 在 -fno-rtti 下编译失败 + +**现象**： +``` +error: 'dynamic_cast' not permitted with '-fno-rtti' +auto* volc = dynamic_cast(protocol_.get()); +``` + +ESP-IDF 项目通常用 `-fno-rtti` 优化二进制大小，禁用 RTTI。 + +**修复**：在 `Protocol` 基类加虚函数： +```cpp +class Protocol { +public: + virtual void LeaveRoom() { CloseAudioChannel(); } +}; +``` +`VolcRtcProtocol::LeaveRoom() override` 实现 stop + destroy。Application 直接 `protocol_->LeaveRoom()` 多态调用。 + +### 6.5 坑 5: LeaveRoom 后 OpenAudioChannel 直接失败 + +**现象**：唤醒后日志 +``` +I (xxxxx) VolcRtcProtocol: 无法打开音频通道：RTC句柄未准备就绪 +``` + +**根因**：原 `OpenAudioChannel` 检查 `if (!rtc_handle_) return false` 直接返回。 + +**修复**：检测 NULL 时触发 `Start()` 异步重建并轮询： +```cpp +if (!rtc_handle_ && iot_ready_) { + iot_ready_ = false; + Start(); + int wait = 0; + while (!rtc_handle_ && wait < 50) { + vTaskDelay(pdMS_TO_TICKS(100)); + wait++; + } + if (!rtc_handle_) return false; +} +``` + +NVS 已缓存 `device_secret`，无需重新走 HTTP 设备注册，重建通常 100ms 完成。 + +### 6.6 坑 6: 字幕 LVGL 锁竞争超时 + +**现象**：日志显示 +``` +W (xxxxx) AI_CHAT_UI: LVGL锁超时，跳过字幕更新 +``` +字幕未显示。 + +**根因**：EnterIdleHibernate 中 `SetChatMessage` 立即调用，但 LeaveRoom 期间 LVGL 锁被 GIF 解码任务竞争，500ms 超时。 + +**修复**： +1. 字幕调用放在 hibernate 流程**最后**（LeaveRoom/codec/recorder 都完成后） +2. 5 次重试间隔 200ms（共 1 秒等待 LVGL 渲染完成） + +```cpp +for (int i = 0; i < 5; i++) { + vTaskDelay(pdMS_TO_TICKS(200)); + if (display) display->SetChatMessage("system", msg); +} +``` + +`ai_chat_set_chat_message` 内部有 `last_content` 去重缓存，锁超时时不更新缓存，下次重试相同内容仍会进入 lvgl_port_lock 路径，**重试有效**。 + +--- + +## 7. 移植到其他项目的最小改动清单 + +### 7.1 前置条件检查 + +| 检查项 | 是否满足 | +|--------|---------| +| 项目使用火山 RTC SDK (`volc_engine_rtc_lite`) | 必须 | +| Protocol / VolcRtcProtocol 类结构存在 | 必须 | +| `last_audible_output_time_` + Dialog Watchdog 机制存在 | 必须（如无则需新增） | +| Application 类有 `Schedule` 调度机制 | 必须 | +| 项目有 PowerSaveTimer | 影响坑 2 的修复方案 | +| Board 有 audio_codec / GetAudioCodec 接口 | 必须 | +| LVGL 锁机制（`lvgl_port_lock`） | 影响坑 6 的修复方案 | + +### 7.2 移植步骤（按顺序） + +1. **加 `LeaveRoom` 虚函数 + 实现** + - `protocol.h` 加 `virtual void LeaveRoom() { CloseAudioChannel(); }` + - `volc_rtc_protocol.h` 加 `void LeaveRoom() override;` + - `volc_rtc_protocol.cc` 实现 stop + destroy + +2. **`OpenAudioChannel` 加重建逻辑** + - 检测 `rtc_handle_=NULL && iot_ready_` 时触发 Start + 轮询 + +3. **Application 加 hibernate 状态** + - `hibernating_` (std::atomic) + - `idle_cycles_` + NVS 持久化函数 + +4. **`CanEnterSleepMode` 加 hibernating 检查** + +5. **新增 `EnterIdleHibernate` / `WakeFromHibernate` 方法** + - 严格按本文 §5.2 模板顺序 + +6. **方案 B + C 双源刷新** + - subtitle 分支加 1 行 + - conv_status 分支加 1 行 + +7. **Dialog Watchdog 触发动作改造** + - `esp_restart()` → `Schedule(EnterIdleHibernate)` + +8. **BOOT 按键回调加唤醒分支** + - `if (IsHibernating()) WakeFromHibernate()` 派发到独立 task + +9. **保留方案 A 用宏关闭**（不删源码） + - 顶部加 `// #define PHASE6_ENABLE_AUDIO_FALLBACK` + - 用 `#ifdef` 包裹 audio output 路径的 3 处 `last_audible_output_time_` 更新 + +### 7.3 项目无 PowerSaveTimer 的情况 + +如果目标项目没有 PowerSaveTimer： +- 坑 2 的 `CanEnterSleepMode` 检查可省略 +- 但仍建议保留 `esp_pm_configure(light_sleep=false)` 作为 ESP-IDF 全局保护 + +### 7.4 项目用 Modem Sleep（WiFi PSM）的情况 + +WiFi PSM 不影响 I2C 总线，可正常使用。 +但建议 hibernate 期间通过 `Board::SetPowerSaveMode(false)` 暂时禁用，避免 WiFi DTIM 与 RTC 重连冲突。 + +--- + +## 8. 时间对比与性能数据 + +### 8.1 唤醒时间分解（实测） + +| 阶段 | 硬重启退出 | 软退出 | 差异 | +|------|----------|--------|------| +| 设备启动（bootloader + 应用初始化） | 2-3s | 0s | ✅ -3s | +| WiFi 重连（NVS 凭据连接 AP） | **10-15s** ⭐ | 0s（保持连接） | ✅ **-15s** | +| RTC 实例创建（`volc_rtc_create`） | ~100ms | ~100ms | — | +| HTTP GetRTCConfig 获取 token | ~1-3s | ~1-3s | — | +| 加入房间（`byte_rtc_join_room`） | ~300ms | ~300ms | — | +| 远程 AI 加入（`bot_message`） | ~0.5-2s | ~0.5-2s | — | +| **总计** | **~15-25s** | **~3-5s** | **-80%** | + +### 8.2 资源消耗 + +| 指标 | 数值 | +|------|------| +| 方案 B 字幕监听 CPU 增量 | ~10ns/字幕 × 10/s = 100ns/s（**<0.001%**） | +| 方案 C 状态监听 CPU 增量 | ~10ns/事件 × 5/对话 ≈ 0 | +| hibernating_ 检查 CPU 增量 | 0（每次 PowerSaveCheck 1 次原子加载） | +| 内存增量 | hibernating_ (1B) + idle_cycles_ (4B) + last_content[256] = ~261B | +| NVS 增量 | namespace `hibernate` 1 个 int32 key | + +### 8.3 状态保留对比 + +| 状态 | 硬重启 | 软退出 | +|------|--------|--------| +| WiFi 凭据 | ✅ NVS 保留 | ✅ | +| 设备配置（音量/亮度等） | ✅ NVS 保留 | ✅ | +| 火山 RTC device_secret | ✅ NVS 缓存 | ✅ | +| RAM 中的对话历史 | ❌ 清空 | ✅ **保留** | +| LVGL UI 状态 | ❌ 重新加载 | ✅ **保留** | +| 数字人 GIF 解码缓存 | ❌ 重新加载 | ✅ **保留** | +| OTA 升级状态 | ✅ otadata 保留 | ✅ | + +--- + +## 9. 验证清单 + +### 9.1 功能验证 + +- [ ] 40s 无活动自动进入软休眠（字幕显示 + 屏幕保持） +- [ ] 用户说话 38s 不被踢出（方案 C LISTENING 触发） +- [ ] AI 长回答 50s 不被踢出（方案 B 字幕持续刷新） +- [ ] BOOT 按键唤醒 → 3-5s 内 RTC 重连完成 +- [ ] 唤醒后正常进行新一轮对话 +- [ ] 连续 5+ 次软休眠 + 唤醒循环无异常 + +### 9.2 异常验证 + +- [ ] 唤醒后无 `Fail to write/read` I2C 错误 +- [ ] 无 `abort() was called` panic +- [ ] 无 `进入低功耗模式：Light Sleep启用` 日志（hibernate 期间） +- [ ] 字幕"已自动退出RTC对话..."实际显示在屏幕上 +- [ ] NVS `hibernate/idle_cycles` 正确累计 + +### 9.3 边界验证 + +- [ ] WiFi 断开期间 BOOT 唤醒不崩溃（应留在 idle 状态） +- [ ] 软休眠期间 BLE 配网请求不冲突 +- [ ] 累计 idle_cycles_ ≥ 50 后下次 BOOT 唤醒触发硬重启 + +### 9.4 License 验证（可选） + +- [ ] 火山 RTC 控制台查看会话时长（确认软退出后不再计费） +- [ ] 用 `volc_rtc.c:475 message received` 日志统计字幕流是否完全停止 + +--- + +## 10. 火山 RTC SDK 关键 API 速查 + +### 10.1 客户端 SDK API（`components/common/inc/volc_rtc.h`） + +```c +typedef void* volc_rtc_t; + +// 创建 RTC 实例（应用启动时调用一次） +volc_rtc_t volc_rtc_create(const char* appid, void* context, + cJSON* p_config, + volc_msg_cb message_callback, + volc_data_cb data_callback); + +// 销毁 RTC 实例 = leaveRoom + destroyRTCEngine ← 真退房 + 释放 License +void volc_rtc_destroy(volc_rtc_t rtc); + +// 启动 AI 任务 + 加入房间（≈ 服务端 StartVoiceChat） +int volc_rtc_start(volc_rtc_t rtc, const char* bot_id, + volc_iot_info_t* iot_info, const char* extra_params); + +// 停止 AI 任务（≈ 服务端 StopVoiceChat，仅 AI 离开房间） +int volc_rtc_stop(volc_rtc_t rtc); + +// 发送数据 +int volc_rtc_send(volc_rtc_t rtc, const void* data, int size, volc_data_info_t* info); + +// 中断 AI 说话 +int volc_rtc_interrupt(volc_rtc_t rtc); +``` + +### 10.2 服务端 HTTP API + +| API | 用途 | 客户端是否必须配合 | +|-----|------|----------------| +| `StartVoiceChat` | 启动 AI 任务（运营/管理后台用） | volc_rtc_start 内部已调用 | +| `StopVoiceChat` | 停止 AI 任务（运营强制下线） | **客户端必须额外调 leaveRoom + destroyRTCEngine** | +| `UpdateVoiceChat` | 修改 AI 任务参数 | 不需要 | + +**结论**：设备端 idle 退出场景**只用客户端 SDK 即可**，无需调用服务端 HTTP API。客户端 destroy 后服务端 AI 任务在 180s 内自动清理。 + +### 10.3 消息类型分类 + +| 前缀 | 类型 | 应用层处理位置 | +|------|------|--------------| +| `subv` | 字幕消息（STT/TTS 内容） | `type=="subtitle"` 分支 | +| `ctrl` | 控制消息（含 conv_status） | `type=="conv_status"` 分支 | +| `tool` | 工具调用（function call） | `type=="response.function_call_arguments.done"` 分支 | +| `info` | 通用信息（status/error） | 通用 type 分发 | +| `conv` | 会话级消息 | 通用 type 分发 | + +--- + +## 附录 A: 配合修改的其他细节 + +### A.1 sleep_mgr 模块（如有） + +如果项目有独立的 `sleep_mgr.c`（如电子吧唧/玩具类项目）： +- AI 模式建议**完全不使用**它（其设计为吧唧/相册类应用场景） +- 用本文档的 hibernate 机制替代 + +### A.2 PowerSaveTimer.OnExitSleepMode 回调 + +如果项目 PowerSaveTimer 的 `OnExitSleepMode` 回调会重新打开 codec： +- 检查回调中是否有 `codec->EnableOutput(true)` +- 如有，hibernate 期间这个回调不应触发（因为 PowerSaveTimer 被 hibernating_ 阻止进入 sleep） +- 若仍误触发，加 `if (Application::IsHibernating()) return` 守卫 + +### A.3 OTA 与软休眠协同 + +软休眠期间收到 OTA 升级请求： +- 建议在 OTA 触发前先调用 `WakeFromHibernate()` +- 避免 OTA 期间 RTC 实例处于 destroyed 状态导致协议层混乱 + +### A.4 BLE 配网与软休眠协同 + +软休眠期间 BLE 配网请求： +- BLE 不受 hibernating_ 影响 +- 但配网完成后建议触发 `WakeFromHibernate()`（如果设备处于 hibernate） + +--- + +## 附录 B: 调试日志关键标记 + +实施后可通过 grep 这些日志验证流程： + +``` +✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine） # LeaveRoom 成功 +🌙 进入空闲休眠：真退房 → 字幕提示（不熄屏） # EnterIdleHibernate 入口 +🛡 累计休眠 N 次（阈值 50），下次唤醒触发硬重启 # 兜底机制即将触发 +☀ 从空闲休眠唤醒 # WakeFromHibernate 入口 +🔵 BOOT in hibernate → 唤醒 # BOOT 按键路径 +Phase 6: RTC 实例不存在，触发重建... # OpenAudioChannel 重建 +Phase 6: RTC 实例已重建（耗时 X ms） # 重建完成 +RTC远程用户加入 # AI 加入房间 +EnterIdleHibernate: 已强制禁用 Light Sleep（保护 I2C 总线） # 双保险生效 +🕒 conv_status=X 刷新对话活跃时间 # 方案 C 触发 +🕒 字幕刷新对话活跃时间（DEBUG 级别） # 方案 B 触发 +LVGL锁超时，跳过字幕更新 # 字幕重试机制提示 +``` + +--- + +## 附录 C: 与本项目的源码映射 + +| 本文档章节 | 源码位置 | +|----------|---------| +| §3.3 LeaveRoom | `main/protocols/volc_rtc_protocol.cc:409` | +| §3.4 OpenAudioChannel 重建 | `main/protocols/volc_rtc_protocol.cc:336` | +| §5.2.1 EnterIdleHibernate | `main/application.cc:4377` | +| §5.2.2 WakeFromHibernate | `main/application.cc:4440` | +| §5.2.3 CanEnterSleepMode | `main/application.cc:3595` | +| §5.2.4 Dialog Watchdog | `main/application.cc:2057` | +| §5.2.5 BOOT 唤醒 | `main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc:570` | +| 方案 B subtitle 刷新 | `main/application.cc:1300` | +| 方案 C conv_status 刷新 | `main/application.cc:1260` | +| 方案 A 宏 + ifdef 包裹 | `main/application.cc:45-48` + `application.cc:2221/2254/2266` | + +--- + +**文档版本**: v1.0 (2026-05-13) +**适用项目**: 任何基于火山 RTC SDK (`volc_engine_rtc_lite`) 的 ESP32 项目 +**实施参考**: 数字人 RTC 项目 Phase 6（`.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/`） diff --git a/docs/Rtc_AIavatar/数字人表情渲染方案_云端预渲染+BLE+OTA.md b/docs/Rtc_AIavatar/数字人表情渲染方案_云端预渲染+BLE+OTA.md index c7c44fe..e20daec 100644 --- a/docs/Rtc_AIavatar/数字人表情渲染方案_云端预渲染+BLE+OTA.md +++ b/docs/Rtc_AIavatar/数字人表情渲染方案_云端预渲染+BLE+OTA.md @@ -2514,6 +2514,210 @@ lvgl_port_unlock(); --- +## 十九、RTC 空闲倒计时方案选型与软退出机制（Phase 6 实施记录） + +> 数字人 RTC 项目 Phase 6 实施。本章节回答两个核心问题： +> 1. **何时倒计时刷新**（监听什么事件？） +> 2. **超时后如何退出 RTC**（释放 License 又快速恢复？） + +### 19.1 三个倒计时刷新方案对比 + +火山 RTC 协议层向应用层暴露 3 类消息事件，对应 3 种倒计时刷新方案： + +| 方案 | 监听源 | 触发频率 | CPU 消耗 | 优势 | 弊端 | +|------|--------|---------|---------|------|------| +| **A 扬声器音频流** | I2S DMA / Opus PCM 输出 | 每 20ms（50Hz） | 中（每秒 50 次时间戳更新） | 已实现零改动；AI 持续说话期间持续刷新 | 不监听用户说话；用户开始说话 → AI 还在思考时倒计时无刷新 | +| **B 字幕监听 (subtitle)** | RTC `subtitle` 消息 | 每秒 5-15 次（流式 ASR/TTS） | 极低（10ns/字幕） | 火山官方推荐；用户 STT 字幕 + AI 流式 TTS 都覆盖 | 流式中间结果重复（已通过去重缓解） | +| **C 智能体状态 (conv_status)** | RTC `conv_status` 状态机消息 | 每轮对话 4-5 次状态切换 | 最低（10ns/事件） | 事件级最早触发（用户开始说话立即 LISTENING）；状态语义清晰 | AI 长说话期间 ANSWERING 状态稳定不切换 → 不刷新 | + +### 19.2 方案选型决策（B + C 双源） + +**业务需求**： +- 用户说话 → 重置（用户在交互） +- AI 思考 → 重置（用户已发起对话） +- AI 回复 → 重置（对话进行中） +- 真正静默 → 倒计时（用户无交互） + +**单方案缺陷**： +- 单用 A：用户说话期间无刷新 → 第 38s 说话被踢出 +- 单用 C：AI 长说话期间无刷新 → AI 朗读 40s 故事被踢出 +- 单用 B：理论可行但重复刷新多 + +**最终方案**：**B + C 双源**（不启用 A，节省 CPU）： +- C 覆盖状态切换（LISTENING/THINKING/ANSWERING/INTERRUPTED/ANSWER_FINISH） +- B 覆盖 AI 持续说话期间的流式字幕 +- A 用 `#ifdef PHASE6_ENABLE_AUDIO_FALLBACK` 关闭（保留代码可恢复） + +实施位置（`main/application.cc`）： + +```cpp +// conv_status 分支（方案 C） +} else if (strcmp(type->valuestring, "conv_status") == 0) { + auto status_val = cJSON_GetObjectItem(root, "status"); + if (status_val) { + last_audible_output_time_ = std::chrono::steady_clock::now(); // 方案 C + int conv_status = status_val->valueint; + ESP_LOGI(TAG, "🕒 conv_status=%d 刷新对话活跃时间", conv_status); + // ... 原有 emoji 切换 + } +} + +// subtitle 分支（方案 B） +} else if (strcmp(type->valuestring, "subtitle") == 0) { + auto data_arr = cJSON_GetObjectItem(root, "data"); + if (data_arr && cJSON_IsArray(data_arr) && cJSON_GetArraySize(data_arr) > 0) { + last_audible_output_time_ = std::chrono::steady_clock::now(); // 方案 B + // ... 原有字幕解析 + } +} +``` + +### 19.3 软退出 RTC 机制 + +#### 19.3.1 旧方案（硬重启退出） + +``` +40s 无活动 → 写 NVS reboot_dlg_idle=1 → esp_restart() + ↓ +重启 → 读 NVS → 跳过开机播报 → 重新走完整初始化（WiFi + RTC） +总耗时 15-25s 不可用（黑屏 + 重连） +``` + +**问题**：用户体验差、屏幕黑屏长达 20s、NVS/RAM 状态丢失。 + +#### 19.3.2 新方案（软退出 RTC + 屏幕保持 + BOOT 唤醒） + +``` +40s 无活动 → Application::EnterIdleHibernate() + ↓ +1. protocol_->LeaveRoom() ← volc_rtc_stop + volc_rtc_destroy（真退房+释放 License） +2. codec->EnableInput/Output(false)（重置 codec 状态机） +3. recorder_pipeline_close（释放录音管道） +4. hibernating_=true（阻止 PowerSaveTimer 进入 Light Sleep） +5. esp_pm_configure(light_sleep=false)（双保险防止 I2C 进入低功耗） +6. SetDeviceState(kDeviceStateIdle) +7. 屏幕字幕："已自动退出RTC对话，按BOOT键重新连接RTC"（不熄屏） +8. NVS 持久化 idle_cycles_++ + +BOOT 按键 → Application::WakeFromHibernate() + ↓ +1. 累计 50 次 → 硬重启清理碎片（兜底） +2. 清空字幕 +3. ToggleChatState() → OpenAudioChannel +4. OpenAudioChannel 检测 rtc_handle_=NULL → 触发 Start() 重建 +5. volc_rtc_create + volc_rtc_start → 加入新房间 +总耗时 ~3-5 秒（无 WiFi 重连，仅 RTC 重建 + HTTP token） +``` + +### 19.4 关键 SDK API 理解 + +| API | 作用 | 释放 License? | +|-----|------|-------------| +| `volc_rtc_stop(rtc)` | ≈ 服务端 StopVoiceChat（仅 AI 任务停止） | ❌ 真人仍在房间继续计费 | +| **`volc_rtc_destroy(rtc)`** | **= leaveRoom + destroyRTCEngine（真人离开+销毁实例）** | ✅ **真退房** | +| StopVoiceChat HTTP API | 服务端运营接口 | ⚠️ 仅 AI 离开，需配合客户端 leaveRoom | + +火山官方文档明确："**完整结束通话客户端必须 leaveRoom + destroyRTCEngine**"。 +`CloseAudioChannel()` 当前只调 stop 不够，新增 `LeaveRoom()` 调用 stop + destroy。 + +### 19.5 火山 RTC `conv_status` 5 状态机 + +| status 值 | 含义 | 触发时机 | +|----------|------|---------| +| 1 LISTENING | 用户说话 / AI 听 | 用户开始说话即时触发 | +| 2 THINKING | AI 思考 | ASR 完成、LLM 推理中 | +| 3 ANSWERING | AI 回答 | TTS 开始 | +| 4 INTERRUPTED | 被打断 | 用户打断 AI | +| 5 ANSWER_FINISH | AI 说完 | TTS 结束 | + +应用层在 `application.cc:1260+` 已有 emoji 切换映射，Phase 6 复用此分支加入时间戳刷新。 + +### 19.6 时间对比 + +| 指标 | 硬重启退出 | **软退出（Phase 6）** | +|------|----------|------------------| +| 设备启动 | 2-3s | 0s | +| WiFi 重连 | 10-15s ⭐ | 0s（保持连接） | +| RTC 实例创建 | ~100ms | ~100ms | +| HTTP GetRTCConfig | ~1-3s | ~1-3s | +| 加入房间 | ~300ms | ~300ms | +| 远程 AI 加入 | ~0.5-2s | ~0.5-2s | +| **总计** | **~15-25s** | **~3-5s** | +| **屏幕表现** | 黑屏 20s | 字幕提示常亮 | +| **NVS/RAM 状态** | 清空 | 保留 | +| **License 释放** | ✅ | ✅ | + +软退出**节省 80% 唤醒时间**，最大头来自不用 WiFi 重连。 + +### 19.7 关键踩坑修复 + +#### 坑 1: codec 状态机不重置 → 唤醒后 I2C 失败 abort + +**现象**：BOOT 唤醒后 `Adev_Codec: Input already open` + `Fail to write to dev 30` → ESP_ERROR_CHECK abort 重启。 + +**修复**：EnterIdleHibernate 中显式 `codec->EnableInput(false); codec->EnableOutput(false);` 重置状态机，让唤醒走完整 `esp_codec_dev_open` 路径。 + +#### 坑 2: PowerSaveTimer Light Sleep 干扰 I2C + +**现象**：hibernate 期间 PowerSaveTimer 10s 后触发 `esp_pm_configure(light_sleep=true)` → ESP32-S3 进入 Light Sleep → I2C 控制器外设进入低功耗 → 唤醒后 ES7210/ES8311 通信失败。 + +**修复**： +1. `CanEnterSleepMode()` 加 `if (hibernating_.load()) return false` +2. EnterIdleHibernate 中 `esp_pm_configure(light_sleep_enable=false)` 双保险 +3. `hibernating_.store(true)` 必须在 `SetDeviceState(kDeviceStateIdle)` **之前**（避免 idle 状态下 PowerSaveCheck 立即触发） + +#### 坑 3: dynamic_cast 在 -fno-rtti 下编译失败 + +**现象**：`error: 'dynamic_cast' not permitted with '-fno-rtti'` + +**修复**：在 `Protocol` 基类加 `virtual void LeaveRoom() { CloseAudioChannel(); }`，`VolcRtcProtocol` override。Application 直接 `protocol_->LeaveRoom()` 多态调用。 + +#### 坑 4: LeaveRoom 后 rtc_handle_=NULL 无法再 OpenAudioChannel + +**现象**：唤醒后 OpenAudioChannel 检查 `if (!rtc_handle_) return false` 直接失败。 + +**修复**：OpenAudioChannel 头部加重建逻辑——检测 `rtc_handle_=NULL && iot_ready_` 时触发 `Start()` 异步重建，轮询 5s 等 `rtc_handle_` 就绪。 + +#### 坑 5: 字幕 LVGL 锁竞争 → SetChatMessage 跳过 + +**现象**：EnterIdleHibernate 中 SetChatMessage 在 LeaveRoom 之后立即调用，LVGL 锁被 GIF 解码竞争，500ms 超时 → 字幕未显示。 + +**修复**： +1. 字幕调用推迟到 hibernate 流程**最后**（LeaveRoom/codec/recorder 都完成后） +2. 调用 5 次重试（每次间隔 200ms 让 LVGL 渲染完成） +3. ai_chat_set_chat_message 已有 last_content 去重缓存，重试不重复加载相同内容 + +### 19.8 内存兜底（防止长期运行碎片化） + +```cpp +static constexpr int IDLE_CYCLES_REBOOT_THRESHOLD = 50; + +// EnterIdleHibernate 中累计 +idle_cycles_++; +SaveIdleCyclesToNvs(); + +// WakeFromHibernate 中检查 +if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ResetIdleCyclesNvs(); + esp_restart(); // 累计 50 次软退出后下次唤醒触发硬重启清理碎片 +} +``` + +50 次按平均每次 5 分钟对话计算约覆盖 4 小时使用时长，防御 RTC 库长期运行的内存累积。NVS 持久化保证重启后保留计数。 + +### 19.9 实测验证（两次连续休眠唤醒） + +| 阶段 | 时序 | +|------|------| +| 第 1 次循环 | 106s 进入 → 130s 唤醒，RTC 加入耗时 3s | +| 第 2 次循环 | 219s 进入 → 267s 唤醒，RTC 加入耗时 2s | + +**未出现**：abort / I2C 失败 / Light Sleep / NVS 数据丢失。 + +详见 `.planning/milestones/digital_human_rtc/phases/phase_06_idle_hibernate/`。 + +--- + ## 附录 B：与文档 v5.1 的映射 | 文档 v5.1 章节 | 本方案对应 | diff --git a/docs/Rtc_AIavatar/音频卡顿_全局资源分析.md b/docs/Rtc_AIavatar/音频卡顿_全局资源分析.md new file mode 100644 index 0000000..15a2b87 --- /dev/null +++ b/docs/Rtc_AIavatar/音频卡顿_全局资源分析.md @@ -0,0 +1,351 @@ +# 音频卡顿全局资源分析与优化建议（只分析不改代码） + +> 范围: 开机本地音效卡顿 + AI 对话扬声器播放卡顿 +> 方法: 从 CPU/PSRAM/任务调度全局画像出发，定位卡顿根因 +> 输出: 高/中/低 ROI 优化建议清单（按工作量排序） + +## 1. 当前资源画像 + +### 1.1 硬件配置 + +| 资源 | 规格 | +|------|------| +| CPU | ESP32-S3 双核 Xtensa LX7 @ **240 MHz** | +| 内部 SRAM | 512 KB | +| PSRAM | 8 MB **QSPI @ 80 MHz**（`CONFIG_SPIRAM_MODE_QUAD=y` / `SPIRAM_SPEED_80M=y`） | +| LCD | ST77916 QSPI 80MHz / 360×360 RGB565 | +| Codec | ES8311（输出）+ ES7210（输入）@ I2C / I2S | +| FreeRTOS | tick @ 100 Hz | + +### 1.2 任务分布与 Core 绑定 + +| 任务名 | Core | 优先级 | 来源 | +|--------|------|--------|------| +| `audio_loop` | **Core 1（强制）** | 8 | `application.cc:639` | +| `main_loop` | **Core 0（强制）** | 4 | `application.cc:646` | +| `lvgl_task` | **任意（实际倾向 Core 0）** | 3 | `lvgl_port_init` task_affinity=-1 | +| `background_task` | 任意 | **2（低）** | `background_task.cc:12` | +| `dialog_watchdog` | Core 0（pinned） | 5 | `application.cc:2036` | +| `volc_rtc_init` | 任意 | 5 | `volc_rtc_protocol.cc:181` | +| `wake_hib` (Phase 6) | 任意 | 5 | BOOT 唤醒派发 | + +### 1.3 关键定时器频率 + +| 定时器 | 频率 | 来源 | +|--------|------|------| +| LVGL refresh | **5ms (200 Hz)** | `lvgl_port_init.task_max_sleep_ms = 500, timer_period_ms = 5` | +| GIF 解码 | **20ms (50 Hz)** | `lv_timer_set_period(gifobj->timer, 20)` | +| Dialog watchdog | 2s | `application.cc:2033 vTaskDelay(2000)` | +| Battery/HTTP report | ~3s | `WifiBoard` | + +## 2. 卡顿根因分析（按影响排序） + +### 2.1 根因 1: PSRAM 80MHz QSPI 带宽竞争 ⭐⭐⭐（最主要） + +**理论带宽**：QSPI 80MHz 单线传输 ≈ **40 MB/s 单向**（读+写共享）。 +**实际带宽**：因协议开销 + cache miss + 总线竞争 ≈ **20-30 MB/s 可用**。 + +**PSRAM 客户端列表**（按访问频率）： + +| 客户端 | 频率 | 单次大小 | 累计带宽 | +|--------|------|---------|---------| +| LVGL 帧缓冲（双 buf or 部分屏幕刷新） | 200 Hz | 14.4 KB（20 行 × 360 × 2B） | ~2.9 MB/s | +| GIF 解码（LZW → RGB565） | 50 Hz | ~30 KB/帧（209×360×2） | ~1.5 MB/s | +| 背景图（常驻 PSRAM 只读） | 0 | 253 KB | 0（缓存） | +| Opus 解码缓冲（AI 说话） | 50 Hz（每 20ms 一帧） | ~1280 B/帧 | ~64 KB/s | +| I2S DMA descriptor + buffer | 持续 | KB 级 | ~32-128 KB/s | +| WiFi RX/TX 缓冲（部分在 PSRAM） | 突发 | 1-2 KB | 变化 | +| RTC 协议层缓冲 | 突发 | KB 级 | 变化 | +| 字幕渲染（中文字体glyph）| 字幕更新时 | KB 级 | 突发 | +| **合计稳态** | — | — | **~5-6 MB/s** | +| **合计突发峰值** | — | — | **~15-20 MB/s** | + +**问题**： +- PSRAM 同一时刻只能服务一个 client（QSPI 是串行总线） +- 突发期（AI 说话 + GIF 切换 + 字幕更新）接近带宽上限 +- 任何 client 等待都会增加延迟，**音频解码对延迟敏感**（I2S DMA 缓冲消耗完前必须填新数据） + +### 2.2 根因 2: AudioLoop 死循环占满 Core 1 ⭐⭐ + +```cpp +// application.cc 中 audio_loop 任务 +void Application::AudioLoop() { + auto codec = Board::GetInstance().GetAudioCodec(); + while (true) { + OnAudioInput(); + if (codec->output_enabled()) { + OnAudioOutput(); + } + } +} +``` + +**问题**： +- **没有 `vTaskDelay`** → busy loop +- Core 1 上 idle task 几乎不运行 +- FreeRTOS watchdog 警告（"task watchdog got triggered"）只是因为 priority 8 高，会导致其他 Core 1 任务（如 WiFi/BLE 协议栈如果在 Core 1）饥饿 + +**影响**： +- Core 1 100% 占用 +- WiFi RX 中断处理可能被延迟（导致 RTC 包丢失重传） +- Opus 解码（在 background_task）可能在 Core 0 也可能在 Core 1，分配不确定 + +### 2.3 根因 3: LVGL/GIF 占用 Core 0 与 main_loop 竞争 ⭐⭐ + +**Core 0 任务**： +- main_loop（priority 4，处理 Schedule lambda 队列） +- lvgl_task（priority 3，affinity=-1 但调度器偏向 Core 0） +- dialog_watchdog（pinned Core 0） +- background_task（priority 2，任意 Core） + +**当 AI 说话时**： +- 字幕到达 → Schedule lambda 入队 +- conv_status 到达 → Schedule lambda 入队 +- 情绪映射 → Schedule lambda 入队（switch GIF） +- GIF 切换 → bg_gif_demo_switch_gif → PSRAM 释放/分配 → LVGL set_src +- LVGL 渲染新帧 +- 同时 background_task 在解码 Opus + +**Core 0 工作量**：5 类任务串行竞争。 + +### 2.4 根因 4: GIF 解码 PSRAM 写入与 I2S DMA 抢同一 PSRAM 总线 ⭐⭐ + +GIF 解码（gifdec）： +- 每 20ms 一次 LZW 解码 +- 解码输出写入 PSRAM 帧缓冲（~30KB） +- LVGL 然后从 PSRAM 读取送到 LCD + +I2S DMA 输出： +- I2S DMA descriptor 链表在 internal SRAM +- 但 PCM 数据 buffer 可能在 PSRAM（`heap_caps_malloc(MALLOC_CAP_SPIRAM)`） +- DMA 突发读 PSRAM → 与 GIF 解码写 PSRAM 竞争 + +**当 PSRAM 总线繁忙时**： +- DMA 等待 PSRAM 总线空闲 +- I2S 缓冲（通常几 KB）消耗完前未填新数据 → 输出断流 → 听觉上的卡顿/爆音 + +### 2.5 根因 5: 开机阶段 PSRAM 写入风暴 ⭐⭐⭐（开机音效卡顿） + +开机时序： +``` +T=0~0.7s: LCD 初始化（少量 PSRAM 写） +T=0.7~2s: bg_gif_demo_start + ├─ esp_jpeg 解码 360×360 JPG → PSRAM 写入 253 KB + └─ hiyori_m06.gif 加载到 PSRAM ~440 KB +T=2~3s: AI 对话屏幕初始化（字幕容器等 LVGL 对象） +T=3s: codec 初始化（I2C 通信） +T=15s+: WiFi 连接成功后 → 播放开机音效（PlaySound P3_LALA_KAIJIBOBAO） + ├─ 读 Flash 中的 P3 数据 + ├─ Opus 解码到 PSRAM PCM buffer + └─ I2S DMA 输出 +``` + +**问题点**： +- 开机音效播放时 LCD/LVGL 还在做 GIF 解码（每 20ms）+ 字幕渲染 +- PSRAM 同时被 GIF 解码、LVGL 帧缓冲、Opus PCM 缓冲、I2S DMA 缓冲争用 +- 第一次冷启动 codec 状态也可能不稳（Phase 1 期间日志中的 "Fail to write to dev 30"） + +### 2.6 根因 6: 字幕高频更新触发 LVGL 全屏重绘 ⭐ + +AI 说话时字幕推送频率高（**81 次 / 30s 实测**）： +- 每条字幕到达 → display->SetChatMessage → lv_label_set_text +- lv_label_set_text **可能触发 chat_label 所在区域重绘** +- 字幕区域 320×56 = 17920 像素 → PSRAM 写入 36 KB + +如果字幕频率 5-15 次/s × 36 KB = **180-540 KB/s 额外 PSRAM 流量**。 + +Phase 5 优化（锁外去重 + 500ms 锁）已减少部分压力，但 LVGL 内部重绘逻辑仍消耗带宽。 + +## 3. 优化建议清单（按 ROI 排序） + +### 3.1 高 ROI（修改简单 + 效果显著） + +#### ★ 建议 1: AudioLoop 加 `vTaskDelay(1)` 让出 Core 1 idle + +```cpp +void Application::AudioLoop() { + auto codec = Board::GetInstance().GetAudioCodec(); + while (true) { + OnAudioInput(); + if (codec->output_enabled()) { + OnAudioOutput(); + } + vTaskDelay(1); // 让出 idle，10ms（FreeRTOS 100Hz tick） + } +} +``` + +**效果**：Core 1 不再 100% 占用，idle task 跑得动，watchdog 喂得到。WiFi 中断/RTC 协议栈不被饥饿。 +**风险**：音频处理频率从 ~每帧立即 改为 10ms 一次。但 OnAudioOutput 内部本身是处理一个完整 PCM 帧（20ms），10ms 调度间隔够。 + +#### ★ 建议 2: GIF 解码降频 20ms → 33ms（30 Hz） + +```cpp +// ai_chat_ui.c 等位置 +lv_timer_set_period(gifobj->timer, 33); // 20ms → 33ms +``` + +**效果**：GIF 解码 CPU 占用减半，PSRAM 写入流量减半（~1.5 MB/s → 0.75 MB/s）。 +**视觉影响**：人眼 30 FPS 完全可接受（电影 24 FPS）。 + +#### ★ 建议 3: LVGL refresh 降频 5ms → 16ms + +```c +// lcd.c 中 lvgl_port_init 配置 +lvgl_cfg.timer_period_ms = 16; // 5ms → 16ms (60Hz) +``` + +**效果**：LVGL 任务 CPU 占用减少 60%，PSRAM 读写减少（~2.9 MB/s → 0.9 MB/s）。 +**视觉影响**：60 FPS LCD 刷新，肉眼无差异。GIF 仍是 30Hz。 + +#### ★ 建议 4: background_task 优先级 2 → 5 + +```cpp +// background_task.cc:12 +xTaskCreate(..., stack_size, this, 5, &background_task_handle_); + ↑ + 2 改为 5 +``` + +**效果**：AI Opus 解码不会被 main_loop（pri 4）延迟。 +**风险**：低，原 priority 2 太保守。 + +#### ★ 建议 5: 字幕去重升级 — 流式中间结果合并 + +当前 `ai_chat_set_chat_message` 锁外去重检查完整 256 字符 strncmp，相同内容跳过。 +建议：增加节流（debounce）逻辑： + +```cpp +static int64_t last_update_us = 0; +const int64_t MIN_INTERVAL_US = 100000; // 100ms 最小更新间隔 +int64_t now_us = esp_timer_get_time(); +if (now_us - last_update_us < MIN_INTERVAL_US) return; +last_update_us = now_us; +``` + +**效果**：流式中间结果每 100ms 最多 1 次更新，PSRAM 写入减少 5-10 倍。 + +### 3.2 中 ROI（修改稍多 + 效果中等） + +#### 建议 6: I2S PCM 缓冲移到 internal SRAM + +I2S DMA 读取 PCM 数据时若 buffer 在 PSRAM，DMA 突发与其他 PSRAM 客户端争用。 +改为 `heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`，让 DMA 读 internal SRAM（带宽 ~1 GB/s 远大于 PSRAM）。 + +**效果**：音频 DMA 完全不受 PSRAM 拥堵影响。 +**代价**：512KB internal SRAM 已经紧张（LVGL .bss + 协议栈 + 堆），可能挤占其他模块。建议先用 `heap_caps_get_free_size(MALLOC_CAP_INTERNAL)` 看余量。 + +#### 建议 7: Schedule lambda 队列流控 + +main_loop 处理 Schedule lambda 是串行的。AI 说话期间 lambda 可能积压： +- conv_status × N +- subtitle × M +- emotion 切换 × K +- 字幕 set_chat_message × L + +可加队列长度警告日志，超过 20 时合并/丢弃中间状态。 + +#### 建议 8: GIF 切换防抖 + +22 情绪 → 3 GIF 已映射，但 `ai_chat_set_emotion` 仍每次 conv_status 调用一次。 +建议加 200ms 防抖：100ms 内同一情绪只切一次 GIF。 + +#### 建议 9: 开机音效预加载到 internal SRAM + +P3 音效解码到 internal SRAM PCM 数组，开机时直接送 DMA： +- 避免开机 PSRAM 风暴期间 Opus 解码与 GIF 解码竞争 + +代价：P3 数据展开后约几十 KB / 个，预加载占内部 SRAM。 + +### 3.3 低 ROI（修改大或效果有限） + +#### 建议 10: PSRAM 升级到 Octal SPI + +ESP32-S3 支持 OPI PSRAM（CONFIG_SPIRAM_MODE_OCT）80MHz Octal → 带宽 ~80 MB/s 翻倍。 +**前提**：硬件 PSRAM 芯片支持 OPI（ESP32-S3-N16R8 通常是 QPI，不支持 OPI）。需要 N16R8V（OPI 版）。 + +#### 建议 11: LVGL 双缓冲改单缓冲 + +减少一份帧缓冲 PSRAM 占用，但会引入撕裂。不建议（视觉问题更糟）。 + +#### 建议 12: 关闭部分协议层日志 + +`volc_rtc.c` 等大量日志 `[INF|volc_rtc.c:475]message received...` 占用 UART 输出。每次日志 1-2ms。 +设置 `CONFIG_LOG_DEFAULT_LEVEL_WARN` 关闭 INFO，省一些 CPU。 + +#### 建议 13: 关闭 PowerSaveTimer 的 Light Sleep（Phase 6 已部分做） + +Phase 6 hibernate 期间已关。但**对话期间** PowerSaveTimer 仍可能在 idle 状态触发 Light Sleep，可考虑彻底关闭（不省那点电耗）。 + +## 4. 推荐实施顺序 + +**第一轮（5 分钟改 5 行代码）**： +1. AudioLoop 加 `vTaskDelay(1)` → 立竿见影 +2. background_task 优先级 2 → 5 +3. GIF 定时器 20ms → 33ms +4. LVGL refresh 5ms → 16ms +5. 字幕节流 100ms 最小间隔 + +**预期效果**：开机音效和 AI 语音卡顿消失 80%。 + +**第二轮（如果第一轮不够）**： +6. I2S PCM 缓冲改 internal SRAM +7. GIF 切换防抖 200ms +8. Schedule lambda 队列流控 + +**第三轮（追求极致）**： +9. P3 音效预加载 +10. 关闭部分协议日志 + +## 5. 测量方法（可选实施） + +### 5.1 CPU 占用监控 + +```cpp +// 添加每 5 秒打印一次 +TaskStatus_t task_status[20]; +UBaseType_t task_count = uxTaskGetSystemState(task_status, 20, NULL); +for (int i = 0; i < task_count; i++) { + ESP_LOGI(TAG, "Task %s: priority=%d, runtime=%lu", + task_status[i].pcTaskName, + task_status[i].uxCurrentPriority, + task_status[i].ulRunTimeCounter); +} +``` + +需要 `CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y`。 + +### 5.2 PSRAM 带宽监控 + +```cpp +// 通过 heap_caps_get_largest_free_block 监控碎片化 +size_t spiram_free = heap_caps_get_free_size(MALLOC_CAP_SPIRAM); +size_t spiram_max_block = heap_caps_get_largest_free_block(MALLOC_CAP_SPIRAM); +ESP_LOGI(TAG, "PSRAM: free=%zu, largest_block=%zu, fragmentation=%.1f%%", + spiram_free, spiram_max_block, + (1.0 - (double)spiram_max_block / spiram_free) * 100); +``` + +### 5.3 音频卡顿量化 + +I2S DMA 缓冲 underrun 计数（如果驱动暴露）。 +或者在 OnAudioOutput 中记录每帧实际写入耗时，> 20ms 警告。 + +## 6. 结论 + +**卡顿根因（按贡献排序）**： +1. PSRAM 80MHz QSPI 带宽 ~20-30 MB/s，多客户端竞争（GIF 解码 + LVGL + Opus + 字幕） +2. AudioLoop busy loop 占满 Core 1 +3. LVGL/GIF 在 Core 0 与 main_loop 竞争 +4. GIF 解码与 I2S DMA 抢 PSRAM 总线 +5. 开机阶段 PSRAM 写入风暴 +6. 字幕高频更新触发 LVGL 重绘 + +**优化策略**：**降低 CPU 时间片冲突 + 减少 PSRAM 流量** + +**第一轮 5 行代码改动可见效**（详见 §4 推荐实施顺序）。 + +**不建议立即修改的方向**： +- ❌ 升级 OPI PSRAM（需要换硬件 SKU） +- ❌ 改 LVGL 双缓冲为单缓冲（视觉撕裂更糟） +- ❌ 完全重写音频任务模型（工作量大风险高） diff --git a/main/application.cc b/main/application.cc index 32edf24..f2508f5 100644 --- a/main/application.cc +++ b/main/application.cc @@ -27,6 +27,7 @@ #include #include #include +#include #include #include #include @@ -43,6 +44,11 @@ extern "C" void ai_chat_resume_animation(void); // 设备空闲无对话状态 倒计时 #define DIALOG_IDLE_COUNTDOWN_SECONDS 40 +// Phase 6: 方案 C（conv_status 状态机刷新）单独使用，关闭方案 A（扬声器流刷新） +// 节省 CPU（方案 A 每 20ms 一帧 PCM 都更新时间戳）。 +// 取消注释下行宏可恢复方案 A 作为兜底（双源刷新）。 +// #define PHASE6_ENABLE_AUDIO_FALLBACK + // 定义设备状态字符串 static const char* const STATE_STRINGS[] = { @@ -74,6 +80,7 @@ Application::Application() { #endif last_audible_output_time_ = std::chrono::steady_clock::now(); // 初始化最后一次有声音输出的时间点 skip_dialog_idle_session_ = false; // 初始化跳过对话待机会话标志为false + LoadIdleCyclesFromNvs(); // Phase 6: 从 NVS 加载累计休眠次数（用于内存碎片兜底） dialog_watchdog_running_ = false; // 初始化对话看门狗运行标志 dialog_watchdog_last_logged_ = -1; // 初始化对话看门狗日志记录 dialog_watchdog_task_handle_ = nullptr; // 初始化对话看门狗任务句柄 @@ -1261,7 +1268,11 @@ void Application::Start() { // RTC 会话状态 → emoji 切换 auto status_val = cJSON_GetObjectItem(root, "status"); if (status_val) { + // Phase 6 方案 C: conv_status 状态切换刷新对话活跃时间 + // 比扬声器音频流更早（事件级），修复"用户开始说话就被踢"边界 bug + last_audible_output_time_ = std::chrono::steady_clock::now(); int conv_status = status_val->valueint; + ESP_LOGI(TAG, "🕒 conv_status=%d 刷新对话活跃时间", conv_status); Schedule([this, display, conv_status]() { switch (conv_status) { case 1: // LISTENING @@ -1290,6 +1301,12 @@ void Application::Start() { } else if (strcmp(type->valuestring, "subtitle") == 0) { // 火山 RTC 字幕消息：data 数组中包含 text、userId、definite auto data_arr = cJSON_GetObjectItem(root, "data"); + if (data_arr && cJSON_IsArray(data_arr) && cJSON_GetArraySize(data_arr) > 0) { + // Phase 6 方案 B: 收到有效字幕（user STT 或 AI 流式 TTS）→ 刷新对话活跃时间 + // 覆盖 AI 持续说话期间 conv_status 不切换的边界场景 + last_audible_output_time_ = std::chrono::steady_clock::now(); + ESP_LOGD(TAG, "🕒 字幕刷新对话活跃时间"); + } if (data_arr && cJSON_IsArray(data_arr)) { for (int i = 0; i < cJSON_GetArraySize(data_arr); ++i) { auto item = cJSON_GetArrayItem(data_arr, i); @@ -2043,28 +2060,15 @@ void Application::StartDialogWatchdog() { // 调试日志 ESP_LOGD(TAG, "Dialog watchdog: elapsed=%d, remaining=%d", (int)elapsed, remaining); - // 如果剩余秒数小于等于0，说明对话空闲倒计时已到，需要重启设备 + // 如果剩余秒数小于等于0，说明对话空闲倒计时已到 → 进入空闲休眠（软退房+熄屏） if (remaining <= 0) { - ESP_LOGI(TAG, "Dialog watchdog idle reached, elapsed=%d, marking and rebooting", (int)elapsed); - Settings sys("system", true); - ESP_LOGI(TAG, "Dialog watchdog: preparing NVS writes (system)"); - sys.SetInt("reboot_dlg_idle", 1); - sys.SetInt("reboot_origin", 1); - ESP_LOGI(TAG, "Dialog watchdog: committing NVS (system)"); - sys.Commit(); - Settings sysr("system"); - int32_t verify = sysr.GetInt("reboot_dlg_idle", 0); - int32_t origin_read = sysr.GetInt("reboot_origin", 0); - if (verify != 1) { - ESP_LOGW(TAG, "Dialog watchdog: NVS verify failed, cause=%d, origin=%d", (int)verify, (int)origin_read); - ESP_LOGW(TAG, "建议: 检查NVS空间是否不足、确认nvs_flash_init成功、避免并发写入(system)"); - } - ESP_LOGI(TAG, "Dialog watchdog (task) set reboot_cause=1, verify=%d, restart in 2000ms", (int)verify); - // 重启前上报设备离线状态 - Board::GetInstance().OnBeforeRestart(); - vTaskDelay(pdMS_TO_TICKS(2000)); - esp_restart();// 重启设备 - app->dialog_watchdog_running_ = false;// 设置看门狗运行标志为false + ESP_LOGI(TAG, "Dialog watchdog 触发：%ds 无对话活动 → 进入空闲休眠", (int)elapsed); + app->dialog_watchdog_running_ = false; // 停止 watchdog 循环 + // Schedule 在主线程执行 EnterIdleHibernate，避免在 watchdog task 里阻塞 3 秒字幕显示 + app->Schedule([app]() { + app->EnterIdleHibernate(); + }); + break; // 退出 watchdog 循环（while/for 取决于 task 结构） } else { // 简化条件判断，移除冗余检查 // 优化桶计算逻辑，使用1秒一个桶，更精确地显示倒计时 @@ -2208,10 +2212,14 @@ void Application::OnAudioOutput() { // 当有可听见的音频输出时，更新最后声音输出时间戳 const float audible_volume_threshold = 0.01f; // 设置一个合理的音量阈值 + (void)audible_volume_threshold; // Phase 6: 默认关闭方案 A 时未使用 +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK + // Phase 6 方案 A 兜底（默认关闭，定义 PHASE6_ENABLE_AUDIO_FALLBACK 启用） if (rms_volume >= audible_volume_threshold) { this->last_audible_output_time_ = std::chrono::steady_clock::now(); ESP_LOGD(TAG, "🔊 更新last_audible_output_time_，当前音量: %.4f", rms_volume); } +#endif #if CONFIG_USE_AUDIO_PROCESSOR // 同步音量到音频处理器，用于动态阈值调整 @@ -2237,9 +2245,11 @@ void Application::OnAudioOutput() { int bytes = (int)(pcm.size() * sizeof(int16_t)); ESP_LOGD(TAG, "写入播放管道: 采样率=%d 字节=%d", src_rate, bytes); player_pipeline_write(player_pipeline_, (char*)pcm.data(), bytes); +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK if (bytes > 0) { this->last_audible_output_time_ = std::chrono::steady_clock::now(); } +#endif if (!first_play_logged && bytes > 0) { ESP_LOGI(TAG, "开始播放下行音频: 字节=%d 采样率=%d", bytes, src_rate); first_play_logged = true; @@ -2247,9 +2257,11 @@ void Application::OnAudioOutput() { } else { ESP_LOGD(TAG, "直接输出PCM到编解码器: 样本=%zu", pcm.size()); codec->OutputData(pcm);// 直接输出PCM数据 +#ifdef PHASE6_ENABLE_AUDIO_FALLBACK if (!pcm.empty()) { this->last_audible_output_time_ = std::chrono::steady_clock::now(); } +#endif if (!first_play_logged && !pcm.empty()) { ESP_LOGI(TAG, "开始播放下行音频: 样本=%zu 采样率=%d", pcm.size(), src_rate); first_play_logged = true; @@ -3590,6 +3602,13 @@ bool Application::CanEnterSleepMode() { return false; } + // Phase 6 关键修复：hibernate 期间禁用 PowerSaveTimer 的 Light Sleep + // 否则 esp_pm_configure(light_sleep_enable=true) 会让 I2C 总线进入低功耗 + // 状态，唤醒后 ES7210/ES8311 通信失败导致 ESP_ERROR_CHECK abort 重启 + if (hibernating_.load()) { + return false; + } + // Now it is safe to enter sleep mode return true; } @@ -4332,3 +4351,143 @@ void Application::HandleBleJsonCommand(const std::string& cmd, int msg_id, cJSON service.SendResponse(cmd, msg_id, -99, "unknown cmd"); } #endif + +// ============================================================ +// Phase 6: 空闲休眠（真退房 + 熄屏 + BOOT 唤醒 + 内存兜底） +// ============================================================ + +extern "C" void pwm_set_brightness(uint8_t percent); // dzbj/pages_pwm.c + +void Application::SaveIdleCyclesToNvs() { + Settings s("hibernate", true); + s.SetInt("idle_cycles", idle_cycles_); +} + +void Application::LoadIdleCyclesFromNvs() { + Settings s("hibernate", false); + idle_cycles_ = s.GetInt("idle_cycles", 0); +} + +void Application::ResetIdleCyclesNvs() { + Settings s("hibernate", true); + s.SetInt("idle_cycles", 0); + idle_cycles_ = 0; +} + +void Application::EnterIdleHibernate() { + if (hibernating_.load()) { + ESP_LOGW(TAG, "已处于休眠状态，跳过重复进入"); + return; + } + ESP_LOGI(TAG, "🌙 进入空闲休眠：真退房 → 字幕提示（不熄屏）"); + + auto display = Board::GetInstance().GetDisplay(); + + // 1. 真退出 RTC 房间（释放 License） + // Protocol 基类的虚函数 LeaveRoom 默认回退到 CloseAudioChannel， + // VolcRtcProtocol 覆写为 volc_rtc_stop + volc_rtc_destroy + if (protocol_) { + protocol_->LeaveRoom(); + } + + // 2. 字幕显示推迟到最后做（此时 LVGL 锁竞争最少）— 见步骤 9 + + // 3. 关闭 codec input/output 让状态机重置 + // 修复 bug：若不关闭，唤醒后 EnableInput(true) 会进入 "已 open" 异常路径 + // → esp_codec_dev_set_in_channel_gain ES_ERROR_CHECK 失败 abort + // → ESP32-S3 软重启而不是恢复对话 + auto codec = Board::GetInstance().GetAudioCodec(); + if (codec) { + ESP_LOGI(TAG, "EnterIdleHibernate: 关闭 codec input/output 重置状态机"); + codec->EnableInput(false); + codec->EnableOutput(false); + } + + // 4. 关闭录音管道（避免唤醒后重新打开时冲突） + if (recorder_pipeline_) { + recorder_pipeline_close(recorder_pipeline_); + recorder_pipeline_ = nullptr; + } + + // 5. 关键时序：先设置 hibernating_=true（阻止 PowerSaveTimer 进入 Light Sleep） + // 再 SetDeviceState(kDeviceStateIdle)（之后 CanEnterSleepMode 会因为 hibernating_=true 而返回 false） + hibernating_.store(true); + + // 6. 双保险：强制 esp_pm 禁用 Light Sleep（保护 I2C/codec 总线不进入睡眠） + // 防止 PowerSaveTimer 已经触发或紧接着触发 esp_pm_configure(light_sleep=true) + // 导致 ES7210/ES8311 唤醒后 I2C 通信失败 → ESP_ERROR_CHECK abort 重启 + esp_pm_config_t pm_config = { + .max_freq_mhz = 240, + .min_freq_mhz = 240, + .light_sleep_enable = false, + }; + esp_pm_configure(&pm_config); + ESP_LOGI(TAG, "EnterIdleHibernate: 已强制禁用 Light Sleep（保护 I2C 总线）"); + + // 7. 设备状态切回 idle（屏幕保持亮起，仅字幕提示） + SetDeviceState(kDeviceStateIdle); + + // 8. 累计休眠次数（NVS 持久化） + idle_cycles_++; + SaveIdleCyclesToNvs(); + ESP_LOGI(TAG, "✓ 已进入空闲休眠（累计第 %d 次）", idle_cycles_); + if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ESP_LOGW(TAG, "🛡 累计休眠 %d 次（阈值 %d），下次唤醒触发硬重启清理内存碎片", + idle_cycles_, IDLE_CYCLES_REBOOT_THRESHOLD); + } + + // 9. 显示退出提示字幕（最后做：此时 LeaveRoom/SetDeviceState 都完成， + // LVGL 锁竞争最少；带重试确保 LVGL 锁超时也能最终显示） + // + // 注意：ai_chat_set_chat_message 内部有 last_content 去重缓存， + // 锁超时时不更新缓存，下次重试相同内容时仍会进入 lvgl_port_lock 路径 + const char* hibernate_msg = "已自动退出RTC对话，按BOOT键重新连接RTC"; + for (int attempt = 0; attempt < 5; attempt++) { + vTaskDelay(pdMS_TO_TICKS(200)); // 让出 CPU 给 LVGL 任务完成当前帧渲染 + if (display) { + display->SetChatMessage("system", hibernate_msg); + } + } + ESP_LOGI(TAG, "✓ 已显示退出提示字幕（5 次重试覆盖 LVGL 锁竞争）"); +} + +void Application::WakeFromHibernate() { + if (!hibernating_.load()) { + return; + } + ESP_LOGI(TAG, "☀ 从空闲休眠唤醒"); + + // 内存兜底：累计达到阈值时硬重启清理碎片 + if (idle_cycles_ >= IDLE_CYCLES_REBOOT_THRESHOLD) { + ESP_LOGI(TAG, "🛡 累计休眠 %d 次，硬重启清理内存碎片", idle_cycles_); + ResetIdleCyclesNvs(); + pwm_set_brightness(80); // 重启前先点亮，避免黑屏时间过长 + Board::GetInstance().OnBeforeRestart(); + vTaskDelay(pdMS_TO_TICKS(500)); + esp_restart(); + return; // 不会执行到这 + } + + // 1. 屏幕未熄屏（Phase 6 改动后不再熄屏），仅打印状态日志 + ESP_LOGI(TAG, "WakeFromHibernate: device_state=%d, idle_cycles=%d", + (int)device_state_, idle_cycles_); + + // 2. 清空 hibernate 期间的字幕提示 + auto display = Board::GetInstance().GetDisplay(); + if (display) { + display->SetChatMessage("system", ""); + } + + // 3. 先复位为 idle 状态（EnterIdleHibernate 已设为 idle，这里幂等） + if (device_state_ != kDeviceStateIdle) { + SetDeviceState(kDeviceStateIdle); + } + + // 4. 触发 RTC 重连（复用 ToggleChatState → OpenAudioChannel → 自动重建 rtc_handle_） + ESP_LOGI(TAG, "WakeFromHibernate: 调用 ToggleChatState() 触发 RTC 重连..."); + ToggleChatState(); + + hibernating_.store(false); + ESP_LOGI(TAG, "✓ 唤醒完成，已触发 RTC 重连（注意：实际重连进度由 ToggleChatState 异步处理）"); +} + diff --git a/main/application.h b/main/application.h index 199e148..29edc03 100644 --- a/main/application.h +++ b/main/application.h @@ -112,6 +112,11 @@ public: bool IsDialogUploadEnabled() const { return dialog_upload_enabled_; }// 是否启用对话上传 void SetDialogUploadEnabled(bool enabled);// 设置对话上传状态 + // Phase 6: 空闲休眠相关 + void EnterIdleHibernate(); // 进入空闲休眠（字幕+真退房+熄屏） + void WakeFromHibernate(); // 从休眠唤醒（亮屏+重连） + bool IsHibernating() const { return hibernating_.load(); } + // // BLE JSON 命令处理（暂不使用） // void HandleBleJsonCommand(const std::string& cmd, int msg_id, cJSON* data, BleJsonService& service); @@ -141,6 +146,15 @@ private: std::atomic last_safe_operation_; // 🔧 最后安全操作时间戳 std::atomic is_switching_to_listening_{false}; // 🔵 标志：正在主动切换到聆听状态 std::atomic is_low_battery_transition_{false}; + + // Phase 6: 空闲休眠状态 + std::atomic hibernating_{false}; // 是否处于熄屏休眠状态 + int idle_cycles_ = 0; // 累计休眠循环次数（NVS 持久化） + static constexpr int IDLE_CYCLES_REBOOT_THRESHOLD = 50; // 累计 50 次触发硬重启清碎片 + void SaveIdleCyclesToNvs(); + void LoadIdleCyclesFromNvs(); + void ResetIdleCyclesNvs(); + ListeningMode listening_mode_ = kListeningModeAutoStop; #if CONFIG_USE_REALTIME_CHAT bool realtime_chat_enabled_ = true; diff --git a/main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc b/main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc index 2a5d4c7..f9ab905 100644 --- a/main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc +++ b/main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc @@ -567,6 +567,20 @@ public: last_click_time = current_time; ESP_LOGI(TAG, "BOOT button clicked"); + // Phase 6: 优先处理空闲休眠唤醒（最高优先级，不依赖 LVGL/状态机） + { + auto &app_wake = Application::GetInstance(); + if (app_wake.IsHibernating()) { + ESP_LOGI(TAG, "🔵 BOOT in hibernate → 唤醒（恢复亮度 + 重连 RTC）"); + // 派发到独立 task 避免阻塞 iot_button 回调（iot_button 在 esp_timer 任务中） + xTaskCreate([](void* arg) { + Application::GetInstance().WakeFromHibernate(); + vTaskDelete(NULL); + }, "wake_hib", 4096, NULL, 5, NULL); + return; + } + } + #if ENABLE_TOUCH_PAD_BUTTONS // 创建一个单独的任务来处理触摸解锁，避免在按钮回调中执行复杂操作 xTaskCreate([](void* arg) { diff --git a/main/protocols/protocol.h b/main/protocols/protocol.h index 7e9c635..75c2b5e 100644 --- a/main/protocols/protocol.h +++ b/main/protocols/protocol.h @@ -54,6 +54,9 @@ public: virtual void Start() = 0; virtual bool OpenAudioChannel() = 0; virtual void CloseAudioChannel() = 0; + // Phase 6: 真退出 RTC 房间（释放 License），默认回退到 CloseAudioChannel + // VolcRtcProtocol 覆写：调用 volc_rtc_stop + volc_rtc_destroy + virtual void LeaveRoom() { CloseAudioChannel(); } virtual bool IsAudioChannelOpened() const = 0; virtual void SendAudio(const std::vector& data) = 0; virtual void SendPcm(const std::vector& data) {} diff --git a/main/protocols/volc_rtc_protocol.cc b/main/protocols/volc_rtc_protocol.cc index e7b1097..8af80fd 100644 --- a/main/protocols/volc_rtc_protocol.cc +++ b/main/protocols/volc_rtc_protocol.cc @@ -334,6 +334,23 @@ void VolcRtcProtocol::LogUplinkStatsMaybe() { } // 🔊 打开音频通道 bool VolcRtcProtocol::OpenAudioChannel() { + // Phase 6: 如果 LeaveRoom 后 rtc_handle_ 被销毁，触发 Start() 重建 + if (!rtc_handle_ && iot_ready_) { + ESP_LOGI(TAG, "Phase 6: RTC 实例不存在，触发重建..."); + iot_ready_ = false; // 由 Start 任务重新置位 + Start(); // 异步触发 volc_rtc_init 任务重建 rtc_handle_ + // 等待 rtc_handle_ 就绪（最多 5 秒） + int wait_ticks = 0; + while (!rtc_handle_ && wait_ticks < 50) { + vTaskDelay(pdMS_TO_TICKS(100)); + wait_ticks++; + } + if (!rtc_handle_) { + ESP_LOGE(TAG, "Phase 6: RTC 重建超时（5s），唤醒失败"); + return false; + } + ESP_LOGI(TAG, "Phase 6: RTC 实例已重建（耗时 %d ms）", wait_ticks * 100); + } if (!rtc_handle_) { ESP_LOGW(TAG, "无法打开音频通道：RTC句柄未准备就绪");// 无法打开音频通道：RTC句柄未准备就绪 return false; @@ -406,6 +423,26 @@ void VolcRtcProtocol::CloseAudioChannel() { } } +// Phase 6: 真退出 RTC 房间（释放 License） +// = volc_rtc_stop + volc_rtc_destroy +// 火山官方文档（StopVoiceChat 说明）: 真人退房必须 leaveRoom + destroyRTCEngine +// 客户端调用 volc_rtc_destroy 后，服务端 AI 任务会在 180s 内自动停止 +void VolcRtcProtocol::LeaveRoom() { + if (rtc_handle_) { + if (is_connected_) { + volc_rtc_stop(rtc_handle_); + is_connected_ = false; + } + volc_rtc_destroy(rtc_handle_); + rtc_handle_ = nullptr; + ESP_LOGI(TAG, "✓ 已真退出 RTC 房间（leaveRoom + destroyRTCEngine）"); + } + is_audio_channel_opened_ = false; + if (on_audio_channel_closed_) { + on_audio_channel_closed_(); + } +} + // 🔊 检查音频通道是否已打开 bool VolcRtcProtocol::IsAudioChannelOpened() const { return is_audio_channel_opened_; diff --git a/main/protocols/volc_rtc_protocol.h b/main/protocols/volc_rtc_protocol.h index 070f195..b7286d5 100644 --- a/main/protocols/volc_rtc_protocol.h +++ b/main/protocols/volc_rtc_protocol.h @@ -19,7 +19,12 @@ public: void SendPcm(const std::vector& data) override;// 🔊 发送PCM音频数据到RTC void SendG711A(const std::vector& data) override;// 🔊 发送G711A音频数据到RTC bool OpenAudioChannel() override;// 🔊 打开音频通道 - void CloseAudioChannel() override;// 🔊 关闭音频通道 + void CloseAudioChannel() override;// 🔊 关闭音频通道（仅 stop 媒体流，不退出房间） + + // Phase 6: 真退出 RTC 房间 = volc_rtc_stop + volc_rtc_destroy（释放 License） + // 与 CloseAudioChannel 区别：CloseAudioChannel 只停媒体流，房间仍占用 + void LeaveRoom() override; + bool IsAudioChannelOpened() const override;// 🔊 检查音频通道是否已打开 void SendAbortSpeaking(AbortReason reason) override;// 🔊 发送中止通话请求 void SendStartListening(ListeningMode mode) override;// 🔊 发送开始监听请求