Xiaomi и Aqara в Home Assistant

Устройства Xiaomi и Aqara подключаются к Home Assistant встроенными интеграциями. Основной путь для Wi-Fi устройств - интеграция Xiaomi Home с входом по аккаунту, без ручных токенов. Датчики добавляет интеграция Xiaomi BLE, шлюзы Aqara - Xiaomi Gateway (Aqara), а устройства с поддержкой HomeKit или Matter - интеграции HomeKit Device и Matter. Отдельный маршрут для шлюзов Xiaomi - сторонняя интеграция XiaomiGateway3, которая ставится через HACS (сторонний каталог интеграций).

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

Набор зависит от того, какие устройства вы подключаете.

Устройство	Что нужно заранее
Wi-Fi устройства, вход по аккаунту	Приложение Xiaomi Home с аккаунтом, устройство заранее добавлено в него. Робот-пылесос должен быть подключен именно к Xiaomi Home, а не к приложению Roborock.
Wi-Fi устройства, ручной ввод	IP-адрес устройства и его 32-символьный API token.
Датчики Xiaomi BLE	Работающая интеграция Bluetooth в Home Assistant.
Шлюз Aqara	Телефон с приложением Mi Home - в нем проходит настройка и получают ключ шлюза. Ключ не обязателен, если пользуетесь только датчиками и бинарными датчиками. Роутер должен поддерживать multicast.
Устройства HomeKit	Код спаривания с корпуса устройства или упаковки - потерянный код восстановить нельзя. Включенное устройство в вашей сети. Если у Home Assistant нет встроенной поддержки Bluetooth, документация советует ESPHome Bluetooth proxy.
Matter	Документация рекомендует запускать сервер Matter как приложение Matter (app, раньше - add-on, аддон) на Home Assistant OS. Для Thread-устройств нужен Thread border router (маршрутизатор сети Thread).

Для Matter также нужен телефон: Android 8.1 как минимум, рекомендуется 12 и выше, либо iPhone с iOS 16 и выше - в другом месте документации минимумом названа iOS/iPadOS 16.4. На телефоне включен Bluetooth, а на Android для приложения Companion разрешение Location стоит в режиме Allow all the time. Держите телефон рядом с border router и устройством. Matter-устройства с Wi-Fi часто используют диапазон 2.4 ГГц. Перед началом обновите Home Assistant до актуальной версии.

Wi-Fi устройства через аккаунт

Wi-Fi устройства Xiaomi подключаются интеграцией Xiaomi Home по аккаунту - это основной путь.

1. Откройте Settings > Devices & services, в правом нижнем углу нажмите Add Integration и выберите в списке Xiaomi Home.
2. Укажите Username - адрес email или имя пользователя аккаунта Xiaomi Home.
3. Введите Password и выберите Server region - тот регион сервера, что используется в приложении Xiaomi Home.

Устройства Xiaomi Home могут не обнаруживаться, когда Home Assistant и устройство находятся в разных подсетях или VLAN.

Ручная настройка по IP и токену

Документация называет этот путь не рекомендуемым. Включите Configure manually, затем укажите IP address устройства и 32-символьный API token. Токены добывают сторонними инструментами - они перечислены ниже.

Датчики Xiaomi BLE

Датчики Xiaomi BLE добавляет интеграция Xiaomi BLE: она сама находит устройства (discovery, автообнаружение), когда в Home Assistant работает Bluetooth.

1. Откройте Settings > Devices & services, нажмите Add Integration и выберите Xiaomi BLE. Другой вход - кнопка My на странице интеграции в документации.
2. Следуйте инструкциям на экране.

Шлюз Aqara

Шлюз Aqara подключается интеграцией Xiaomi Gateway (Aqara) по локальной сети, а ключ шлюза берут в приложении Mi Home на телефоне.

1. Откройте Settings > Devices & services - шлюз должен обнаружиться сам и появиться в обзоре.
2. Выберите configure и пройдите шаги с необязательными настройками.
3. Если шлюз не появился, нажмите значок + в правом нижнем углу и найдите xiaomi_aqara.
4. Для остальных шлюзов повторите настройку.

Ключи, созданные в iOS-версии приложения, иногда вызывают ошибку invalid key - в таком случае используйте Android-телефон или эмулятор.

Устройства HomeKit

Устройства с поддержкой HomeKit подключаются интеграцией HomeKit Device по коду спаривания.

1. В Settings > Devices & services найдите обнаруженное устройство, выберите Configure на интеграции HomeKit Device и введите HomeKit pairing code.
2. Добавьте устройство в комнату и нажмите Finish.

