home-automation

frigate/README.md

@@ -0,0 +1,111 @@
+# Frigate
+
+## 🎥 Overview
+Frigate is an open-source network video recorder (NVR) with real-time AI-based object detection.  
+It is designed to work with IP cameras and integrates tightly with Home Assistant to provide smart, event-driven automations.
+
+## 🚀 What it does
+- Records video streams from IP cameras
+- Performs real-time object detection (people, animals, vehicles, etc.)
+- Generates events and snapshots based on detections
+- Provides a web UI for live view, recordings, and review
+- Integrates with MQTT and Home Assistant
+
+## 🌐 Website
+- https://frigate.video/
+
+## ⚙️ Features
+- Real-time object detection using TensorFlow Lite
+- Motion detection + object classification
+- RTSP camera support
+- Event-based recording (not just continuous)
+- Timeline and review UI
+- MQTT integration for automation
+- Multi-camera support
+
+## 🧠 AI Acceleration
+Frigate works best with hardware acceleration:
+
+- **Google Coral TPU (recommended)** → best performance, low power
+- CPU-only → works but limited performance
+- GPU acceleration (optional, more complex)
+
+## 📦 Kubernetes Deployment Notes
+- Requires:
+  - Persistent storage (recordings + config)
+  - Access to camera streams (RTSP)
+- Recommended setup:
+  - PVC for `/config` and `/media`
+  - Service + Ingress for web UI
+- Optional:
+  - Device passthrough for Coral TPU:
+    - `/dev/bus/usb` (USB Coral)
+- Considerations:
+  - High disk I/O (video recording)
+  - CPU usage if no accelerator is present
+
+## 📁 Storage Structure
+- `/config` → Frigate configuration (YAML)
+- `/media` → recordings, clips, snapshots
+
+## 🔌 Integrations
+- **Home Assistant** (native integration)
+- MQTT broker (required for event communication)
+- RTSP cameras (e.g. Reolink)
+
+## 🎥 Camera Integration
+Typical flow:
+
+Camera (RTSP)
+    ↓
+Frigate (detects objects)
+    ↓
+MQTT (events)
+    ↓
+Home Assistant (automations, notifications)
+
+## 🔐 Authentication
+- Built-in authentication for UI
+- Can be secured behind:
+  - Reverse proxy (Ingress / NGINX)
+  - SSO (e.g. Authentik via OAuth2 proxy)
+
+## ⚠️ Things to know
+- Object detection requires tuning for best results
+- CPU-only setups may struggle with multiple cameras
+- Storage grows quickly → plan retention policies
+- Requires stable RTSP streams from cameras
+
+## 🧠 Why use it
+- Local, privacy-friendly camera processing
+- Powerful AI detection without cloud dependency
+- Deep integration with Home Assistant
+- Efficient event-based recording
+
+## 🔧 Typical Stack in Undercloud
+- Frigate → NVR + AI detection
+- Home Assistant → automation + UI
+- MQTT (Mosquitto) → event bus
+- Reolink cameras → video source
+- Coral TPU (optional) → AI acceleration
+
+## 📝 Example Config Snippet
+```yaml
+mqtt:
+  host: mqtt.apps.undercloud.dev
+
+cameras:
+  living_room:
+    ffmpeg:
+      inputs:
+        - path: rtsp://user:password@camera-ip/stream
+          roles:
+            - detect
+            - record
+    detect:
+      enabled: true
+    objects:
+      track:
+        - person
+        - dog
+        - cat