基于 openvela 的 ESP32-S3-Korvo V4 多模态导盲犬辅助 AI Agent

参赛队名： 赛博召唤师
所选赛题： 路径 B：已有平台深度适配
赛事： 第三届中国研究生操作系统开源创新大赛

---

作品简介

本作品基于酷世 DIY ESP32-S3-Korvo V4 开发板，完成 openvela 平台深度适配，并实现面向导盲犬场景的多模态 AI Agent 辅助系统。

视障人士依靠导盲犬规避风险，但导盲犬无法用语言描述前方环境。本作品通过终端获取环境图像，经视觉大模型提取障碍类型和方位等信息，以 TTS 语音和 LCD 界面反馈给使用者，形成“环境感知—信息分析—结果反馈”的完整链路。

在环境识别之外，终端还提供与 PC 的双向音视频通话。使用者通过触摸按钮或对应的实体功能键发起紧急呼叫和拍照识别；BLE 应用广播固定名称 GuideAgent-BLE，手机和 PC 可连接并读取设备信息。

提交目录

文件/目录	说明
docs/项目说明书.pdf	项目说明书
docs/项目创新说明.pdf	主要创新、代码位置与验证依据
docs/成员分工及主要贡献说明.pdf	成员分工与主要贡献
docs/人工智能及第三方工具使用说明.pdf	人工智能及第三方工具使用说明
决赛答辩 PPT	现场答辩演示文稿
作品原创承诺书.pdf	原创承诺书
presentation/	决赛答辩 PPT 与功能演示 MP4 视频
demo/	演示固件与部署操作说明；见 demo/README.md
tests/	测试脚本、配置、原始日志及功能/性能验证材料；使用方法见 tests/README.md
src/README.md	代码覆盖层、依赖、构建与平台适配说明
src/apply.sh	将覆盖层应用到 openvela 工作区的脚本
demo/nuttx.bin	GuideAgent 与 BLE 综合演示固件

硬件平台

• 主控: ESP32-S3
• 摄像头: OV3660
• 音频采集: ES7210 四通道 ADC
• 音频输出: ES8311 DAC
• 显示: ST7789 LCD (240×280)
• 触摸: CST816S
• 存储: 16 MB Flash + 8 MB Octal PSRAM
• 连接: Wi-Fi、BLE

软件架构

openvela/NuttX RTOS 为基础，接入以下能力：

• 系统与网络: 系统启动、NSH、PSRAM、Wi-Fi、DHCP、DNS、TCP/IP、TLS
• 音频: ES7210 四通道 I2S/TDM 采集 + ES8311 播放 + TTS 语音反馈
• 摄像头: OV3660 驱动 + LCD_CAM/GDMA + V4L2 设备节点
• 显示与触摸: ST7789 LCD、CST816S 触摸、LVGL 基础适配与 GuideAgent 整帧显示
• AI Agent: openvela 原生 Agent + C Tool + Markdown Skill
• GuideAgent: 拍照识别、照片与文本显示、连续语音播报及 PC 双向音视频通话
• 实体按键: GPIO5 ADC 分压采样与去抖，分别映射为呼叫／挂断键和识别键
• BLE: ESP32-S3 控制器经 NuttX raw HCI 接入 NimBLE，由独立 guideble 应用提供广播、连接管理及 GATT 设备信息服务

系统环境与主要依赖

• 构建：Ubuntu 22.04 或 WSL Linux，使用 trunk-5.5 openvela 基线及 ESP32-S3 工具链；需要 Git、repo、GNU make、CMake 和 Python 3。
• PC 演示：Windows、Python 3.12（含 tkinter）、USB 串口驱动，配备麦克风、扬声器和摄像头。
• 烧录及通话程序：esptool、pyserial、numpy、opencv-python、sounddevice、Pillow。依赖版本与安装命令见 demo/README.md。
• 云端识别与播报：使用可用的视觉模型和 TTS 服务，在板端配置对应地址、模型、密钥与音色。

演示与验证入口

1. 按 demo/README.md 安装工具、烧录 demo/nuttx.bin，在板端 NSH 配置 Wi-Fi、视觉模型和语音服务参数。
2. 启动 src/tools/guide_remote_server.py，在板端指定 PC 地址并打开 GuideAgent 页面，演示识别播报、双向音视频通话及挂断。
3. 使用手机 nRF Connect 扫描 GuideAgent-BLE 并连接，读取 Device Information 服务中的型号与固件信息；板端执行 guideble status 查看连接状态。

演示参数通过 guideagent config set 命令设置，板端保存后重启保留。测试材料、执行方法及结果索引见 tests/README.md，BLE 操作说明见 guideble README。