Батарейному устройству может понадобиться нажатие кнопки, чтобы оно проснулось для спаривания. Home Assistant находит только аксессуары, которые еще не спарены с другим контроллером.

Matter-устройства

Новое Matter-устройство добавляется только из приложения Home Assistant Companion на телефоне. Запускается комиссионинг (commissioning), то есть процесс ввода устройства в сеть.

Через iPhone

1. Нажмите Add device и выберите No. It’s new.
2. Отсканируйте QR-код устройства камерой телефона. Если код не читается, выберите More options и введите код вручную.
3. Выберите Add to Home Assistant - начнется комиссионинг, он может занять несколько минут.
4. По завершении нажмите Done, затем Finish, а если ничего не меняли - Skip and finish.

Через Android

1. Включите устройство - подайте питание или вставьте батарею - и отсканируйте его QR-код. Когда появится запрос Choose an app, выберите Home Assistant.
2. Если окно не появилось, откройте Settings > Connectivity > Matter, выберите Add device, затем No. It’s new и Setup without QR-code для ручного ввода кода.

Уже в другом контроллере

Если устройство уже работает с другим контроллером, при добавлении выберите Yes. It’s already in use и укажите этот контроллер.

Шлюз через XiaomiGateway3

Шлюзы Xiaomi, включая Multimode Gateway 2, подключаются сторонней интеграцией XiaomiGateway3 из HACS - она добавляет шлюз и все его Zigbee, BLE и Mesh устройства. Сетевые настройки должны соответствовать README интеграции, иначе шлюз может работать нестабильно.

1. В HACS откройте Integrations, нажмите Plus, найдите XiaomiGateway3 и выберите Install. Если HACS не виден среди интеграций, поможет разбор проблемы HACS не появляется в списке интеграций Home Assistant.
2. Добавьте интеграцию дважды через Add Integration, выбрав Xiaomi Gateway3. Первая запись - облачная версия, она подтягивает из облака токены и имена ваших устройств; если токен шлюза уже известен, этот шаг можно пропустить.
3. Вторая запись - Gateway: добавляет сам шлюз и все подключенные Zigbee, BLE и Mesh устройства. В поле Host укажите IP-адрес шлюза, зафиксированный на Wi-Fi роутере. Поля Token и Key заполняйте по необходимости: ключ нужен только для Xiaomi Multimode Gateway с прошивкой 1.5.5.
4. Если на втором шаге интеграции нет в списке, очистите кеш браузера.
5. Новое Zigbee-устройство добавляется командой шлюза Zigbee pairing.

Режим ZHA

Шлюз можно отдать под ZHA (Zigbee Home Automation) - стандартный компонент Home Assistant для управления Zigbee. Интеграция работает в режимах ZHA и z2m (Zigbee2MQTT). При настройке ZHA в поле Serial device path укажите socket://{gatewayIP}:8888.

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

Токены, ключи и особенности отдельных шлюзов, которые нужны в нестандартных случаях.

• Токены Xiaomi. Поддерживаемый сообществом Xiaomi Cloud Tokens Extractor достает токены устройств вашего аккаунта Xiaomi. На Windows и macOS токен доступа можно получить приложением Get MiHome devices token.
• Ключи Xiaomi BLE. MiBeacon v2/v3 использует AES без аутентификации, ключ - 24 шестнадцатеричных символа (12 байт). MiBeacon v4/v5 - AES с аутентификацией, ключ из 32 шестнадцатеричных символов (16 байт); нужный bind key Home Assistant импортирует из вашего аккаунта. Telink Flasher от pvvx генерирует новые ключи для поддерживаемых устройств. У части устройств Yeelight шифрование V2/V3, их ключ этими методами не определить. Датчику Flower Care (HHCCJCY01) может понадобиться обновление прошивки в официальном приложении, минимальная подтвержденная рабочая версия - 3.2.1.
• Шлюзы Aqara. Hub v1 работает без проблем, hub v2 может требовать включения локального API, иногда со вскрытием корпуса. Шлюз lumi.gateway.aqhm01 не поддерживается - в Mi Home нельзя включить dev mode. Home Assistant в Docker запустите с --net=host.
• Matter. Если сервер Matter уже работает в другом приложении (app) Home Assistant или собственном контейнере, используйте его. Для OpenThread (Connect ZBT-1, ZBT-2, SkyConnect) в роли border router действует отдельная настройка. Matter-мост позволяет управлять устройствами из их родного приложения.
• HomeKit. HomeKit Bridge работает со стороны Apple Home: он открывает устройства Home Assistant для Siri и Apple Home - выберите Configure на этой интеграции. У устройств с поддержкой Thread статус Thread виден в настройках устройства и включается там же. Устройство на Thread через Apple border router, например HomePod mini, сначала удалите из приложения Apple Home, не сбрасывая само устройство.
• XiaomiGateway3. Zigbee-устройство можно привязать только к одному шлюзу. BLE и Mesh устройства работают одновременно в Mi Home и Home Assistant. Matter поддерживается только на Xiaomi Multimode Gateway 2 (EU) с прошивкой 1.0.7_0019 и выше. Кастомная Zigbee-прошивка работает только в режимах ZHA и z2m.

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

