内容
# 视觉桥接 AI 眼镜
视觉桥接 AI 眼镜是一个基于 ESP32 的可穿戴 AI 硬件固件项目。它将小型摄像头、麦克风、扬声器、显示屏和无线模块转化为一个语音驱动的助手，可以看到、聆听、说话并连接到云 AI 服务。
该项目旨在用于实验性 AI 眼镜和紧凑型嵌入式助手。它结合了实时音频交互、摄像头捕捉、图像解释、设备端 MCP 工具以及对多个 ESP32 板系列的支持。
## 功能
- 从板载麦克风捕获语音输入。
- 通过 WebSocket 或 MQTT/UDP 通信路径传输音频。
- 使用 ESP-SR 支持唤醒词和音频处理。
- 使用 OPUS 编码和解码语音数据。
- 从支持的 ESP32 摄像头板捕获图像。
- 将图像发送到视觉端点进行解释或问答。
- 在 OLED 或 LCD 屏幕上显示状态、文本和表情符号反馈。
- 支持兼容板上的电池报告和电源管理。
- 通过 MCP 工具公开设备控制，包括扬声器、LED、GPIO、伺服器和摄像头操作。
- 支持 Wi-Fi 和选定的蜂窝模块工作流程。
## 为什么存在
Visionbridge 是物理视觉和 AI 推理之间的桥梁。目标是制作一个小型可穿戴设备，可以回答有关环境的问题，对话式地响应，并在无需手机屏幕作为主要接口的情况下控制本地硬件。
对于 AI 眼镜，最重要的流程是：
1. 唤醒或激活助手。
2. 提出语音问题。
3. 在需要视觉上下文时捕捉照片。
4. 将图像和问题发送到 AI 视觉服务。
5. 说出或显示响应。
## 项目结构
```text
main/
application.* 设备应用主流程
mcp_server.* 设备端 MCP 工具和摄像头操作
protocols/ WebSocket、MQTT 和共享协议逻辑
audio/ 音频编解码器、处理和唤醒词支持
display/ OLED、LCD、LVGL、图像、GIF 和表情符号显示代码
led/ LED 驱动器和效果
boards/ 板载特定引脚映射和硬件驱动器
docs/
websocket.md WebSocket 协议说明
mqtt-udp.md MQTT 和 UDP 协议说明
mcp-protocol.md MCP 协议交互流程
mcp-usage.md MCP 设备控制示例
partitions/
v1/, v2/ ESP-IDF 分区表
scripts/
构建助手、音频工具、图像转换器和资产实用程序
```
## 硬件目标
该固件支持许多基于 ESP32 的板，并可以适应自定义 AI 眼镜硬件。眼镜式构建最相关的目标是带有以下功能的 ESP32-S3 板：
- 摄像头支持
- PSRAM
- 麦克风输入
- 扬声器或放大器输出
- Wi-Fi
- 可选显示屏
- 可选电池管理
此树中支持摄像头的板示例包括 LilyGO T-CameraPlus S3、M5Stack CoreS3、SenseCAP Watcher、ESP32-S3 摄像头板以及几个 Waveshare 或自定义 S3 板。
对于自定义眼镜 PCB，请从 `main/boards/` 下复制最接近的板，然后更新：
- `config.h` 中的 GPIO 赋值
- `config.json` 中的板元数据
- 摄像头、音频、显示屏和电源轨的板初始化代码
- 如果需要新的板选择选项，则更新 `main/Kconfig.projbuild`
- 如果添加新的板源文件夹，则更新 `main/CMakeLists.txt`
## 软件需求
- ESP-IDF 5.4 或更新版本
- Git
- ESP-IDF 所需的 Python 依赖项
- 支持的 ESP32 目标，通常为 `esp32s3`，适用于基于摄像头的构建
可选工具：
- 带有 ESP-IDF 扩展的 VS Code 或 Cursor
- 用于供应和调试的串行监视器
- 来自 `scripts/` 的音频/图像转换脚本
## 构建
首先设置 ESP-IDF，然后从仓库根目录构建：
```bash
idf.py set-target esp32s3
idf.py menuconfig
idf.py build
```
在 `menuconfig` 中，选择板类型、语言、协议设置、资产设置和构建所需的任何硬件特定选项。
## 烧录
通过 USB 连接设备，然后烧录和监控：
```bash
idf.py -p COMx flash monitor
```
在 Linux 或 macOS 上，将 `COMx` 替换为串行设备，例如：
```bash
idf.py -p /dev/ttyUSB0 flash monitor
```
## 配置说明
固件通过设备设置流程存储运行时设置，例如 Wi-Fi 凭证、协议令牌、服务器地址和视觉端点数据。避免在固件中提交个人 `sdkconfig`、生成的构建文件、本地 `.env` 文件或私有凭证。
仓库故意忽略常见的本地工件：
- `build/`
- `managed_components/`
- `sdkconfig`
- `sdkconfig.old`
- `.env`
- `.vscode/`
- `.DS_Store`
- `._*`
## 视觉流程
摄像头流程围绕设备端 MCP 服务器实现：
- `main/mcp_server.cc` 注册摄像头工具。
- `main/boards/common/camera.h` 定义摄像头接口。
- `main/boards/common/esp32_camera.*` 实现 ESP32 摄像头捕捉和图像解释。
- `main/boards/sensecap-watcher/sscma_camera.*` 处理 SenseCAP 摄像头路径。
当配置视觉端点时，助手可以捕捉帧，附加用户问题，并将其发送到服务器进行解释。
## 协议
Visionbridge 支持两种主要的通信模式：
- 用于实时助手会话的 WebSocket。
- 用于消息信号和音频传输的 MQTT 加 UDP。
参见：
- [WebSocket 协议](docs/websocket.md)
- [MQTT/UDP 协议](docs/mqtt-udp.md)
- [MCP 协议](docs/mcp-protocol.md)
- [MCP 使用示例](docs/mcp-usage.md)
## 安全性和隐私
AI 眼镜可以捕捉敏感的音频和图像。在公共部署之前，将此固件视为开发平台，并审查以下领域：
- 不要在固件中硬编码生产密钥。
- 不要在生产构建中记录 Wi-Fi 密码或私钥。
- 为图像解释端点使用 HTTPS 或其他受保护的传输。
- 使录音和摄像头捕捉行为对佩戴者和附近的人明显。
- 仅存储操作所需的最低限度数据。
## 开发提示
- 在添加自定义硬件之前，从已知的有效板配置开始。
- 将 `sdkconfig.defaults` 保留在版本控制之下，但生成的 `sdkconfig` 保留在本地。
- 在更改板选择或目标芯片后重新构建。
- 使用串行日志验证摄像头、显示屏、音频编解码器和网络初始化。
- 将板特定代码隔离在 `main/boards/<board-name>/` 下。
## 许可证
该项目在 MIT 许可证下发布。参见 [LICENSE](LICENSE)。
## 致谢
Visionbridge AI 眼镜建立在 ESP32 嵌入式 AI 生态系统之上，包括 ESP-IDF、ESP-SR、LVGL、ESP 摄像头支持、OPUS 音频组件和 XiaoZhi ESP32 项目结构。
