🌐 English Documentation

用户指南

本指南说明如何使用 MiBee Cam 固件，包括配置、Web 界面使用和功能设置。

Web 界面访问

连接方式

STA 模式（推荐）

设备自动连接到您的 WiFi 网络
从路由器的设备列表中查找设备 IP，或检查串口监视器
访问：http://<设备-ip>/

AP 模式（首次配置）

连接到 WiFi 网络：MiBeeCam（密码：mibeecam2026）
在浏览器中打开：http://192.168.4.1/

Web 界面页面

1. 仪表板（`/`）

主仪表板显示实时设备状态：

设备信息：名称、运行时间、WiFi 状态
摄像头状态：分辨率、FPS、JPEG 质量
存储信息：SD 卡状态、可用空间
运动检测：当前状态、事件数量
系统健康：CPU 温度、内存使用
网络信息：IP 地址、信号强度

2. 预览（`/preview.html`）

带控制的实时 MJPEG 视频预览：

实时流：实时摄像头画面
捕获按钮：拍摄单张照片
分辨率选择器：更改摄像头分辨率（VGA/SVGA/XGA/UXGA）
质量滑块：调整 JPEG 质量（1-63，值越低质量越好）
下载按钮：将当前帧保存到您的计算机

3. 配置（`/config.html`）

完整的设备配置界面：

WiFi 设置：SSID、密码、设备名称
摄像头设置：分辨率、帧率、JPEG 质量
运动检测：阈值、冷却时间
摄像头设置：分辨率、帧率、JPEG 质量
时间设置：时区、NTP 服务器

4. 文件（`/files.html`）

照片文件管理：

照片库：按日期组织的保存照片列表
下载：单独下载照片
删除：删除照片

配置选项

WiFi 配置

设置	描述	默认值	范围
WiFi 模式	STA 或 AP 模式	STA	STA/AP
SSID	网络名称（STA 模式）	空	字符串
密码	网络密码	空	字符串
设备名称	主机名/标识	MiBeeCam	32 字符

摄像头配置

设置	描述	默认值	范围
分辨率	摄像头分辨率	VGA (640×480)	0=VGA,1=SVGA,2=XGA,3=UXGA
帧率	FPS 目标值	15	1-30
JPEG 质量	图像质量（值越低质量越好）	12	1-63
闪光控制	LED 亮度	0	0-255（PWM）

运动检测

设置	描述	默认值	范围
运动阈值	灵敏度级别	5	1-255
冷却时间	触发之间的最小间隔	10 秒	1-255 秒
保存照片	将运动照片保存到 SD 卡	启用	是/否

时间配置

设置	描述	默认值	范围
时区	POSIX 时区字符串	CST-8	字符串
NTP 服务器	时间服务器	pool.ntp.org	域名/IP

LED 状态指南

状态 LED（GPIO33）指示不同的系统状态：

模式	图案	描述
常亮	启动中	系统正在启动
	快速闪烁（0.5秒亮，0.5秒灭）	WiFi 连接中
	慢速闪烁（2秒亮，2秒灭）	WiFi 已连接
	中等闪烁（1秒亮，1秒灭）	AP 模式
	红色快速闪烁（0.2秒亮，0.8秒灭）	错误

📁 SD 卡使用

⚠️ GPIO14 共享说明：MiBee Cam 上，GPIO14 引脚被摄像头（XCLK）和 SD 卡（CLK）共享使用。固件采用 SD 卡初始化 → 摄像头初始化 → SD 卡重新初始化的顺序来避免冲突。

支持的格式

文件系统：FAT16/FAT32
容量：最多 32GB（推荐 8GB-16GB）
速度：推荐 Class 10 或更高

文件组织

照片按以下目录结构存储：

/sdcard/photos/
├── 2024-12-30/
│   ├── 14-30-25.jpg
│   ├── 14-32-10.jpg
│   └── 14-35-42.jpg
├── 2024-12-31/
│   ├── 09-15-33.jpg
│   └── 09-18-05.jpg
└── motion_events/
    ├── 2024-12-30/
    └── 2024-12-31/

存储管理

自动清理：当可用空间 < 20% 时，删除最旧的照片
手动清理：使用 Web 界面删除特定照片
监控：在仪表板上显示存储状态

亮度检测与智能闪光

固件使用灰度像素探测来检测场景亮度——这是 OV2640 传感器在 MiBee 开发板上最可靠的方法。

