rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub

08 · Home Assistant — подробный разбор

Эта глава описывает особенности работы rbAmp в HA: обнаружение, нативный API, панель энергии, долгосрочную статистику, карточки Lovelace, автоматизации и работу в средах, где HA запущен в Docker или WSL.

Cross-references:


1 · Обнаружение: mDNS или IP вручную

Узлы 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).

Порядок обнаружения:

  1. Прошейте ESP32 и дайте ему загрузиться. Он подключается к WiFi и начинает объявлять себя по mDNS как .local.
  2. В HA: Настройки → Устройства и службы → Интеграции (Settings → Devices & Services → Integrations). Появится баннер «New devices found» или ищите ESPHome в списке интеграций со значком обнаружения.
  3. Нажмите «Настроить» ("Configure") у новой записи. HA запросит ключ шифрования, если он задан (§3).
  4. Все датчики добавляются к устройству автоматически.

Ручное добавление (если 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. Для домашней доверенной сети это приемлемо. Для большей безопасности добавьте ключ:

YAML
api:
  encryption:
    key: "BASE64_ENCODED_32_BYTE_KEY"

Создание ключа:

Shell
python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

Когда вы добавляете устройство в HA (Настройки → Устройства и службы → ESPHome → Добавить), введите тот же ключ. HA сохраняет его в конфигурации интеграции и использует автоматически для всех последующих подключений к этому узлу.

Поместите ключ в secrets.yaml:

YAML
# secrets.yaml (untracked, next to the device YAML)
api_key: "BASE64_ENCODED_32_BYTE_KEY"
YAML
# 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):

YAML
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 и т. д. с модуля с несколькими каналами

Для установки на весь дом с одним вводом:

  1. Нажмите «Add consumption» (Добавить потребление) в разделе Grid consumption (Потребление из сети).
  2. Выберите сущность Mains Energy.
  3. При желании задайте тариф (EUR/кВт·ч или местную валюту) для учёта стоимости.

Для установки из трёх модулей (сеть + солнечная станция + EV из примера 11 в 06_examples.md):

  1. Потребление из сети: House Energy (из meter_house).
  2. Возврат в сеть: Solar Energy Exported (из meter_solar, STANDARD (STD); на BASIC оставьте пустым).
  3. Солнечные панели: Solar Energy (из meter_solar).
  4. Отдельное устройство: 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 узла.

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 узла.

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:

  1. Инструменты разработчика (Developer Tools) → Статистика (Statistics).
  2. Найдите сущность (например, sensor.rbamp_ui1_mains_energy).
  3. Убедитесь, что у его строки есть 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 узла.

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 узла.

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 узла.

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 узла.

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 узла.

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:

Shell
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 узла.

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 (рекомендуется большинству пользователей):

  1. Аддон хранит конфигурации YAML в /config/esphome/ (доступно через файловую систему HA или редактор аддона).
  2. secrets.yaml лежит рядом с YAML-файлами устройства в /config/esphome/.
  3. Первыйexternal_componentsпуть должен быть доступен изнутри контейнера аддона. Варианты:
    • Рекомендуется: используйте удалённую форму: source: github://rb-amp/rbamp-esphome@v1.9.0 (компонент публикуется на GitHub).
    • Либо скопируйте каталог components/rbamp/ в /config/esphome/components/ и укажите path: components/ (относительный).
  4. OTA: аддон сам выполняет прошивку по OTA — нажмите «Install» на карточке устройства, и аддон попытается OTA на последний известный IP. Прошивка по USB также доступна через последовательный порт аддона, если ESP32 подключён к хосту HA.

В надстройку встроен просмотрщик логов (кнопка «Logs» на карточке устройства) — аналог esphome logs в CLI.


14 · Именование сущностей и стабильность entity ID

Entity ID в HA образуются из имени узла ESPHome и поля name: датчика:

Text
sensor._

Для узла rbamp-ui1 и датчика с name: "Mains Voltage":

Text
sensor.rbamp_ui1_mains_voltage

ID сущностей используются в автоматизациях, шаблонных датчиках, дашбордах Lovelace и конфигурации панели энергии. Изменение name: датчика в YAML создаёт новый ID сущности и ломает все ссылки на старый. Продумайте имена датчиков до первого развёртывания.

Чтобы переименовать датчик, не сломав ID сущности:

  1. Переименуйте датчик в YAML.
  2. Прошейте устройство заново.
  3. В 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)