内容
# M5Camera MCP 固件
独立的 ESP32 固件，将 M5Stack M5Camera/OV2640 模块转换为 Wi-Fi 相机、Web UI、OTA 目标和 MCP 服务器，供 Codex 或其他 MCP 客户端使用。
```text
MCP 客户端
└── m5camera_mcp # 相机状态、捕获、流 URL、OV2640 设置
```
该设备通过 HTTP 和 MCP 公开相机控制和诊断。它是一个专注的相机服务器，而不是一个通用的自动化控制器。
## 您将获得
- 暗色移动 Web UI，包含实时状态、快照流、捕获、设置、Wi-Fi 和 OTA 页面。
- `/status.json` 处的 JSON 诊断信息。
- `/capture.jpg` 处的 JPEG 捕获。
- 使用周期性快照的 `/stream.html` 流页面。
- `/mcp` 处的 MCP 端点，包含用于状态、捕获、流 URL、相机设置和重启的工具。
- 首次运行设置 AP：`m5camera-setup`。
- 通过 `MCP_AUTH_TOKEN` 可选的 bearer-token 保护。
## 硬件
- M5Stack M5Camera 或兼容的 ESP32 相机板。
- OV2640 传感器。
- 用于首次刷写的 USB 串行适配器/电缆。
- 2.4 GHz Wi-Fi 网络用于正常操作。
## 仓库布局
```text
src/ 固件模块
include/ 板配置、引脚、可选令牌模板
test/ PlatformIO Unity 测试
skills/m5camera-mcp/ 用于此 MCP 服务器的 Codex 技能
docs/ 实现计划和源代码提示
platformio.ini PlatformIO 环境
partitions.csv 支持 OTA 的闪存布局
```
## 快速入门
构建固件：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio run
```
通过 USB 刷写：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio run -t upload --upload-port /dev/ttyUSB1
```
打开串行监视器：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio device monitor -p /dev/ttyUSB1 -b 115200
```
常见的 Linux 端口是 `/dev/ttyUSB0`、`/dev/ttyUSB1` 和 `/dev/ttyACM0`。如果上传不自动重置，请按住 `BOOT`/`IO0`，重置或重新连接电源，然后在上传开始后释放。
## 首次 Wi-Fi 设置
1. 打开相机电源。
2. 如果未配置 Wi-Fi，请连接到 AP `m5camera-setup`。
3. 打开 `http://192.168.4.1/`。
4. 选择 Wi-Fi 网络，输入密码，然后保存。
5. 等待重启。
6. 打开 `http://m5camera.local/` 或串行日志中打印的 IP 地址。
当前测试设备地址：`http://192.168.14.42/`。
## Web UI
打开：
```text
http://m5camera.local/
```
共享的标题栏显示相机状态、Wi-Fi/IP 和活动帧设置。每个 HTML 页面都提供导航：
- `相机`：实时预览、捕获、下载、状态摘要。
- `流`：周期性快照流，包含捕获和下载控件。
- `设置`：帧大小、方向、JPEG 质量、亮度、对比度、饱和度、白平衡、曝光和增益。
- `Wi-Fi`：扫描网络并保存凭证。
- `OTA`：通过 Wi-Fi 上传新固件。
## OTA 更新
首次 USB 刷写后，从 Web UI 构建并上传固件：
```text
http://m5camera.local/ota
```
或使用 curl：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio run
curl -F firmware=@.pio/build/m5camera/firmware.bin http://m5camera.local/ota
```
使用 bearer 认证：
```bash
curl -H 'Authorization: Bearer <token>' \
-F firmware=@.pio/build/m5camera/firmware.bin \
http://m5camera.local/ota
```
## 将 MCP 服务器添加到 Codex
注册相机为可流式传输的 HTTP MCP 服务器：
```bash
codex mcp add m5camera_mcp --url http://192.168.14.42/mcp
```
或，如果网络上启用了 mDNS：
```bash
codex mcp add m5camera_mcp --url http://m5camera.local/mcp
```
检查注册：
```bash
codex mcp list
codex mcp get m5camera_mcp
```
在添加服务器后重启 Codex，以便在会话中显示工具。
如果启用了 `MCP_AUTH_TOKEN`：
```bash
export M5CAMERA_MCP_TOKEN='<token>'
codex mcp add m5camera_mcp \
--url http://192.168.14.42/mcp \
--bearer-token-env-var M5CAMERA_MCP_TOKEN
```
## MCP 工具
| 工具 | 用途 |
| --- | --- |
| `camera_status` | 返回诊断信息、IP、堆、PSRAM、帧设置、方向和最后错误。 |
| `camera_capture` | 捕获 JPEG 并返回 URL 或 base64 有效载荷。 |
| `camera_set_params` | 应用 OV2640 参数：帧大小、方向、质量、亮度、对比度、饱和度、白平衡、曝光、增益。 |
| `camera_stream_url` | 返回 MJPEG URL 或周期性快照 URL。 |
| `camera_reboot` | 安排控制器重启。 |
通过原始 JSON-RPC 示例：
```bash
curl -s http://m5camera.local/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
捕获：
```bash
curl -s http://m5camera.local/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"camera_capture","arguments":{"return_mode":"url"}}}'
```
临时调整图像设置：
```bash
curl -s http://m5camera.local/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"camera_set_params","arguments":{"brightness":2,"contrast":1,"saturation":-1,"whitebal":true,"awb_gain":true,"exposure_ctrl":true,"gain_ctrl":true,"save":false}}}'
```
仅当您希望设置在重启后保持不变时，才使用 `save:true`。
## HTTP 参考
| 方法 | 路径 | 描述 |
| --- | --- | --- |
| `GET` | `/` | 主 Web UI 或 Wi-Fi 设置页面。 |
| `GET` | `/status` | HTML 状态页面。 |
| `GET` | `/status.json` | 机器可读的诊断信息。 |
| `GET` | `/capture.html` | 捕获页面。 |
| `GET` | `/capture.jpg` | 最新 JPEG 捕获。 |
| `GET` | `/stream.html` | 浏览器流页面。 |
| `GET` | `/stream` | 保留的 MJPEG 端点；当前返回未实现，除非启用。 |
| `GET/POST` | `/settings` | 相机设置 UI 和 JSON 更新端点。 |
| `GET/POST` | `/ota` | OTA 表单和固件上传端点。 |
| `GET/POST` | `/wifi` | Wi-Fi 设置 UI 和凭证保存端点。 |
| `GET` | `/wifi/scan` | Wi-Fi 扫描 JSON。 |
| `POST` | `/wifi/forget` | 清除 Wi-Fi 凭证并重启。 |
| `POST` | `/reboot` | 安排重启。 |
| `POST` | `/factory-reset` | 清除 Wi-Fi 和相机设置，然后重启。 |
| `POST` | `/mcp` | MCP JSON-RPC 端点。 |
## 测试
顺序运行 PlatformIO 命令。它们共享 `.pio/build`，并行运行可能会在链接过程中损坏目标文件。
编译测试：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio test -e m5camera --without-uploading --without-testing
```
在连接的设备上运行 Web UI Unity 测试：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio test -e m5camera --filter test_web_ui --upload-port /dev/ttyUSB1
```
运行设备测试后，再次刷写正常的固件：
```bash
PLATFORMIO_CORE_DIR=.pio-core pio run -t upload --upload-port /dev/ttyUSB1
```
## 可选 Codex 技能
此仓库包含用于操作相机 MCP 服务器的 Codex 技能：
```text
skills/m5camera-mcp/
```
要使其能够被本地 Codex 会话自动发现，请将符号链接到您的个人技能目录：
```bash
ln -s "$(pwd)/skills/m5camera-mcp" ~/.agents/skills/m5camera-mcp
```
然后重启 Codex。
## 配置和机密信息
默认设置位于 `include/config.h` 中。Bearer-token 保护由预处理器宏 `MCP_AUTH_TOKEN` 控制。对于本地保护构建，请添加构建标志，例如：
```ini
build_flags =
-DCORE_DEBUG_LEVEL=3
-DMCP_AUTH_TOKEN=\"change-me\"
```
请勿将真实令牌提交到存储库中。`include/secrets.example.h` 仅是一个模板，用于本地实验，除非您将其连接到自己的构建配置中。
## 故障排除
| 症状 | 尝试方法 |
| --- | --- |
| 无法通过 `m5camera.local` 找到设备 | 使用串行监视器读取 IP 地址，然后打开 `http://<ip>/`。 |
| 无 Wi-Fi 连接 | 连接到 `m5camera-setup` 并重新配置 Wi-Fi。 |
| 上传通过 USB 失败 | 传递 `--upload-port`，如果需要，降低上传速度，或在重置过程中手动使用 `BOOT`/`IO0`。 |
| Web UI 正常，但 Codex 无法看到工具 | 运行 `codex mcp get m5camera_mcp`，验证 URL，然后重启 Codex。 |
| 图像倒置 | 打开设置或调用 `camera_set_params`，并使用 `orientation:"up"`、`"down"`、`"right"` 或 `"left"`。 |
| 人脸过暗 | 尝试临时设置：`brightness:2`、`contrast:1`、`saturation:-1`，并启用自动白平衡/曝光/增益。 |
## 许可证
该项目在 GNU 通用公共许可证 v3.0 或更高版本下获得许可。参见 [LICENSE](LICENSE)。
SPDX 标识符：
```text
GPL-3.0-or-later
```
固件和测试使用的第三方组件允许此选择：
| 组件 | 许可证 | 备注 |
| --- | --- | --- |
| ArduinoJson | MIT | 允许，GPL 兼容。 |
| ThrowTheSwitch Unity | MIT | 测试框架仅；允许，GPL 兼容。 |
| Arduino-ESP32 框架 | LGPL-2.1-or-later | GNU LGPL 与 GPLv3 兼容。 |
| PlatformIO Espressif32 平台/工具 | Apache-2.0 和工具特定许可证 | 构建工具/平台代码不是此项目源代码的一部分；Apache-2.0 与 GPLv3 兼容，但仅与 GPLv2 不兼容。 |
由于 Apache-2.0 与仅 GPLv2 不兼容，因此此仓库使用 GPLv3-or-later 而不是仅 GPLv2。