工作原理

灰度探测（主要方法）：每 30 秒，摄像头临时切换到 GRAYSCALE+QQVGA（160×120）模式并捕获一帧。所有像素亮度值取平均，生成准确的亮度读数（0-100%）。模式切换后丢弃 2 帧预热帧以确保曝光稳定。然后摄像头恢复 JPEG 模式。整个探测过程约 1.5 秒。
JPEG 回退：当灰度探测不可用时（例如 MJPEG 流客户端已连接，摄像头模式切换会中断流），系统回退到 JPEG 帧大小启发式——较小的 JPEG 文件表示较暗的场景。精度较低但始终可用。
自动闪光：当在暗场景中检测到运动事件（brightness_pct < flash_threshold）时，闪光灯 LED（GPIO4）会以 ~80% PWM 占空比自动开启（MiBee 板没有限流电阻，~80% 是安全上限），拍照后立即关闭。
暗场景运动灵敏度：在暗场景中，JPEG 帧的字节差异非常小，运动更难被检测到。固件会在检测到暗场景时自动将有效运动阈值降低为配置值的 1/4（最低 5%）。

为什么不用传感器寄存器？

OV2640 的 AEC（自动曝光控制）寄存器曾被测试作为亮度来源，但在连续 JPEG 捕获模式下不可靠——aec_value 稳定在最大值（671）且不随实际光照条件变化。灰度像素采样是该传感器唯一可靠的方法。

算法与公式

灰度探测（主要方法）：

avg = sum(所有像素字节) / 总像素数        // 0-255 灰度平均值
pct = avg × 100 / 255                       // 归一化到 0-100%
is_dark = (pct < flash_threshold)

实测值（MiBee 板，SVGA，quality=10）：

暗室（无灯光）：avg=32, pct=12%
对着天花板灯光：avg=136, pct=53%

JPEG 帧大小回退：

jpeg_kb = 帧大小 / 1024
if jpeg_kb >= 22:   pct = 100%      // 明亮
elif jpeg_kb <= 12: pct = 0%        // 非常暗
else:               pct = (jpeg_kb - 12) × 100 / 10   // 12-22 KB 线性映射
is_dark = (pct < flash_threshold)

实测 JPEG 大小（SVGA，quality=10）：

暗室：~12-14 KB
室内昏暗：~14-17 KB
对着灯光：~17-25 KB

闪光灯 LED PWM 控制：

// GPIO4，LEDC Timer 1 / Channel 1（Timer 0 被摄像头 XCLK 占用）
// PWM：2 kHz，8 位分辨率（0-255 占空比）
// 占空比 = 205（~80%）— MiBee 安全上限（无限流电阻）

开灯：ledc_set_duty(205) → 等待 200ms 预热 → 拍照 → ledc_set_duty(0)
关灯：ledc_set_duty(0)

闪光灯仅在 handle_motion_event() 中用于最终拍照。运动检测期间不会在参考帧/比较帧之间开灯——这样做会产生虚假的 80%+ 帧差异。

暗场景运动阈值降低：

if 暗场景:
    effective_thresh = max(motion_threshold / 4, 5)   // 配置值的 1/4，最低 5%
else:
    effective_thresh = motion_threshold               // 使用配置值

配置参数

设置	描述	默认值	范围
flash_threshold	触发闪光的亮度百分比阈值	40	0-100

阈值参考：

0 = 永不触发闪光（闪光禁用）
20-30 = 仅在非常暗的场景触发闪光
34-40（推荐）= 在中等偏暗的室内环境触发闪光
60-80 = 在较暗的光线下触发闪光（走廊、黄昏等）
100 = 每次运动事件都触发闪光

亮度监控

亮度数据可通过以下渠道查看：

仪表板（/index.html）：每 10 秒自动刷新，显示 scene_dark 状态
状态 API（GET /api/status）：返回 brightness_pct（亮度百分比）、brightness_method（"grayscale" 或 "jpeg-fallback"）、scene_dark（是否暗场景）
Prometheus 指标（GET /metrics）：esp32_brightness_value、esp32_brightness_method{method="grayscale|jpeg-fallback"}、esp32_scene_dark
串口日志：Grayscale probe: avg=32, pct=12%, dark=YES (probe took 1490 ms)

运动检测

工作原理

运动检测使用帧差算法：

