34. Файлы в Home Assistant.

В этом материале сделаем небольшой вдох-выдох после первого знакомства с кодом в предыдущей статье и перед углублением в него же в будущем.

Как известно, вся конфигурация и интерфейс ХА описываются с помощью языка YAML.

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

И первым по важности среди них стоит configuration.yaml. Это основной файл настроек системы, и система прежде всего смотрит на указанные в нём параметры и ссылки на другие модули для обращения к ним.

Так же есть фалы automations.yaml, scenes.yaml и scripts.yaml.

В которых хранятся соответственно: автоматизации, скрипты и сцены, созданные в интерфейсе ХА. Текст (код) их лучше менять через интерфейс, или через редактор кода в интерфейсе.

Понятное дело что любой объект в системе (сенсор, переключатель и т.д.) со всеми его атрибутами должен быть где-то и как-то прописан и указан. То, что он измеряет или показывает, к какому типу он относится и пр. Все эти объекты прописаны в файлах названных по типу каждой группы объектов, и находятся они в папке .storage. Туда мы не ходим, там ничего не меняем, только если нет жгучего желания переставлять систему.

Внутренняя структура представления объектов.

В  Home Assistant можно создавать и свои (виртуальные) объекты. Переключатели, кнопки, сенсоры, бинарные сенсоры и т.д.

Существует несколько способов хранить вот эти самые рукотворные объекты. Использовать несколько способов сразу довольно тяжело для новичка. Да и не совсем разумно с точки зрения логики. Но обо всём по порядку.

В начале файла configuration.yaml есть небольшой блок, указывающий где могут находиться все, в том числе и дополнительные (самодельно-рукотворные) объекты и как они будут обрабатываться.

automation: !include automations.yaml

script: !include scripts.yaml

scene: !include scenes.yaml

sensor: !include_dir_merge_list includes/sensors

switch: !include includes/switches.yaml

template: !include includes/templates.yaml

#binary_sensor: !include_dir_merge_list includes/bin_sensor

#group: !include groups.yaml

#packages: !include_dir_merge_list includes/packages

#timer: !include includes/timer.yaml

#counter: !include includes/counter.yaml

    Как известно, в ХА есть платформы и есть домены. Например TEMPLATE - это платформа шаблонов. На её основе можно создать объекты в доменах sensor, binary_sensor, switch, automation и всех остальных. НО! Хранятся эти объекты по разному. 

    Все объекты созданные вручную на платформе TEMPLATE сохраняются каждый в своём файле или директории согласно домену. Кроме, объектов доменов sensor и binary_sensor. Они сохраняются в файле или директории платформы, а не своего домена. Эта информация актуальна на середину октября 2022 года, версия Home Assistant 2022.10.4, Supervisor 2022.10.0, операционная система 9.2. 

В данном примере:

- Домен автоматизации - в файле automations.yaml находящемся в той же папке что и главный конфиг.

- Домен скрипты - аналогично.

- Домен сцены - аналогично.

- Домен сенсоры - Каждый сенсор может быть записан в виде отдельного файла. Этот файл должен лежать в папке sensors, которая находится внутри папки includes.

- Домен выключатели - указывает на общий файл выключателей, в том числе и самодельных, написанных на основе платформы шаблонов, находящемся в корне папки includes.

- Платформа шаблоны. В данном примере, все обычные и бинарные самодельные сенсоры будут находиться в одном файле.

По аналогии указаны и остальные объекты. Закомментированы они потому, что используются системные установки без изменения.

Однако же!

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

Пакеты (packages - пакаджи).

Пакаджем является набор всех сущностей используемых для того или иного случая. В него входят и автоматизации, и сенсоры, и шаблоны всех видов, выключатели. В общем все мыслимые и немыслимые виды объектов в ХА.

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

Синтаксис.

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

а. В общем файле конфигурации

б. В отдельном или общем файле платформы (например шаблоны)

в. В отдельном или общем файле доменов.

г. В пакадже.

При этом, синтаксис написания кода такого объекта будет отличаться в зависимости от способа где он будет записан.