运行条件与已知限制

识别与播报依赖网络和配置的云端服务。板子与 PC 通话时接入同一局域网，允许 Python 访问音视频设备并通过防火墙开放通话端口。

默认演示固件运行 GuideAgent 页面和 guideble；原生 AI Agent 使用对应配置运行。BLE 提供单连接、只读设备信息服务，音视频通话通过 Wi-Fi 传输。识别以低分辨率图像提供环境辅助信息，实际反馈受场景、服务响应和网络状况影响；视频刷新受相机采集、Wi-Fi 与 LCD SPI 传输影响。测试结论按 tests/README.md 中对应的固件配置和实测记录核对。

代码覆盖层说明

src/ 目录包含比赛所需的全部代码修改，以文件覆盖层形式组织：

1. 准备已 repo sync 的干净 trunk-5.5 openvela 工作区
2. 执行 src/apply.sh --openvela-dir /path/to/openvela，按 .apply_manifest 应用 705 个清单文件
3. 使用 camera_audio_wifi_ble 配置构建演示固件
4. 烧录至开发板验证

从提交目录执行覆盖，再在准备好的 openvela 工作区构建：

bash src/apply.sh --openvela-dir /path/to/openvela
cd /path/to/openvela
export PATH="$PWD/prebuilts/gcc/linux-x86_64/xtensa-esp32s3-elf/bin:$PATH"
./build.sh vendor/espressif/boards/esp32s3/esp32s3-korvo-2/configs/camera_audio_wifi_ble -j8

锁定依赖、SDK 准备及完整步骤见 构建与运行和 src/README.md。NimBLE 固定版本源码包随覆盖层提供，构建时自动解压。

测试方法

在 Linux 或 WSL 安装 Python 3.9 及以上和 C 编译器 cc，从提交目录运行主机回归：

PYTHONDONTWRITEBYTECODE=1 python3 tests/测试及验证材料/check_source.py

板端标准用例、真实设备采集、网络与 BLE 验证的命令和材料索引见 tests/README.md。图像识别和双向通话的实机操作见 demo/README.md。

社区贡献

本作品中具备通用价值的修改已提交至 openvela 社区评审：

仓库	PR 链接	内容
open-vela/nuttx	https://github.com/open-vela/nuttx/pull/321	ES7210 四通道音频驱动
open-vela/nuttx	https://github.com/open-vela/nuttx/pull/324	OV3660 通用驱动
open-vela/nuttx	https://github.com/open-vela/nuttx/pull/325	ESP32-S3 Camera 接入
open-vela/nuttx	https://github.com/open-vela/nuttx/pull/327	Korvo-2 ES7210 板级接入
open-vela/nuttx	https://github.com/open-vela/nuttx/pull/328	ST7789 LCD 板级接入
open-vela/vendor_espressif	https://github.com/open-vela/vendor_espressif/pull/8	Korvo-2 vendor 配置
open-vela/packages_ai_agent	https://github.com/open-vela/packages_ai_agent/pull/25	AI Agent 硬件 Tool 和 Skill

关键文档索引

文档	位置	内容
项目说明书	docs/项目说明书.pdf	完整项目说明
项目创新说明	docs/项目创新说明.pdf	主要创新、技术贡献及验证依据
演示部署	demo/README.md	烧录、网络、服务参数及演示操作
测试材料	tests/README.md	脚本使用方法及结果索引
答辩与演示	presentation/	答辩 PPT、识别播报、紧急呼叫和原生 Agent 演示视频
代码说明	src/README.md	覆盖层结构、构建、烧录、验证
BSP 移植总览	文档	移植顺序、Kconfig/defconfig/链接脚本
BSP 基础配置	文档	代码获取、BSP 分层、构建烧录
音频移植	文档	ES7210 驱动、I2S TDM、验证
摄像头移植	文档	OV3660、LCD_CAM GDMA、V4L2
显示移植	文档	ST7789 SPI、board glue、资源冲突
AI Agent 集成	文档	C Tool、Markdown Skill、配置
验收指南	文档	验收矩阵、证据留存、常见问题
实体按键	按键说明	ADC 采样、去抖及业务映射
GuideAgent 页面	页面说明	页面布局、整帧显示及任务切换
图像识别与播报	识别说明	拍照、图像上传、识别结果及语音播放
PC 双向通话	通话说明	音视频传输、界面控制及会话结束
BLE 平台适配	BLE 说明	NimBLE 接入、构建配置及连接验证
xTS 测试用例	测试用例	用例清单与已通过项的结果、日志