捕获连续的 JPEG 帧
转换为灰度并调整大小以便比较
计算帧之间的像素差异
如果差异超过阈值，触发运动事件

配置

阈值：值越高灵敏度越低（1-255）
冷却时间：运动事件之间的最小时间（秒）
区域：比较帧的中心区域（640x480 → 320x240）

运动事件

当检测到运动时：

LED 表示运动（短暂闪烁）
照片保存到 SD 卡
事件记录到串口输出

📶 存储管理

SD 卡使用：

照片按日期自动保存到 SD 卡
支持手动下载和删除照片
可用空间实时监控

命令行界面

使用 `curl` 进行 API 访问

获取状态

curl http://192.168.1.100/api/status

更新 WiFi 配置

curl -X POST http://192.168.1.100/api/config \
  -H "Content-Type: application/json" \
  -d '{"wifi_ssid":"MyNetwork","wifi_pass":"MyPassword"}'

捕获照片

curl -o captured.jpg http://192.168.1.100/capture

重启设备

curl -X POST http://192.168.1.100/api/reboot

串口监视器命令

通过 USB 连接（COM8）：

# 帮助命令
help

# 获取当前配置
get config

# 重启设备
reboot

# 恢复出厂设置
reset

常见问题排查

WiFi 连接问题

检查凭据：验证 SSID 和密码是否正确
仅限 2.4GHz：确保您的路由器支持 2.4GHz WiFi
信号强度：如果信号弱，移近路由器
AP 模式回退：如果 STA 失败，设备自动进入 AP 模式

摄像头问题

无视频：检查摄像头模块是否正确安装
图像失真：检查摄像头镜头和连接
分辨率问题：从 VGA 开始以获得稳定性
PSRAM 错误：确保安装了 4MB PSRAM 且正常工作

SD 卡问题

未检测到：尝试不同的 SD 卡或重新插入
文件系统：使用 FAT32 格式化
读写错误：使用高质量的 SD 卡（Class 10+）
存储已满：清理旧照片或使用更大的卡

运动检测

太灵敏：增加阈值值
不够灵敏：降低阈值值
误触发：调整冷却时间
无检测：检查摄像头对焦和照明

性能优化

CPU 使用率

流传输：VGA 分辨率下约 15 FPS，占用约 40% CPU
运动检测：激活时约 5% CPU
空闲：约 2% CPU 使用率

内存管理

空闲堆栈：应保持 >20KB
PSRAM：摄像头使用最多 2.4MB
SPIFFS：Web 界面 ~500KB

电源节省

深度睡眠：不支持（摄像头需要连续电源）
电源管理：根据负载自动进行时钟调节
LED 控制：为节省电源可以禁用状态 LED

安全考虑

网络安全

WiFi 加密：推荐使用 WPA2
Web 界面：契约 v1.9（2026-09-18）起无设备级密码，信任边界是路由器的 WPA2
API 访问：契约 v1.9（2026-09-18）起全部端点免认证，在可信局域网内开放

数据安全

照片：存储在 SD 卡上本地

🔒 物理安全

重置方式：使用 Web 界面或 API 进行重置（BOOT 按钮已禁用）
LED 状态：系统健康状态的视觉指示
温度监控：自动热保护

用户指南

Web 界面访问

连接方式

STA 模式（推荐）

AP 模式（首次配置）

Web 界面页面

1. 仪表板（/）

2. 预览（/preview.html）

3. 配置（/config.html）

4. 文件（/files.html）

配置选项

WiFi 配置

摄像头配置

运动检测

时间配置

LED 状态指南

📁 SD 卡使用

支持的格式

文件组织

存储管理

亮度检测与智能闪光

工作原理

为什么不用传感器寄存器？

算法与公式

配置参数

亮度监控

运动检测

工作原理

配置

运动事件

📶 存储管理

命令行界面

命令行界面

使用 curl 进行 API 访问

获取状态

更新 WiFi 配置

捕获照片

重启设备

串口监视器命令

常见问题排查

WiFi 连接问题

摄像头问题

SD 卡问题

运动检测

性能优化

CPU 使用率

内存管理

电源节省

安全考虑

网络安全

数据安全

🔒 物理安全

提示和最佳实践

安放

维护

监控

支持和资源

文档

1. 仪表板（`/`）

2. 预览（`/preview.html`）

3. 配置（`/config.html`）

4. 文件（`/files.html`）

使用 `curl` 进行 API 访问