Установка Home Assistant на контроллер Wiren Board

Описание

Home Assistant — это open-source платформа для автоматизации, которую разрабатывает и поддерживает сообщество home-assistant.io. Существует одноимённый мобильный клиент, который может управлять контроллером по локальной сети или через облако производителя.

Платформу можно установить на контроллер Wiren Board и использовать вместо стандартного веб-интерфейса для управления подключёнными устройствами.

Совместимость

Контроллеры Wiren Board 8/8M и более новые модели являются предпочтительными для работы с Home Assistant. Это связано с тем, что поддержка Home Assistant для предыдущих поколений (Wiren Board 6 и Wiren Board 7 на архитектуре armhf) была прекращена в конце 2025 года, и обновления для них больше не выпускаются. Подробнее в заявлении разработчиков.

Установка

Чтобы не потерять установленный софт и его данные, обновляйте ПО контроллера только через менеджер пакетов apt. Подробнее читайте в статье Программное обеспечение Wiren Board.

Встроенный флеш-накопитель контроллера разбит на разделы и для пользователя отведён самый большой из них, который монтируется в папку /mnt/data. Нужно учесть эту особенность при установке программ, а также при обновлении прошивки контроллера.

Копируйте команды из инструкции, вставляйте их в консоль контроллера с помощью клавиш Shift+Insert и запускайте клавишей Enter. В случае ошибок, внимательно читайте вывод, там будут инструкции и подсказки. Внимание! Если на вашем контроллере размер корневого раздела rootfs 1 Гб, расширьте его до 2 Гбайт или больше по инструкции.

Мы будем использовать рекомендуемый разработчиком платформы метод Home Assistant Container. В нём нет супервизора, поэтому установка аддонов (дополнений) из веб-интерфейса Home Assistant недоступна.

В большинстве случаев в дополнение завёрнут сторонний софт: zigbee2mqtt, ESPHome, Node-RED и т. п., который вы можете поставить отдельно теми же контейнерами. Возможно, эта статья по переезду с супервизора в docker вам поможет: Использование docker-compose.yaml вместо супервизора Home Assistant.

Установка:

Установите docker по инструкции.

Создайте каталог под установку:

mkdir -p /mnt/data/.docker-compose/home-assistant
cd /mnt/data/.docker-compose/home-assistant

Создайте внутри:

mkdir -p config/home-assistant
mkdir -p store/media

Откройте файл конфига docker-compose.yaml в редакторе:
```
nano docker-compose.yaml
```

Вставьте в него строки:

Для контроллера Wiren Board 8:

services:
  # HomeAssistant
  homeassistant:
    container_name: home-assistant
    image: homeassistant/home-assistant:latest

    volumes:
      # Local path where your home assistant config will be stored
      - ./config/home-assistant:/config
      - ./store/media:/media
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro # <-- Bluetooth адаптер
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: "${MYTZ}"
    privileged: true
    labels:
      - "com.centurylinklabs.watchtower.monitor-only=true"

Для контроллера Wiren Board 6 и 7:

services:
  # HomeAssistant
  homeassistant:
    container_name: home-assistant
    image: ghcr.io/home-assistant/armhf-homeassistant:latest

    volumes:
      # Local path where your home assistant config will be stored
      - ./config/home-assistant:/config
      - ./store/media:/media
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro # <-- Bluetooth адаптер
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: "${MYTZ}"
    privileged: true
    labels:
      - "com.centurylinklabs.watchtower.monitor-only=true"

Сохраните и закройте файл: Ctrl+S и Ctrl+X.
Укажите в файле .env вашу таймзону:
- UTC (Универсальное время):
```
echo "MYTZ=UTC" >> .env
```
- Центральная Европа (CEST/CET):
```
echo "MYTZ=Europe/Berlin" >> .env
```
- Москва (МСК):
```
echo "MYTZ=Europe/Moscow" >> .env
```
- Полный список доступных зон в Linux можно посмотреть командой:
```
timedatectl list-timezones
```
Запустите контейнер в фоновом режиме командой:
```
docker compose up -d
```

После запуска контейнера откройте браузер и введите адрес своего контроллера в сети и порт 8123. Например: http://192.168.42.1:8123. Консоль можно закрыть.

Обновление

Для обновления подключите контроллер к интернету и выполните команды на получение образа и пересоздание контейнеров:

cd /mnt/data/.docker-compose/home-assistant
docker compose pull homeassistant  # Обновляем образ
docker compose up -d homeassistant  # Пересоздаём контейнер

Так как всю конфигурацию мы храним в каталоге config, при пересоздании контейнера все настройки сохранятся.

Работа с устройствами Wiren Board

Внимание! Интеграция Wiren Board и MQTT-интеграция — это два взаимоисключающих подхода. Интеграция Wiren Board самостоятельно подключается к MQTT-брокеру контроллера и автоматически создает сущности на основе топиков устройств. При использовании MQTT-интеграции вы сами описываете устройства и их топики в configuration.yaml.

Установка интеграции Wiren Board

Настройка происходит с помощью разработанного нами модуля интеграции с Home Assistant. Модуль автоматически создаст описание в файле configuration.yaml из MQTT-топиков устройств.

