Battery State Card: карточка уровня заряда для Home Assistant

Карточка battery state card отображает в Lovelace-интерфейсе Home Assistant уровень заряда всех батарейных устройств одним списком — датчиков протечки, датчиков движения, пультов и термометров, — и подсвечивает те из них, чей заряд опустился ниже заданного порога. Это пользовательская (кастомная) карточка, она не входит в стандартный набор Home Assistant, поэтому перед использованием её нужно установить отдельно, чаще всего через магазин интеграций HACS.

Ниже разберём установку, базовую и расширенную настройку, типичные ошибки вроде пустой карточки или отсутствующих сущностей, а также способы сгруппировать устройства по комнатам и получать уведомления о разрядке. Инструкция ориентирована на актуальные версии Home Assistant с поддержкой YAML- и UI-редактора дашбордов.

Что такое battery state card и зачем она нужна

Battery state card — это кастомная Lovelace-карточка, которая автоматически собирает сущности с классом устройства battery и показывает их заряд в компактном виде: иконка, название, проценты и цветовая индикация. Вместо того чтобы вручную добавлять каждый датчик в стандартную карточку «Сущности», вы получаете самообновляющийся список — новое устройство с батареей появится в карточке без правки конфигурации.

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

Установка через HACS

Самый простой способ установки — через HACS (Home Assistant Community Store). Если HACS ещё не установлен, сначала выполните его установку по официальной документации проекта, так как процедура периодически меняется.

Когда HACS уже работает, порядок действий следующий:

• 🔍 Откройте HACS в боковом меню Home Assistant и перейдите в раздел Frontend.
• 📦 Найдите карточку по запросу battery state и откройте её страницу.
• ⬇️ Нажмите кнопку загрузки/установки и дождитесь завершения.
• 🔄 Перезагрузите интерфейс (обновите страницу с очисткой кэша) или перезапустите Home Assistant, если карточка не появилась в редакторе.

После установки ресурс карточки обычно регистрируется автоматически. Проверить это можно в Настройки → Панели → Ресурсы — там должна присутствовать запись, ссылающаяся на файлы карточки в каталоге /hacsfiles/.

⚠️ Внимание: если ранее вы устанавливали карточку вручную (копированием файлов в www), удалите старую ручную регистрацию ресурса, иначе возможны конфликты версий и ошибки «Custom element doesn't exist».

Ручная установка без HACS

Если HACS не используется, карточку можно установить вручную. Для этого файл JavaScript-модуля карточки скачивается из официального репозитория проекта и помещается в папку config/www/ вашей установки Home Assistant. Затем ресурс регистрируется в конфигурации Lovelace.

Пример записи ресурса в configuration.yaml для режима YAML:

lovelace:
resources:
- url: /local/battery-state-card.js
type: module

Путь и точное имя файла сверяйте с репозиторием проекта — структура релизов может меняться. После добавления ресурса перезапустите Home Assistant и очистите кэш браузера: фронтенд часто держит старую версию скриптов, и без жёсткого обновления страницы карточка не определится.

Базовая настройка карточки

Минимальная конфигурация карточки в YAML-редакторе дашборда выглядит так:

type: custom:battery-state-card
title: Заряд батарей

Уже с такими двумя строками карточка соберёт все сущности, у которых устройство класса battery, и выведет их списком. Дальше можно управлять порогами, сортировкой и видимостью.

Точный перечень поддерживаемых параметров и их синтаксис зависят от версии карточки — перед настройкой сверяйтесь с README проекта. Ниже пример более осмысленной конфигурации: показывать только устройства с зарядом ниже порога и сортировать их по возрастанию уровня.

type: custom:battery-state-card
title: Требуют замены батареи
sort_by_level: asc
filter:
include:
- name: entity_id
value: sensor.*_battery
operator: ">"
# пример фильтрации — синтаксис уточняйте в документации версии

Фильтрация и группировка устройств

Когда устройств много, полезно разбить их на несколько карточек: например, отдельно датчики в доме, отдельно — в гараже и на улице. Для этого используется механизм фильтров по entity_id, по имени или по атрибутам. Можно также явно перечислить нужные сущности через параметр entities, если автоматическое обнаружение захватывает лишнее.

Типичная задача — исключить устройства, у которых «батарея» на самом деле является ноутбуком или телефоном, подключённым через companion-приложение. Такие сущности отфильтровываются по шаблону имени или по интеграции. Конкретный синтаксис операторов фильтра (contains, регулярные выражения и т.п.) различается между версиями карточки, поэтому примеры берите из документации именно вашей установленной версии.

