Skip to main content

MQTT

Protocol
MQTT
Created: 12/22/2021
Updated: 3/14/2026

The mqtt integration allows Viseron to connect to an MQTT broker and publish and subscribe to topics.

It is also used to integrate with Home Assistant.

Configuration​

Configuration example
/config/config.yaml
mqtt:
  broker: mqtt_broker.lan
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_pass
mqtt​map required
MQTT configuration.

Topics​

Viseron internally manages entities, which in turn are published to MQTT topics. Available entity domains are:

  • binary_sensor: Binary sensors show on/off states
  • image: Images are published as JPEGs
  • sensor: Sensors show any values
  • toggle: Toggles are used to switch things on or off
tip

You can observe the logs to find the entity ids.

Binary sensor topics​

{base_topic}/binary_sensor/{camera_identifier}_connected/state​

Shows if Viseron is connected to a camera.

Payloads
{
  "state": "on",
  "attributes": {}
}

{base_topic}/binary_sensor/{camera_identifier}_recorder/state​

Shows whether the recorder is recording or not.

Payloads
{
  "state": "off",
  "attributes": {
    "name": "Porch Recorder",
    "domain": "binary_sensor",
    "id": 33406,
    "start_time": "2025-03-12T10:14:10.887491+00:00",
    "start_timestamp": 1741774450.887491,
    "end_time": null,
    "end_timestamp": null,
    "date": "2025-03-12",
    "thumbnail_path": "/thumbnails/porch/33406.jpg",
    "objects": [
      {
        "label": "person",
        "confidence": 0.93,
        "rel_width": 0.092,
        "rel_height": 0.391,
        "rel_x1": 0.761,
        "rel_y1": 0.081,
        "rel_x2": 0.853,
        "rel_y2": 0.472
      }
    ]
  }
}

{base_topic}/binary_sensor/{camera_identifier}_object_detected/state​

A JSON formatted payload is published to this topic when any configured label is in the field of view.

Payloads
{
  "state": "on",
  "attributes": {}
}

{base_topic}/binary_sensor/{camera_identifier}_object_detected_{label}/state​

A JSON formatted payload is published to this topic when a specific configured label is in the field of view.

Payloads
{
  "state": "on",
  "attributes": {
    "count": 2
  }
}

{base_topic}/binary_sensor/{camera_identifier}_zone_{zone}_object_detected/state​

A JSON formatted payload is published to this topic when any configured label is in the specific zone.

Payloads
{
  "state": "on",
  "attributes": {}
}

{base_topic}/binary_sensor/{camera_identifier}_zone_{zone}_object_detected_{label}/state​

A JSON formatted payload is published to this topic when a specific configured label is in the specific zone.

Payloads
{
  "state": "on",
  "attributes": {
    "count": 2
  }
}

{base_topic}/binary_sensor/{camera_identifier}_motion_detected/state​

A JSON formatted payload is published to this topic when motion is detected.

Payloads
{
  "state": "on",
  "attributes": {}
}

{base_topic}/binary_sensor/{camera_identifier}_face_detected_{person name}/state​

A JSON formatted payload is published to this topic when a tracked face is detected.

Payloads
{
  "state": "on",
  "attributes": {
    "camera_identifier": "<camera_identifier>",
    "camera_name": "<camera name>",
    "name": "<person name>",
    "confidence": "<detection confidence>",
    "coordinates": "<detection coordinates>"
  }
}

{base_topic}/binary_sensor/{camera_identifier}_still_image_available/state​

A JSON formatted payload is published to this topic when still image becomes available/unavailable.

Payloads
{
  "state": "on",
  "attributes": {}
}

Toggle topics​

{base_topic}/toggle/{camera_identifier}_connection/command​

Used for turning on/off a camera. Payload should be ON or OFF.

Payloads
ON

{base_topic}/toggle/{camera_identifier}_connection/state​

Camera connection state.

Payloads
{
  "state": "on",
  "attributes": {}
}

{base_topic}/toggle/{camera_identifier}_manual_recording/command​

Used for starting/stopping a manual recording. Payload should be a valid JSON, ON or OFF.

Payloads
{
  "action": "start",
  "duration": 120
}

or

ON

{base_topic}/toggle/{camera_identifier}_manual_recording/state​

Manual recording state.

Payloads
{
  "state": "on",
  "attributes": {}
}

Image topics​

{base_topic}/image/{camera_identifier}_latest_thumbnail/image​

A JPEG encoded image is published to this topic when a new recording starts. The object that triggered the recorder will have its bounding box drawn.

{base_topic}/image/{camera_identifier}_latest_thumbnail/attributes​

A JSON formatted payload with attributes (currently empty)

Sensor topics​

{base_topic}/sensor/{camera_identifier}_object_detector_fps/state​

A JSON formatted payload is periodically published to with an estimate of the current object detectors processing FPS.

Payloads

preprocessor_fps and inference_fps is used to calculate the state, which is the same as the theoretical_max_fps

{
  "state": 34.2,
  "attributes": {
    "preprocessor_fps": 305.2,
    "inference_fps": 34.3,
    "theoretical_max_fps": 34.2
  }
}

{base_topic}/sensor/{camera_identifier}_operation_state/state​

A JSON formatted payload is published to this topic to indicate the current status of the camera

Payloads
{
  "state": "scanning_for_objects",
  "attributes": {}
}

{base_topic}/sensor/{camera_identifier}_image_classification/state​

Viseron state topic​

{base_topic}/state​

A JSON formatted payload is published to this topic to indicate the current status of Viseron.

Payloads
online

Last Will Topic​

{base_topic}/lwt​

MQTT Last will and Testament

Payloads
online

Home Assistant MQTT Discovery​

Viseron integrates into Home Assistant using MQTT discovery.

note

Home Assistant integration is disabled by default. You enable it by adding home_assistant to your mqtt config.

Viseron will create a number of entities depending on your configuration.

The paragraphs below show a few of the most notable ones.

Cameras​

  1. A camera entity named camera.{camera_identifier}_latest_thumbnail is created.

Sensors​

  1. A status sensor named sensor.{camera_identifier}_operation_state is created. The state is set to idle, recording, scanning_for_motion, scanning_for_objects or error_scanning_frame depending on the situation.
  2. A sensor that shows current the object detector FPS.

Binary Sensors​

A variable amount of binary sensors will be created based on your configuration.

  1. An entity showing if any tracked object is in view.
  2. An entity for each tracked object showing if the label is in view.
  3. An entity for each zone showing if any tracked object is in the zone.
  4. An entity for each tracked object in a zone showing if the label is in the zone.
  5. An entity showing if motion is detected.
  6. An entity showing if a face is detected.
  7. An entity showing camera connection.

Switch​

  1. A switch used to arm/disarm a camera. When disarmed, no system resources are used for the camera.

Troubleshooting​

To enable debug logging for mqtt, add the following to your config.yaml
/config/config.yaml
logger:
  logs:
    viseron.components.mqtt: debug