How Frigate Integrates with Home Assistant via MQTT: A Complete Technical Guide

Frigate integrates with Home Assistant via MQTT by publishing retained state topics, command topics, and JSON event streams through a dedicated paho-mqtt client wrapper, enabling bidirectional control and real-time monitoring of camera feeds.

Frigate is an open-source Network Video Recorder (NVR) with AI-powered object detection. Its MQTT integration serves as the primary communication bridge for Home Assistant, allowing the home automation platform to consume camera states, trigger automations based on detection events, and remotely control camera settings without requiring direct API calls.

MQTT Configuration Architecture

The MQTT configuration is defined in frigate/config/mqtt.py using Pydantic models. This configuration file exposes all parameters necessary to establish the broker connection and customize the topic structure.

• enabled: Toggle to activate or deactivate MQTT entirely
• host and port: Broker connection endpoints (default port 1883)
• topic_prefix: Default is frigate, but customizable to allow multiple Frigate instances on a single broker
• client_id: Unique identifier for the MQTT client session
• qos: Quality of Service level for message delivery guarantees
• tls_config: Optional encryption settings for secure broker connections
• user and password: Authentication credentials

Changing the topic_prefix is essential when running multiple Frigate instances, as it prevents topic collisions while allowing Home Assistant to distinguish between cameras on different servers.

The MQTT Client Wrapper

The core communication logic lives in frigate/comms/mqtt.py, which implements the MqttClient class. This wrapper abstracts the paho-mqtt library and handles asynchronous connection management, message publishing, and subscription handling.

Connection Lifecycle

When Frigate starts, the MqttClient initializes an asynchronous connection to the configured broker. During setup, it configures a Last Will and Testament (LWT) message on <prefix>/available with the payload offline, which the broker publishes automatically if Frigate disconnects unexpectedly.

Upon successful connection, the _on_connect callback executes and invokes _set_initial_topics, which publishes retained messages for every camera's current state, including:

• Processing enabled/disabled status
• Detection mode state
• Recording configuration
• Snapshot settings
• Motion detection state

These retained messages ensure Home Assistant receives the current state immediately upon subscribing, even if the state changed while Home Assistant was offline.

Core Topic Categories

Frigate organizes MQTT communication into four distinct topic types, all prefixed with the configured topic_prefix (default: frigate).

Availability Topics

The <prefix>/available topic serves as the heartbeat for the integration. Frigate publishes online when the connection establishes, stopped during a graceful shutdown, and offline via the LWT mechanism during unexpected disconnections. Home Assistant uses this topic as the availability_topic in MQTT entity configurations to mark sensors as unavailable when Frigate is offline.

State Topics

For each configured camera, Frigate publishes retained boolean states to specific subtopics:

• <prefix>/<camera>/enabled/state: "ON" when the camera is actively processing, "OFF" when disabled
• <prefix>/<camera>/detect/state: Reflects whether object detection is currently active for that camera
• <prefix>/<camera>/motion/state: "ON" when motion is detected, automatically clearing to "OFF" after the configured mqtt_off_delay
• <prefix>/<camera>/recordings/state: Indicates if continuous or event-based recording is enabled
• <prefix>/<camera>/audio/state: Shows audio detection status when audio events are configured

These topics map directly to Home Assistant binary sensors and switches, providing real-time visibility into camera operations.

Control Topics

Home Assistant can control Frigate cameras by publishing to command topics ending in /set. The MqttClient registers callbacks for these topics in on_mqtt_command, which strips the prefix and forwards payloads to Frigate's internal dispatcher.

Common control patterns include:

• Publishing "OFF" to <prefix>/<camera>/detect/set to temporarily disable object detection
• Publishing "ON" to <prefix>/<camera>/enabled/set to restart processing for a specific camera
• Sending PTZ commands to <prefix>/<camera>/ptz/set to move cameras to specific presets

Runtime changes made via MQTT are not persisted across Frigate restarts; they serve as temporary operational overrides rather than configuration changes.

Event Topics

Detection events emit JSON-encoded messages to two primary topics:

• frigate/events: Published when a new object enters the frame, containing the event ID, label (person, car, etc.), bounding box coordinates, and confidence score
• frigate/tracked_object_update: Published continuously while objects remain in the frame, providing updated positions and attributes

