Adding Integrations
Let’s start by adding your first integration Integrations connect and integrates Home Assistant with your devices, services, and more.
[Learn more] so that you can see and change a smart home device A device is a model representing a physical or logical unit that contains entities. .
From the sidebar, click on Settings > Devices & Services. At this screen you will be able to set up integrations with Home Assistant. You might notice a discovered section. This section contains integrations that were found on your network and can easily be added with a few clicks. If your integrations are not discovered, click the Add integration button in the lower right and search for your integration in that list.
In this example, we’ll add a Chromecast to Home Assistant. Chromecast uses the Google Cast integration. Although the below example has already discovered the device, let’s add it manually.
First, press the Add integration button in the lower right and search for your integration in that list.
Select Google Cast from the list. Because my Chromecast device was already discovered, it asks if I want to add the discovered one or a different one. I will choose the latter and setup another instance.
It now asks for the network IP address of the device. Describing how to identify a devices IP address is beyond the scope of this article because each network is different. However, the router is usually a good place to look. In this example, it’s 192.168.1.99.
If it was successful, it will show a message and allow you to set the area Places within your home such as rooms, spaces, etc. it belongs to.
When you’re done, navigate back to the web interface and voila, your devices are ready for you to control. You can always go back to add and remove integrations in the future.
If you get stuck, need more information, or want to see what the setup process is like, use the integration documentation.
Как установить недостающий компонент для интеграции Home Assistant?
Установка зависимых пакетов процедура не сложная, но требует понимания, а также обязательно нужно посещать сайт pypi.org для уточнения. Не все пакеты ставятся через консоль pip install и некоторые пакеты требуют предварительно скомпилированные библиотеки, такие пакеты ставятся через LuCI, через менеджер пакетов. Некоторые интеграции нужно расскомментировать через config_flows.py. Также интеграции можно закидывать в папку custom_components , туда же будут закидываться пользовательские интеграции
Инструкция
Внимание! В самом низу вы можете посмотреть видео инструкцию по установке flux_led. Принцип установки точно такой же как и в текстовой инструкции. Данная видео инструкция может помочь вам лучше понять как ставить недостающий компонент для интеграции Home Assistant.
- Сперва вы должны знать версию установленного Home Assistant, если вы не знаете какая у вас стоит версия Home Assistant, то посмотреть версию можно перейти
- По адресу http://ip:8123/config/info
- Настройки => О системе
-
соответствующий вашей версии Home Assistant и распакуйте из архива папку components . Полный путь к папке core-год.месяц.число.zip\core-год.месяц.число\homeassistant\components\
- Находим в папке components нужную нам интеграцию и копируем в /usr/lib/python3.9/site-packages/homeassistant-2021.11.2-py3.9.egg/homeassistant/components , где homeassistant-2021.11.2-py3.9.egg это версия вашего Home Assistant.
- Если у вас стоит Home Assistant версии 2021.09.1 , то здесь будет homeassistant-2021.09.1-py3.9.egg
- Если у вас стоит Home Assistant версии 2021.10.5 , то здесь будет homeassistant-2021.10.5-py3.9.egg
- Если у вас стоит Home Assistant версии 2021.11.0 , то здесь будет homeassistant-2021.11.0-py3.9.egg
- Проверяем файлик config_flows.py. Файлик config_flows.py находится по адресу /usr/lib/python3.9/site-packages/homeassistant-2021.11.2-py3.9.egg/homeassistant/generated/config_flows.py , где homeassistant-2021.11.2-py3.9.egg это версия вашего Home Assistant.
- Если у вас стоит Home Assistant версии 2021.09.1 , то здесь будет homeassistant-2021.09.1-py3.9.egg
- Если у вас стоит Home Assistant версии 2021.10.5 , то здесь будет homeassistant-2021.10.5-py3.9.egg
- Если у вас стоит Home Assistant версии 2021.11.0 , то здесь будет homeassistant-2021.11.0-py3.9.egg
В файлике config_flows.py есть список интеграции, все они закомментированы. Сделано это специально для экономии места на шлюзе. Найдите из списка нужную интеграцию и расскомментируйте ее, а после сохраните изменение
- Также, в каждой интеграции, которые находятся в папке components есть файл manifest.json (манифест), где содержится полезная информация
Пример интеграции Mobile App
Открываем manifest.json интеграции Mobile App и ищем строчку requirements. В requirements указываются требуемые пакеты ["PyNaCl==1.4.0", "emoji==1.5.0"]
Делаем проверку зависимых пакетов командой pip show PyNaCl emoji . Версии пакетов не указываем, всегда указываем без версии. Если пакеты не установлены, то будет сообщение, что таких пакетов нет, значит, значит надо установить эти пакеты с указанием версии как в manifest.json, но есть пакеты, которые надо ставить через LuCI. Чтобы понять, нужно открыть сайт pypi.org и в поиск вставить имя пакета, в нашем случае PyNaCl. Всегда надо читать про любой пакет на этом сайте. Указали нужный пакет и читаете что за пакет. Пакет PyNaCl — это привязка Python к libsodium, которая является ответвлением библиотеки Networking and Cryptography. Поэтому пакет PyNaCl будем ставить через LuCI, через пакет менеджеров. Ставим через LuCI python3-pynacl
Пакет Emoji написан для Python, поэтому его ставим через консоль
Пример интеграции WLED
Открываем manifest.json интеграции WLED и ищем строчку requirements. В requirements указывается требуемый пакет wled==0.8.0
Делаем проверку зависимых пакетов командой pip show wled . Версии пакетов не указываем, всегда указываем без версии. Если пакеты не установлены, то будет сообщение, что таких пакетов нет, значит, значит надо установить эти пакеты с указанием версии как в manifest.json Снова воспользуемся сайтом pypi.org. Пакет WLED это асинхронный клиент Python для WLED, поэтому его будем ставить через консоль.
Но, тут есть один нюанс, пакет wled собран в poetry, поэтому, даже, если вы поставите wled==0.8.0 , то интеграция не запустится, потому что надо до установить зависимый пакет. Ставим вот этот пакет packaging
Пример интеграции Xiaomi Gateway
Открываем manifest.json интеграции Xiaomi Gateway и ищем строчку requirements. В requirements указывается требуемый пакет PyXiaomiGateway==0.13.4
Делаем проверку зависимых пакетов командой pip show PyXiaomiGateway . Версии пакетов не указываем, всегда указываем без версии. Если пакеты не установлены, то будет сообщение, что таких пакетов нет, значит, значит надо установить эти пакеты с указанием версии как в manifest.json Снова воспользуемся сайтом pypi.org. Смотрим про пакет PyXiaomiGateway, автор тут ничего не указал, поэтому его будем ставить через консоль.
Дополнительно
Можно создать папку custom_components и закинуть туда папки с интеграциями из папки components . Важно. Если закинули интеграцию в custom_components , то необходимо открыть config_flows.py , если там есть данная интеграция, то расскомментируйте ее, а также потребуется установка требуемых пакетов из manifest.json. Читаем инструкцию выше или в справочнике: Как отследить требуемый пакет для интеграции через утилиту htop?
Справочник
Как отследить требуемый пакет для интеграции через утилиту htop?
Запустите htop в консоли (просто указываем htop), а только после этого в Home Assistant запускайте установку интеграции. В утилите htop следите за процессом. Нужно смотреть долго и внимательно, нас должна привлечь внимание строка pip install —quiet
Пример запуска интеграции WLED через Home Assistant 
Здесь мы видим, что идет попытка установить пакет wled==0.8.0, соответственно, рекомендую остановить Home Assistant через LuCI, System => Startup, чтобы Home Assistant не пытался установить нужный пакет и шлюз при этом не завис. Ставим пакет нужный пакет, запускаем Home Assistant и запускаем интеграцию.
Как я разрабатывал интеграцию для Home Assistant
Так сложилось что недавно я поставил себе Home Assistant (далее HA) для управления всем моим зоопарком устройств из одного места, что оказалось довольно удобно. Но без ложки дегтя никуда и нашлось все таки одно устройство, интеграции для которого в HA не было, а привязать его хотелось. Было решено написать собственную интеграцию. Если интересно, что из этого вышло, добро пожаловать под кат.
Статья является описанием моего пути разработки, возможно он не верный, так же я не являюсь Python-разработчиком, писал на нем первый раз, поэтому возможно множество ошибок или использования антипаттернов.
Прочитав инструкцию по разработке интеграций на официальном сайте, стало ясно что придется писать на Python. Хоть и инструкция довольно подробная, некоторые моменты мне показались не очевидными и пришлось столкнуться со многими трудностями, искать решения в других кастомных компонентах, поэтому решил описать свой опыт в статье, возможно он будет кому то полезен. В статье постараюсь описать обобщенный процесс разработки интеграции, и не сосредотачиваться на том устройстве для которого я ее разрабатывал.
Структура файлов
Модуль кастомной интеграции для HA состоит из каталога с несколькими файлами, который нужно поместить в каталог HA custom_components. Сразу важный момент, название каталога должно полностью соответствовать названию компонента — в терминологии HA называется Domain.
В каталоге должны как минимум содержаться следующие файлы:
__init__.py — Файл инициализации, выполняется при загрузке компонента.
config_flow.py — Файл не обязательный, но используется для конфигурирования процесса настройки компонента.
const.py — не обязательный файл, который используется для обозначения констант.
Файлы объектов — для каждого типа объектов, которое может реализовывать интеграция, нужно создать файл, например:
sensor.py — для описания объектов типа сенсор, для сбора каких либо метрик.
switch.py — для описания объектов типа переключатель.
binary_sensor.py — бинарный сенсор, имеет только два положения.
Полный список поддерживаемых в HA объектов можно найти на официальном сайте.
Какие — либо другие файлы необходимые для реализации интеграции.
В моем случае было необходимо разработать компонент, который обращается во внешнее API для получения данных с сенсоров или управления устройством. В статье буду публиковать только важные, на мой взгляд, части кода, чтобы не вызвать путаницы полные листинги кода можно посмотреть по ссылке на github.
Пример файла manifest.json из моей интеграции:
Описание полей хорошо представлено на официальном сайте
Отмечу важный момент, поле domain должно обязательно совпадать с названием каталога и с именем которое будет использоваться в других файлах.
Чтобы не запутаться можно создать константу с именем домена в файле const.py, затем импортировать его в других файлах.
Содержимое моего файла const.py .
В моем проекте был еще один дополнительный файл sst.py (назвать его можно как угодно, я называл исходя из разрабатываемой интеграции), в котором я описал интеграцию. Т.е. в этом файле выполняются все запросы, полученная из API информация преобразуется в классы, описанные в файле. А к этому файлу в свою очередь уже обращаются остальные части интеграции. Судя по найденным мною примерам, это общепринятая практика и сделана для того, чтобы избежать дублирования запросов, т. к. одно устройство в терминологии HA может представлять из себя одновременно несколько объектов, например сенсор и переключатель. Поэтому данные запрашиваются один раз сохранятся в объектах классов из файла sst.py, а затем вызовами из файлов объектов (sensor.py, switch.py и т. д.) получается информация из них или отправляются команды.
Схема взаимодействия интеграции
Чуть подробнее расскажу про структуру моего файла для интеграции, он состоит из нескольких классов.
Для всех классов устройств нужно реализовать конструктор, в котором сохраняется информация о объекте, а так же методы для получения из объекта информации, которую вы хотите выводить в HA и методы для управления например метод включения и выключения для switch.
Так же обязательно нужно реализовать метод обновления информации, может быть как обновление одного устройства так и обновление всех устройств интеграции сразу. Зависит от возможности API и структуры устройств.
Этот файл не используется напрямую HA поэтому к нему каких то особенных требований нет, просто необходимо реализовать работу с API.
Дальше рассмотрим уже использование этого файла файлом инициализации. В этом файле ключевое это вызов создания родительского объекта интеграции и метода заполнения его данными. Файл запускается в момент загрузки модуля, после загрузки HA либо после настройки интеграции.
Файл config_flow.py используется для описания процесса конфигурирования, можно обойтись без него, если конфигурацию устройства описывать в файле configuration.yaml. В моем примере ему нужно было передать логин и пароль для подключения к сервису.
Дальше необходимо создать файлы с описанием объектов, которые будет использовать HA. Здесь появляются уже требования к файлам, для каждого типа объектов есть требуемый список свойств, со списком можно ознакомиться на официальном сайте.
В каждом файле каждого типа может быть описана реализация нескольких типов устройств, главное чтобы они соответствовали типу файла.
Рассмотрим пример реализации сенсора:
Тут стоит обратить внимание на иерархию устройств и объектов в HA. Каждое устройство может содержать один или несколько объектов. Например рассмотрим гипотетический выключатель, у него есть объекты:
Переключатель (switch) — собственно для управления включением и выключением.
Уровень заряда батареи (sensor) — отображает процент заряда.
Состояние (binary_sensor) — текущее состояние выключателя.
В интерфейсе HA объекты отображаются как элементы устройства, поэтому связанные объекты необходимо связать между собой, для этого у них указывается одинаковый идентификатор объекта.
В одном объекте необходимо указать полную информацию об устройстве
В остальных достаточно указывать только идентификатор, такой же как у основного объекта
Так же необходимо реализовать метод update для обновления информации о состоянии, HA будет его периодически вызывать. Т.к. у меня информация обновляется целиком для всего устройства, метод update я реализовал только в одном объекте.
Который вызывает метод обновления в основном файле интеграции. HA периодически вызывает метод обновления только у одного объекта, но при его вызове обновляется информация по всем.
Установка магазина HACS в Home Asisstant
Если вы столкнулись с тем, что после добавления вашего устройства конфигурацию HA, вы получаете сообщение “неизвестная интеграция”, то это первый звоночек в сторону того, что вам срочно нужен HACS.
Надумал я тут, что мои термостаты с кривым китайским приложением и кривой интеграцией в google home стоит добавить в home assistant. Забиваю в гугле ключевые слова и вижу простой мануал. Делаю все по нему и ничего не работает, впрочем — это частая история.
Далее мы начинаем читать страничку-описание проекта и тоже особенно зацепиться не за что. Читаем форумы и появляется первое описание про то, что интеграцию нужно скачать с GitHub и положить в папку custom_components. Это был первый звоночек.
Начинаем изучать подробнее, что же это за папка такая. В первых упоминаниях сказано, что находится она в папке с конфигом. В своей инструкции по установке я писал, что путь мы указываем при конфигурации контейнера.
Итого, моя команда будет выглядеть так:
docker run -d — name=”home-assistant” -v /home/@user/smarthome:/config -v /etc/localtime:/etc/localtime:ro — net=host — restart always homeassistant/home-assistant:stable
/home/@user/smarthome и есть тот путь. Переходим туда и создаем папку custom_components рядом с остальными файлами конфигурации докера. В папку помещаем нашу интеграцию и перезагружаемся. Но ничего не заработало. Продолжаем читать дальше☺. Находим первое упоминание про магазин сторонних интеграций HACS. Данный компонент является сторонней надстройкой, который включает в себя похожее на маркетплейс функционал со сторонними компонентами.
Но создается впечатление, что этот магазин есть у всех, но только не у меня. Позже я нашел упоминание, что HACS действительно есть во многих распространенных сборках, но только не в home assistant core который устанавливается в докер по умолчанию по моей инструкции. Ищем пути решения и натыкаемся на мануал по установке HACS. Тот что на русском имеет ошибки, тот что я нашел на английском — работает. Мне повезло, т.к. я искал именно на английском, поэтому я решил поделиться инструкцией ниже:
1. Мы переходим в директорию с конфигом к Home Asisstant, выше я писал где она и как это понять.
2. Переходим в папку custom_components, которую я уже создал ранее.
3. Распаковываем в нее архив с GitHub
4. Перезагружаем HA.
5. Переходим в раздел интеграции, жмем новую и в поиске вводим HACS
6. Если вы получили все как на картинке выше, то я вас поздравляю и можете переходить на пункт №8. А для всех остальных: открываем браузер → настройки → конфиденциальность и безопасность → очистить историю → за все время → все галки ткнуть → удалить данные