• 🏠 Группируйте карточки по помещениям через фильтры по entity_id или по области (area), если ваша версия это поддерживает.
• 📱 Исключайте смартфоны и ноутбуки — их «заряд» не требует замены батарейки и только засоряет список.
• 🔋 Оставьте в главной карточке только устройства ниже порога, а полный список вынесите на отдельную вкладку дашборда.
• 🏷️ Используйте bulk_rename, чтобы имена в списке были короткими и читаемыми.

Типичные проблемы и их решение

Самая частая жалоба — ошибка «Custom element doesn't exist: battery-state-card». Она означает, что браузер не загрузил скрипт карточки: либо ресурс не зарегистрирован, либо закэширована старая версия фронтенда. Проверьте раздел ресурсов, путь к файлу и обновите страницу с очисткой кэша. Если установка была через HACS, убедитесь, что сама карточка действительно скачана — в HACS она должна отображаться как установленная.

Вторая распространённая ситуация — карточка пустая, хотя батарейные устройства в системе есть. Возможная причина: у сущностей не выставлен класс устройства battery, и автоматическое обнаружение их не видит. Проверить это можно в Настройки → Устройства и службы → Сущности или в инструментах разработчика, посмотрев атрибут device_class конкретного датчика. Если класс отсутствует, его иногда можно задать через кастомизацию сущности (customize) — при условии, что интеграция отдаёт заряд числом в процентах.

⚠️ Внимание: не путайте battery state card с похожими карточками (например, battery-entity или auto-entities). У них разные имена типов в YAML, и конфигурация одной карточки не заработает с другой — проверяйте строку type:.

Третья проблема — некорректные значения: вместо процентов отображается «unknown» или состояние вроде «Good». Это значит, что сущность отдаёт не числовой уровень, а текстовое состояние. В таком случае либо настройте в карточке отображение состояния как текста (если версия это позволяет), либо создайте шаблонный сенсор, преобразующий состояние в число.

Как создать template-сенсор уровня заряда

В configuration.yaml или через интерфейс помощников создайте шаблонный сенсор, который читает атрибут battery_level исходного устройства и возвращает его как число с unit_of_measurement: "%" и device_class: battery. После этого новая сущность автоматически появится в battery state card. Точный синтаксис шаблона зависит от структуры атрибутов вашей интеграции — проверяйте в Developer Tools → States.

Уведомления о разрядке батарей

Карточка показывает состояние только на дашборде, но не предупреждает сама. Чтобы получать уведомления, создайте автоматизацию: триггер — падение числового состояния сенсора батареи ниже выбранного вами порога, действие — отправка уведомления через сервис notify. Для нескольких устройств удобно перечислить сущности в одном триггере и использовать в тексте уведомления переменную trigger.entity_id, чтобы видеть, какое именно устройство разрядилось.

Порог выбирайте с запасом: многие датчики на «пальчиковых» батарейках и CR2032 начинают работать нестабильно ещё до полной разрядки, а показания заряда у дешёвых устройств часто неточны и прыгают. Показания уровня заряда у Zigbee- и BLE-датчиков — ориентировочные: устройство может отключиться раньше, чем карточка покажет критическое значение. Поэтому автоматизацию лучше настроить заранее, а не ждать нуля.

⚠️ Внимание: после замены батарейки некоторые датчики продолжают показывать старый уровень заряда, пока не отправят новый отчёт, — это может занять часы. Не считайте это неисправностью карточки.

FAQ: частые вопросы

Почему карточка выдаёт ошибку «Custom element doesn't exist»?

Браузер не загрузил скрипт карточки. Проверьте, что карточка установлена (через HACS или вручную), ресурс зарегистрирован в настройках панелей, а затем обновите страницу с очисткой кэша. Также убедитесь, что в type: указано именно custom:battery-state-card без опечаток.

Карточка пустая, хотя датчики с батареями есть. Что делать?

Скорее всего, у сущностей не задан device_class: battery, и автоматическое обнаружение их пропускает. Проверьте атрибуты сущности в инструментах разработчика и при необходимости задайте класс через кастомизацию или добавьте сущности вручную через параметр entities.

Можно ли показывать только разряженные устройства?

Да. Используйте фильтры по уровню заряда и сортировку sort_by_level, а также сворачивание списка. Точный синтаксис фильтров зависит от версии карточки — сверяйтесь с документацией проекта.

Чем battery state card отличается от стандартной карточки «Сущности»?

Стандартная карточка требует вручную перечислять каждую сущность и не умеет автоматически находить новые устройства. Battery state card собирает батарейные сущности сама, поддерживает сортировку по заряду, пороги, фильтры и массовое переименование.

Нужен ли HACS для работы карточки?

Нет. HACS лишь упрощает установку и обновление. Карточку можно установить вручную, поместив JS-файл в папку www и зарегистрировав ресурс — но обновлять её тогда придётся также вручную.