Événements Frigate MQTT expliqués : topics, payloads et alertes à distance

L'intégration Frigate MQTT est le moyen par lequel le NVR Frigate signale au reste de votre système qu'il a vu une personne, une voiture ou un chien, et c'est la façon la plus propre de construire des alertes et des automatisations au-dessus d'une détection d'objets locale. Dans ce guide, vous découvrirez chaque topic publié par Frigate, ce que contient réellement le payload des événements, et comment relayer uniquement les détections importantes de votre réseau local vers un broker cloud pour les recevoir n'importe où.

Comment Frigate utilise MQTT

Frigate exécute localement la détection d'objets sur les flux de vos caméras, généralement avec un détecteur Coral, Hailo, OpenVINO ou GPU. L'enregistrement et la revue des clips se font dans son interface web, mais tout ce qui relève des événements sort via MQTT. Frigate est un client MQTT : il se connecte au broker que vous indiquez, publie son état et ses événements, et s'abonne à quelques topics de commande pour que vous puissiez activer ou désactiver à distance la détection, l'enregistrement ou les instantanés.

Grâce à cette conception, Frigate ne se soucie pas de qui consomme les données. Home Assistant, Node-RED, un script Python ou une application MQTT sur téléphone peuvent tous s'abonner aux mêmes topics en même temps. Dans une maison connectée, Jeedom et Domoticz savent aussi communiquer en MQTT. Si le modèle pub/sub est nouveau pour vous, il est utile de comprendre à quoi sert un broker MQTT avant de tout relier.

Configurer la section MQTT dans Frigate

Le bloc mqtt du fichier config.yml de Frigate le dirige vers un broker. La plupart des installations exécutent un conteneur Mosquitto local à côté de Frigate :

mqtt:
  enabled: true
  host: mosquitto        # container name or IP of the local broker
  port: 1883
  topic_prefix: frigate  # every topic starts with this
  client_id: frigate     # must be unique on the broker
  user: frigate
  password: "{FRIGATE_MQTT_PASSWORD}"
  stats_interval: 60     # seconds between frigate/stats messages

cameras:
  driveway:
    mqtt:
      enabled: true      # publish snapshots for this camera
      timestamp: false
      bounding_box: true
      crop: true
      height: 270
      quality: 70

Deux paramètres sont à l'origine de la majorité des demandes d'aide. D'abord, client_id doit être unique : si deux instances Frigate partagent l'ID par défaut frigate sur un même broker, elles vont se déconnecter mutuellement en boucle. Ensuite, si vous modifiez topic_prefix, chaque automatisation qui écoute sur frigate/... doit être modifiée aussi.

Référence des topics Frigate MQTT

Voici les topics que vous utiliserez le plus souvent, avec le préfixe par défaut frigate :

Des paires set/state similaires existent pour les enregistrements, les instantanés et la détection de mouvement. Consultez la documentation MQTT officielle de Frigate pour votre version, car les nouvelles versions ajoutent des topics comme les éléments de revue et les mises à jour d'objets suivis.

Lire le payload frigate/events

Chaque objet suivi produit une séquence de messages sur frigate/events : un new, plusieurs messages update à mesure que l'objet se déplace ou que le score s'améliore, et un end lorsqu'il disparaît. Chaque message contient l'état complet de l'objet avant et après le changement. Un exemple abrégé :

{
  "type": "new",
  "before": { "id": "1729076512.48-ab12cd", "label": "person", "top_score": 0.0 },
  "after": {
    "id": "1729076512.48-ab12cd",
    "camera": "driveway",
    "label": "person",
    "score": 0.82,
    "top_score": 0.84,
    "false_positive": false,
    "start_time": 1729076512.48,
    "end_time": null,
    "current_zones": ["front_path"],
    "entered_zones": ["front_path"],
    "has_snapshot": true,
    "has_clip": false
  }
}

Les champs importants pour les alertes :

1. after.id reste stable pendant toute la durée de vie de l'objet ; utilisez-le pour dédupliquer.
2. after.top_score est la meilleure confiance observée jusqu'ici, plus fiable que le score instantané.
3. after.false_positive passe à false dès que Frigate est sûr que l'objet est réel. Alerter avant ce moment génère du bruit.
4. after.entered_zones vous permet d'alerter uniquement quand quelqu'un s'engage réellement sur l'allée, pas quand il passe dans la rue.
5. type: end avec end_time renseigné clôt l'événement : c'est le bon moment pour récupérer le clip via l'API HTTP de Frigate.

Une erreur courante consiste à déclencher sur chaque update. Une personne qui traverse l'image peut générer de nombreuses mises à jour : une automatisation naïve envoie alors une rafale de notifications pour une seule visite.

Pourquoi relayer les événements Frigate vers un broker cloud

