MQTT в Home Assistant: broker, topics, retained, QoS и почему устройства иногда «залипают»

Что такое MQTT простыми словами

MQTT — лёгкий publish/subscribe протокол обмена сообщениями. Устройства не обязаны соединяться напрямую друг с другом. Они подключаются к broker и либо публикуют сообщения в topics, либо подписываются на них.

Например, счётчик публикует текущую мощность в topic house/power/total, а Home Assistant подписывается на него. При этом тот же topic одновременно может читать Node-RED, Grafana-bridge или другой контроллер.

Зачем нужен MQTT broker

Broker — центральная точка MQTT-обмена. Он принимает сообщения от publishers и доставляет их всем подходящим subscribers.

В домашней автоматизации broker часто выполняет несколько задач:

• связывает Home Assistant и внешние контроллеры;
• передаёт телеметрию датчиков и счётчиков;
• доставляет команды исполнительным устройствам;
• хранит retained messages;
• отслеживает соединения клиентов;
• реализует ACL и аутентификацию.

Один из самых распространённых broker — Eclipse Mosquitto. В Home Assistant OS его часто разворачивают как add-on, но broker может работать и на отдельном Linux-сервере, NAS или другом постоянно включённом устройстве.

Topics: как MQTT понимает, кому отправлять данные

Topic — строковый путь, по которому публикуется сообщение. Обычно структуру строят иерархически через символ /.

house/kitchen/temperature
house/kitchen/humidity
house/boiler/status
house/power/total
house/gate/state

Подписчик может слушать конкретный topic или использовать wildcard.

Что такое retained message и почему оно может «оживлять» старое состояние

Если publisher отправляет сообщение с флагом RETAIN, broker сохраняет последнее retained-сообщение для этой topic. Когда новый subscriber подпишется позже, broker сразу отправит ему сохранённое значение.

Это полезно для текущего состояния, но опасно для команд и кратковременных событий.

Где retained обычно полезен

• последнее известное состояние устройства;
• статическая конфигурация;
• MQTT Discovery messages;
• некоторые availability/status topics при правильной логике.

Где retained часто вреден

• команда «открыть ворота»;
• импульс «перезагрузить»;
• одноразовое событие кнопки;
• триггер сценария.

Как удалить retained message

По MQTT 5 retained-сообщение удаляется публикацией сообщения с нулевой длиной payload в ту же topic с установленным RETAIN.

QoS 0, QoS 1 и QoS 2: какой выбрать

QoS 0

Сообщение отправляется без подтверждения доставки. Это самый лёгкий режим. Для температуры, мощности или RSSI, публикуемых каждые несколько секунд, потеря одного пакета обычно незаметна.

QoS 1

Broker/клиент подтверждает доставку. Сообщение может быть доставлено повторно, поэтому обработчик должен по возможности быть идемпотентным.

QoS 2

Использует более сложный четырёхшаговый обмен для исключения повторной доставки на уровне MQTT. В домашней автоматизации QoS 2 нужен редко.

LWT: как Home Assistant понимает, что устройство действительно offline

Last Will and Testament — сообщение, которое клиент заранее передаёт broker при подключении. Если соединение оборвётся некорректно, broker публикует Will Message за клиента.

Обычно используют отдельную availability topic:

device/boiler/availability = online
device/boiler/availability = offline

При штатном подключении устройство публикует online, а Will Message заранее настроено как offline.

Как MQTT интегрируется с Home Assistant

В Home Assistant есть официальная MQTT integration. После подключения к broker она может создавать MQTT sensors, switches, lights, binary sensors, climate entities и другие типы объектов.

У сущности обычно есть отдельные topics:

state_topic: house/pump/state
command_topic: house/pump/set
availability_topic: house/pump/availability

Такое разделение важно: state topic сообщает фактическое состояние, command topic принимает желаемое действие, availability topic показывает доступность.

MQTT Discovery: автоматическое создание сущностей

Home Assistant умеет автоматически создавать MQTT entities по специальным discovery topics. Устройство публикует конфигурацию, а Home Assistant создаёт сущность без ручного YAML.

homeassistant/sensor/boiler_temp/config

Discovery особенно удобно для устройств, которые должны автоматически добавляться после установки или перезапуска.

ESPHome: Native API или MQTT

ESPHome поддерживает оба подхода. Для обычного проекта Home Assistant чаще проще Native API: он обеспечивает прямую интеграцию, автоматическое появление сущностей и не требует отдельного broker.

MQTT не делает ESPHome автоматически надёжнее. Он добавляет ещё один компонент — broker, который тоже должен работать и быть доступен.

Как строить topics, чтобы система не превратилась в хаос

Для домашней системы удобно придерживаться стабильной структуры:

house/{zone}/{device}/{parameter}

house/kitchen/climate/temperature
house/boiler/controller/state
house/power/meter1/voltage_l1
house/gate/controller/availability

Полезные правила:

• не включать IP-адрес в topic, если он может измениться;
• использовать стабильный device ID;
• отделять state от command;
• отделять availability от обычного состояния;
• не смешивать единицы измерения внутри одной topic;
• не менять структуру topics без необходимости на работающем объекте;
• документировать topics для инженерных устройств.

Как защитить MQTT broker

Broker получает доступ ко многим состояниям и командам дома, поэтому его нельзя считать безобидным внутренним сервисом.

• не разрешайте anonymous access без явной необходимости;
• используйте отдельные учётные записи для разных сервисов;
• ограничивайте ACL по topics;
• не публикуйте порт broker напрямую в интернет;
• для удалённых площадок используйте VPN или защищённый канал;
• применяйте TLS там, где трафик выходит за пределы доверенного сегмента;
• не храните пароль broker открытым в публичных конфигурациях;
• обновляйте Mosquitto и клиентские библиотеки.

Как диагностировать MQTT, если Home Assistant показывает странное состояние

1. 1

   Подписаться на нужную ветку

   Посмотреть реальные сообщения через MQTT Explorer или mosquitto_sub.

2. 2

   Проверить retained

   Если значение появляется мгновенно после subscribe, выяснить, не retained ли оно.

3. 3

   Проверить state и command topics

   Убедиться, что они не перепутаны.

4. 4

   Проверить availability

   Посмотреть, кто публикует online/offline и есть ли LWT.

5. 5

   Проверить client ID

   Два клиента с одинаковым Client Identifier могут выбивать друг друга из broker.

6. 6

   Проверить ACL

   Клиент может подключаться, но не иметь права читать или публиковать нужную topic.

7. 7

   Проверить QoS и reconnect

   Особенно если сообщения дублируются после потери связи.

mosquitto_sub -h 192.168.1.10 \
  -u ha_debug \
  -P 'PASSWORD' \
  -v \
  -t 'house/#'

Типичные ошибки MQTT в умном доме