MQTT и Mosquitto в Home Assistant

Для обмена MQTT-сообщениями в Home Assistant подключите интеграцию MQTT к брокеру Mosquitto - серверу, который принимает и раздает сообщения. Отправлять и читать их можно прямо из интерфейса Home Assistant. Ошибки MQTT-подключения встречаются и при настройке Zigbee2MQTT.

Что понадобится

Приложение Mosquitto доступно только на Home Assistant OS. В текущей документации Home Assistant прежние аддоны называются приложениями (apps). Сама интеграция MQTT доступна при любом способе установки Home Assistant, см. документацию.

• Брокер с поддержкой протокола MQTT версии 5 - такое требование у Home Assistant, см. документацию интеграции.
• Сам Mosquitto - брокер сообщений по модели publish/subscribe (публикация и подписка), сайт проекта - mosquitto.org.
• Учетные данные клиента MQTT. Приложение Mosquitto отклоняет анонимные подключения, поэтому заранее решите, какое имя пользователя и пароль использовать.

Установка и настройка

Установите и запустите приложение Mosquitto broker, создайте пользователя и подключите интеграцию MQTT.

1. Установите приложение

Откройте магазин приложений Settings > Apps > Install app, найдите Mosquitto broker и нажмите INSTALL. Порядок установки описан в документации Mosquitto.

2. Запустите брокер

Запустите приложение, подождите, пока оно стартует, и проверьте вывод журнала - по нему видно, как прошел запуск.

3. Создайте пользователя MQTT

Создайте пользователя Home Assistant в разделе Settings > People > Users. Для этого используйте раздел пользователей, а не вкладку Configuration приложения Mosquitto. Если создание пользователя не видно, включите в профиле режим Advanced Mode. Имя не может быть homeassistant или addons, оба имени зарезервированы.

4. Примите найденную интеграцию

Откройте Settings > Devices & Services > Integrations, выберите найденную интеграцию MQTT, при желании включите discovery (автоматическое обнаружение устройств) и подтвердите добавление.

5. Если интеграция не нашлась, добавьте вручную

Откройте Settings > Devices & services, нажмите Add Integration и выберите MQTT. Для ручного варианта укажите имя хоста или IP-адрес брокера, порт и учетные данные.

6. Проверьте настройки discovery

Откройте Configure MQTT Options и проверьте включение discovery и его префикс. Устройству нужны топик (канал MQTT-сообщений) конфигурации вида <discovery_prefix>/<component>/[<node_id>/]<object_id>/config и payload (содержимое сообщения).

7. Проверьте обмен сообщениями

Откройте у интеграции Configure, выберите Publish a packet, укажите топик и Payload, затем нажмите Publish. Чтобы принимать сообщения, выберите Listen to a topic, укажите топик # и нажмите Start listening.

Другие способы

Вместо Mosquitto можно подключить другой совместимый брокер. Сущности можно добавлять вручную:

• Через интерфейс. Используйте кнопку Add MQTT device или поддерживаемые подзаписи интеграции.
• Через YAML. Опишите датчик в configuration.yaml в секции mqtt, блок sensor, ключ state_topic, затем перезапустите Home Assistant. Подробнее - в документации MQTT-датчика.

Важные ограничения

Стандартные порты MQTT - 1883 без шифрования и 8883 с шифрованием. Для TLS-шифрования задайте файлы certfile и keyfile в разделе ssl приложения (аддона). Все TLS-клиенты должны доверять этому сертификату.

Чтобы несколько MQTT-сущностей группировались в одно устройство, нужны identifiers или connections в секции device, а информация об устройстве у сущности требует unique_id.

Частые проблемы

Проверьте учетные данные клиента, адрес брокера и настройки сети. В таблице приведен опыт пользователей форума; справа указано число веток с проблемой.

Проблема	Что помогало пользователям	Веток
Устройства и сущности MQTT не появляются, хотя сообщения идут или клиенты онлайн	Включить Auto Discovery в Solar Assistant; для динамических MQTT-датчиков - отладить скрипт с подробными журналами (debug) интеграции MQTT и MQTT Explorer	6
Ошибка авторизации error: received null username or password for unpwd check	Исправить несовпадение пароля клиента; при настройке интеграции с новым пользователем - добавить имя и пароль в конфигурацию приложения (аддона); при ошибке MQTT failed to connect у Zigbee2MQTT - использовать имя и пароль без дефиса	5
Неверное имя хоста или адрес брокера, подключения и сообщения не доходят	В Home Assistant в Docker на Windows - указать IP-адрес машины с Docker вместо localhost; для внешнего Frigate - заменить core-mosquitto на IP-адрес брокера	4
Датчики делят один топик, в журнале 2024-02-16 16:00:32.204 WARNING (MainThread) [homeassistant.helpers.template] Template variable warning: 'dict object' has no attribute 'POWER1' when rendering '{{ value_json.POWER1 }}'	Публиковать каждый параметр в отдельный топик с сохранением последнего сообщения (retained) и подписывать датчики на них. Для LOGO - использовать триггерные переменные и условие непустого ключа, чтобы пропускать сообщения только с отметкой времени; для датчиков присутствия и освещенности - также сверять регистр state_topic. Подробный разбор - общий топик у MQTT-датчиков	3
Сеть Docker мешает Home Assistant подключиться к брокеру	Исправить конфигурацию моста macvlan; при Mosquitto в Docker - следовать инструкции по Home Assistant в Docker и перезапустить Docker	2
Сущности пропадают или остаются в состоянии unknown (неизвестно) после старта Home Assistant, сообщение "This entity is no longer being provided by the mqtt integration. If the entity is no longer in use, delete it in settings."	Вручную перезапускать приложение (аддон) Zigbee2MQTT после старта Home Assistant или автоматизировать перезапуск по идентификатору приложения (slug); для света Shelly - публиковать status_update при старте Home Assistant	2
Подключение падает с ошибкой failed to receive on socket: [Errno 104] Connection reset by peer	При самоподписанном сертификате - передать CA-файл, чтобы применялась опция TLS insecure	2
Интеграции MQTT нет в списке, при добавлении появляется It's not showing among the already installed integrations, and when I try to add it, I only get as far as this message: "single_instance_allowed".	Включить показ отключенных интеграций, затем включить MQTT и перенастроить ее	1

Частые вопросы

Можно ли обойтись без ручной установки Mosquitto?

Да, интеграция MQTT может сама установить и настроить Mosquitto, а также сгенерировать внутренние учетные данные. Для авторизации клиентов есть и отдельный вариант с локальными пользователями приложения Mosquitto вместо пользователей Home Assistant. Их задают в самом приложении через logins, username и password.

Как восстановить обнаружение и значения датчиков после старта?

Для обнаружения нужны повторные discovery-сообщения, а для немедленного получения последнего значения датчика - сохраненное состояние. При старте MQTT обнаруженным элементам снова нужны сообщения конфигурации. Восстановить их помогает retained discovery - сохраненная конфигурация обнаружения - или повторная публикация при сообщении о запуске (Birth). Если состояние публикуется с флагом RETAIN, датчик сразу получает последнее значение; иначе его начальное состояние не определено.

Как проверить брокер без интерфейса Home Assistant?

Используйте утилиты командной строки mosquitto_pub и mosquitto_sub. Первая поддерживает MQTT версий 5 и 3.1.1, публикует одно сообщение в топик и завершает работу. Опции -h, -p, -t, -m задают хост, порт, топик и содержимое сообщения, см. man-страницу. Вторая подписывается на топик и печатает принятые сообщения; опции -h, -p, -t, -v задают хост, порт, топик и подробный вывод.