Для примера возьмём интеграцию работающую с сервисом отслеживания посылок 17track. Следуя документации, необходимо добавить следующий код в файл configuration.yaml:

sensor:

  - platform: seventeentrack

    username: EMAIL_ADDRESS

    password: YOUR_PASSWORD

Однако, если нет желания захламлять основной файл этим кодом, то можно вынести новый сенсор в отдельный файл. Создадим его (не забыв указать расширение yaml) в директории для сенсоров. Т.к. в главном конфиге уже указано что файлы домена сенсор находятся по определённому адресу, то файл для 17track будет выглядеть так:

  - platform: seventeentrack

    username: EMAIL_ADDRESS

    password: YOUR_PASSWORD

Таким же способом можно добавить ещё один файл сенсора в ту же папку. Он создаст целую кучу полезных сущностей для мониторинга системы. И их не нужно будет добавлять вручную.

Системный мониторинг:

  - platform: systemmonitor

    resources:

      - type: disk_use_percent

        arg: /config

      - type: disk_use

      - type: disk_free

      - type: memory_use_percent

      - type: memory_use

      - type: memory_free

      - type: swap_use_percent

      - type: swap_use

      - type: swap_free

      - type: processor_use

      - type: last_boot

Для завершения работы с этой директорией, можно накинуть парочку последних сенсоров для получения курсов валют с сайта Банка Израиля. Работают они на платформе REST. Сенсор открывает документ XML в формате JSON  по указанному адресу и берёт значение из определённого поля в самом коде. Округляет полученное значение до двух знаков после запятой. Делает он это раз в 6 часов, чтобы не нагружать сайт лишний раз. Да и к тому же данные там обновляются не чаще.

- platform: rest

scan_interval: 360
resource: https://boi.org.il/PublicApi/GetExchangeRate?key=USD
name: USD2ILS
state_class: measurement
unit_of_measurement: ₪
value_template: "{{ value_json.currentExchangeRate | round(2)}}"
icon: mdi:currency-usd

И такой же, но для Евро:

- platform: rest

scan_interval: 360
resource: https://boi.org.il/PublicApi/GetExchangeRate?key=EUR
name: EUR2ILS
state_class: measurement
unit_of_measurement: ₪
value_template: "{{ value_json.currentExchangeRate | round(2)}}"
icon: mdi:currency-eur

Как видно из этих примеров и объяснения выше: если в файле configuration.yaml указан домен или платформа в виде отдельного файла или списка файлов внутри директории, то в самих файлах устройств не нужно писать первую строку, которая определяет этот домен или платформу.

Секреты.

Иногда нужно указать в настройках данные, которые относятся к категории For Your Eyes Only. Например пароли, ключи API, токены доступа и т.д. Конфигурационные файлы хранят данные в виде обычного незашифрованного текста. И может сложиться ситуация, когда кто-то посторонний может увидеть эти данные (поделились кодом неработающего файла на форуме, отправили скриншот кому-то, загрузили свой удачный конфиг на гитхаб чтобы поделиться со всем миром радостью и т.д.). Чтобы избежать подобной утечки информации, существует механизм secrets. 

Работает он следующим образом:

Создаём файл secrets.yaml в той же директории, в которой находится configuration.yaml.

Записи в нём должны выглядеть следующим образом:

параметр: значение

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

Возьмём в качестве примера уже упомянутый конфиг для интеграции 17track. Там просят указать адрес электронной почты в качестве имя пользователя, и пароль. Значит в файл секретов можно добавить что-то вроде:

17trkusr: abc@123.com

17trkpwd: 12345678

Теперь, в том месте настроек системы где нужно указать имя пользователя, пишем !secret 17trkusr, а вместо пароля - !secret 17trkpwd.

Таким образом, итоговый текст конфига будет иметь вид:

  - platform: seventeentrack

    username: !secret 17trkusr

    password: !secret 17trkpwd

Система будет "знать" что если в поле указано !secret, то нужно обратиться к файлу secrets.yaml  и взять значение указанное относительно соответствующего идентификатора.

В следующей статье подробнее рассмотрим работы с шаблонами.