Как устанавливать репозитории из GitHub в Home Assistant: HACS, custom_components и ручной способ

Когда я только начинал свой путь в мир Home Assistant, меня постоянно мучил вопрос: почему в официальном каталоге интеграций нет половины вещей, которые я видел в чужих дашбордах? Почему кто-то управляет кондиционером через красивую карточку, а у меня в списке только базовые сущности?

Ответ оказался простым: огромная экосистема Home Assistant живёт за пределами официального репозитория. Разработчики со всего мира публикуют свои интеграции, карточки Lovelace и даже целые темы оформления прямо на GitHub. И сегодня я расскажу, как получить к ним доступ.

Зачем вообще нужны сторонние репозитории?

Прежде чем нырять в технические детали, давайте честно ответим на вопрос: а зачем нам вообще что-то ставить с GitHub, если Home Assistant и так умеет почти всё?

Во-первых, скорость. Официальное хранилище интеграций проходит строгую проверку, и это правильно. Но из-за этого новые интеграции попадают туда с задержкой. На GitHub же разработчик может выложить свежую версию своего творения хоть сегодня, и она сразу станет доступна пользователям.

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

В-третьих, это просто удобно. HACS (Home Assistant Community Store) превращает процесс установки из ручного копирования файлов в пару кликов мышью. Но обо всём по порядку.

Три способа установки: выбираем свой

Есть три основных пути установки интеграций из GitHub:

1. HACS — самый популярный и удобный способ. По сути, это менеджер пакетов для Home Assistant.
2. Ручная установка через custom_components — классика жанра, когда вы вручную копируете файлы в папку конфигурации.
3. Прямая установка через терминал — гибридный вариант, где вы скачиваете архив и распаковываете его прямо из SSH-консоли.

Каждый способ имеет право на жизнь. HACS удобен для повседневного использования, ручной способ — когда нужно быстро поставить что-то одно и не хочется разворачивать целую инфраструктуру. Терминальный вариант — для тех, кто привык работать через SSH и не хочет возиться с веб-интерфейсом.

Установка HACS: пошаговое руководство

HACS — это не просто интеграция, это целая экосистема. С его помощью вы сможете устанавливать не только интеграции, но и карточки для Lovelace, темы оформления и даже целые панели управления. О том, какие именно карточки стоит поставить в первую очередь, я писал в отдельной статье про лучшие HACS-карточки Lovelace, но сейчас давайте разберёмся с установкой самого HACS.

Шаг 1: Подготовка

Перед установкой HACS убедитесь, что ваш Home Assistant обновлён до актуальной версии. HACS требует версию не ниже 2021.1, но я рекомендую иметь свежую сборку — так меньше шансов наткнуться на несовместимость.

Также вам понадобится доступ к интерфейсу Home Assistant через браузер и права администратора. Если вы используете Home Assistant OS, то всё это у вас уже есть.

Шаг 2: Скачивание HACS

Самый надёжный способ — скачать архив с официального GitHub-репозитория HACS. Заходим на страницу релизов и ищем последнюю версию. Обратите внимание: нам нужен файл hacs.zip, а не исходный код.

# Если вы работаете через SSH, можно скачать напрямую с GitHub
wget https://github.com/hacs/integration/releases/latest/download/hacs.zip

Шаг 3: Распаковка в папку custom_components

Теперь нам нужно распаковать архив в папку custom_components/hacs внутри каталога конфигурации Home Assistant. Если вы используете Home Assistant OS, проще всего это сделать через файловый менеджер Samba или аддон File editor.

# Создаём папку, если её ещё нет
mkdir -p custom_components/hacs

# Распаковываем архив
unzip hacs.zip -d custom_components/hacs

Шаг 4: Перезагрузка и настройка

После того как файлы на месте, перезагружаем Home Assistant. В интерфейсе заходим в «Настройки» → «Устройства и службы» и нажимаем «Добавить интеграцию». В поиске вводим HACS.

Вас встретит мастер настройки, который попросит подтвердить несколько вещей: включить «Расширенный режим», согласиться с условиями использования и авторизоваться через GitHub. Да-да, для работы HACS нужен аккаунт GitHub — это не прихоть, а способ защиты от спама.

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

Ручная установка: когда HACS не нужен

Иногда бывает так, что какая-то интеграция ещё не добавлена в HACS, или вы не хотите устанавливать HACS ради одной вещи. Тогда на помощь приходит ручной способ.

Структура custom_components

Всё начинается с понимания структуры папок. В каталоге конфигурации Home Assistant есть папка custom_components. Внутри неё для каждой интеграции создаётся своя подпапка с именем, совпадающим с доменом интеграции.

Например, если мы хотим установить интеграцию awesome_light, структура будет такой:

config/
├── custom_components/
│   └── awesome_light/
│       ├── __init__.py
│       ├── manifest.json
│       ├── light.py
│       └── ...
├── configuration.yaml
└── ...

Пошаговый процесс

1. Находим репозиторий. Допустим, мы нашли на GitHub интересную интеграцию. Идём в раздел Releases или просто клонируем репозиторий.

2. Скачиваем файлы. Нам нужны только файлы из папки custom_components/<имя_интеграции>.

# Клонируем репозиторий во временную папку
git clone https://github.com/username/awesome_light.git /tmp/awesome_light

# Копируем нужную папку в конфигурацию Home Assistant
cp -r /tmp/awesome_light/custom_components/awesome_light /config/custom_components/

3. Проверяем зависимости. В файле manifest.json указаны зависимости и минимальная версия Home Assistant.

