Frigate/README.md

# 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://<your-pi-ip>: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