Як навести лад в файлі конфігурації Home Assistant

Колись в моїх файлах конфігурації Home Assistant був повний хаос, і пройшло трохи часу перш, ніж я впорядкував їх. Файл configuration.yaml був перенасичений кодом і дезорганізований. Мої автоматизації були в одному файлі, а я маю понад 100 автоматизацій. Всі мої сценарії були в подібній ситуації. З часом, я створив десятки шаблонів для датчиків і binary_sensor, усі у своїх configuration.yaml файлах. Після того, як я почав плутатися в конфігурації і налаштуваннях, я наважився на “генеральне прибирання”.

Преамбула

Я хочу сказати, що ця стаття не є обговоренням найкращих способів організації файлів конфігурації Home Assistant. Тут буде вказано декілька пунктів, на які варто звернути увагу. Буде загострено увагу на тому, що і як я вирішив зробити в процесі створення конфігурації для Home assistant. Сподіваюся, мій досвід допоможе декому з вас.

Початковий стан файлів конфігурації Home Assistant

Я використовую Home Assistant протягом майже трьох років. За цей час я значно розширив можливості Home Assistant у своєму розумному домі, створивши численні автоматизації та додавав нові інтеграції. Що я не робив, так це не планував і не скорочував конфігураційні файли.

Усі мої автоматизації були в одному великому файлі (automations.yaml). Також, в одному файлі (scripts.yaml) були і всі мої сценарії. Мій configuration.yaml був наповнений великою кількістю сенсорів, ламп, вимикачів і ще багато іншого. Стало важко щось знаходити та керувати файлами.

Я хотів зробити кожен із пунктів конфігурації більш керованим. Не хотів прокручувати й шукати щось в довгих файлах лише для того, щоб зробити невеликі правки. Хочеться, щоб було легше відстежувати помилки (зазвичай, друкарські) в моїх конфігураціях. Необхідно, щоб було зрозуміло, куди потрібно додавати новий код.

Параметри організації файлів конфігурації Home Assistant

Home Assistant має кілька варіантів розділення коду. Їхня документація детально пояснює ці варіанти.

Ви можете використовувати include, щоб просто перемістити всю інтеграцію в новий окремий файл або файли.
Можете використовувати більш розширені версії include, щоб перемістити цілі інтеграції в папки з файлами.
Приклади допоможуть пояснити ці варіанти.

Основи параметра include

Почнемо з найпростішого прикладу:

automation: !include automations.yaml

Цей рядок, розміщений у вашому configuration.yaml файлі, повідомляє Home Assistant, що ваш код автоматизації знаходиться у файлі, який називається automations.yaml, що розміщено в тій же папці конфігурації. Аналогічно, ви можете розбити більше частин вашого configuration.yml файлу:

automation: !include automations.yaml
switch: !include switches.yaml
light: !include lights.yaml

Наведений вище приклад переміщує код автоматизації, вимикачів і освітлювальних приладів в окремі файли.

Розширені параметри include

Для розширених параметрів я скопіюю пояснення безпосередньо з документації Home Assistant:

• !include_dir_list поверне вміст каталогу у вигляді списку, при цьому вміст кожного файлу буде записом у списку. Записи списку впорядковано на основі алфавітно-цифрового порядку імен файлів.
• !include_dir_named поверне вміст каталогу у вигляді словника, який відображає ім’я файлу => вміст файлу.
• !include_dir_merge_list поверне вміст каталогу у вигляді списку шляхом об’єднання всіх файлів в один великий список.
• !include_dir_merge_named повертає вміст каталогу у вигляді словника, завантажуючи кожен файл і об’єднуючи його в один великий словник.
  Давайте розглянемо приклад кожного з них:

automation: !include_dir_list automations/

У цьому випадку кожна окрема автоматизація містилася б у власному файлі YAML всередині каталогу automations/. Таким чином, у вас можуть бути файли turn_on_lights.yaml та turn_off_lights.yaml в каталозі автоматизації, у кожному з них є своя автоматизація.

Порівняйте це з:

automation: !include_dir_merge_list automations/

У цьому випадку кожен файл YAML у каталозі automations/може мати кілька автоматизацій всередині. Ви можете написати правила для вмикання та вимкнення світла у файлі під назвою lights.yaml. Ключова річ, яку слід пам’ятати під час використання директиви merge_list, полягає в тому, що всі автоматизації у всіх файлах мають бути у форматі списку (з дефісом), наприклад:

- alias: "Turn on Light"
  trigger:
    - platform: state
      entity_id: device.iphone
      to: "home"
  action:
    - service: light.turn_on
      target:
        entity_id: light.living_room

але не:

alias: "Turn on Light"
trigger:
  - platform: state
    entity_id: device.iphone
    to: "home"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room

!include_dir_named та !include_dir_merged_named працюють аналогічно, але замість того, щоб об’єднувати файли в список, вони об’єднують їх у словник. Наприклад, скрипти завантажуються до словника, тому варто використовувати такий запис замість списку, як то:

script: !include_dir_named scripts/

щоб об’єднати файли в scripts каталозі, кожен із яких містить один сценарій, або

script: !include_dir_merge_named scripts/

для об’єднання файлів у scripts каталозі, які можуть містити більше одного сценарію.

Що було вирішено змінити.

Я вирішив використовувати комбінацію директив include, щоб розділити свій конфігураційний файл. Організував свої автоматизації як об’єднаний список. Таким чином, можна зберігати групи автоматизації в одному файлі. Наприклад, у мене є файл irrigation.yaml для автоматизації зрошення і файл hvac.yaml для автоматизації системи опалення та охолодження. Так само для своїх сценаріїв я створив об’єднаний словник.

Для датчиків, бінарних сенсорів, ламп, вимикачів, груп, shell команд і input_numbers використовував просту директиву include, щоб зберегти їх у власних файлах. Я не налаштовую і не додаю і не змінюю їх так часто, як автоматизації, і їх не так багато, тому думаю, що окремий файл для кожного є нормальним. Ось відповідний розділ мого configuration.yaml:

group: !include groups.yaml
automation: !include automations.yaml
automation mine: !include_dir_merge_list automations/
script: !include_dir_merge_named scripts/
sensor: !include sensors.yaml
binary_sensor: !include binary_sensors.yaml
switch: !include switches.yaml
light: !include lights.yaml
rest_command: !include rest.yaml
remote: !include remote.yaml
shell_command: !include shell.yaml
input_number: !include input_number.yaml

Зверніть увагу на рядки 2 і 3 вище. У мене є звичайна директива включення та директива об’єднання списку для automations. Це дозволяє мені організувати автоматизацію, яку я пишу у файли, в той час як автоматизації, згенеровані UI, все ще зберігатимуться у automations.yaml .

А як щодо packages?

Інший спосіб організувати свої файли – це використання пакетів. Пакети дозволяють об’єднувати інтеграції (наприклад, light, switch, input_boolean тощо) разом. Ви можете комбінувати packages з директивами include для більш логічного групування функцій у вашій конфігурації. Наприклад, ви можете мати package для домашнього кінотеатру, який міститиме все освітлення, аудіо-відео обладнання та автоматизацію для кімнати в одному пакеті.

Останні думки

Сподіваюся, після прочитання статті у вас виникнуть нові ідеї про те, як організувати конфігураційні файли вашого Home Assistant. Я хотів би почути, як це робите саме ви. Дайте мені про це знати в коментарях.