Frigate MQTT Events erklärt: Topics, Payloads und Remote-Alarme

Über die Frigate MQTT-Integration teilt der Frigate NVR dem Rest Ihres Systems mit, dass er eine Person, ein Auto oder einen Hund gesehen hat. Sie ist der sauberste Weg, Alarme und Automatisierungen auf Basis lokaler Objekterkennung aufzubauen. In diesem Leitfaden lernen Sie jedes Topic kennen, das Frigate veröffentlicht, erfahren, was der Event-Payload tatsächlich enthält, und sehen, wie Sie nur die wichtigen Erkennungen aus Ihrem lokalen Netzwerk an einen Cloud-Broker weiterleiten, damit Sie sie überall empfangen können.

Wie Frigate MQTT nutzt

Frigate führt die Objekterkennung auf Ihren Kamerastreams lokal aus, meist mit einem Coral-, Hailo-, OpenVINO- oder GPU-Detektor. Aufzeichnung und Clip-Sichtung finden in der Weboberfläche statt, doch alles Ereignisgesteuerte läuft über MQTT. Frigate ist ein MQTT-Client: Er verbindet sich mit einem von Ihnen angegebenen Broker, veröffentlicht Zustände und Events und abonniert eine Handvoll Befehls-Topics, damit Sie Erkennung, Aufzeichnung oder Schnappschüsse aus der Ferne ein- und ausschalten können.

Durch dieses Design ist es Frigate egal, wer die Daten konsumiert. Home Assistant, Node-RED, ein Python-Skript oder eine MQTT-App auf dem Smartphone können dieselben Topics gleichzeitig abonnieren. Wenn Ihnen das Pub/Sub-Modell neu ist, hilft es, zu verstehen, was ein MQTT-Broker macht, bevor Sie alles verbinden.

Den MQTT-Abschnitt in Frigate konfigurieren

Der mqtt-Block in der config.yml von Frigate verweist auf einen Broker. Die meisten Installationen betreiben einen lokalen Mosquitto-Container neben 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

Zwei Einstellungen verursachen die meisten Support-Threads. Erstens muss client_id eindeutig sein: Teilen sich zwei Frigate-Instanzen die Standard-ID frigate auf einem Broker, werfen sie sich gegenseitig in einer Schleife hinaus. Zweitens muss jede Automatisierung, die auf frigate/... lauscht, ebenfalls angepasst werden, wenn Sie topic_prefix ändern.

Referenz der Frigate MQTT Topics

Dies sind die Topics, die Sie am häufigsten verwenden werden, ausgehend vom Standardpräfix frigate:

Ähnliche set/state-Paare gibt es für Aufzeichnungen, Schnappschüsse und Bewegungserkennung. Prüfen Sie die offizielle Frigate-MQTT-Dokumentation für Ihre Version, denn neuere Releases fügen Topics wie Review-Elemente und Aktualisierungen verfolgter Objekte hinzu.

Den Payload von frigate/events lesen

Jedes verfolgte Objekt erzeugt eine Folge von Nachrichten auf frigate/events: eine new-Nachricht, mehrere update-Nachrichten, während sich das Objekt bewegt oder der Score steigt, und eine end-Nachricht, wenn es das Bild verlässt. Jede Nachricht enthält den vollständigen Objektzustand vor und nach der Änderung. Ein gekürztes Beispiel:

{
  "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
  }
}

Die für Alarme wichtigen Felder:

1. after.id bleibt über die gesamte Lebensdauer des Objekts stabil; nutzen Sie es zur Deduplizierung.
2. after.top_score ist die beste bisher gemessene Konfidenz und zuverlässiger als der momentane score.
3. after.false_positive wird false, sobald Frigate sicher ist, dass das Objekt echt ist. Alarme vor diesem Zeitpunkt erzeugen nur Rauschen.
4. Mit after.entered_zones lösen Sie nur dann einen Alarm aus, wenn jemand tatsächlich den Weg betritt, und nicht, wenn er auf der Straße vorbeigeht.
5. type: end mit gesetztem end_time schließt das Event ab und ist der richtige Zeitpunkt, den Clip über die HTTP-API von Frigate abzurufen.

