На прошлой неделе в статье XDA рассказывалось о умном доме, который рухнул за один вечер. Владелец навел порядок в названиях устройств, нажал сохранить, и все автоматизации, ссылающиеся на старые ID, замолчали. Свет перестал реагировать на движение. Утренняя рутина пропустила половину шагов. Панель управления заполнилась красными восклицательными знаками. Home Assistant ничего не предупредил перед изменением; ничего не откатило его после.
Такая история встречается достаточно часто, чтобы именование сущностей Home Assistant заслуживало собственного набора инструментов, а не просто переименования в свободный день. Семь приложений для рабочего стола ниже охватывают весь необходимый спектр перед тем, как касаться хотя бы одного ID: сухие прогоны рефакторинга, проверка YAML, поиск по всем файлам, псевдонимы, которые отделяют удобное имя от машинного ключа, процессы переименования Zigbee и Z-Wave, которые синхронизируются обратно с сущностями, и контроль версий, чтобы ошибки можно было отменить за секунды.
На что обратить внимание при настройке именования сущностей
- Сухие прогоны рефакторинга. Переименование должно предпросмотреть каждую автоматизацию, скрипт, сцену, панель управления и ссылку на чертеж перед тем, как зафиксировать что-либо.
- Проверка YAML. Нарушенный отступ или висячий
entity_id:должны вызвать ошибку в вашем редакторе, а не испортить вашу утреннюю рутину. - Поиск ID сущностей по автоматизациям, скриптам и сценам. Один ярлык, чтобы найти каждое место, где появляется
light.living_room_lamp, включая внутри шаблонов. - Поддержка псевдонимов. Удобные имена должны быть свободны для изменения без касания базовому ID сущности, на который полагаются автоматизации.
- Переименование устройств Zigbee и Z-Wave, которое синхронизируется обратно с сущностями. Переименование устройства в пользовательском интерфейсе ZHA или Z-Wave JS должно распространяться на каждую сущность, которую это устройство раскрывает, а не оставлять сирот.
- Конфигурация под контролем версий. Git или эквивалент, чтобы плохой рефакторинг был на расстоянии одного
git revertот исцеления.
Быстрое сравнение
| Приложение | Лучше всего подходит для | Обрабатывает ссылки переименования | Стоимость |
|---|---|---|---|
| Home Assistant | Основной диалог переименования | Да, встроено | Бесплатно |
| Studio Code Server | Редактирование и поиск YAML | Да, через поиск по файлам | Бесплатно |
| HACS | Установка остального списка | Нет, предварительное условие | Бесплатно |
| ESPHome | Оборудование DIY, единственный источник истины | Да, при компиляции | Бесплатно |
| Node-RED | Сложные визуальные автоматизации | Частично, за поток | Бесплатно |
| Automation Editor | Редактирование одной автоматизации в пользовательском интерфейсе | Да, встроено | Бесплатно |
| Custom Brand Icons | Визуальный аудит соглашений об именовании | Нет, визуально перехватывает отклонение | Бесплатно |
Приложения
1. Home Assistant
Загрузить: Home Assistant
Начните отсюда, потому что основной инструмент значительно улучшился в этом. С версии 2023.4 диалог настроек сущности содержит инструмент “Entity ID rename”, который ищет автоматизации, скрипты, сцены, панели управления и чертежи для ссылок на старый ID и предлагает обновить их в один проход. Сначала выполняется как предпросмотр, перечисляя каждое совпадение с его файлом и строкой, и фиксируется только после подтверждения.
Этот предпросмотр — это самая полезная страховочная сетка в стеке. Он перехватывает шаблонизированные ссылки внутри Jinja, которые простой текстовый поиск пропустил бы, и отмечает случаи, когда ID появляется внутри якоря YAML или файла пакета, к которому пользовательский интерфейс в противном случае не коснулся бы. Когда он не может автоматически разрешить ссылку (например, ID сущности, построенный во время выполнения из переменной), он говорит об этом вместо того, чтобы молча пропустить.
Улов: он знает только об источниках, которые может видеть. Пользовательские интеграции, которые хранят ID сущностей в собственных JSON-файлах, или потоки NodeRED, сохраненные вне .storage, нуждаются во втором проходе с инструментами дальше по этому списку.
2. Studio Code Server
Загрузить: Studio Code Server
Надстройка HACS, которая помещает полный VS Code в вкладку браузера, указывая прямо на /config. Проверка YAML включена по умолчанию, расширение Home Assistant поставляется предустановленным, и Ctrl+Shift+F выполняет поиск по всему проекту, который соблюдает .gitignore.
Для именования сущностей это то место, где происходит аудит второго прохода. После того как основной диалог переименования выполнится, откройте Studio Code Server, найдите старый ID и подтвердите, что совпадений нет. Если какие-либо вернутся, они обычно находятся в файлах, которые диалог не может проверить: определения команд оболочки, URL-адреса датчиков REST или датчики шаблонов, построенные с state_attr(). Исправьте их там, зафиксируйте, перезагрузитесь.
Автодополнение заслуживает отдельного упоминания. Введите entity_id: и он предлагает живой реестр, поэтому опечатки никогда не выживают до времени выполнения. Переименуйте устройство завтра, и предложения обновятся при следующей перезагрузке.
3. HACS (Home Assistant Community Store)
Загрузить: HACS
Не инструмент именования, а предварительное условие. HACS — это менеджер пакетов сообщества, который устанавливает Studio Code Server, Custom Brand Icons и несколько интеграций для качества жизни, которые делают возможным остальной рабочий процесс. Настройка — это разовая операция: включите расширенный режим в своем профиле, перейдите к интеграции HACS через команду оболочки, перезагрузитесь и добавьте интеграцию.
Две привычки, которые стоит принять после того, как HACS установлен. Во-первых, закрепите версии вместо отслеживания main на чем-либо, что касается сущностей, потому что неожиданное критическое изменение во время рефакторинга переименования — это наихудший возможный момент. Во-вторых, используйте встроенный просмотр журнала изменений HACS перед каждым обновлением. Это часто единственное место, где критическое поведение переименования вызывается заранее.
4. ESPHome
Загрузить: ESPHome
Для всего на оборудовании ESP32 или ESP8266 ESPHome — это уровень именования. Установите name: living-room-lamp один раз в YAML устройства, и каждая сущность, которая загружается на эту плату (light.living_room_lamp, sensor.living_room_lamp_temperature, и т.д.), получает соответствующий ID. Измените поле name:, перезагрузитесь, и Home Assistant увидит новые ID при следующей загрузке.
Этот единственный источник истины — это то, что предотвращает отклонение, описанное в статье XDA. Старый шаблон был: переименуйте устройство в Home Assistant, переименуйте его снова в ESPHome, надейтесь, что обе стороны согласны. Текущий шаблон: переименуйте его в ESPHome, дайте Home Assistant следовать. Это меньшая площадь поверхности, чтобы держать согласованность, и контролируемые версией файлы .yaml означают, что каждое переименование — это разница в репо.
Совместите его с основным диалогом переименования для начального переключения. ESPHome создает новые ID при первой загрузке; диалог переписывает ссылки на старые. Два прохода, нет сирот.
5. Node-RED
Загрузить: Node-RED
Когда автоматизации выходят за двадцать или тридцать и редактор YAML начинает чувствовать себя узким, визуальный редактор потоков Node-RED — это обычный следующий шаг. ID сущностей становятся первоклассными гражданами на холсте: каждый узел, который касается одного, показывает его в метке, а боковая панель имеет поиск живого реестра, поэтому неправильный ввод ID невозможно сохранить.
Для именования сущностей конкретно, поиск за поток Node-RED — это инструмент. Откройте поток, нажмите Ctrl+F, введите старый ID, и каждый узел, который его ссылается, загорится. Переименуйте массово через панели конфигурации узлов, разверните, готово. Потоки экспортируются как JSON, поэтому они счастливо живут в том же репо git, что и остальная конфигурация.
Компромисс: Node-RED работает вместе с собственным движком автоматизации Home Assistant, а не заменяет его, поэтому переименование ID сущности теперь должно быть применено в двух местах. Ведите контрольный список.
6. Automation Editor (встроенный)
Загрузить: Automation Editor (поставляется с Home Assistant)
Стоковый редактор пользовательского интерфейса часто недооценивается. Для редактирования одной автоматизации он рассматривает ID сущностей как ссылки, доступные для поиска: измените средство выбора сущности триггера, и соответствующие поля условия и действия обновятся при одном сохранении. Без редактирования YAML вручную, без риска затерять запятую.
Место, которое оно занимает в этом списке, — это приглашение “Rename”, которое появляется, когда вы изменяете устройство или сущность, на которую ссылается автоматизация. Оно предлагает тот же предпросмотр ссылок обновления по конфигурации, что и основной диалог, ограниченный автоматизацией, которая у вас открыта. Для распространенного случая отредактируйте одну автоматизацию, заметьте, что связанная сущность получила более удобный ID, примите переименование, сохраните и двигайтесь дальше.
Для всего, охватывающего несколько автоматизаций, используйте основной диалог переименования вместо этого. Это для хирургических однофайловых изменений.
7. Custom Brand Icons
Загрузить: Custom Brand Icons
Нечетный, и тот, который окупается быстрее всего. Custom Brand Icons — это интеграция HACS, которая позволяет вам прикреплять значки поставщиков и продуктов к сущностям по шаблону. Дайте каждой сущности light.living_* одно и то же значок лампы, каждому sensor.*_battery одно и то же значок батареи, каждому switch.plug_* одно и то же значок розетки.
Преимущество рефакторинга переименования — визуальное. Откройте панель управления после переименования, и любая сущность, которая выпала за пределы шаблона (опечатка, устаревший псевдоним, устройство, которое было переименовано, но не связанный помощник), показывает значок по умолчанию вместо семейного значка. Неправильное переименование появляется как визуальный выброс перед тем, как появиться как нарушенная автоматизация.
Установите шаблоны один раз для вашего соглашения об именовании, храните их в configuration.yaml, и каждое будущее переименование либо соответствует шаблону, либо объявляет о себе.
Как выбрать правильный стек
Базовый уровень, для каждой настройки: Home Assistant плюс HACS плюс Studio Code Server плюс git. Эта комбинация дает вам основной диалог переименования, поиск второго прохода, канал пакетов сообщества для всего остального и кнопку отмены.
Добавьте ESPHome, если какие-либо из ваших сущностей поступают из оборудования DIY. Это перемещает источник истины для этих имен из пользовательского интерфейса Home Assistant в контролируемый версией YAML и устраняет целый класс ошибок отклонения.
Добавьте Node-RED, если у вас есть больше чем несколько десятков автоматизаций или если какие-либо из них охватывают более трех или четырех шагов. Визуальный редактор легче проверить в масштабе, и поиск за поток — это то, как вы перехватываете сирот ID в сложных потоках.
Добавьте Custom Brand Icons рано, а не поздно. Установка шаблонов перед переименованием означает, что панель управления становится инструментом обнаружения изменений, а не просто отображением.
Редактор автоматизации всегда доступен и стоит использовать для редактирования однофайловых изменений. Это не замена основному диалогу переименования, когда изменение касается нескольких автоматизаций, но это самый быстрый путь для повседневной уборки.
Часто задаваемые вопросы
Автоматически ли переименование сущности в Home Assistant обновляет каждую автоматизацию, которая ее использует?
С версии 2023.4 диалог переименования ID сущности ищет автоматизации, скрипты, сцены, панели управления и чертежи для ссылок и предлагает обновить их в один проход. Сначала показывает предпросмотр. Он не может видеть ссылки внутри пользовательских интеграций, которые хранят ID в собственных файлах, или внутри потоков Node-RED, поэтому поиск второго прохода в Studio Code Server все еще стоит выполнить после каждого переименования.
Какова разница между удобным именем и ID сущности?
ID сущности (light.living_room_lamp) — это машинный ключ, который автоматизации, скрипты и шаблоны используют для адресации сущности. Удобное имя (“Living room lamp”) — это метка, которая появляется на панелях управления, голосовых помощниках и уведомлениях. Свободно изменяйте удобное имя; ID сущности остается стабильным и никакая автоматизация не сломается. Изменяйте ID сущности только через диалог переименования, чтобы ссылки обновились.
Должны ли устройства переименовываться из пользовательского интерфейса интеграции или из настроек сущности?
Переименуйте устройство из пользовательского интерфейса интеграции (ZHA, Z-Wave JS, ESPHome и т.д.), когда целью является изменение каждой сущности, которую это устройство раскрывает за один раз. Переименуйте отдельную сущность, когда только одна из сущностей устройства нуждается в другом ID. Оба потока теперь запускают тот же предпросмотр обновления ссылок, поэтому страховочная сетка одна и та же в любом случае.
Как вы проверяете конфигурацию Home Assistant на опечатки ID сущностей перед тем, как они вызовут сбои?
Studio Code Server с расширением Home Assistant — это самая быстрая проверка. Откройте поиск по всему проекту для entity_id: и сканируйте что-либо, что не автодополняется для живого реестра. Для сценарной проверки hassio ha check (эквивалент CLI встроенного валидатора конфигурации) будет отмечать ссылки на сущности, которые не существуют, и git diff после каждого изменения делает обзор привычкой с одной командой.
Безопасно ли переименовывать сущности на производстве экземпляра Home Assistant?
Безопаснее, чем было, если переименование проходит через диалог настроек сущности или приглашение связанного редактора автоматизации. Сначала сделайте резервную копию из пользовательского интерфейса, выполните переименование в спокойное окно, и перезагрузите затронутую интеграцию или перезагрузитесь после изменения. Если что-либо выглядит неправильно, репо git, который остальная часть этого стека поощряет вас держать, — это самый быстрый способ вернуться к предыдущему состоянию.