Home Assistant can subscribe to these topics to trigger automations, populate template sensors, or generate notifications with snapshot URLs. The payload format includes fields such as type, label, score, and snapshot URL paths.

Statistics and Profiling

Frigate periodically publishes system statistics to frigate/stats and current profile information to frigate/profile/state. These topics contain JSON payloads with CPU usage, GPU inference times, camera FPS, and memory consumption, enabling Home Assistant dashboard widgets to monitor system health.

Home Assistant Configuration Examples

To consume Frigate's MQTT topics in Home Assistant, configure MQTT sensors and switches in configuration.yaml:

Binary Sensor for Motion Detection

mqtt:
  binary_sensor:
    - name: "Front Door Motion"
      state_topic: "frigate/front_door/motion/state"
      availability_topic: "frigate/available"
      payload_on: "ON"
      payload_off: "OFF"
      qos: 0
      device_class: motion

Switch to Toggle Detection

mqtt:
  switch:
    - name: "Front Door Detection"
      state_topic: "frigate/front_door/detect/state"
      command_topic: "frigate/front_door/detect/set"
      payload_on: "ON"
      payload_off: "OFF"
      availability_topic: "frigate/available"
      qos: 0
      retain: true

Automation Trigger for Object Detection

automation:
  - alias: "Person detected at front door"
    trigger:
      - platform: mqtt
        topic: "frigate/events"
        value_template: "{{ value_json.type == 'new' and value_json.label == 'person' and value_json.camera == 'front_door' }}"
    action:
      - service: notify.mobile_app_phone
        data:
          message: "Person detected at front door"
          data:
            image: "/api/frigate/notifications/{{ trigger.payload_json.after.id }}/snapshot.jpg"

Implementation Deep Dive

The bidirectional flow relies on specific implementation details in frigate/comms/mqtt.py. The _on_connect method (lines 74-80) subscribes to all /set topics using wildcard patterns, then invokes _set_initial_topics to ensure Home Assistant receives current states immediately after reconnection.

The on_mqtt_command dispatcher parses incoming command payloads and routes them to the appropriate camera processes. This design decouples the MQTT transport layer from Frigate's internal event bus, allowing the system to handle high-throughput detection events while maintaining responsive control channel performance.

For complete topic documentation and payload schemas, reference docs/docs/integrations/mqtt.md in the Frigate repository.

Summary

• Frigate integrates with Home Assistant via MQTT using a configurable paho-mqtt client wrapper defined in frigate/comms/mqtt.py and configured through frigate/config/mqtt.py.
• The integration uses retained state topics for camera status, command topics for runtime control, and JSON event topics for detection notifications.
• The <prefix>/available topic with LWT support provides reliable availability monitoring for Home Assistant entities.
• All topic prefixes are customizable via the topic_prefix configuration option, supporting multi-instance deployments.
• Runtime control commands affect immediate operation but do not persist across Frigate restarts.

Frequently Asked Questions

How do I configure MQTT settings in Frigate?

MQTT settings are configured in your Frigate configuration file (typically config.yaml) under the mqtt: section. The frigate/config/mqtt.py file defines all available options including host, port, topic_prefix, client_id, and TLS settings. At minimum, you must specify the broker host; all other values use sensible defaults including the frigate topic prefix.

Why does Home Assistant show my Frigate entities as unavailable?

Home Assistant marks entities as unavailable when the availability_topic (default: frigate/available) does not show online. Check that Frigate is running, has network connectivity to your MQTT broker, and that the topic_prefix in your Home Assistant configuration matches Frigate's configuration exactly. The LWT mechanism ensures entities go offline if Frigate crashes or loses network connectivity.

Can I control PTZ cameras through the MQTT integration?

Yes. Frigate publishes PTZ command topics at <prefix>/<camera>/ptz/set that accept preset names or directional commands. Home Assistant can publish to these topics using the mqtt.publish service in automations or by configuring MQTT number or select entities for absolute positioning, depending on your camera's capabilities and Frigate version.

Are MQTT control changes persistent across Frigate restarts?

No. Changes made via MQTT command topics (such as disabling detection or recordings) are runtime-only modifications managed by the internal dispatcher in frigate/comms/mqtt.py. To make permanent changes, update your Frigate configuration file and restart the container. This design prevents temporary automation-driven changes from persisting unintentionally after system maintenance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}