{
  "domain": "awesome_light",
  "name": "Awesome Light",
  "codeowners": ["@username"],
  "config_flow": true,
  "dependencies": ["mqtt"],
  "documentation": "https://github.com/username/awesome_light",
  "iot_class": "local_polling",
  "requirements": ["some-python-package==1.2.3"],
  "version": "1.0.0"
}

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

Типичные ошибки при ручной установке

Самая частая ошибка — неправильная структура папок. Люди скачивают весь репозиторий целиком и кладут его в custom_components, а нужно класть только внутреннюю папку с именем домена.

Вторая ошибка — забывают про зависимости. Если в manifest.json указан пакет Python, его нужно установить вручную. Обычно это делается через pip, но в Home Assistant OS всё немного сложнее — там лучше использовать HACS, который автоматически ставит зависимости.

Третья ошибка — несоответствие версий. Интеграция может требовать более новую версию Home Assistant, чем у вас установлена. В этом случае вы увидите предупреждение в логах, а интеграция может работать некорректно.

Установка через терминал: для тех, кто любит командную строку

Если вы привыкли работать через SSH, этот способ вам понравится. Он особенно удобен, когда нужно быстро поставить несколько интеграций разом или автоматизировать процесс.

# Переходим в каталог конфигурации
cd /config

# Скачиваем архив с GitHub
wget https://github.com/username/awesome_light/archive/refs/tags/v1.0.0.tar.gz

# Распаковываем
tar -xzf v1.0.0.tar.gz

# Копируем нужную папку
cp -r awesome_light-1.0.0/custom_components/awesome_light custom_components/

# Удаляем временные файлы
rm -rf awesome_light-1.0.0 v1.0.0.tar.gz

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

Проверка результата: как убедиться, что всё работает

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

1. Проверка через логи

Первым делом смотрим логи Home Assistant. Если интеграция не загрузилась, там будет соответствующая ошибка.

# Просмотр логов в реальном времени
docker logs -f homeassistant

Или через веб-интерфейс: «Настройки» → «Система» → «Журнал».

2. Проверка через интерфейс

Если интеграция поддерживает настройку через UI, она появится в списке при добавлении новой интеграции. Просто нажимаем «Добавить интеграцию» и ищем её по имени.

3. Проверка через API

Для продвинутых: можно проверить список загруженных интеграций через REST API.

# Запрос списка интеграций через API
curl -X GET "http://your-home-assistant:8123/api/config" 
  -H "Authorization: Bearer YOUR_LONG_LIVED_TOKEN"

4. Типичные проблемы и их решение

Если интеграция не появляется, проверьте:

• Права на файлы. Убедитесь, что файлы доступны для чтения пользователю, под которым работает Home Assistant.

# Устанавливаем правильные права
chmod -R 755 /config/custom_components/awesome_light

• Синтаксис manifest.json. Одна лишняя запятая или неправильная кодировка — и интеграция не загрузится.

• Конфликт с другой интеграцией. Иногда две интеграции используют один и тот же домен. В этом случае поможет только удаление одной из них.

Обновление интеграций: поддерживаем всё в актуальном состоянии

Обновление — это отдельная боль. Если вы используете HACS, то всё просто: заходите в раздел «Обновления» и нажимаете кнопку. HACS сам скачает новую версию и перезапустит нужные компоненты. Подробнее об этом я рассказывал в статье про установку и безопасное обновление пользовательских интеграций.

При ручной установке обновление — это повторение процесса установки. Но есть нюанс: перед обновлением обязательно сделайте резервную копию конфигурации. Я обычно делаю так:

# Создаём резервную копию перед обновлением
cp -r /config/custom_components/awesome_light /backup/awesome_light_$(date +%Y%m%d_%H%M%S)

Безопасность: важные предостережения

Установка интеграций с GitHub — это всегда доверие незнакомому коду. Поэтому я выработал для себя несколько правил:

1. Проверяйте рейтинг и количество звёзд. Если у репозитория больше 1000 звёзд и активные обсуждения в issues — это хороший знак.

2. Читайте код. Хотя бы бегло просмотрите __init__.py. Если видите подозрительные вызовы API или загрузку внешних скриптов — лучше не рисковать.

3. Используйте отдельного пользователя GitHub. Для авторизации HACS не стоит использовать основной аккаунт. Создайте отдельный, с ограниченными правами.

4. Делайте бэкапы. Перед установкой любой интеграции — резервная копия конфигурации. Это спасёт вас от множества проблем. О том, как правильно организовать бэкапы, я писал в статье про надёжный бэкап Home Assistant.

Что ещё можно поставить через GitHub?

Помимо интеграций, через GitHub можно устанавливать:

• Карточки Lovelace — это виджеты для панели управления.
• Темы оформления — полная смена внешнего вида интерфейса.
• Сторонние панели — например, Node-RED или Studio Code Server.
• Пакеты автоматизаций — готовые наборы сценариев.

Отдельно хочу выделить интеграции LocalTuya и Adaptive Lighting, которые я подробно разбирал в статье про локальный умный дом без облака. Это отличные примеры того, как сторонние интеграции расширяют возможности Home Assistant.

Заключение

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

Мой совет: начинайте с HACS. Это самый безопасный и удобный способ, который подойдёт большинству пользователей. Ручную установку осваивайте, когда появится специфическая задача, которую HACS не решает. А терминальный способ — для тех, кто хочет автоматизировать процесс обновления.

Главное — не бойтесь экспериментировать. Home Assistant потому и стал таким популярным, что позволяет каждому настроить систему под себя. А GitHub — это бесконечный источник новых возможностей. Просто не забывайте о безопасности и делайте резервные копии перед каждым серьёзным изменением.

Удачных экспериментов!