Так сложилось что недавно я поставил себе 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,   для этого в соответствии с инструкцией нужно выложить код на GitHub и добавить файл hacs.json с описанием интеграции, затем репозиторий можно добавить через интерфейс HACS в пункте «Пользовательские репозитории» и установить его одной кнопкой.    На этом все, всем успехов в домашней автоматизации!