08 · Home Assistant — подробный разбор
Эта глава описывает особенности работы rbAmp в HA: обнаружение, нативный API, панель энергии, долгосрочную статистику, карточки Lovelace, автоматизации и работу в средах, где HA запущен в Docker или WSL.
Cross-references:
- Быстрый старт:
05_quickstart.md - Примеры YAML (Lovelace, автоматизации):
06_examples.md - Интеграции DIY (MQTT, InfluxDB, Lambda):
07_diy_integrations.md - Документация HA: https://www.home-assistant.io/
1 · Обнаружение: mDNS или IP вручную
Автообнаружение mDNS (рекомендуется)
Узлы ESPHome объявляют себя по mDNS (многоадресный DNS), когда YAML содержит блок api:. Интеграция ESPHome в HA слушает эти объявления и автоматически предлагает новые устройства.
Что нужно автоматическому обнаружению, чтобы работать:
- ESP32 и HA должны находиться в одном сегменте канального уровня L2 (один VLAN, без роутера между ними). mDNS — многоадресный и не проходит через роутер без дополнительной настройки (ретранслятор mDNS / прокси Avahi).
- Multicast UDP не должен блокироваться роутером или функцией изоляции клиентов на точке доступа. Бытовые точки часто имеют функцию «AP isolation» или «wireless isolation» — она блокирует multicast между устройствами. Отключите её для VLAN IoT или для конкретных устройств.
- HA должен корректно разрешать mDNS. В развёртываниях Docker / WSL это иногда требует дополнительной сетевой настройки (см. §10).
Порядок обнаружения:
- Прошейте ESP32 и дайте ему загрузиться. Он подключается к WiFi и начинает объявлять себя по mDNS как
..local - В HA: Настройки → Устройства и службы → Интеграции (Settings → Devices & Services → Integrations). Появится баннер «New devices found» или ищите ESPHome в списке интеграций со значком обнаружения.
- Нажмите «Настроить» ("Configure") у новой записи. HA запросит ключ шифрования, если он задан (§3).
- Все датчики добавляются к устройству автоматически.
Ручное добавление (если mDNS заблокирован)
Настройки → Устройства и службы → Добавить интеграцию → ESPHome (Settings → Devices & Services → Add Integration → ESPHome).
Введите IP ESP32 (смотрите в таблице DHCP роутера или в журнале загрузки ESPHome — строка [I][wifi:189]: IP: 192.168.x.y). Порт по умолчанию — 6053.
Назначьте статическую аренду DHCP для MAC-адреса ESP32 в роутере, чтобы IP не менялся после перезагрузки роутера.
2 · Нативный API ESPHome (порт 6053) и MQTT
ESPHome поддерживает два транспорта. Оба работают с rbAmp.
| Свойство | Нативный API (порт 6053) | MQTT |
|---|---|---|
| Интеграция HA | Первый класс: отдельная интеграция ESPHome с автообнаружением | Общий: требуется брокер MQTT, ручная настройка сущностей или MQTT discovery |
| Шифрование | Встроенный (протокол шума, опционально) | Зависит от настройки TLS брокера |
| Задержка | Низкая — прямой TCP без брокера | Зависит от брокера |
| Надёжность | Автоматическое переподключение | Зависит от доступности брокера |
| Без HA | Бесполезно (API специфичен для HA) | Любой подписчик MQTT может его получить |
| Сложность настройки | Никакой дополнительной инфраструктуры | Требуется работающий брокер MQTT |
Рекомендация: используйте нативный API (блок api:), если основной потребитель — HA. Добавляйте mqtt:, только если нужен параллельный потребитель вне HA (Grafana, Node-RED, собственные скрипты). Оба могут сосуществовать в одном YAML.
Нативный API — путь, описанный в этом документе. Подробности MQTT — в 07_diy_integrations.md §2.
3 · Ключ шифрования
По умолчанию нативный API без шифрования — любой хост локальной сети может подключиться к порту 6053. Для домашней доверенной сети это приемлемо. Для большей безопасности добавьте ключ:
api:
encryption:
key: "BASE64_ENCODED_32_BYTE_KEY"
Создание ключа:
python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"
Когда вы добавляете устройство в HA (Настройки → Устройства и службы → ESPHome → Добавить), введите тот же ключ. HA сохраняет его в конфигурации интеграции и использует автоматически для всех последующих подключений к этому узлу.
Поместите ключ в secrets.yaml:
# secrets.yaml (untracked, next to the device YAML)
api_key: "BASE64_ENCODED_32_BYTE_KEY"
# device YAML
api:
encryption:
key: !secret api_key
Если вы меняете ключ, нужно удалить и заново добавить устройство в HA.
4 · Настройка панели энергии
Датчики energy rbAmp (и energy_1, energy_2, energy_exported, energy_total, energy_exported_total и т. д.) поставляются уже настроенными с (energy_net использует state_class: total, потому что может уменьшаться; reactive_energy* — в varh):
device_class: energy
state_class: total_increasing
unit_of_measurement: Wh
Это именно та комбинация, которую ожидает панель Energy в HA для накопительных датчиков потребления или генерации. Дополнительные шаблонные датчики не нужны. Каждому датчику энергии нужны voltage и current, объявленные в том же блоке sensor: (добавьте internal: true, чтобы скрыть их от Home Assistant).
Добавление датчиков на панель Energy
Настройки → Панели управления → Energy (Settings → Dashboards → Energy). Панель содержит четыре раздела:
| Раздел | Какой датчик rbAmp использовать |
|---|---|
| Потребление из сети | energy (импорт из сети) или energy_total (STANDARD (STD), все каналы) |
| Возврат в сеть | Нужен модуль STANDARD (STD) — модуль BASIC всегда показывает 0 для экспорта. energy_exported требует bidirectional: true плюс voltage и current в том же блоке; energy_exported_total охватывает все каналы (только STANDARD (STD)) |
| Солнечные панели | energy с модуля, измеряющего выход солнечного инвертора (модуль STANDARD (STD), если тот же модуль должен также сообщать экспорт) |
| Домашний аккумулятор | Не применимо (rbAmp не измеряет постоянный ток) |
| Отдельные устройства | energy_1, energy_2 и т. д. с модуля с несколькими каналами |
Для установки на весь дом с одним вводом:
- Нажмите «Add consumption» (Добавить потребление) в разделе Grid consumption (Потребление из сети).
- Выберите сущность
Mains Energy. - При желании задайте тариф (EUR/кВт·ч или местную валюту) для учёта стоимости.
Для установки из трёх модулей (сеть + солнечная станция + EV из примера 11 в 06_examples.md):
- Потребление из сети:
House Energy(изmeter_house). - Возврат в сеть:
Solar Energy Exported(изmeter_solar, STANDARD (STD); на BASIC оставьте пустым). - Солнечные панели:
Solar Energy(изmeter_solar). - Отдельное устройство:
EV Charger Energy(изmeter_evcharger).
Сохранение в NVS и панель энергии
Компонент ESPHome сохраняет суммарную энергию в NVS ESP32 каждые 5 минут (и при чистом выключении, например при перезагрузке или OTA). На модуле STANDARD итоги берутся из собственных счётчиков энергии модуля, поэтому они также переживают перезапуски модуля и остаются монотонными. При загрузке значения восстанавливаются из NVS и сразу публикуются — до подключения HA и до первого срабатывания update_interval.
Это не даёт панели энергии принять кратковременный 0 Wh за сброс счётчика. Если HA видит, что значение total_increasing упало до 0, он принимает разницу за границу расчётного периода и отбрасывает накопленную историю.
Наихудшая потеря данных при внезапном отключении питания — до 5 минут накопления (≈5 Вт·ч при средней нагрузке 60 Вт — незаметно в суточных итогах).
last_reset после OTA или перезагрузки ESP32
Панель Energy в HA использует device_class energy + state_class total_increasing без явной привязки last_reset — это рекомендуемая конфигурация ESPHome. При перезагрузке ESP32 компонент восстанавливает значение из NVS до первого publish_state, поэтому HA видит непрерывный монотонно растущий ряд и не вставляет на график служебный сброс. Так задумано.
Пограничные случаи, в которых может быть виден заметный «сброс»:
-
NVS повреждён (магическое число не совпадает или не сходится CRC). Компонент стартует с 0 Вт·ч, а HA фиксирует разрыв. Признак: на дашборде виден «утренний всплеск» в момент загрузки узла после долгого простоя. Исправление: проверьте журнал загрузки ESP32 на сообщения
[E][rbamp_nvs]— они укажут причину (несовместимая раскладка NVS, низкий заряд в момент записи и т. п.). Восстановите из резервной копии истории HA или уберите фантомный всплеск утилитами HA. -
Замена оборудования (новый ESP32, тот же модуль). Компонент стартует с 0 Вт·ч — модуль не передаёт свой накопленный счёт по I²C (модуль и компонент ведут раздельные накопители; модуль предоставляет только мгновенные значения для интеграции). HA фиксирует разрыв. Исправление: после прошивки нового ESP32 задайте начальное значение энергии вручную через
mqtt.publish(для MQTT) или временной правкой YAML с инициализацией lambda. Либо примите разрыв как однократное событие. -
update_interval:заметно изменён между сборками прошивки (например, 60 → 600 с). Само изменение ничего не сбрасывает, но более длинные циклы дают более грубые «ступени» на графике. Визуально это похоже на смену режима накопления; функционально всё в порядке. -
Записи HA были обрезаны или восстановлены из старой резервной копии. Это не сторона ESPHome — это сторона HA: HA может считать часть будущих значений «прошлыми» и перерисовать график. К ESPHome это отношения не имеет.
При плановой OTA-перепрошивке last_reset не выставляется, снимок NVS восстанавливается примерно за 50 мс до подключения HA, и панель энергии не видит разрыва. Это базовый сценарий.
5 · Счётчик коммунальных услуг
Интеграция utility_meter в HA выводит периодически сбрасываемые датчики из любого датчика total_increasing. Используйте её, чтобы получить суточные, недельные и месячные кВт·ч помимо сырого накопителя.
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
# configuration.yaml
utility_meter:
energy_daily:
source: sensor.rbamp_ui1_mains_energy
cycle: daily
energy_monthly:
source: sensor.rbamp_ui1_mains_energy
cycle: monthly
energy_yearly:
source: sensor.rbamp_ui1_mains_energy
cycle: yearly
HA создаёт три новых сущности (sensor.energy_daily и т. д.), которые сбрасываются в 0 в начале каждого периода. Они отлично подходят для просмотра отдельных устройств на панели Energy и как основа для шаблонных датчиков стоимости.
Примеры расчёта стоимости и кВт·ч/день — в 06_examples.md §10.
6 · Датчик статистики для мин / макс / среднего
Датчик statistics в HA вычисляет скользящие мин, макс, среднее и стандартное отклонение за настраиваемое окно времени по истории любого датчика:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
# configuration.yaml
sensor:
- platform: statistics
name: "Mains Power 1h Average"
entity_id: sensor.rbamp_ui1_mains_power
state_characteristic: mean
sampling_size: 60 # last 60 points
max_age:
hours: 1
- platform: statistics
name: "Mains Power 24h Peak"
entity_id: sensor.rbamp_ui1_mains_power
state_characteristic: value_max
max_age:
hours: 24
Эти производные датчики полезны для управления спросом (окно пикового потребления, месячный максимум для тарифной оплаты) и обнаружения аномалий (если максимум мощности за 24 часа внезапно превышает исторические нормы).
7 · Долгосрочная статистика
HA записывает датчики с state_class: total_increasing и state_class: measurement в свою базу долгосрочной статистики (LTS). Данные LTS хранятся бессрочно (независимо от хранения краткосрочного рекордера).
Чтобы проверить, что датчик rbAmp попадает в LTS:
- Инструменты разработчика (Developer Tools) → Статистика (Statistics).
- Найдите сущность (например,
sensor.rbamp_ui1_mains_energy). - Убедитесь, что у его строки есть
statistic_idи недавнийlast_stats_ts.
LTS используется панелью энергии для исторических видов и экспортируется через «Download statistics» HA.
Если вы заменяете модуль rbAmp (новое железо, новый entity ID), старая история LTS автоматически не переносится. Чтобы сохранить историю, оставьте тот же name: для каждого датчика в новом YAML. ESPHome формирует entity ID из имени узла и имени датчика; совпадающие имена дают тот же statistic_id.
8 · Карточки Lovelace
Карточка потока энергии (встроенная)
Встроенная панель Energy в HA уже содержит карточку потока энергии вверху страницы настроек Energy. Она появляется, когда панель Energy настроена (потребление из сети, солнечная генерация, аккумулятор). Дополнительная настройка не нужна.
Датчик-стрелка
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 5000
name: "Live Power"
unit: W
severity:
green: 0
yellow: 2000
red: 3500
Карточка списка датчиков
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
type: entities
title: "rbAmp UI1"
entities:
- entity: sensor.rbamp_ui1_mains_voltage
name: Voltage
- entity: sensor.rbamp_ui1_mains_current
name: Current
- entity: sensor.rbamp_ui1_mains_power
name: Power
- entity: sensor.rbamp_ui1_mains_power_factor
name: Power Factor
- entity: sensor.rbamp_ui1_mains_frequency
name: Frequency
- entity: sensor.rbamp_ui1_mains_energy
name: Energy (total)
Мини-карточка графика (HACS)
Установлено через HACS (§11):
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
type: custom:mini-graph-card
entities:
- entity: sensor.rbamp_ui1_mains_power
name: Power
hours_to_show: 6
points_per_hour: 4
line_width: 2
show:
extrema: true
average: true
Apex Charts (HACS)
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
type: custom:apexcharts-card
header:
title: "Power (W)"
show: true
graph_span: 24h
span:
end: now
series:
- entity: sensor.rbamp_ui1_mains_power
name: Power
type: area
stroke_width: 2
fill_raw: last
- entity: sensor.rbamp_ui1_mains_power
name: 1h avg
type: line
stroke_width: 1
color: orange
group_by:
func: avg
duration: 1h
9 · Автоматизации HA и on_value в ESPHome
И автоматизации HA, и on_value в ESPHome реагируют на изменения датчиков rbAmp. Выбор инструмента:
| Сценарий | Автоматизация HA | ESPHome on_value |
|---|---|---|
| Push-уведомление | Да — доступ ко всем службам HA (notify, TTS и т. д.) | Нет — у ESP32 нет службы уведомлений |
| Управление реле на том же ESP32 | Возможно (HA → переключатель), но с задержкой | Да — работает на устройстве, без зависимости от сети |
| Срабатывание, когда HA офлайн | Нет | Да — ESP32 работает автономно |
| Сложные условия (сочетание сущностей, истории, календаря) | Да | Ограниченно — лямбда на C++, без доступа к состоянию HA |
| Задержка реакции | ~1–5 с (Wi-Fi + обмен через API) | ~0 мс (тот же цикл событий) |
| Реакция на публикацию MQTT | Да (триггер MQTT) | N/A |
Практический совет: используйте ESPHome on_value для локальных действий с малой задержкой (переключение реле, светодиодный индикатор, зуммер), а автоматизации HA — для всего, что требует сервисов HA (уведомления, активация сцен, планирование по календарю, комбинации с другими сущностями).
Пример автоматизации HA, объединяющей rbAmp и переключатель HA:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
automation:
- alias: "Cut dishwasher when peak tariff starts"
trigger:
- platform: time
at: "16:00:00" # start of the peak tariff
condition:
- condition: numeric_state
entity_id: sensor.rbamp_ui1_mains_power
above: 1500 # only switch off if the load is high
action:
- service: switch.turn_off
target:
entity_id: switch.dishwasher_socket
10 · WSL и Docker
HA часто работает в Docker (образ homeassistant/home-assistant или Home Assistant OS в виртуальной машине). ESPHome запускается либо как надстройка HA (в той же контейнерной среде), либо как отдельный контейнер Docker.
mDNS в Docker / WSL
mDNS (многоадресный UDP 5353) по умолчанию не проходит через границы сетей Docker. Если HA в Docker, а ESP32 в физической LAN:
- Сетевой режим Docker host (
--network hostв Linux) даёт контейнеру доступ к multicast и обычно решает проблему. - Ретранслятор mDNS: инструменты вроде
avahi-daemonс правильнымallow-interfacesилиmdns-repeaterпередают multicast между мостом Docker (docker0) и физическим интерфейсом LAN. - Ручное добавление: полностью обходит mDNS — добавьте ESP32 в интеграцию HA ESPHome вручную по IP.
В Windows с WSL2 виртуальная машина WSL2 имеет собственный виртуальный сетевой адаптер. Контейнеры Docker внутри неё могут находиться за двумя слоями NAT (Windows → WSL2 → мост Docker). mDNS почти наверняка не заработает — добавляйте по IP.
Надстройка ESPHome Add-on и автономный ESPHome
При использовании надстройки HA ESPHome Add-on контейнер надстройки разделяет сетевое пространство имён с HA (при сетевом режиме host, который по умолчанию для HA OS). mDNS и обнаружение устройств работают без дополнительной настройки.
Если вы запускаете ESPHome как отдельный контейнер Docker, убедитесь, что контейнер имеет доступ к физической LAN (--network host в Linux) и что /dev/ttyUSB0 (или ваш COM-порт) проброшен для прошивки по USB:
docker run -it --rm --network host \
-v /path/to/configs:/config \
--device /dev/ttyUSB0:/dev/ttyUSB0 \
ghcr.io/esphome/esphome compile /config/ui1.yaml
Статический IP для надёжного OTA
В среде Docker / VLAN настоятельно рекомендуются статические аренды DHCP для устройств ESP32 rbAmp. Они предотвращают:
- Устаревший IP-адрес, записанный в HA для записи интеграции ESPHome.
- Неудачная OTA-прошивка (
esphome upload --device 192.168.x.y). - Сбой любой автоматизации, которая обращается к API по IP.
11 · HACS (Home Assistant Community Store)
HACS — сторонний менеджер интеграций для HA, дающий доступ к карточкам, интеграциям и автоматизациям, созданным сообществом. Для базовой работы rbAmp он не нужен, но полезен для более богатых карточек Lovelace из §8.
Установите из https://hacs.xyz/. Затем установите эти сообщественные карточки:
| Карточка | Категория HACS | Использование с rbAmp |
|---|---|---|
mini-graph-card |
Фронтенд | График мощности / тока во времени |
apexcharts-card |
Фронтенд | Графики с несколькими сериями |
lovelace-card-mod |
Фронтенд | Пользовательский CSS для любой карточки |
energy-flow-card-plus |
Фронтенд | Улучшенная диаграмма потока энергии |
Установка и управление HACS описаны в его документации. Карточки описаны в соответствующих репозиториях GitHub.
12 · Push-уведомления по порогу
Мобильное приложение HA (home-assistant.io/integrations/mobile_app) даёт push-уведомления на iOS и Android. В сочетании с датчиками rbAmp вы получаете мгновенные оповещения о перегрузке по току, мощности, потере сети или любому другому порогу:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
automation:
- alias: "rbAmp over-current alert"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_current
above: 14.0 # alert at 14 A (below a typical 16 A breaker)
for:
seconds: 10
action:
- service: notify.mobile_app_your_phone_name
data:
title: "Over-current warning"
message: >
Current is {{ states('sensor.rbamp_ui1_mains_current') | round(2) }} A
— approaching 16 A breaker limit.
data:
push:
sound:
name: default
critical: 1 # a critical alert bypasses Do Not Disturb (iOS)
interruption-level: critical
- alias: "rbAmp mains loss alert"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_voltage
below: 10
for:
seconds: 5
action:
- service: notify.mobile_app_your_phone_name
data:
title: "Mains power lost"
message: "Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V."
Чтобы сервис notify.mobile_app_* был доступен, приложение HA Companion должно быть установлено на целевом устройстве, а интеграция mobile-app — настроена в HA. Подробности на https://companion.home-assistant.io/.
13 · Настройка аддона ESPHome в HA
При использовании надстройки HA ESPHome Add-on (рекомендуется большинству пользователей):
- Аддон хранит конфигурации YAML в
/config/esphome/(доступно через файловую систему HA или редактор аддона). secrets.yamlлежит рядом с YAML-файлами устройства в/config/esphome/.- Первый
external_componentsпуть должен быть доступен изнутри контейнера аддона. Варианты:- Рекомендуется: используйте удалённую форму:
source: github://rb-amp/rbamp-esphome@v1.9.0(компонент публикуется на GitHub). - Либо скопируйте каталог
components/rbamp/в/config/esphome/components/и укажитеpath: components/(относительный).
- Рекомендуется: используйте удалённую форму:
- OTA: аддон сам выполняет прошивку по OTA — нажмите «Install» на карточке устройства, и аддон попытается OTA на последний известный IP. Прошивка по USB также доступна через последовательный порт аддона, если ESP32 подключён к хосту HA.
В надстройку встроен просмотрщик логов (кнопка «Logs» на карточке устройства) — аналог esphome logs в CLI.
14 · Именование сущностей и стабильность entity ID
Entity ID в HA образуются из имени узла ESPHome и поля name: датчика:
sensor._
Для узла rbamp-ui1 и датчика с name: "Mains Voltage":
sensor.rbamp_ui1_mains_voltage
ID сущностей используются в автоматизациях, шаблонных датчиках, дашбордах Lovelace и конфигурации панели энергии. Изменение name: датчика в YAML создаёт новый ID сущности и ломает все ссылки на старый. Продумайте имена датчиков до первого развёртывания.
Чтобы переименовать датчик, не сломав ID сущности:
- Переименуйте датчик в YAML.
- Прошейте устройство заново.
- В HA: Настройки → Устройства и службы → ESPHome → ваше устройство → нажмите сущность-датчик → значок шестерёнки → верните идентификатор сущности к старому значению (или задайте новый и обновите все ссылки) (Settings → Devices & Services → ESPHome).
Альтернатива — функция HA «Entity ID rename» (Настройки → Сущности → поиск → нажать сущность → изменить имя / entity ID): она позволяет отделить отображаемое имя от entity ID. Отображаемое имя можно свободно менять, не затрагивая автоматизации.
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/08_has_integrations.md (v1.9.1)