camera

📖 Project Wiki: CammyCam Scalable IoT Camera System

Repo: github.com/iamfatben/camera Stack: ESP32 S3 (Arduino/C++), FastAPI Hub (Docker or Metal), Vite + Vue (Frontend)

✈️ 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
Glossary	Terminology reference

---

🌲 Project Overview

A modular IoT camera system with a cozy, retro feel.

• 🧠 ESP32 S3 cameras run in standalone mode or connect to a hub service (Docker/Pi/native).
• 📡 Hub (optional) aggregates multiple cameras and provides storage, OTA updates, and diagnostics.
• 🖼 Web UI (Vite + Vue) served from ESP SD card or via the hub’s backend.
• 🔦 Camera-only mode works without an SD card for quick wireless use.
• 🔁 Real-time video, snapshots, retention settings, and local/offloaded storage are all built-in.
• ⚙️ Default ESP32 camera resolution is VGA (640x480) for predictable memory usage.
• 🔒 Wi-Fi credentials are stored encrypted with AES-CTR and HMAC integrity.
• 📶 Optional backup SSID and AP fallback keep cameras reachable when the main network fails.
• 🔔 MQTT events integrate cameras with Home Assistant.

Progress on major features is tracked in Status Tracker. Additional reference material is available in the docs/ directory. See Unit Testing for how to run the project’s test suites and collect coverage reports.

🚀 Quick Start

# create venv and install hub requirements
python3 -m venv .venv
source .venv/bin/activate
pip install -r pi/requirements.txt
cd pi && ../start-local.sh

start-local.sh launches the hub over HTTPS and advertises the address defined by the CAMMY_NAME environment variable (defaults to a unique cammy-<id>.local). If generating certificates manually, run mkcert and move the files to certs/cammy.local.pem and certs/cammy.local-key.pem before starting the server.

Local Setup (Ubuntu/WSL)

Run the helper script to install packages, trust the local CA and create a Python environment:

./install-deps.sh
source .venv/bin/activate
./start-local.sh

install-deps.sh installs avahi-daemon, avahi-utils, and dbus so avahi-publish is available for mDNS announcements.

Run python tools/setup_cammy_env.py to prepare the virtual environment and Node packages before starting the hub.

The script reads CAMMY_NAME from .env if present to generate certificates. On WSL you may need to add 127.0.0.1 cammy.local to C:\Windows\System32\drivers\etc\hosts when mDNS resolution fails. CAMMY_TZ can be set to control the time zone for token expiration timestamps (default America/New_York).

Serve the UI for development:

cd ui
npm install
npm run dev

Build and flash the firmware using PlatformIO:

cd esp/esp32-cammycam
pio run -t upload

Build the Docker Image

Use the Python helper to compile the UI, create certificates and build the container:

python tools/build_docker.py

📂 Folder Structure

camera/
├── esp/           # ESP32 firmware (PlatformIO)
├── pi/            # FastAPI hub backend
│   └── localcam/  # Optional USB camera helper
├── ui/            # Vue 3 frontend
├── docs/          # Documentation site
└── tools/         # Helper scripts and launcher

🧪 Testing

Run the checks before committing:

cd esp/esp32-cammycam && pio test && cd ../../
cd pi && pytest -q && cd ..
python tools/run_pylint.py  # lint all Python files
cd ui && npm run build && cd ..

Coverage details are described in Unit Testing.

📈 Status Tracking

Progress on features and milestones is maintained in Status Tracker.

API Docs

Once the hub is running visit https://localhost/login to sign in. After logging in you can open the API docs at /api-docs.

🪧 Cozy Cabin Style

All components follow the Cozy Cabin Style Guide:

• Warm Cabin Cream backgrounds, bold Fire Orange CTAs, green Deep Forest success cues.
• Typography: Montserrat, Roboto, Fredoka One.
• Big rounded buttons, soft shadows, and visual warmth.

📬 Contributing

Patches are welcome for personal use. Please follow the coding style in located here and run tests before opening a pull request.