跳过导航，直接进入主要内容跳过导航，直接进入主要内容跳过导航，直接进入主要内容

ESP32 ESP-IDF OV2640 License

🌐 English Documentation

API 参考文档

本文档提供 MiBee Cam 固件 REST API 的完整参考，包括所有端点、参数和示例。

概述

MiBee Cam 提供 RESTful API 接口，允许通过 HTTP 请求控制和监控系统。API 支持以下功能：

  • 设备状态监控：获取系统健康信息、网络状态和指标
  • 配置管理：更新 WiFi、摄像头和其他设置
  • 文件管理：SD 卡照片浏览、下载和删除
  • 视频流：实时 MJPEG 流传输
  • 录像控制：启动/停止 AVI 视频录制
  • 运动检测：帧差分运动检测和拍照

API 基础信息

基础 URL

  • STA 模式：http://<设备-ip>/
  • AP 模式：http://192.168.4.1/

重要说明

⚠️ 摄像头初始化工作流程：为了解决 ESP32 已知的 DMA 冻结问题，固件采用"先启动 WiFi STA 模式，在回调中初始化摄像头"的策略。启动时会延迟 1-2 秒进行摄像头初始化。

认证

契约 v1.9（2026-09-18）起的固件没有设备级密码：Web 管理密码（X-Password 头与 /api/auth 流程）已移除。所有 HTTP 端点在可信局域网内开放，信任边界是路由器的 WPA2。

响应格式

  • 成功响应：HTTP 200 + JSON 数据
  • 错误响应：HTTP 400/500 + 错误消息
  • 流响应：HTTP 200 + multipart/x-mixed-replace 数据

常见错误代码

代码 描述
200 成功
400 请求参数错误
404 资源未找到
500 服务器内部错误

设备状态 API

/api/status - 获取设备状态

获取设备完整状态信息。

请求

GET /api/status
Host: 192.168.1.100

响应

{
  "status": "running",
  "hostname": "MiBeeCam",
  "uptime": 86400,
  "wifi": {
    "mode": "STA",
    "connected": true,
    "ssid": "MyWiFi",
    "bssid": "AA:BB:CC:DD:EE:FF",
    "ip": "192.168.1.100",
    "signal": -45,
    "connected_time": 3600,
    "ssid_2": "",
    "pass_2": "",
    "allow_ap_fallback": false
  },
  "camera": {
    "resolution": "VGA",
    "fps": 15,
    "quality": 12,
    "format": "JPEG",
    "buffer": 0.6,
    "status": "active"
  },
  "storage": {
    "sd_card": {
      "present": true,
      "total": 15892485120,
      "used": 5242880,
      "available": 15887252240,
      "percent_used": 0.033
    }
  },
  "motion": {
    "enabled": true,
    "detected": false,
    "last_event": "2024-12-30T14:30:25Z",
    "total_events": 125
  },
  "system": {
    "temperature": 45.2,
    "heap": 45012,
    "stack_watermark": 2048,
    "psram": 0,
    "time": "2024-12-30T14:35:42Z",
    "timezone": "CST-8",
    "config_version": 9,
    "config_magic": 2864434392
  }
}

字段说明

  • status: 设备状态 (running, ap_mode, error)
  • uptime: 运行时间（秒）
  • wifi: WiFi 连接详细信息
  • camera: 摄像头状态信息
  • storage: 存储使用情况
  • motion: 运动检测状态
  • system: 系统指标和时间

配置 API

/api/config - 获取配置

获取当前系统配置。

请求

GET /api/config
Host: 192.168.1.100

响应

{
  "wifi_ssid": "MyWiFi",
  "wifi_pass": "MyPassword",
  "device_name": "MiBeeCam",
  "resolution": 0,
  "fps": 15,
  "jpeg_quality": 12,
  "timezone": "CST-8",
  "motion_threshold": 30,
  "motion_cooldown": 5,
  "vflip": 0,
  "wifi_tx_power": 80,
  "flash_threshold": 40,
  "timelapse_enabled": 0,
  "timelapse_interval_s": 60,
  "timelapse_burst_count": 3,
  "record_mode": 0,
  "allow_ap_fallback": false
}

注意：密码字段不会在响应中返回。

/api/config - 更新配置

更新系统配置。

请求

POST /api/config
Host: 192.168.1.100
Content-Type: application/json

{
  "wifi_ssid": "NewNetwork",
  "wifi_pass": "NewPassword",
  "resolution": 1,
  "motion_threshold": 25
}

参数

  • wifi_ssid: WiFi 网络名称
  • wifi_pass: WiFi 密码
  • device_name: 设备主机名
  • resolution: 分辨率 (0=VGA, 1=SVGA, 2=XGA, 3=UXGA)
  • fps: 帧率目标
  • jpeg_quality: JPEG 质量 (0-63，数字越小质量越高)
  • timezone: 时区字符串
  • motion_threshold: 运动检测阈值 (1-100)
  • motion_cooldown: 运动检测冷却时间（秒）
  • vflip: 垂直翻转 (0=关闭, 1=开启)
  • wifi_tx_power: WiFi 发射功率 (0-80，80=20dBm)
  • flash_threshold: 闪光阈值 (0-100)
  • record_mode: 录像模式 (0=关闭, 1=连续, 2=延时, 3=动态)
  • allow_ap_fallback: 是否允许 AP 模式回退

