基于 ESP32-S31-Korvo-1 的多功能智能音箱固件

ESP32-S31-Korvo-1 一体多用途固件，支持蓝牙音箱、PC 音乐副屏、局域网对讲、录音回放、MJPEG 视频播放、WiFi A/B 双槽 OTA、USB 高速扩展屏，搭载 LVGL 9 图形界面，SET 按键一键在主固件与 USB 副屏固件之间切换。

功能总览

设备集成 7 个功能标签页，覆盖音频、显示、网络、系统管理：

• CALL 局域网对讲：UDP 全双工语音对讲，16kHz 单声道，端到端延迟≤100ms
• REC 本地录音：录音保存至 SD 卡为 WAV 格式，支持在文件页面回放
• AUDIO 音乐中心：SD 卡本地音乐硬件解码播放，支持切换板载扬声器、蓝牙推流输出
• SINK 蓝牙音箱：A2DP Sink 接收手机蓝牙音频，同步展示歌名、播放进度与滚动歌词
• VIDEO 视频播放：播放 SD 卡 MJPEG 格式 AVI 视频，硬件 JPEG 解码 + PPA 缩放，800×480 全屏播放
• PC PC 音乐副屏：局域网接收 PC 媒体播放信息，展示旋转专辑封面、滚动歌词，支持媒体快捷控制
• SYS 系统设置：WiFi、蓝牙、RGB 灯光管理，固件版本查看、A/B 槽 OTA 升级、存储与系统状态监控

配套下拉仪表盘，支持 SNTP 网络校时、和风天气实时展示。音频采用统一调度服务，播放、录音、对讲互斥管理，避免音频通路冲突。

双固件分区架构

板载 16MB Flash 采用三固件槽设计：

• ota_0 /ota_1：主固件 A/B 双槽，WiFi OTA 只在这两个槽轮换，升级失败自动回滚，防止变砖
• uext 专属槽：独立存放 USB 扩展屏固件，OTA 升级不会覆盖该分区
  通过 SET 按键一键切换：主固件可跳转至 USB 副屏；副屏模式下按下 SET，自动切回主系统。
  USB 副屏固件为独立工程，接入 Windows 后配合已签名 IDD 驱动，识别为一块 800×480、最高 60FPS 的标准扩展显示器，同时支持五点触摸。

WiFi OTA 升级（A/B 双槽）

设备作为 HTTP 客户端主动拉取固件，控制通路复用 UDP，数据传输复用 TCP，无需外网或者 PC 被设备反向访问。

• 支持版本校验、SHA256 校验、断点续传，256KB 分段哈希存入 NVS，中断后可恢复下载
• 升级界面为 LVGL 全屏遮罩，升级过程禁止触摸操作
• 多重防砖机制：固件 CRC 校验、镜像合法性校验、升级后自验证、Bootloader 自动回滚
• 支持双向 OTA：设备主动查询 PC 端最新固件版本，一键发起升级；也支持手动切换运行槽

工程架构与 AI Agent 开发闭环

项目采用分层解耦架构，业务 middleware 层与 LVGL UI 层完全隔离，UI 不直接操作硬件、音频外设，保证代码规范、稳定性。
同时配套完整的开发规范、检查清单、自动化脚本，形成一套 AI Agent 可直接执行的嵌入式开发流程：读取规范文档 → 按模板编写代码 → 编译 → 自动烧录 → 脚本抓取串口日志 → 自动判断运行状态，迭代调试。
配套编码红线约束，规避常见 RTOS、音频、PSRAM 栈、缓存相关的崩溃问题。

硬件信息

• 主控：ESP32-S31，双核 RISC-V 320MHz
• 屏幕：4.3 寸 800×480 RGB565 屏幕，GT1151 五点电容触摸
• 音频：ES8389 音频 Codec，双麦克风、双 NS4150B 功放
• 存储：16MB Flash + 16MB Octal PSRAM；LittleFS 存放壁纸素材，SD 卡存放音频、视频、录音文件
• USB：Type‑A 为高速 OTG 口（USB 副屏）；Type‑C 为调试串口，用于烧录、查看日志
• 开发环境：ESP-IDF v6.1.0

配套上位机

提供两套 PC 端程序，二选一使用：

1. PySide6 上位机 pc_host：完整功能，局域网对讲、PC 媒体信息推送、WiFi OTA 固件管理、固件归档记录
2. C# 轻量 pc_now_agent：抓取 Windows 系统媒体播放信息，UDP 推送给设备做音乐副屏

快速上手

1. 使用 EIM 工具安装 ESP-IDF v6.1.0，激活 IDF 终端
2. 编译固件，烧录主固件，首次烧录同步刷写 LittleFS 素材分区
3. 可选：定点烧写 uext 副屏固件到专属分区
4. 安装 PC 上位机，连接同一局域网，即可使用对讲、PC 音乐副屏功能
5. USB 副屏模式：Type‑A 口直连 Windows 电脑，安装配套签名 IDD 驱动，系统识别为扩展显示器

项目进度

已完成：音频链路、LVGL 界面、WiFi 联网与天气、UDP 对讲、SD 卡多媒体、蓝牙 A2DP、PC 音乐副屏、A/B 双槽 OTA、USB 副屏双向切换。

本项目基于 Apache-2.0 协议开源。