Ein häufiger Fehler ist es, bei jedem update auszulösen. Eine Person, die durch das Bild läuft, kann viele Updates erzeugen, sodass eine naive Automatisierung für einen einzigen Besuch eine Flut von Benachrichtigungen verschickt.

Warum Frigate-Events an einen Cloud-Broker weiterleiten

Der lokale Broker ist innerhalb des Hauses oder Standorts perfekt, aber von Ihrem Smartphone im Mobilfunknetz ist er ohne offene Ports nicht erreichbar, und Mosquitto dem Internet auszusetzen ist ein Sicherheitsproblem. Das sicherere Muster arbeitet ausschließlich ausgehend: Ein kleiner Forwarder im selben Netzwerk abonniert den lokalen Broker, filtert Events und veröffentlicht kompaktes JSON an einen Cloud-MQTT-Broker. Ihr Smartphone, ein Remote-Dashboard oder ein zweiter Standort abonnieren dort. Auf Ihrem Heimrouter lauscht nichts.

Die Weiterleitung ermöglicht es außerdem, den Payload zu verschlanken. Schnappschüsse können Dutzende Kilobyte groß sein, und der öffentliche MQTT-Broker akzeptiert höchstens 64 KB pro Nachricht. Der Forwarder sendet daher nur Metadaten und belässt Bilder auf dem lokalen Frigate-Server.

Sie könnten Frigate auch direkt auf einen entfernten Broker richten, indem Sie host und port ändern und client_id auf die Client ID setzen, die mit Ihren Zugangsdaten ausgegeben wurde, denn ConnectMQ bindet Client IDs an Zugangsdaten. In der Praxis ist ein Filter dazwischen besser: Home Assistant funktioniert lokal weiter, wenn das Internet ausfällt, und nur relevante Events verlassen das Netzwerk.

Python-Forwarder: lokales Frigate zu ConnectMQ

Das folgende Skript verwendet paho-mqtt 2.x. Es abonniert den lokalen Broker, leitet eine Nachricht weiter, wenn eine Person oder ein Auto zu einer sicheren Erkennung wird, und eine weitere, wenn sie endet, spiegelt die Verfügbarkeit von Frigate und gibt einen Remote-Befehl zum Ein- und Ausschalten der Erkennung an Frigate zurück.

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()

Führen Sie es auf dem Frigate-Host aus und beobachten Sie die entfernte Seite von einem beliebigen Rechner aus. Verwenden Sie das Präfix, das das Skript ausgegeben hat:

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

Laufen Sie vor einer Kamera vorbei, und Sie sollten pro Besuch genau zwei Nachrichten sehen: started und ended. Um den Befehlspfad zu testen, veröffentlichen Sie OFF an connectmq/demo/<your-id>/frigate/cmd/driveway/detect.

Der öffentliche MQTT-Broker ist für jeden lesbar, der das Topic errät. Behandeln Sie ihn daher nur als Sandbox für Tests und Prototypen. Für ein echtes Zuhause oder einen echten Standort erstellen Sie einen privaten Broker und setzen REMOTE_PORT=8883 sowie die Werte REMOTE_USER, REMOTE_PASS und REMOTE_CLIENT_ID aus dem Portal. Betreiben Sie das Befehls-Relay nicht auf einem öffentlichen Topic.

Überwacht Frigate Tore, Rampen oder Hallenzugänge auf einem Werksgelände, ordnen Sie die weitergeleiteten Events am besten in Ihren Unified Namespace (UNS) ein, etwa unter acme/werk-augsburg/logistik/tor-3/kamera/person/event. So folgen sie derselben ISA-95-Hierarchie wie Ihre Maschinendaten. Videodaten von Beschäftigten unterliegen in Deutschland der DSGVO, und Kameras im Betrieb sind in der Regel mitbestimmungspflichtig; senden Sie deshalb auch hier nur die nötigen Metadaten.

Alarme auf dem Smartphone empfangen

