Frigate and Home Assistant

Introduction

Home Assistant is a free and open-source software for home automation designed to be a central control system for smart home devices with a focus on local control and privacy.

Frigate is an open source NVR built around real-time AI object detection.

A quick note about hardware

While it is possible to run this set-up in a virtualised environment (e.g. ProxMox), and I did while I was testing, it is not recommended. For this reason, I picked up a Dell Optiplex 5050 with an i5-6500, 8GB RAM and 500GB disk space; which cost me ~£50.

As Frigate can utilise QuickSync, I was firm on not getting anything older than Skylake which added H.265/HEVC support (ref).

Installing Docker

Both Home Assistant and Frigate can be run in Docker containers, and doing so is the recommended install method for Frigate, so first we need to install Docker.

# update existing list of packages
sudo apt update
# install a few prerequisite packages which let apt use packages over HTTP
sudo apt install apt-transport-https ca-certificates curl software-properties-common
# add the GPG key for the official Docker repository to your system
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# add the Docker repository to APT sources
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# update your existing list of packages again for the addition to be recognized
sudo apt update
# make sure you are about to install from the Docker repo instead of the default Ubuntu repo
apt-cache policy docker-ce
# install Docker
sudo apt install docker-ce

Docker should now be installed, the daemon started, and the process enabled to start on boot. You can check it is running with sudo systemctl status docker

Executing the Docker Command Without Sudo

# add your username to the docker group
sudo usermod -aG docker ${USER}
# apply the new group membership
su - ${USER}
# confirm that your user is added to the docker group
groups

Install Docker Compose

# download Docker Compose
mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.3.3/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
# make it executable
chmod +x ~/.docker/cli-plugins/docker-compose
# check it was successful
docker compose version

Install Home Assistant

In a location of your choosing, create a docker-compose.yaml file; I have opted to create a docker directory, in my home directory (~/docker). Within that file, add the following:

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: 'ghcr.io/home-assistant/home-assistant:stable'
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

Save, exit the file, and run docker compose up -d to download the homeassistant image and start the container. Once the container has started, open a browser and navigate to http://<serverIP>:8123 to set-up your Home Assistant installation.

Install MQTT broker

In your docker-compose.yaml file, add the following to set-up a MQTT broker.

version: '3'
services:
  homeassistant:
  ## ...

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto
    volumes:
      - /home/ubuntu/mosquitto/conf:/mosquitto/config
      - /home/ubuntu/mosquitto/data:/mosquitto/data
      - /home/ubuntu/mosquitto/log:/mosquitto/log
    restart: unless-stopped
    environment:
      - PUID=1000
        PGID=1000
    ports:
      - 1883:1883
      - 9001:9001

Next, in which ever location you have defined to hold conf, create a conf/mosquitto.conf file with the following contents:

listener 1883 0.0.0.0
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

## Authentication ##
# By default, Mosquitto >=2.0 allows only authenticated connections. Change to true to enable anonymous connections.
allow_anonymous false
password_file /mosquitto/config/password.txt

And a conf/password.txt file with the following contents, which sets up a default admin/password user.

admin:$7$101$cnSh5Ey47Rm/kO2o$deMGXkDTwIXDn0v8aSVyj8Dwel13Ob1If8dHaq8Nj+LMfsPl1sM9x4RdJBc8421Q72+qJBPFy50d5NMkUPzr1A==

By default, mosquitto will listen on port 1883 (MQTT).