响应

{
  "success": true,
  "message": "Configuration updated successfully",
  "needs_reboot": true
}

摄像头 API

/capture - 捕获照片

捕获单张 JPEG 照片。

请求

GET /capture
Host: 192.168.1.100

响应

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45232

[JPEG 二进制数据]

/stream - MJPEG 流

提供实时 MJPEG 视频流。

请求

GET /stream
Host: 192.168.1.100

响应

HTTP/1.1 200 OK
Content-Type: multipart/x-mixed-replace; boundary=frame
Connection: keep-alive

--frame
Content-Type: image/jpeg

[JPEG 帧数据 1]
--frame
Content-Type: image/jpeg

[JPEG 帧数据 2]
--frame
Content-Type: image/jpeg

[JPEG 帧数据 3]

文件管理 API

/api/files - 列出文件

获取 SD 卡上的照片文件列表。

请求

GET /api/files?limit=10&offset=0
Host: 192.168.1.100

参数

  • limit: 返回的文件数量（可选，默认 20）
  • offset: 分页偏移量（可选，默认 0）

响应

{
  "files": [
    {
      "name": "2024-12-30_14-35-42.jpg",
      "size": 45232,
      "timestamp": 1735565742
    },
    {
      "name": "2024-12-30_14-30-25.jpg",
      "size": 38421,
      "timestamp": 1735565425
    }
  ],
  "total": 125,
  "limit": 10,
  "offset": 0
}

/api/files - 删除文件

删除 SD 卡上的照片文件。

请求

DELETE /api/files?name=2024-12-30_14-35-42.jpg
Host: 192.168.1.100

参数

  • name: 要删除的文件名（必需）

响应

{
  "success": true,
  "message": "File deleted successfully"
}

/api/download - 下载文件

下载 SD 卡上的照片文件。

请求

GET /api/download?name=2024-12-30_14-35-42.jpg
Host: 192.168.1.100

参数

  • name: 要下载的文件名（必需）

响应

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: attachment; filename="2024-12-30_14-35-42.jpg"
Content-Length: 45232

[JPEG 二进制数据]

录像控制 API

/api/record - 启动/停止录像

启动或停止视频录制。

请求

POST /api/record?action=start
Host: 192.168.1.100

参数

  • action: start 或 stop（必需）

响应

{
  "success": true,
  "message": "Recording started",
  "mode": "continuous"
}

Curl 示例

# 启动连续录像
curl -X POST "http://192.168.1.100/api/record?action=start"

# 停止录像
curl -X POST "http://192.168.1.100/api/record?action=stop"

/api/record - 获取录像状态

返回录像状态和信息。

请求

GET /api/record
Host: 192.168.1.100

响应

{
  "recording": true,
  "mode": "continuous",
  "duration": 3600,
  "segments": 12,
  "total_size": 125829120,
  "current_file": "rec_2024-12-30_14-30-25.avi"
}

存储管理 API

/api/storage - 获取存储状态

返回存储使用情况和清理状态。

请求

GET /api/storage
Host: 192.168.1.100

响应

{
  "sd_card": {
    "available": true,
    "total": 31457280,
    "free": 15728640,
    "used": 15728640,
    "photo_count": 25,
    "video_count": 3
  },
  "cleanup": {
    "photo_threshold": 20,
    "video_threshold": 10,
    "last_cleanup": "2024-12-30T14:30:00Z"
  }
}

延时摄影 API

/api/timelapse/start - 启动延时摄影

启动延时摄影。

请求

POST /api/timelapse/start
Host: 192.168.1.100

响应

{
  "success": true,
  "message": "Timelapse started",
  "interval": 60,
  "burst_count": 3
}

/api/timelapse/stop - 停止延时摄影

停止延时摄影。

请求

POST /api/timelapse/stop
Host: 192.168.1.100

响应

{
  "success": true,
  "message": "Timelapse stopped"
}

/api/timelapse/status - 获取延时摄影状态

返回延时摄影状态。

请求

GET /api/timelapse/status
Host: 192.168.1.100

响应

{
  "enabled": true,
  "running": true,
  "interval": 60,
  "burst_count": 3,
  "photos_taken": 45,
  "last_photo": "2024-12-30_14-30-25.jpg"
}

系统管理 API

/api/flash - 控制闪光灯

控制 LED 闪光灯。

请求

POST /api/flash
Host: 192.168.1.100

响应

{
  "success": true,
  "message": "Flash control executed"
  "flash_state": "auto"
}

/api/reboot - 重启设备

重启设备。

请求

POST /api/reboot
Host: 192.168.1.100

响应

{
  "success": true,
  "message": "Rebooting device",
  "restart_time": 5
}

/api/reset - 恢复出厂设置

恢复出厂设置。

注意：BOOT 按钮工厂重置功能已禁用，因为 GPIO0 被用作摄像头 XCLK 引脚。请使用此 API 端点进行重置。

