diff --git a/Frigate/README.md b/Frigate/README.md new file mode 100644 index 0000000..6202b7a --- /dev/null +++ b/Frigate/README.md @@ -0,0 +1,201 @@ +# Frigate on Raspberry Pi 5 with a USB Google Coral + +A ready-to-use Frigate NVR deployment for a Raspberry Pi 5 using a USB Google +Coral EdgeTPU for hardware-accelerated object detection. + +Based on the official Frigate documentation: https://docs.frigate.video/ + +--- + +## What's in this folder + +``` +frigate/ +├── docker-compose.yml # Container definition (USB Coral passthrough, ports, volumes) +├── config/ +│ └── config.yml # Frigate configuration (detector, cameras, recording) +├── storage/ # Recordings, snapshots, and exports live here +└── README.md # This file +``` + +--- + +## Before you start — hardware notes + +- **Power the Pi properly.** Use the official 27W USB-C supply for the Pi 5. +- **The USB Coral is power-hungry.** If you also attach a USB SSD or other USB + devices, the Pi may not supply enough power and you'll get instability. Use a + **powered external USB hub** in that case. +- **Plug the Coral into a USB 3.0 (blue) port**, ideally through the powered hub. +- **No hardware video decode on the Pi 5.** Unlike the Pi 4, the Pi 5 does not + expose a `/dev/video11` decoder for Frigate, so camera decoding runs on the + CPU. Keep camera count and detect resolution modest, and use camera + **substreams** for the detect role (the included config already does this). + +--- + +## Step 1 — Prepare the OS + +Use a **64-bit** Debian-based OS (Raspberry Pi OS 64-bit, Bookworm or Trixie). +Flash it, boot, then update: + +```bash +sudo apt update && sudo apt full-upgrade -y +sudo reboot +``` + +## Step 2 — Install Docker and Docker Compose + +```bash +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +``` + +Add your user to the `docker` group so you don't need `sudo` each time: + +```bash +sudo usermod -aG docker $USER +``` + +Log out and back in (or reboot) for the group change to apply, then verify: + +```bash +docker --version +docker compose version +``` + +## Step 3 — Connect and verify the USB Coral + +Plug the Coral in (USB 3.0 port, powered hub if you have other USB devices). +The Frigate container ships with the EdgeTPU libraries built in, so you do **not** +need to install any Coral runtime on the host — passing `/dev/bus/usb` into the +container (already configured in `docker-compose.yml`) is enough. + +Confirm the host sees it: + +```bash +lsusb +``` + +A freshly plugged Coral appears as `Global Unichip Corp.`; after it runs +inference once it re-enumerates as `Google Inc.`. Either is fine. + +## Step 4 — Put these files on the Pi + +Copy this entire `frigate/` folder to the Pi (e.g. to your home directory so it +lives at `~/frigate`). You can use `scp`, a USB stick, or `git`. + +```bash +cd ~/frigate +``` + +## Step 5 — Set your shm-size (shared memory) + +Frigate stores decoded frames in shared memory. Calculate the minimum per camera +using your **detect** resolution (this example is 720p, including logs): + +```bash +python3 -c 'print("{:.2f}MB".format((1280 * 720 * 1.5 * 20 + 270480) / 1048576 + 40))' +# ~66.63MB for one 720p camera +``` + +Multiply the per-camera portion by your number of cameras and add ~40MB for +logs. The provided `docker-compose.yml` uses `512mb`, which comfortably covers +several cameras. Adjust the `shm_size` value if needed. + +## Step 6 — Edit the config for your cameras + +Open `config/config.yml` and update: + +- **Camera RTSP URLs** — replace `user`, `password`, IP, and stream paths with + your camera's real values. The RTSP path format varies by manufacturer. +- **`detect` width/height** — must match the resolution of the stream assigned + the `detect` role. +- **MQTT** — set `enabled: true` and fill in the host if you use Home Assistant. + +Also change `FRIGATE_RTSP_PASSWORD` in `docker-compose.yml` from `password` to +something of your own. + +## Step 7 — Start Frigate + +```bash +cd ~/frigate +docker compose up -d +``` + +Follow the logs to confirm a clean startup and that the Coral was found: + +```bash +docker logs -f frigate +``` + +Look for the EdgeTPU being detected and an inference speed (typically ~8–15ms on +a USB Coral). Press `Ctrl+C` to stop following the logs. + +## Step 8 — Open the web UI + +``` +https://:8971 +``` + +On first launch Frigate creates an admin account. Check the container logs for +the initial password, log in, and change it. + +--- + +## Verifying the Coral is actually being used + +In the web UI, open the **System / Metrics** page. Your `coral` detector should +be listed with an inference speed and a detection FPS. If the inference speed is +very high (hundreds of ms), detection is running on CPU and the Coral is not +being used properly — see troubleshooting below. + +## Troubleshooting: Coral not detected + +Try these in order: + +1. Restart the container: `docker compose restart` +2. Unplug/replug the Coral, then restart. +3. Use a **powered USB hub** if other USB devices are attached — power + starvation is the most common cause of instability on the Pi. +4. Try a different USB port; prefer USB 3.0 (blue). +5. Confirm `lsusb` shows the Global Unichip or Google device. + +Official EdgeTPU troubleshooting: https://docs.frigate.video/troubleshooting/edgetpu + +--- + +## Updating Frigate later + +```bash +cd ~/frigate +docker compose pull +docker compose up -d +``` + +## Useful commands + +```bash +docker compose up -d # start (detached) +docker compose down # stop and remove the container +docker compose restart # restart +docker logs -f frigate # follow logs +``` + +--- + +## Ports reference + +| Port | Purpose | +|------|----------------------------------------------------| +| 8971 | Authenticated web UI + API (use this) | +| 5000 | Internal unauthenticated UI/API (expose carefully) | +| 8554 | RTSP restreaming | +| 8555 | WebRTC (two-way talk), TCP + UDP | + +## Documentation + +- Installation: https://docs.frigate.video/frigate/installation +- Object detectors (Coral): https://docs.frigate.video/configuration/object_detectors +- Full config reference: https://docs.frigate.video/configuration/reference +- Camera setup: https://docs.frigate.video/frigate/camera_setup diff --git a/Frigate/config.yml b/Frigate/config.yml new file mode 100644 index 0000000..7d8e77a --- /dev/null +++ b/Frigate/config.yml @@ -0,0 +1,51 @@ +mqtt: + enabled: false # set to true and fill in host below if you use Home Assistant / MQTT + # host: 192.168.1.10 + # port: 1883 + # user: mqtt_user + # password: mqtt_password + +detectors: + coral: + type: edgetpu + device: usb # single USB Coral. Uses the bundled Mobiledet model by default. + +cameras: + camera_1: + ffmpeg: + inputs: + # Full-resolution main stream -> used for recording + - path: rtsp://user:password@192.168.1.50:554/stream1 + roles: + - record + # Lower-resolution substream -> used for detection (saves CPU on the Pi 5) + # If your camera has no substream, delete this block and add "detect" + # to the roles list above instead. + - path: rtsp://user:password@192.168.1.50:554/stream2 + roles: + - detect + detect: + width: 1280 # must match your detect (sub)stream resolution + height: 720 + fps: 5 + +record: + enabled: true + retain: + days: 7 + mode: motion + +snapshots: + enabled: true + retain: + default: 14 + +# Objects to track. Defaults to person if omitted. +objects: + track: + - person + - car + - cat + - dog + +version: 0.16-0 diff --git a/Frigate/docker-compose.yml b/Frigate/docker-compose.yml new file mode 100644 index 0000000..8bdb5c6 --- /dev/null +++ b/Frigate/docker-compose.yml @@ -0,0 +1,26 @@ +services: + frigate: + container_name: frigate + privileged: true # simplifies USB Coral access; can be tightened later + restart: unless-stopped + stop_grace_period: 30s + image: ghcr.io/blakeblackshear/frigate:stable + shm_size: "512mb" # adjust per the calculation in the README (Step 5) + devices: + - /dev/bus/usb:/dev/bus/usb # passes the USB Coral into the container + volumes: + - /etc/localtime:/etc/localtime:ro + - ./config:/config + - ./storage:/media/frigate + - type: tmpfs # 1GB in-memory cache for recording segments + target: /tmp/cache + tmpfs: + size: 1000000000 + ports: + - "8971:8971" # authenticated UI + API + # - "5000:5000" # internal unauthenticated access — expose carefully + - "8554:8554" # RTSP restreaming + - "8555:8555/tcp" # WebRTC over TCP + - "8555:8555/udp" # WebRTC over UDP + environment: + FRIGATE_RTSP_PASSWORD: "password" # change this diff --git a/Frigate/frigate.tar.gz b/Frigate/frigate.tar.gz new file mode 100644 index 0000000..b5f01a8 Binary files /dev/null and b/Frigate/frigate.tar.gz differ diff --git a/Frigate/frigate.zip b/Frigate/frigate.zip new file mode 100644 index 0000000..279499a Binary files /dev/null and b/Frigate/frigate.zip differ