MQTT Explorer: как пользоваться для диагностики умного дома

MQTT Explorer это настольный клиент MQTT, который показывает всё, что публикуется в брокер. Проще говоря, это лупа для брокера: она не управляет домом, а показывает, какие топики и сообщения в нём реально есть. Инструмент нужен в одной типовой ситуации: устройство вроде бы подключено, но его объектов в Home Assistant нет, и надо понять, публикует ли оно данные вообще.

Коротко: MQTT Explorer подключается к брокеру по адресу и порту 1883 и показывает дерево всех топиков. Он автоматически подписывается на все топики и на системные сообщения брокера, поэтому в дереве видны и текущие значения, и сохранённые retained-записи. Это диагностический инструмент, а не приложение для управления умным домом: команды через него отправляют только для проверки.

Что такое MQTT Explorer и зачем он нужен

Он показывает всё, что публикуется в брокер MQTT, и служит для диагностики, а не для управления умным домом. Если устройство подключено, но не отображается в Home Assistant, этот инструмент помогает проверить, отправляет ли оно сообщения вообще. Начните с материала про MQTT в Home Assistant: там разобраны брокер, учётная запись и подключение интеграции.

Чтобы использовать MQTT Explorer, нужно указать параметры подключения к брокеру. Если сообщения от устройства есть, а объектов в Home Assistant нет, проблема может быть в формате данных или в топике автообнаружения. Инструмент показывает структуру сообщений и их содержимое. Если устройство не отправляет сообщений, проверять надо его настройки и сеть, а не Home Assistant.

Установка и платформы

MQTT Explorer это открытый проект, код которого доступен на GitHub в репозитории thomasnordquist/MQTT-Explorer. Для работы достаточно настольной версии, собранной на Electron. Она работает на Windows, macOS и Linux и позволяет отслеживать сообщения в реальном времени. Для домашней отладки такого набора обычно хватает. Если нужно смотреть топики с другого компьютера, есть режим браузера и запуск в Docker. Настольная версия это основной инструмент для диагностики, а Docker добавляет гибкость в сложных сценариях.

Первое подключение к брокеру

Начинается с запуска MQTT Explorer. В окне нового подключения указывают имя соединения, например «Home Assistant». В поле хоста вводят IP-адрес или имя компьютера, где установлен брокер, например адрес Home Assistant в локальной сети. Порт выбирают в зависимости от протокола: 1883 для обычного MQTT, 8883 для TLS или 80 и 443 для WebSocket. Типовые сочетания собраны в таблице.

Если порт указан неверно, соединение не установится, и вместо дерева появится ошибка подключения.

Логин и пароль брокера вводят в том же диалоге. Убедитесь, что они совпадают с настройками в Home Assistant. Если данные неверны, соединение откажется. После успешного подключения можно проверить, появляется ли устройство в списке топиков. Если нет, проверьте, включено ли устройство в сеть и правильно ли настроены параметры в Home Assistant.

Автоподписка и что попадает в дерево

После подключения клиент автоматически подписывается на два шаблона: решётка, то есть все топики, и $SYS/решётка для системных сообщений брокера. Поэтому в дереве сразу видно всё, что публикуется в данный момент. Это позволяет быстро определить, какие устройства отправляют данные и какие сообщения генерирует брокер.

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

Как читать дерево топиков

Чтобы понять, как устройства взаимодействуют в системе, нужно изучить структуру топиков. Каждый топик разделен слэшем и образует иерархию, которую можно разворачивать. Первый уровень часто указывает на интеграцию или устройство, например homeassistant/status или zigbee2mqtt/имя устройства. Устройства Zigbee2MQTT публикуют свои состояния именно по такому шаблону. Далее идут узлы и атрибуты, которые описывают состояние или параметры. Разворачивая узлы, видно, сколько устройств реально выходит на связь и какие данные они отправляют.

Отдельно смотрят атрибуты состояния: online или offline, значения датчиков, команды. Если нужного топика в дереве нет, устройство не подключено к брокеру или не публикует данные. Это самый быстрый способ отделить проблему устройства от проблемы Home Assistant.

Retained-сообщения и автообнаружение

Брокер MQTT хранит последнее сообщение с флагом retain и отправляет его сразу после подключения нового клиента. Это позволяет увидеть текущие значения устройств, даже если они временно не отправляют данные. В топиках автообнаружения Home Assistant используются именно эти сообщения для создания объектов. Если retained-запись повреждена или устарела, объект может не появиться или работать некорректно.

Проверьте, не повреждены ли retained-сообщения в топиках автообнаружения. Устаревшие данные могут вызвать сбои в работе объектов. Если устройство не появляется в Home Assistant, попробуйте перезапустить брокер или обновить конфигурацию.