请求

POST /api/reset
Host: 192.168.1.100

响应

{
  "success": true,
  "message": "Factory reset completed",
  "restart_time": 3
}

监控和指标 API

/api/metrics - Prometheus 指标

提供兼容 Prometheus 格式的系统指标。

请求

GET /api/metrics
Host: 192.168.1.100

响应

# HELP esp32_heap_free Heap memory free bytes
# TYPE esp32_heap_free gauge
esp32_heap_free 45012

# HELP esp32_stack_watermark Stack watermark in bytes
# TYPE esp32_stack_watermark gauge
esp32_stack_watermark 2048

# HELP esp32_temperature Temperature in Celsius
# TYPE esp32_temperature gauge
esp32_temperature 45.2

# HELP wifi_signal_strength WiFi signal strength in dBm
# TYPE wifi_signal_strength gauge
wifi_signal_strength -45

# HELP esp32_uptime System uptime in seconds
# TYPE esp32_uptime counter
esp32_uptime 86400

# HELP motion_events_total Total motion detection events
# TYPE motion_events_total counter
motion_events_total 125

# HELP photos_taken_total Total photos taken
# TYPE photos_taken_total counter
photos_taken_total 245

cURL 使用示例

基本状态检查

# 获取设备状态
curl -s http://192.168.1.100/api/status | jq .

# 获取配置
curl -s http://192.168.1.100/api/config | jq .

配置管理

# 更新配置
curl -X POST http://192.168.1.100/api/config \
  -H "Content-Type: application/json" \
  -d '{"wifi_ssid":"MyNetwork","wifi_pass":"MyPass","resolution":1}'

摄像头控制

# 捕获照片
curl http://192.168.1.100/capture -o photo.jpg

# 查看流（在浏览器中打开）
# http://192.168.1.100/stream

文件管理

# 列出文件
curl -s "http://192.168.1.100/api/files?limit=5" | jq .

# 下载文件
curl -o photo.jpg "http://192.168.1.100/api/download?name=2024-12-30_14-35-42.jpg"

# 删除文件
curl -X DELETE "http://192.168.1.100/api/files?name=2024-12-30_14-35-42.jpg"

录像控制

# 启动录像
curl -X POST "http://192.168.1.100/api/record?action=start"

# 停止录像
curl -X POST "http://192.168.1.100/api/record?action=stop"

# 查看录像状态
curl -s http://192.168.1.100/api/record | jq .

延时摄影

# 启动延时摄影
curl -X POST http://192.168.1.100/api/timelapse/start

# 停止延时摄影
curl -X POST http://192.168.1.100/api/timelapse/stop

# 查看延时状态
curl -s http://192.168.1.100/api/timelapse/status | jq .

系统管理

# 控制闪光灯
curl -X POST http://192.168.1.100/api/flash

# 重启设备
curl -X POST http://192.168.1.100/api/reboot

# 恢复出厂设置
curl -X POST http://192.168.1.100/api/reset

# 获取 Prometheus 指标
curl -s http://192.168.1.100/api/metrics

错误处理

常见错误及解决方法

400 Bad Request

  • 原因：请求参数错误
  • 解决：检查请求格式和参数

404 Not Found

  • 原因：端点不存在
  • 解决：检查 API 路径

500 Internal Server Error

  • 原因：服务器内部错误
  • 解决：查看设备日志，检查资源使用情况

错误响应格式

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}

安全注意事项

  • 信任边界：契约 v1.9（2026-09-18）起设备无 Web 密码，边界在路由器的 WPA2
  • HTTPS：当前不支持，建议在专用网络中使用
  • 网络隔离：将设备放在专用网络中
  • 访问控制：限制 API 访问 IP 范围
  • 定期更新：保持固件最新版本以修复安全漏洞

GPIO14 共享引脚说明

⚠️ 重要提醒：GPIO14 引脚在 MiBee Cam 上被摄像头和 SD 卡共享使用（摄像头 XCLK 和 SD 卡 CLK）。固件采用严格的初始化顺序来解决冲突：SD 卡初始化 → 摄像头初始化 → SD 卡重新初始化。如果遇到相关功能异常，请检查此引脚连接。

API 终端列表

终端 方法 描述
/api/status GET 设备状态和传感器数据
/api/config GET 当前配置 JSON
/api/config POST 更新配置
/api/flash POST 控制 LED 闪光灯
/api/reboot POST 重启设备
/api/reset POST 恢复出厂设置
/api/metrics GET Prometheus 指标
/capture GET 单 JPEG 捕获
/stream GET MJPEG 视频流
/api/files GET 列出 SD 卡照片
/api/download GET 下载照片
/api/files DELETE 删除照片
/api/record POST 录像控制（启动/停止）
/api/record GET 录像状态和信息
/api/storage GET 存储使用情况
/api/timelapse/start POST 启动延时摄影
/api/timelapse/stop POST 停止延时摄影
/api/timelapse/status GET 延时摄影状态
可访问性增强功能已加载，支持焦点管理、键盘导航和屏幕阅读器