MQTT в Home Assistant: брокер Mosquitto, настройка и discovery

MQTT — простой протокол, через который устройства умного дома обмениваются сообщениями: датчик публикует температуру, Home Assistant её получает, а команда «включить розетку» уходит обратно тем же путём. Через MQTT работают Zigbee2MQTT, прошивки Tasmota и ESPHome, самодельные датчики и скрипты. Мы подняли брокер Mosquitto и Home Assistant 2026.10 в Docker, подключили их, завели устройства через MQTT discovery и по дороге собрали несколько граблей. Ниже — настройка шаг за шагом.

Как работает MQTT

• Брокер — сервер-посредник, через который идут все сообщения. Самый популярный — Mosquitto.
• Топик — «адрес» сообщения, например test/balkon/state. Устройства публикуют в топики, а кто нужно — подписывается на них.
• Retain — флаг «запомнить»: брокер хранит последнее сообщение в топике и сразу отдаёт его новым подписчикам. Об этом флаге — ниже, у нас с ним связаны две грабли.

MQTT-брокер для Home Assistant: Mosquitto в Docker

На Home Assistant OS брокер ставится приложением (бывшим дополнением) Mosquitto broker в пару кликов. В Docker — отдельным контейнером. Наш docker-compose.yml:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - 1883:1883
    volumes:
      - ./mosquitto/config:/mosquitto/config
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=Europe/Moscow
    volumes:
      - ./ha:/config

Встал Mosquitto 2.1.2. Образ весит 42 МБ, в памяти брокер занял около 3 МБ — для сравнения, Home Assistant рядом занял около 320 МБ. Как устроен Docker Compose — в статье Docker Compose для начинающих.

Грабля 1: пустая папка конфига

Контейнер сразу ушёл в перезапуски с ошибкой:

Error: Unable to open config file '/mosquitto/config/mosquitto.conf'.

Подключённая пустая папка ./mosquitto/config закрыла собой стандартный конфиг внутри образа. Файл mosquitto.conf нужно создать до запуска.

Грабля 2: «local only mode»

Мы положили конфиг без настройки сетевого порта — только сохранение данных. Брокер запустился, но в логе честно написал:

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

Подключиться к нему с хоста не удалось. Mosquitto 2 без строки listener принимает подключения только изнутри контейнера. Рабочий конфиг — с портом и паролями, как советует документация Mosquitto:

persistence true
persistence_location /mosquitto/data/
log_dest stdout

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

Пользователя для Home Assistant создаём командой внутри контейнера:

docker exec mosquitto sh -c 'touch /mosquitto/config/passwd \
  && mosquitto_passwd -b /mosquitto/config/passwd ha придумайте-пароль \
  && chmod 0700 /mosquitto/config/passwd \
  && chown mosquitto:mosquitto /mosquitto/config/passwd'
docker restart mosquitto

Права 0700 — не прихоть: без них Mosquitto предупреждает, что будущие версии откажутся читать файл с паролями. Проверка: без пароля брокер отвечает Connection Refused: not authorised, с паролем сообщение уходит.

Как добавить MQTT в Home Assistant

По документации интеграции MQTT: Настройки → Устройства и службы → Добавить интеграцию → MQTT, затем адрес брокера, порт 1883, логин и пароль. У нас Home Assistant работает в режиме сети хоста, поэтому адрес брокера — 127.0.0.1.

Грабля 3: «Не удалось подключиться» вместо «неверный пароль»

Сначала мы ввели адрес без логина и пароля. Home Assistant ответил «Не удалось подключиться», хотя брокер был доступен и просто не пустил анонима. Если видите эту ошибку при работающем брокере — проверьте логин и пароль, а не сеть. С правильным паролем интеграция добавилась сразу.

MQTT discovery: устройства сами появляются в Home Assistant

Чтобы не описывать каждое устройство в YAML, Home Assistant слушает топики с префиксом homeassistant/. Устройство (или ваш скрипт) публикует туда своё описание — и в системе появляется устройство с объектами. Так работает, например, Zigbee2MQTT. Наш тест — датчик температуры и влажности:

mosquitto_pub -h 127.0.0.1 -u ha -P пароль -r \
  -t homeassistant/sensor/test_balkon/temperature/config \
  -m '{"name":"Температура","unique_id":"test_balkon_temp",
       "state_topic":"test/balkon/state",
       "value_template":"{{ value_json.temperature }}",
       "unit_of_measurement":"°C","device_class":"temperature",
       "device":{"identifiers":["test_balkon"],"name":"Датчик на балконе"}}'

Так же описали влажность (тот же state_topic, поле humidity) и розетку-выключатель с command_topic. Затем отправили данные: {"temperature":12.4,"humidity":71} в test/balkon/state — и в Home Assistant появился «Датчик на балконе» с двумя значениями.

Команда работает в обратную сторону: при включении розетки в Home Assistant в топике test/rozetka/set появилось сообщение ON. Важно: интерфейс показал розетку включённой только после того, как «устройство» (у нас — команда вручную) подтвердило состояние в test/rozetka/state. Пока подтверждения нет, переключатель остаётся в прежнем положении — это нормально.

Мелочь про имена: объект «Розетка» в устройстве «Тестовая розетка» получил идентификатор switch.testovaia_rozetka_rozetka — имя устройства и объекта склеиваются. Если у устройства один объект, укажите в описании "name": null — тогда объект возьмёт имя устройства. Так мы сделали для датчика двери и получили binary_sensor.dver_bez_retain.

Retain: что будет после перезапуска

Мы перезапустили Home Assistant и посмотрели, что осталось:

Вывод: описание для discovery публикуйте с retain, иначе после перезапуска Home Assistant устройство «отвалится». Документация отмечает и способ лучше: устройство само заново отправляет описание, когда Home Assistant сообщает о запуске в топик homeassistant/status (сообщение online). Для датчиков, которые шлют данные раз в несколько минут, unknown после перезапуска — нормально.

Удалить устройство из discovery можно пустым сообщением с retain в тот же топик …/config.

Как смотреть, что идёт по MQTT

• Командная строка: mosquitto_sub -h адрес -u ha -P пароль -t '#' -v — показывает все сообщения со всеми топиками.
• MQTT Explorer — бесплатная программа с деревом топиков для Windows, macOS и Linux.
• Сам Home Assistant: на странице интеграции MQTT есть «Настроить» — там можно опубликовать сообщение и подписаться на топик, а у каждого устройства — пункт «MQTT Info» с последними сообщениями.

И о безопасности: не открывайте порт 1883 в интернет и не оставляйте allow_anonymous true. Если брокер нужен снаружи — через частную сеть. Как поставить сам Home Assistant — в статье установка Home Assistant, а оповещения о событиях из MQTT-датчиков — по статье про уведомления Home Assistant.

Источники: Home Assistant: MQTT, Mosquitto: способы аутентификации, Mosquitto: mosquitto.conf, образ eclipse-mosquitto, MQTT Explorer. Тест — Mosquitto 2.1.2 и Home Assistant 2026.10.2 в Docker. Проверено 20 октября 2026 года.