Matter не подключается к Home Assistant: проверяем Thread, IPv6 и код

Телефон прочитал QR-код, устройство помигало — и Home Assistant снова написал, что подключение не удалось. Очередной заводской сброс редко объясняет причину. Гораздо полезнее выяснить, на каком участке остановилось добавление.

Эта инструкция посвящена диагностике Matter в Home Assistant. Будем идти от простого к сложному: проверим тип устройства, сервер, телефон, локальную сеть и только затем настройки Thread. Рабочие устройства заранее удалять не нужно.

Для знакомства с назначением протоколов есть базовый разбор Matter и Thread. Здесь сосредоточимся на поиске сбоя при подключении; названия меню и порядок действий сверяем с актуальной документацией ниже.

Быстрая развилка: Wi-Fi или Thread

Посмотрите маркировку и инструкцию конкретной модели. Надпись Matter не означает, что внутри обязательно есть Thread.

• Matter over Wi-Fi: устройство подключается к Wi-Fi; отдельный Thread Border Router ему не нужен.
• Matter over Thread: нужен пограничный маршрутизатор Thread, соединённый с вашей LAN, и доступные телефону данные этой Thread-сети.
• Только Thread без Matter: проверьте прикладной протокол. Например, Thread-устройство HomeKit добавляется другим способом.
• Обычное Wi-Fi-устройство без Matter: QR-код приложения производителя не превращает его в Matter-устройство.

Если устройство относится к последнему случаю, ищите его интеграцию: на сайте есть разбор локальных Wi-Fi-интеграций Home Assistant. Повторять мастер Matter в таком случае бессмысленно.

Не путайте три компонента

Matter Server хранит данные контроллера и обменивается командами с устройствами. Интеграция Matter соединяет Home Assistant с этим сервером.

Thread Border Router передаёт IP-пакеты между Thread и домашней сетью. Он может быть отдельным устройством и не обязан находиться в том же корпусе, что Home Assistant.

Телефон участвует в первичном добавлении и передаче сетевых данных. Bluetooth часто нужен именно на этом этапе; постоянное управление не обязано идти через Bluetooth телефона.

Настройка Matter не прошивает произвольный Zigbee-адаптер в Thread автоматически. Разделение ролей и процедура подключения описаны в документации Matter Home Assistant.

Шаг 1. Убедитесь, что Home Assistant видит Matter Server

В HAOS откройте Settings → Devices & services → Matter. Проверьте, что интеграция загружена и соединение с сервером установлено. Если мастер предлагает установить официальный Matter Server, завершите этот шаг и дождитесь его запуска.

При ошибке соединения откройте журнал самого Matter Server. Пока интеграция не может подключиться к серверу, QR-код розетки диагностировать рано.

Home Assistant Container требует отдельного Matter Server и корректной сетевой конфигурации. Старый python-matter-server уже архивирован: разработчики перенесли работу в matterjs-server. При ручной установке проверяйте актуальный проект и указания по переходу, а не закрепляйте образ из старой инструкции. Обращайте внимание на постоянный каталог данных: удаление контейнера вместе с данными контроллера — совсем не то же самое, что обычный перезапуск.

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

Шаг 2. Проверьте телефон и режим добавления

Используйте актуальное приложение Home Assistant Companion. Включите Bluetooth и необходимые разрешения для поиска устройств и локальной сети. Проверьте, что приложение подключено к правильному серверу Home Assistant.

Для нового устройства включите режим сопряжения по инструкции производителя. Долгое нажатие может означать и вход в pairing, и полный сброс — это зависит от модели. Сканируйте Matter QR или вводите соответствующий цифровой setup-код. Не вводите содержимое произвольной QR-ссылки как цифровой код.

Если мастер не видит устройство даже рядом с телефоном, проверьте режим сопряжения и разрешения Bluetooth. Если видит, но останавливается позже, переходите к сети. Этапы обнаружения и установления соединения описаны в разборе commissioning от Google. Зафиксируйте текст ошибки и этап: «не найдено устройство» и «таймаут после передачи сети» требуют разных проверок.

Шаг 3. IPv6 нужен внутри дома, даже без IPv6 у провайдера

Работа сайтов по IPv4 ещё не доказывает, что Matter может связаться с устройством. Ему нужны локальная IPv6-связность и обнаружение через mDNS. Глобальный IPv6-адрес от провайдера для этого не обязателен.

Для первого теста разместите Home Assistant, телефон, Wi-Fi-устройство и Border Router в простой доверенной LAN. Гостевой SSID с изоляцией клиентов — плохой стенд для диагностики. Проверьте, что IPv6 включён в сетевых настройках HA.

Не начинайте с отключения всего firewall. Сначала сравните поведение в обычной LAN и в проблемном сегменте. Если в LAN устройство добавляется, круг поиска сужается до маршрутизации, multicast и правил между сегментами.

Отражатель mDNS решает обнаружение сервисов, но не создаёт IPv6-маршруты. Поэтому «поставил mDNS repeater, всё равно не работает» — вполне ожидаемая ситуация. Для сложных VLAN используйте требования к сети из официальной документации, а не случайный список открытых портов.

Шаг 4. Для Thread проверьте сеть и credentials

Откройте интеграцию Thread и посмотрите, какая сеть выбрана предпочтительной. Наличие найденного Border Router ещё не означает, что телефон получил ключи именно его сети.

Если Home Assistant создал вашу первую Thread-сеть, передайте её данные телефону. В Android Companion для этого есть Sync Thread credentials в разделе Troubleshooting. В iOS передача доступна через настройки Thread и Send credentials to phone. Названия пунктов могут отличаться по языку интерфейса.

Если дома уже есть Thread от Apple или Google, сначала импортируйте данные нужной сети в Home Assistant и выберите её согласно соответствующему сценарию. Не создавайте новую сеть только потому, что старый Border Router обнаружился автоматически. Разные сети не объединяются от одинакового имени.

Порядок импорта и передачи ключей для разных платформ приведён в инструкции по Thread. Не публикуйте credentials и setup-коды в скриншотах диагностики.

Устройство уже работает в Apple Home или Google Home

Начинайте с функции совместного доступа Matter в той экосистеме, где устройство уже добавлено. Откройте новое окно сопряжения, получите свежий код и в Home Assistant выберите добавление уже настроенного устройства.

Заводской код на корпусе и временный код совместного доступа выполняют разные роли. Для multi-admin используйте код из текущего окна сопряжения; если время истекло, создайте новый. Заводской код не «сгорает навсегда» — он нужен, в частности, после заводского сброса.

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

Подключилось, но пропадает или не показывает нужную функцию

Работает рядом с Border Router, пропадает на месте установки: проверьте питание, радиопокрытие и доступность соседних Thread-узлов. Батарейный датчик не следует считать ретранслятором только из-за логотипа Thread.

Пропадает после перезапуска роутера: сравните доступность Border Router, IPv6 и сервера до и после перезагрузки. Не меняйте одновременно радио, Wi-Fi и версии приложений — потеряете связь между действием и результатом.

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

У вас уже работает Zigbee: менять весь комплект ради устранения ошибки одной Matter-розетки не требуется. Для сравнения возможностей есть ZHA или Zigbee2MQTT.

Перед повторной попыткой запишите четыре вещи: модель и прошивку устройства, Wi-Fi или Thread, этап сбоя и версии HA/Matter Server/Companion. С такими данными журнал превращается в инструмент диагностики, а очередной сброс перестаёт быть единственным планом.