Le broker local est parfait à l'intérieur de la maison ou du site, mais il n'est pas joignable depuis votre téléphone en données mobiles sans ouvrir de ports, et exposer Mosquitto sur Internet pose un problème de sécurité. Le schéma le plus sûr est uniquement sortant : un petit relais sur le même réseau s'abonne au broker local, filtre les événements et publie un JSON compact vers un broker MQTT cloud. Votre téléphone, un tableau de bord distant ou un second site s'y abonnent. Rien n'écoute sur votre box.

Le relais permet aussi d'alléger le payload. Les instantanés peuvent peser des dizaines de kilo-octets et la zone de test publique accepte au maximum 64 Ko par message : le relais n'envoie donc que des métadonnées et laisse les images sur le serveur Frigate local.

Vous pourriez diriger Frigate directement vers un broker distant en modifiant host et port et en réglant client_id sur le client ID fourni avec vos identifiants, car ConnectMQ lie les client IDs aux identifiants. En pratique, un filtre intermédiaire est préférable : Home Assistant continue de fonctionner localement si Internet tombe, et seuls les événements pertinents quittent le réseau.

Relais Python : de Frigate local vers ConnectMQ

Le script ci-dessous utilise paho-mqtt 2.x. Il s'abonne au broker local, relaie un message lorsqu'une personne ou une voiture devient une détection fiable et un autre lorsqu'elle se termine, reflète la disponibilité de Frigate et renvoie à Frigate une commande distante d'activation ou de désactivation de la détection.

pip install "paho-mqtt>=2.0"

import json
import os
import uuid

import paho.mqtt.client as mqtt

LOCAL_HOST = os.getenv("LOCAL_HOST", "localhost")
LOCAL_USER = os.getenv("LOCAL_USER")
LOCAL_PASS = os.getenv("LOCAL_PASS")

REMOTE_HOST = os.getenv("REMOTE_HOST", "broker.connectmq.com")
REMOTE_PORT = int(os.getenv("REMOTE_PORT", "1883"))
REMOTE_USER = os.getenv("REMOTE_USER")          # unset for the public test area
REMOTE_PASS = os.getenv("REMOTE_PASS")
REMOTE_CLIENT_ID = os.getenv("REMOTE_CLIENT_ID", f"frigate-fwd-{uuid.uuid4().hex[:8]}")
PREFIX = os.getenv("REMOTE_PREFIX", f"connectmq/demo/{uuid.uuid4().hex[:8]}/frigate")

LABELS = {"person", "car"}
MIN_SCORE = float(os.getenv("MIN_SCORE", "0.75"))
forwarded = set()   # event ids already announced

# ---------- remote (cloud) client ----------
remote = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=REMOTE_CLIENT_ID)
if REMOTE_USER:
    remote.username_pw_set(REMOTE_USER, REMOTE_PASS)
if REMOTE_PORT == 8883:
    remote.tls_set()
remote.will_set(f"{PREFIX}/forwarder/status", "offline", qos=1, retain=True)


def on_remote_connect(client, userdata, flags, reason_code, properties):
    print("remote connected:", reason_code)
    client.publish(f"{PREFIX}/forwarder/status", "online", qos=1, retain=True)
    client.subscribe(f"{PREFIX}/cmd/+/detect", qos=1)


def on_remote_message(client, userdata, msg):
    camera = msg.topic.split("/")[-2]
    value = msg.payload.decode().upper()
    if value in ("ON", "OFF"):
        local.publish(f"frigate/{camera}/detect/set", value)
        print(f"relayed detect {value} to {camera}")


remote.on_connect = on_remote_connect
remote.on_message = on_remote_message

# ---------- local (Frigate) client ----------
local = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=f"frigate-fwd-local-{uuid.uuid4().hex[:6]}")
if LOCAL_USER:
    local.username_pw_set(LOCAL_USER, LOCAL_PASS)


def on_local_connect(client, userdata, flags, reason_code, properties):
    print("local connected:", reason_code)
    client.subscribe([("frigate/events", 0), ("frigate/available", 0)])


def on_local_message(client, userdata, msg):
    if msg.topic == "frigate/available":
        remote.publish(f"{PREFIX}/nvr/status", msg.payload, qos=1, retain=True)
        return

    event = json.loads(msg.payload)
    after = event["after"]
    if after["label"] not in LABELS or after.get("false_positive", True):
        return

    event_id = after["id"]
    if event["type"] in ("new", "update"):
        if event_id in forwarded or after["top_score"] < MIN_SCORE:
            return
        forwarded.add(event_id)
        state = "started"
    elif event["type"] == "end":
        if event_id not in forwarded:
            return
        forwarded.discard(event_id)
        state = "ended"
    else:
        return

    summary = {
        "id": event_id,
        "camera": after["camera"],
        "label": after["label"],
        "score": round(after["top_score"], 2),
        "zones": after.get("entered_zones", []),
        "state": state,
        "start": after["start_time"],
        "end": after.get("end_time"),
    }
    topic = f"{PREFIX}/{after['camera']}/{after['label']}/event"
    remote.publish(topic, json.dumps(summary), qos=1)
    print("forwarded", topic, summary["state"], summary["score"])