Скопируйте папку wirenboard из репозитория в директорию /mnt/data/.docker-compose/home-assistant/config/home-assistant/custom_components/.
Откройте веб-интерфейс Home Assistant.
Перезапустите Home Assistant: перейдите в Инструменты разработчика → Перезапуск.
Добавьте интеграцию: перейдите в Настройки → Устройства и службы → Добавить интеграцию и выберите wirenboard.
Поля Хост/Порт предварительно заполнены значениями по умолчанию для подключения к контроллеру. Изменяйте их только при необходимости.

Установка MQTT-интеграции

Home Assistant может управлять Modbus-устройствами с помощью MQTT, для этого нужно установить MQTT-интеграцию и настроить получение и отправку данных.

Установите MQTT-интеграцию:

Перейдите в веб-интерфейс Home Assistant.
В панели слева кликните на пункт Configuration.
На открывшейся странице найдите пункт Devices & Services и зайдите в него.
Нажмите внизу на кнопку Add Integration.
Введите в поле поиска MQTT и выберите найденную интеграцию.
Через несколько секунд откроется окно настройки, в котором заполните поля Broker — localhost и Port — 1883. В стандартной конфигурации контроллера логин и пароль не используются, эти поля оставьте пустыми. Нажмите кнопку Submit.

Установка MQTT-интеграции
Configuration
Devices & Services
Add Integration
Поиск интеграции
Настройка интеграции
Установленная интеграция

Ручная настройка связи с устройствами

Настройка интеграции завершена, теперь надо для каждого устройства создать описание в файле configuration.yaml, для этого откройте файл с помощью редактора:

nano /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml

где /mnt/data/.docker-compose/home-assistant/config/home-assistant/ — путь к конфигурационному каталогу.

В процессе настройки вы будете добавлять в файл секции и описывать в них параметры, например, для описания реле нужно использовать секцию switch.

После редактирования сохраните файл и перезапустите Home Assistant, для этого перейдите в его веб-интерфейсе Configuration → Settings и нажмите кнопку Restart. После нажатия на кнопку файл конфигурации будет проверен и, если он содержит ошибки, вы получите сообщение с подробностями. Чаще всего ошибки связаны с неверными отступами строк, которые имеют значение.

Так как места на контроллере не очень много, рекомендуем ограничить количество сохраняемых в архиве данных. Добавьте для этого в файл настроек строки, где 14 — глубина архива в днях, а 2048 — размер архива в мегабайтах (2 ГБ):

recorder:
  purge_keep_days: 14
  db_max_size: 2048

Несколько моментов:

Полный синтаксис и поддерживаемые типы устройств смотрите в описании MQTT Discovery.
Адреса MQTT-топиков смотрите в стандартном веб-интерфейсе контроллера, раздел Settings → MQTT Channels.
В state_topic пишете адрес MQTT-топика, а в command_topic — тот же адрес, только в конец добавляете /on.

Сенсоры создаются в группе mqtt:, объявленной в примере с датчиком температуры. Подробнее о формате читайте в документации Home Assistant.

Выведем данные с датчика температуры процессора:

mqtt:
  sensor:
    - unique_id: wb_cpu_temperature
      name: "CPU Temperature"
      state_topic: "/devices/hwmon/controls/CPU Temperature"
      unit_of_measurement: "°C"

Настроим управление выходами A1 и A2, этот пример можно использовать для управления модулями реле:

#mqtt:
  switch:
    - unique_id: wb_a1_switch
      name: "WB A1 Switch"
      state_topic: "/devices/wb-gpio/controls/A1_OUT"
      command_topic: "/devices/wb-gpio/controls/A1_OUT/on"
      payload_on: "1"
      payload_off: "0"
      retain: true
    - unique_id: wb_a2_switch
      name: "WB A2 Switch"
      state_topic: "/devices/wb-gpio/controls/A2_OUT"
      command_topic: "/devices/wb-gpio/controls/A2_OUT/on"
      payload_on: "1"
      payload_off: "0"
      retain: true

Настроим управление зуммером контроллера, этот пример можно использовать при подключении диммера светодиодных ламп:

#mqtt:
  light:
    - unique_id: wb_buzzer
      name: "Buzzer"    
      state_topic: "/devices/buzzer/controls/enabled"
      command_topic: "/devices/buzzer/controls/enabled/on"
      brightness_state_topic: '/devices/buzzer/controls/volume'
      brightness_command_topic: '/devices/buzzer/controls/volume/on'
      brightness_scale: 100
      payload_on: "1"
      payload_off: "0"
      retain: true

Настройка Modbus-устройства Wiren Board
MQTT-топики в веб-интерфейсе контроллера
Редактирование файла конфигурации
Кнопка перезагрузки Home Assistant
Пример сообщения об ошибке
Устройства в веб-интерфейсе Home Assistant
Управление зуммером

Доступ через облако

Чтобы открывать Home Assistant не только из локальной сети, добавьте его как сервис в Wiren Board Cloud: на странице контроллера нажмите «Сервисы» и выберите Home Assistant из каталога — порт 8123 подставится сам.

Сразу после добавления Home Assistant ответит 400: Bad Request — по умолчанию он не доверяет запросам, пришедшим через облако. Добавьте в /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml текст ниже и перезапустите контейнер docker restart home-assistant:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1
    - 172.16.0.0/12

Открыть Home Assistant через облако можно только в браузере. На телефоне откройте облачную ссылку в браузере, сохраните её ярлыком на домашний экран для удобства.