Ограничения зависят от интеграции: часть связана с сетью, часть - с поддержкой устройств.

Интеграция	Ограничения
Xiaomi Home	Методы добычи токенов рассчитаны на старые версии Mi Home и с текущими не проверялись. Если нужны токены нескольких устройств, приложение может показать токен, который не подойдет устройству. После сброса Wi-Fi робот-пылесос генерирует новый токен.
Xiaomi BLE	BLE Mesh устройства не поддерживаются. Часть сущностей появляется позже - соответствующие значения вещаются реже. Flower Care читает батарею раз в сутки и требует хорошего сигнала; после обновления прошивки приложение и аккаунт Flower Care больше не нужны.
Xiaomi Gateway (Aqara)	Замком Aqara управлять нельзя, видны только его данные. У шлюзов с MAC-адресом на 04:CF:8C или 7C:49:EB может быть закрыт порт 9898, тогда способ не сработает. Сброс шлюза - держать кнопку 30 секунд и настраивать заново.
HomeKit Device	Кнопки, пульты и дверные звонки отдают только события - настраивайте их через автоматизации устройств. Для устройств не из списка поддержки сущности могут не создаться, но устройство появится в реестре устройств. Через VLAN нужен mDNS reflector. Если код спаривания простой или угадываемый, интеграция предупредит об этом при спаривании.
Matter	Приложение Matter Server не поддерживается на 32-битных платформах, отдельный Docker-контейнер тоже не поддерживается. Thread-устройствам нужен Home Assistant OS 10 и выше. Сборки Android-приложения без Google Play services не добавляют Matter. Home Assistant как контроллер поддерживает только управление Matter-устройствами. IPv6-трафик (multicast) должен свободно доходить до хоста Home Assistant. Matter рассчитан на обычную домашнюю сеть, VLAN и корпоративные функции могут мешать.
XiaomiGateway3	Zigbee-устройства в режимах ZHA и z2m этой интеграцией не управляются. Wi-Fi устройства Xiaomi не поддерживаются. Если один шлюз обслуживает два Home Assistant, версии интеграции на них должны совпадать. Данные о батарее BLE-устройств зависят от прошивки; на прошивках вне рекомендованного списка работа не гарантирована.

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

Можно ли управлять замком Aqara из Home Assistant?

Нет, Home Assistant не умеет управлять замками Aqara, он только показывает их данные. Это ограничение интеграции Xiaomi Gateway (Aqara), которая работает по локальной сети через шлюз. Если нужно именно управление замком, этот путь не подойдет. Остальные ограничения интеграции собраны в таблице выше, например закрытый порт 9898 у части шлюзов.

Потерял код спаривания HomeKit - что делать?

Восстановить код нельзя. Он напечатан на устройстве или упаковке, и в документации прямо сказано, что способа восстановления нет. Поищите код на коробке и корпусе. Заодно проверьте, не спарено ли устройство с другим контроллером: Home Assistant находит только аксессуары, которые еще свободны.

Датчик Xiaomi BLE добавился, но сущности появляются не сразу. Это нормально?

Да, это возможное поведение. Часть значений датчик вещает реже остальных, поэтому некоторые сущности появляются с задержкой. У Flower Care батарея читается один раз в сутки, чтобы не разряжать ее, а соединению нужен хороший сигнал. Если устройство не появилось совсем, проверьте, что интеграция Bluetooth в Home Assistant работает.

После сброса Wi-Fi робот-пылесос отвязался в Home Assistant. Почему?

После сброса настроек Wi-Fi робот-пылесос генерирует новый токен доступа. Если пылесос добавлен вручную по IP-адресу и токену, получите новый 32-символьный токен и впишите его заново. Если токены нужны для нескольких устройств, приложение Xiaomi Home может показать токен, который не подходит конкретному устройству. Для работы по аккаунту пылесос должен числиться именно в Xiaomi Home, а не в Roborock.

Можно ли добавить Matter-устройство с компьютера?

Нет, новое Matter-устройство добавляется только из приложения Home Assistant Companion на телефоне. На Android нужна сборка с Google Play services: версии без них добавлять Matter не умеют. Bluetooth на телефоне должен быть включен, а на Android разрешение Location нужно выставить в режим Allow all the time.