local.on_connect = on_local_connect
local.on_message = on_local_message

remote.connect(REMOTE_HOST, REMOTE_PORT, keepalive=60)
remote.loop_start()
local.connect(LOCAL_HOST, 1883, keepalive=60)
print("forwarding to", PREFIX)
local.loop_forever()

Exécutez-le sur l'hôte Frigate, puis surveillez le côté distant depuis n'importe quelle machine. Utilisez le préfixe affiché par le script :

mosquitto_sub -h broker.connectmq.com -p 1883 -i watcher-7f3a2c \
  -t 'connectmq/demo/<your-id>/frigate/#' -v

Passez devant une caméra : vous devriez voir exactement deux messages par visite, started et ended. Pour tester le chemin des commandes, publiez OFF sur connectmq/demo/<your-id>/frigate/cmd/driveway/detect.

Le serveur MQTT public gratuit est lisible par quiconque devine le topic : considérez-le uniquement comme un bac à sable. Pour une vraie maison ou un vrai site, créez un broker privé, définissez REMOTE_PORT=8883 ainsi que les valeurs REMOTE_USER, REMOTE_PASS et REMOTE_CLIENT_ID fournies par le portail. N'exécutez pas le relais de commandes sur un topic public.

Recevoir les alertes sur votre téléphone

Comme le broker cloud parle MQTT standard, tout ce qui peut s'abonner peut vous alerter : une application cliente MQTT sur votre téléphone, un flux Node-RED qui envoie une notification push via le service de votre choix, ou une instance Home Assistant distante. Si vous construisez un tableau de bord dans le navigateur, connectez-vous en WebSocket sécurisé sur le port 8084 avec le chemin /mqtt. Dans le portail ConnectMQ, l'explorateur de topics en direct montre l'arrivée des événements relayés, ce qui est pratique pour ajuster MIN_SCORE et les zones.

Dépannage de Frigate MQTT

1. Frigate journalise « Unable to connect to MQTT server ». Vérifiez que host est résolu à l'intérieur du conteneur Frigate ; localhost y désigne le conteneur lui-même, pas la machine hôte.
2. La connexion tombe toutes les quelques secondes. Deux clients utilisent le même client ID. Donnez un ID distinct à Frigate et à chaque relais.
3. Aucun événement, alors que l'interface affiche des détections. L'objet ne figure peut-être pas dans la liste objects.track de la caméra, ou un paramètre required_zones le filtre.
4. Trop d'alertes. Alertez sur top_score et entered_zones, ignorez les update après le premier relais et ajoutez si besoin des délais de récupération par caméra.
5. Instantanés rejetés par le broker distant. Ils dépassent la taille maximale des messages ; gardez les images en local et envoyez des liens ou des métadonnées.

Pour des pipelines de détection plus avancés, découvrez le fonctionnement de la détection d'objets YOLO via MQTT ou comment construire la détection de personnes sur un ESP32-CAM, ainsi que le guide IA et IoT pour une vue d'ensemble.

Recevez vos alertes Frigate à distance avec ConnectMQ

Un broker cloud privé est la pièce manquante entre un NVR local et des alertes fiables quand vous n'êtes pas chez vous. ConnectMQ est un broker MQTT managé avec TLS sur le port 8883, des identifiants générés et un explorateur de topics pour le débogage. Commencez avec l'offre gratuite Serverless sur app.connectmq.com, sans carte bancaire, puis dirigez le relais vers votre nouveau broker.

Questions fréquentes

Frigate a-t-il besoin d'un broker MQTT ?

MQTT est facultatif pour l'enregistrement et l'interface web, mais l'intégration Home Assistant et toutes les automatisations basées sur les événements en dépendent. La plupart des utilisateurs exécutent Mosquitto sur le même hôte.

Quelle est la différence entre frigate/events et frigate/reviews ?

frigate/events décrit les objets suivis individuellement tout au long de leur cycle de vie. Les éléments de revue regroupent l'activité en alertes et détections correspondant à ce que vous voyez dans l'interface de revue, ce qui convient souvent mieux aux notifications.

Puis-je envoyer les instantanés Frigate vers un broker cloud ?

Seulement s'ils respectent la taille maximale des messages du broker, qui est de 64 Ko sur la zone de test publique. Envoyer des métadonnées et récupérer les images à la demande via l'API de Frigate est généralement plus propre et moins coûteux.

Est-il sûr d'exposer plutôt mon broker Mosquitto local ?

Ce n'est pas recommandé. Un relais sortant vers un broker TLS authentifié évite d'ouvrir des ports sur votre box et garde le broker local privé.