Настройка Home Assistant ZHA через Docker и подключение первого устройства

Home Assistant ZHA (Zigbee Home Automation) — это встроенная интеграция, которая позволяет управлять Zigbee-устройствами через подключенный к серверу USB-координатор (usb-dongle). В этой инструкции мы разберем процесс подключения координатора через настройки в Docker Compose, запуск интеграции ZHA в интерфейсе приложения, а также подключение первого zigbee-устройства.

Настройка Docker Compose для Zigbee-координатора

После подключения Zigbee-координатора к серверу он создает локальную Zigbee-сеть и принимает сигналы от устройств: например, сработал датчик движения или открылась дверь. Чтобы Home Assistant мог получать эти данные, нужно пробросить координатор в Docker-контейнер.

Откройте файл docker-compose.yml и добавьте в конфигурацию сервиса блок devices, указав путь к вашему Zigbee-координатору:

services:
  hass:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /home/ваш_пользователь/имя_директории:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Moscow
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

^O Записать ^X Выход

После добавления параметра devices необходимо пересоздать контейнер, чтобы изменения вступили в силу:

docker compose up -d --force-recreate hass

Где hass — это имя сервиса, указанное в разделе services вашего файла docker-compose.yml. Если вы назвали его иначе, замените hass на ваше имя сервиса.

Проверьте доступность устройства внутри контейнера:

docker exec homeassistant ls -l /dev/ttyUSB0

При правильных настройках вывод на экран будет следующим:

crw-rw----    1 root     dialout   188,   0 Oct  7 12:19 /dev/ttyUSB0

Если команда возвращает ошибку:

ls: /dev/ttyUSB0: No such file or directory

То устройство недоступно внутри контейнера. Проверьте следующие настройки:

Узнайте точное имя устройства на хосте:

ls -l /dev/ttyUSB* /dev/ttyACM*

Если устройство имеет другое имя (например, /dev/ttyACM0), исправьте путь в блоке devices файла docker-compose.yml и пересоздайте контейнер.

Убедитесь, что в docker-compose.yml указан параметр privileged: true и в том, что ваш пользователь входит в группу dialout:

groups

Если группа отсутствует, добавьте в нее своего пользователя:

sudo usermod -a -G dialout $USER

После этого необходимо выйти из системы (logout) и войти снова, затем пересоздать контейнер.

Устройство должно быть подключено до запуска контейнера. Если координатор был подключен после старта контейнера, пересоздайте его:

docker compose up -d --force-recreate hass

Настройка ZHA в Home Assistant

Теперь координатор доступен внутри контейнера и передает данные в Home Assistant. Но сам Home Assistant не умеет обрабатывать их напрямую — ему нужен программный модуль, который преобразует сигналы от датчиков в понятные приложению команды и состояния. Эту задачу решает встроенная интеграция Zigbee Home Automation (ZHA).

Откройте веб-интерфейс Home Assistant (http://IP-адрес:8123) и перейдите в раздел: Настройки → Устройства и службы → Добавить интеграцию (кнопка в правом нижнем углу). В строке поиска введите ZHA и выберите найденный вариант:

Home Assistant автоматически обнаружит подключенный USB-координатор и предложит начать настройку.

Для создания новой сети выберите автоматическую настройку, для восстановления существующей конфигурации — ручную.

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

После завершения настройки откроется страница координатора с базовой информацией об устройстве и статусом сети.

Нажмите «добавить дочерние устройства«, чтобы запустить поиск новых устройств. Переведите подключаемое устройство (датчик, выключатель) в режим сопряжения — обычно для этого нужно удерживать кнопку в течение 5–10 секунд:

После обнаружения устройства задайте ему имя и выберите комнату. Это упростит навигацию в интерфейсе и создание автоматизаций.

На странице интеграции Zigbee Home Automation отображаются все подключенные устройства: координатор, датчики, выключатели и лампы. Отсюда можно управлять каждым устройством и переходить к его настройкам.

Архитектура взаимодействий ZHA через Docker

Чтобы наглядно представить, как именно происходит обмен данными между физическими устройствами и интеграцией ZHA внутри контейнера, взгляните на следующую схему:

На схеме изображено, как сигнал от Zigbee-устройств передаётся в USB-координатор, который подключён к Raspberry Pi. Сервер распознаёт его как /dev/ttyUSB0, а через настройки docker-compose.yml устройство пробрасывается внутрь контейнера Home Assistant, где ZHA использует его для создания и управления Zigbee-сетью.

Ограничения ZHA и совместимость устройств

Встроенная интеграция ZHA удобна в использовании, но поддержка устройств в ней ограничена официальным списком. Популярные бюджетные устройства (особенно на базе Tuya) часто работают с ZHA нестабильно: связь с ними может пропадать, а удаление устройства иногда вызывает зависание интеграции, что требует перезагрузки контейнера. По этой причине многие пользователи выбирают решение с открытым исходным кодом Zigbee2MQTT, которое обеспечивает более стабильную работу с широким спектром устройств.

Однако если вы используете устройства, официально поддерживаемые Home Assistant, переход на сторонние решения может быть излишним — возможностей ZHA вполне достаточно для базовых сценариев.

Итоги: настройка Zigbee-координатора и запуск ZHA

Мы разобрали процесс проброса Zigbee-координатора в Docker-контейнер и подключение первого устройства через встроенную интеграцию ZHA. Такое решение оптимально для подключения официально поддерживаемых умных устройств и базовых сценариев автоматизации. Если в процессе эксплуатации вы столкнетесь с несовместимостью устройств или нестабильной связью, переходите на более гибкую альтернативу — Zigbee2MQTT.