Da der Cloud-Broker reines MQTT spricht, kann Sie alles alarmieren, was abonnieren kann: eine MQTT-Client-App auf Ihrem Smartphone, ein Node-RED-Flow, der über einen Benachrichtigungsdienst Ihrer Wahl eine Push-Nachricht sendet, oder eine entfernte Home-Assistant-Instanz. Wenn Sie ein Browser-Dashboard bauen, verbinden Sie sich über sicheres WebSocket auf Port 8084 mit dem Pfad /mqtt. Im ConnectMQ-Portal zeigt der Live-Topic-Explorer die weitergeleiteten Events beim Eintreffen an, was beim Feinabstimmen von MIN_SCORE und Zonen praktisch ist.

Fehlerbehebung bei Frigate MQTT

1. Frigate protokolliert „Unable to connect to MQTT server“. Prüfen Sie, ob host innerhalb des Frigate-Containers aufgelöst wird; localhost ist dort der Container selbst, nicht der Host-Rechner.
2. Die Verbindung bricht alle paar Sekunden ab. Zwei Clients verwenden dieselbe Client ID. Geben Sie Frigate und jedem Forwarder eine eigene ID.
3. Keine Events, obwohl die Oberfläche Erkennungen zeigt. Das Objekt steht möglicherweise nicht in der Liste objects.track der Kamera, oder eine Einstellung required_zones filtert es heraus.
4. Zu viele Alarme. Lösen Sie anhand von top_score und entered_zones aus, ignorieren Sie update nach der ersten Weiterleitung und fügen Sie bei Bedarf Abklingzeiten pro Kamera hinzu.
5. Schnappschüsse werden vom entfernten Broker abgelehnt. Sie überschreiten das Limit für die Nachrichtengröße; behalten Sie Bilder lokal und senden Sie Links oder Metadaten.

Für tiefergehende Erkennungspipelines sehen Sie sich an, wie YOLO-Objekterkennung über MQTT funktioniert oder wie Sie eine Personenerkennung auf einem ESP32-CAM aufbauen, und lesen Sie den Leitfaden zu KI und IoT für das Gesamtbild.

Remote-Alarme von Frigate mit ConnectMQ

Ein privater Cloud-Broker ist das fehlende Bindeglied zwischen einem lokalen NVR und Alarmen, auf die Sie sich auch unterwegs verlassen können. ConnectMQ ist ein verwalteter MQTT-Broker mit TLS auf Port 8883, generierten Zugangsdaten und einem Topic-Explorer zum Debuggen. Starten Sie mit dem kostenlosen Serverless-Plan unter app.connectmq.com, ohne Kreditkarte, und richten Sie den Forwarder dann auf Ihren neuen Broker.

Häufig gestellte Fragen

Braucht Frigate einen MQTT-Broker?

Für Aufzeichnung und Weboberfläche ist MQTT optional, aber die Home-Assistant-Integration und alle ereignisgesteuerten Automatisierungen hängen davon ab. Die meisten Nutzer betreiben Mosquitto auf demselben Host.

Was ist der Unterschied zwischen frigate/events und frigate/reviews?

frigate/events beschreibt einzelne verfolgte Objekte über ihren Lebenszyklus. Review-Elemente fassen Aktivitäten zu Alerts und Detections zusammen, die dem entsprechen, was Sie in der Review-Oberfläche sehen, und eignen sich daher oft besser für Benachrichtigungen.

Kann ich Frigate-Schnappschüsse an einen Cloud-Broker senden?

Nur wenn sie in das Limit für die Nachrichtengröße des Brokers passen, das beim öffentlichen MQTT-Broker bei 64 KB liegt. Metadaten zu senden und Bilder bei Bedarf über die API von Frigate abzurufen ist in der Regel sauberer und günstiger.

Ist es sicher, stattdessen meinen lokalen Mosquitto-Broker freizugeben?

Das wird nicht empfohlen. Ein ausgehender Forwarder zu einem authentifizierten TLS-Broker vermeidet offene Ports auf Ihrem Router und hält den lokalen Broker privat.