camera

🎯 MVP: Scalable IoT Camera System (CammyCam)

Supports standalone ESP32 camera operation and optional hub aggregation (Docker, Pi, or bare metal).

✈️ Table of Pages

Below is a quick reference table of the main documentation pages.

Page	Description
What Sets it Apart	Why you should just do it yourself and the cost
MVP	High level project goals and summary
Status Tracker	Feature progress table
Unit Testing	Test and coverage instructions
Build It Yourself	Clone & Docker setup guide
Firmware	Firmware API reference
Hub Guide	Hub API reference
Communication Methods	Communication and architecture

---

📦 Project Summary

This project builds a modular, scalable IoT camera system using Seeed Studio XIAO ESP32 S3 Sense boards and an optional hub (e.g. Raspberry Pi 5 or any Docker-capable host).

• Each ESP32 functions independently and provides a WebSocket-enabled video stream and snapshot UI.
• A “hub” can optionally aggregate, relay, and manage multiple ESP32 cameras over a private or local network.
• The hub runs a FastAPI backend, exposing REST/WebSocket APIs, diagnostics, and user management.

See Status Tracker for up-to-date progress on these features.

---

🖼 UI Style and Vibe

All UI interfaces follow the Cozy Cabin Style Guide, featuring warm, woodgrain-inspired themes with relaxing, friendly components.

---

⚙️ Hardware Inventory

Cameras

• 3x Seeed Studio XIAO ESP32 S3 Sense
  • 2.4GHz Wi-Fi, BLE 5.0
  • OV2640 Camera, Digital Mic
  • 8MB PSRAM/Flash, Micro SD

Hub/Server (Optional)

• 1x Raspberry Pi 5 (4GB RAM)
  • Dual-band Wi-Fi, HDMI, PCIe, RTC
  • microSD (128GB) or NVMe boot

Power

• 15x TP4056 5V 1A Type-C Charging Modules (with battery protection)
• 10x 5V 30mA Mini Solar Panels (53mm x 30mm)

---

🧠 Core Architecture

Mode	Description
Standalone	ESP32 starts in Soft AP mode with full local UI and config
Hub Mode	ESP32 connects to user-provided SSID and syncs with a hub server
Hub	Runs FastAPI backend (on Pi, Docker, or metal) to manage cameras

---

🎯 MVP Features

ESP32 Camera (Standalone & Fallback)

• Soft AP mode (cammy-setup) with captive UI for first-time config
• Web UI via SD card:
  • Live video stream
  • Snapshots (JPEG)
  • Configuration interface:
    • Wi-Fi settings
    • Frame rate adjustment
    • Video retention (10–120 seconds)
    • Hub IP/SSID entry
  • SD card diagnostics (space left, file list)
  • Download MP4/JPEG files
• Local recording to SD card:
  • Snapshots as JPEG
  • Video as MP4
• Optional hub connection:
  • Manual join/leave UI
  • Reconnect retries on boot

---

Hub Mode (Optional Pi/Docker Aggregator)

Not hardware-dependent: can run on Raspberry Pi, bare metal, or inside Docker.

• Hosts FastAPI backend with:
  • Camera registry and discovery (manual for now)
  • Real-time video relay (WebSocket)
  • Camera management APIs (register, update, delete)
  • Snapshot and video aggregation
  • OTA firmware management
  • REST API for control, sync, config
• UI includes:
  • Diagnostics dashboard
  • Storage & SD card visibility
  • Battery and solar status (if available)
  • Event notifications (camera offline, battery low, OTA ready)

---

📡 Communication & Streaming

Type	Protocol	Notes
Video Stream	WebSocket	Real-time, low-latency MJPEG or raw
Commands	REST API	JSON-based control and config
File Sync	HTTP/POST	ESP32 can push videos/snapshots to hub

---

🔒 Security & Networking

• ESP32 runs in unauthenticated fallback mode (isolated AP)
• Hub enforces authentication (JWT/session):
  • Admin: full access
  • Super: settings/download
  • Viewer: read-only
• WebSocket streams use an ECDH handshake with AES encryption
• Wi-Fi passwords are encrypted with AES-CTR and an HMAC for integrity
• Backup SSID and optional AP fallback keep cameras online when the primary network fails
• Default subnet (when private): 192.168.3.0/29
• No IPv6
• No WAN/internet access unless configured

---

🔋 Power Management

• ESP32s powered by 18650 Li-ion via TP4056
• Optional mini solar panels connected to TP4056 input
• Battery stats via ADC (pin TBD in final schematic)
• Diagnostics UI displays:
  • Battery %
  • Charging status
  • Solar charging (if applicable)

---

🔄 Deployment & Updates

• ESP32 UI served from SD card (precompiled Vite frontend)
• Hub can serve UI via FastAPI StaticFiles or Nginx container
• OTA firmware hosted and delivered by Hub
  • Tracks versions and enables safe rollback (dual partition)

---

👤 Users & Roles

• Default user: admin / cammy-cam
• Role-based access:
  • Admin: Full control
  • Super: Can update settings, trigger OTA
  • Viewer: View-only access
• First login enforces password reset

---

🔍 Diagnostics & Logging

• Hub UI shows:
  • Connected ESP32s and status
  • Last heartbeat + last file sync
  • Wi-Fi signal strength
  • Storage/SD usage
  • Battery diagnostics
  • OTA logs and UI notifications

---

❓ What’s Not Finalized Yet (TBD)

• Battery ADC pin definition
• OTA update UX flow
• Future network auto-discovery (mDNS/SSDP)
• Webhook/API for third-party integrations (e.g., Home Assistant, Discord)
• Hub Docker packaging and deployment

---

🧱 Stack

Component	Stack
ESP32	Arduino/C++, CameraWebServer, WebSocket+REST
Hub	Python 3.12+, FastAPI, async, OpenAPI docs
Frontend	Vite, Vue, Cozy Cabin UI
Media	MP4 (video), JPEG (snapshots)

---

🛠 Development & Next Steps

• All code and documentation are maintained at: https://github.com/iamfatben/camera
• Finalize pinouts and battery reporting
• Complete OTA update flow and version tracking
• Package the hub for Docker deployment
• Optimize frontend components for ESP vs. Hub deployment