To test that everything is set-up properly, download MQTT Explorer (or similar if it's not available on your operating system), and connect using your servers IP, port 1883, and the default admin/password credentials.

To change the admin password, run the following command and you will be prompted for the new password.

docker compose exec mosquitto mosquitto_passwd -c /mosquitto/config/password.txt admin

Then restart the container

docker restart mosquitto

Set-up Home Assistant MQTT integration

Within your Home Assistant UI (in the browser), navigate to Settings > Devices & Services > Add Integration. Search for MQTT, select it and configure the same connection information from when we used MQTT Explorer in the last step.

While in the Integration page, you can click Configure on the MQTT integration and public/listen to a topic, which you could test with MQTT Explorer to ensure everything is working so far.

Install Frigate

In your docker-compose.yaml file, add the following to set-up Frigate.

version: '3'
services:
  homeassistant:
    # ...

  mosquitto:
    # ...

  frigate:
    container_name: frigate
    image: blakeblackshear/frigate:stable
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /path/to/config.yml:/config/config.yml:ro
      - /path/to/media:/media/frigate
    restart: unless-stopped
    environment:
      FRIGATE_RTSP_PASSWORD: 'password'
    ports:
      - 5000:5000
      - 1935:1935
    privileged: true
    shm_size: '256mb'
    devices:
      - /dev/dri/renderD128

Next, in the location you have chosen for your config.yml file, create it and add the following contents (Note: Look out for the TODO's for where you need change the config).

mqtt:
  # TODO - change to your MQTT settings
  host: <host>
  user: <user>
  password: <password>

ffmpeg:
  # TODO - This is the Hardware Acceleration for Intel-based CPUs (<10th Generation) via Quicksync
  # check that this fits your use case - https://docs.frigate.video/configuration/hardware_acceleration
  hwaccel_args: -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format yuv420p

cameras:
  # You can create multiple cameras, by adding additional blocks after this camera
  # customise the camera name (camera_one) as you wish.
  camera_one:
    ffmpeg:
      # I use two streams for Frigate. A lower quality one for detection and a higher quality for recording.
      # Adjust as is necessary for your use case.
      inputs:
        # TODO - replace with your rtsp stream
        - path: <high quality rtsp stream>
          roles:
            - record
        # TODO - replace with your rtsp stream
        - path: <low quality rtsp stream>
          roles:
            - detect
            - rtmp
    detect:
      # TODO - ensure these values are correct for your detect stream. In my case, this is the low quality rtsp stream.
      width: 640
      height: 360
      fps: 5
    rtmp:
      enabled: True
    snapshots:
      enabled: True
    record:
      enabled: True
      # Keeps all recordings for two days
      retain:
        days: 2
      # Keeps event based recordings for ten days
      events:
        retain:
          default: 10

For additional configuration options, refer to the Frigate Docs.

Run docker compose up -d to start the Frigate container. Accessing Frigate on <server-ip>:5000 should show you your cameras. If you see green screens, start by looking at your logs by running docker logs frigate to see where the problem is coming from.

Debugging

The following are scenarios I have personally come across and am sharing here in the hopes it will help somebody out.

RTMP does not support H.265

If you see errors such as Video codec hevc not compatible with flv in the logs, check if your camera stream is outputting H.265. If it is, switch it to H.264 or turn RTMP off with:

rtmp:
  enabled: false

Home Assistant -> Frigate integration

You now have three services set-up.

Home Assistant, accessible on <server-ip>:8123
Frigate, accessible on <server-ip>:5000
MQTT, which you shouldn't need to access from now on

We can view our camera streams, recordings and snapshots, but it would be great if we also got mobile notifications when an event is picked up.

Note: These are the steps I perform on an iPhone; setting things up may differ for Android.

Mobile & User set-up

First, download the Home Assistant mobile application, select your server, and login.

Now, from the Home Assistant web application (in your browser), you should be able to go to Developer Tools > Services, search for mobile and you should see your phone in this list. Select it, and try sending a test notification. All being well, you'll receive the notification on your phone.

Repeat this step for as many phones as are needed (additional users can be set-up in Settings > People).

Keep a note of the Service name for all phones (e.g. notify.mobile_app_iphone).

Create a Notify Group

On your server, edit your Home Assistant config/configuration.yaml file and add the following, which create a notify group called all_phones:

notify:
  - name: 'all_phones'
    platform: group
    services:
      - service: mobile_app_iphone

Add as many services for phones you set-up in the last stage.

Restart the Home Assistant container with docker restart homeassistant, navigate to Developer Tools > Services and search/test for the notify group notify.all_phones. If that worked, you're ready to move onto the next stage.

Install HACS

First, enter the Home Assistant container with docker exec -it homeassistant bash and then run the HACS download script with wget -O - https://get.hacs.xyz | bash -.

Restart the container with docker restart homeassistant.

Next, go to Settings > Devices & Services > Add Integration > Search and install HACS, following the on-screen instructions.

Set-up the Frigate Integration

The Frigate integration is available via the default HACS repository. The install go to HACS > Integrations > HACS > Explore and Download Repositories > Frigate.

Restart the Home Assistant container with docker restart homeassistant.

Then add the integration by going to Settings > Devices & Services > Add Integration > Frigate.

Configuration > Integrations > Add Integration > Frigate > add your Frigate URL and press Submit.

All being well, you should be asked to add each of your cameras to Home Assistant. When you are done, press Finish.

Set-up notifications from Home Assistant

First, we need to set-up the blueprint. Go to https://github.com/SgtBatten/HA_blueprints for the latest version and instructions.

Next, go to Settings > Automation & Scenes > Create Automation. Select Frigate Notification (0.11.0.6) - SgtB as the Blueprint to use, choose the camera you would like to set-up notifications for (e.g. camera.back_garden), then either choose a single device, or use the notification group we set-up earlier (all_phones).

Configure other options as you see fit and press Save. Name your new automation and give it an optional description, then press Save again.

For my cameras, I enable Alert Once and Update Thumbnail, and set Trigger Objects to only notify me of person objects.

Now, next time your camera spots someone, you should get a mobile notification!

Set-up the Frigate Lovelace card (Bonus)

This section assumes you have turned on Advanced Moved by going to your profile > enabling Advanced Mode.

First, install the card by going to HACS > Frontend > Explore & Download Repositories > Search and Install "Frigate Card"

Next, go to your Dashboard > open the kebab menu > Manage resources > Add Resource > /hacsfiles/frigate-hass-card/frigate-hass-card.js > press Submit.

Now you can Add Card > Frigate Card and configure to your liking.