# How Frigate Integrates with Home Assistant via MQTT: A Complete Technical Guide > Learn how Frigate integrates with Home Assistant via MQTT. Discover how Frigate publishes state, command topics, and event streams for seamless bidirectional control and real-time camera monitoring. - Repository: [Blake Blackshear/frigate](https://github.com/blakeblackshear/frigate) - Tags: how-to-guide - Published: 2026-05-25 --- **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`](https://github.com/blakeblackshear/frigate/blob/main/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`](https://github.com/blakeblackshear/frigate/blob/main/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 `/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 `/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: - **`//enabled/state`**: `"ON"` when the camera is actively processing, `"OFF"` when disabled - **`//detect/state`**: Reflects whether object detection is currently active for that camera - **`//motion/state`**: `"ON"` when motion is detected, automatically clearing to `"OFF"` after the configured `mqtt_off_delay` - **`//recordings/state`**: Indicates if continuous or event-based recording is enabled - **`//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 `//detect/set` to temporarily disable object detection - Publishing `"ON"` to `//enabled/set` to restart processing for a specific camera - Sending PTZ commands to `//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`](https://github.com/blakeblackshear/frigate/blob/main/configuration.yaml): ### Binary Sensor for Motion Detection ```yaml 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 ```yaml 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 ```yaml 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`](https://github.com/blakeblackshear/frigate/blob/main/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`](https://github.com/blakeblackshear/frigate/blob/main/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`](https://github.com/blakeblackshear/frigate/blob/main/frigate/comms/mqtt.py) and configured through [`frigate/config/mqtt.py`](https://github.com/blakeblackshear/frigate/blob/main/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 `/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`](https://github.com/blakeblackshear/frigate/blob/main/config.yaml)) under the `mqtt:` section. The [`frigate/config/mqtt.py`](https://github.com/blakeblackshear/frigate/blob/main/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 `//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`](https://github.com/blakeblackshear/frigate/blob/main/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.