Как отправить тестовое сообщение

В окне публикации MQTT Explorer введите топик, который используется устройством для приема команд. Укажите payload, то есть данные, которые отправляются, например команду включения или выключения. Выберите уровень QoS: 0 означает отправку без гарантии доставки, 1 доставку минимум один раз, 2 ровно один раз. Уровень QoS влияет на надежность передачи, но не гарантирует, что устройство получит сообщение. Если устройство не отвечает, проверьте, правильно ли задан топик и payload, и убедитесь, что оно подключено к брокеру.

Флаг retain позволяет сохранить сообщение в брокере после отключения клиента. Если включить его, сообщение останется доступным для новых подключений. Это удобно для тестирования, когда устройство временно отключено. Публикуйте команду в топик устройства и наблюдайте за реакцией. Если устройство не реагирует, попробуйте перезапустить его или проверьте настройки брокера. Убедитесь, что все параметры соответствуют документации устройства, иначе сообщение может не доставляться.

Поиск и фильтры

Помогают упростить работу с деревом тематики. Дерево можно фильтровать по подстроке, по включающим и исключающим шаблонам, а также по регулярным выражениям. Подстановочные знаки плюс и решётка позволяют уточнить поиск. Если брокер обслуживает десятки устройств, без фильтра дерево становится нечитаемым. Можно оставить только один узел и отслеживать его изменения. Это особенно полезно при диагностике конкретного устройства.

Фильтры позволяют фокусироваться на нужных данных, убирая лишние. Например, можно отфильтровать только темы, связанные с определённым типом устройства. Это упрощает анализ и помогает быстрее выявить проблемы. Если устройство не появляется в системе, проверьте, не заблокировано ли оно фильтром. Также можно использовать подстановочные знаки для поиска по частям названий.

Диагностика: устройство не появляется в Home Assistant

Если устройство не появляется в Home Assistant, первым делом проверяют топик автообнаружения. Для Home Assistant это homeassistant/типкомпонента/имяузла/config. Если сообщение в этом топике есть и помечено retain, смотрят, совпадает ли имя узла с тем, что ожидает система. Некоторые устройства отправляют данные в этот топик после подключения, но если сообщение отсутствует, проблема может быть в настройках самого устройства или в соединении с брокером.

Если сообщений в топике нет, искать проблему нужно на стороне устройства, сети или настроек брокера. Проверяют, включено ли устройство, корректно ли настроены параметры подключения и нет ли ошибок в логах брокера. Общий порядок разбора сбоев описан в материале про диагностику умного дома. Ничего не нужно менять в Home Assistant, пока не убедятся, что данные поступают извне.

Безопасность при работе с брокером

Требует внимания к деталям. Подписка на все топики отображает данные в открытом виде: логины, токены, статусы устройств. Это может выглядеть как простой текст, но содержит конфиденциальную информацию. Скриншоты дерева топиков нельзя публиковать без проверки, чтобы не утечь данные. Никогда не подключайтесь к чужому брокеру без разрешения, это нарушает приватность и может привести к утечке информации.

Открывать порт 1883 в интернете без шифрования и пароля, опасно. Такие действия делают брокер уязвимым для атак. Даже если вы уверены в безопасности сети, стоит использовать TLS-шифрование и сложные пароли. Это защитит данные от несанкционированного доступа и снизит риски утечки информации. Проверяйте настройки безопасности перед публикацией или передачей данных.

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

Вопрос: Нужен ли интернет для работы самого клиента

MQTT Explorer не требует интернета для работы. Он просто подключается к локальному брокеру MQTT, который может находиться в домашней сети или на удаленном сервере. Главное, чтобы брокер был доступен по сети и настроен правильно.

Вопрос: Чем он отличается от вкладки MQTT в Home Assistant

MQTT Explorer показывает брокер как есть: сырые топики, payload, флаги retain и уровни QoS, и позволяет опубликовать тестовое сообщение. Home Assistant показывает не топики, а готовые объекты, которые создаются из сообщений автообнаружения. Для поиска причины сбоя нужен первый инструмент, для повседневного управления второй.

Вопрос: Почему дерево топиков пустое сразу после подключения

Пустое дерево чаще всего означает, что подключение установлено не к тому брокеру или что в нём действительно ничего не публикуется. Retained-записи видны сразу после подключения, поэтому если их нет, значит этот брокер их не хранит. Проверьте, тот ли адрес и порт указаны и с тем ли брокером работает Home Assistant.

Вопрос: Как удалить retained-сообщение из брокера

Опубликуйте в тот же топик пустой payload с включённым флагом retain. Брокер заменит сохранённое сообщение пустым и удалит запись. Просто отключить клиент недостаточно: без публикации с retain старое значение останется в брокере.