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

06 · Кулинарная книга YAML

Эта глава открывается флагманскими сценариями — реальными схемами развёртывания, для которых компонент создан в v1.3 (сеть + N субнагрузок на одной шине с синхронизацией fleet_gc_enable, процесс настройки, смешанный CT на нескольких каналах, синхронизация GC парка). За ними идут сценарии с одним модулем — от минимального UI1 до промышленного развёртывания с автоматизациями HA.

Каждый пример самодостаточен: скопируйте его, укажите имя своей платы и учётные данные Wi-Fi, соберите и прошейте. Там, где пример отличается от минимального шаблона, пояснение объясняет причину.

Cross-references:

  • Схема компонента, карта регистров, протокол учёта по периодам, топология из нескольких модулей, синхронизация GC по парку и правило мягкой проверки NACK: 09 · Справочник API
# Сценарий Топология Когда использовать
1 Сеть + N подгрузок — канон 80 % UI1 + N× I2/I3 Учёт всего дома с разбивкой по ответвлениям
2 Процесс развёртывания (новый → парк) последовательно, по одному Ввод в эксплуатацию новой партии модулей
3 Смешанный CT на нескольких каналах (UI3 с разными клещами) UI3 Учёт смешанных нагрузок с оптимизацией точности
4 Синхронизация парка GC (жёсткая синхронность) N× UI/I Многоабонентские кластеры и субучёт
5 UI1 — один канал (минимум) UI1 Hello-world: один модуль
6 UI1 с настройкой UI1 Все стандартные ручки ESPHome
7 UI3 — трёхканальный со смешанными клипсами UI3 Один модуль с несколькими каналами
8 Шина с несколькими модулями (синхронизация GC) N× UI/I fleet_gc_enable + group_id на трёх модулях
9 Однократная смена адреса I²C один Настройка одного модуля
10..20 Интеграции и автоматизации HA смешанные Шаблоны развёртывания в промышленной эксплуатации
21 Модуль STANDARD (STD) — итоги энергии на устройстве любой Общие итоги, реактивная энергия, start_current_ua:
22 Переключение номинала SCT, ct_model_force любой Смена номинала без потери точности
Примечание

Сценарии 1–4 — флагманские, они нацелены на канонический развёртывание v1.3 пакета. Их код использует fleet_gc_enable + поверхность идентичности + чтение-сравнение-запись и отработан на гетерогенной установке UI1+I2+I3. Сценарии 5–22 — одномодульные и компактные шаблоны. Сценарий 8 — короткая конфигурация шины из трёх модулей.


1 · Сеть + N субнагрузок (канон 80%) — интегрированная система учёта

Цель: канонический способ развёртывания пакета — согласованная система учёта на гетерогенном парке, замкнутая в рамках одной загрузки ESPHome (обнаружение → настройка → включение GC → цикл [publish_state + авто-отправка тика GC]).

Аппаратура (стенд UI1 + I2 + I3): UI1@0x50 + I2@0x51 + I3@0x52; нагрузка ~0.58 A; подтяжки по строке «3 модуля» таблицы 04_hardware.md (вырезать все, одна внешняя пара 2.7–3.3 kΩ).

YAML
esphome:
  name: home-fleet

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

# Three rbAmp modules on shared bus, all with fleet_gc_enable + group_id=1
# for synchronized period snapshots (tight sync between mains + sub-meters).
rbamp:
  - id: mains_meter         # UI1 on the mains feed
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

  - id: boiler_meter        # I2 on the boiler + washing machine
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]
    fleet_gc_enable: true
    group_id: 1

  - id: panel_meter         # I3 on the distribution-panel branches
    address: 0x52
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: mains_meter
    voltage:      { name: "Mains Voltage" }
    current:      { name: "Mains Current" }
    power:        { name: "Mains Power", id: mains_power_state }
    power_factor: { name: "Mains PF" }
    energy:       { name: "Mains Energy" }
    frequency:    { name: "Mains Frequency" }

  - platform: rbamp
    rbamp_id: boiler_meter
    # I2 is a current-only module: it has no voltage input, so it reports currents only
    # (power and energy need a UI module with voltage).
    current:   { name: "Boiler Current" }       # 20A CT
    current_1: { name: "Washer Current" }       # 10A CT

  - platform: rbamp
    rbamp_id: panel_meter
    current:   { name: "Lighting Current" }     # 5A CT
    current_1: { name: "Appliances Current" }   # 30A CT
    current_2: { name: "Sub-panel Current" }    # 20A CT

  # Optional: template sensor for the household power (same sensor: list, not a second sensor: key)
  - platform: template
    name: "Household Total Power"
    update_interval: 60s
    accuracy_decimals: 0
    unit_of_measurement: "W"
    device_class: power
    lambda: |-
      // Sum of power from the mains meter only (sub-meters are a subset of the same mains)
      auto v = id(mains_power_state);
      return v.has_state() ? v.state : 0.0f;

Пример вывода (нагрузка ~0.58 A)

Text
[I][i2c:136]: Found i2c device at address 0x50
[I][i2c:136]: Found i2c device at address 0x51
[I][i2c:136]: Found i2c device at address 0x52
[C][rbamp:450]: mains_meter:  variant=UI1, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: boiler_meter: variant=I2,  capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: panel_meter:  variant=I3,  capability=0x…, fleet_gc=on, group=1
[I][rbamp:493]: GC latch enabled fleet-wide: 3 modules in group 1

ITER 1 @ 60s: GC tick=1, 3/3 in_sync
  mains:   V=232.6  I=5.79  P=1259 W   E_total: 0 → 0.35 Wh
  boiler:  I=[11.58, 3.87]                                ; current-only
  panel:   I=[3.84, 2.55, 5.84]                           ; current-only

Замечания по использованию

  • Один синхронизированный цикл — вся система. На каждом тике update_interval ESP32 отправляет кадр GC на 0x00 → все 3 модуля снимают снимок своих накопителей периода в один момент на проводе (проверено 3/3 in_sync под нагрузкой).

  • mains_power в неоднородном парке = активная мощность с UI1 (mains_meter). Вспомогательные счётчики (I2/I3) измеряют только ток, канонической P у них нет. В каноне 80% mains_power ≈ суммарная мощность всех нагрузок (mains_meter охватывает ввод).

  • Вт·ч на модулях BASIC интегрируются на ESP32 по его собственным часам (время между снимками), поэтому все модули парка используют одну временную базу. Модули STANDARD ведут собственные счётчики энергии, которые компонент накапливает.

  • Устойчив к пропаданию. Если один модуль выпадает с шины (провизионирование / перезапуск питания), остальные продолжают работать; HA показывает «Unavailable» для его сущностей до восстановления.


2 · Порядок провизионирования (девственный → парк)

Цель: канонический порядок ввода новых модулей в работу — от заводского 0x50 до уникальных адресов парка. Показывает двухфазную фиксацию адреса (v1.3, пригодна для производства) и обязательное правило «один девственный модуль на шине одновременно».

Шаг 2.1 — провизионирование сети UI1 (0x50 → 0x50, sensor_class + ct_model)

YAML
# Connect ONLY the UI1 to the bus. Flash this YAML.
rbamp:
  - id: provisioning_target
    address: 0x50
    # new_address not needed — 0x50 is already fine for UI1
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: provisioning_target
    voltage:      { name: "Provision UI1 Voltage" }
    current:      { name: "Provision UI1 Current" }

text_sensor:
  - platform: template
    name: "Provision UI1 variant"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_variant_str();'
  - platform: template
    name: "Provision UI1 UID"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_uid_hex();'
  - platform: template
    name: "Provision UI1 capability"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_capability_hex();'

Проверка: в HA вы должны видеть sensor.provision_ui1_variant == "UI1" и sensor.provision_ui1_capability, показывающий ненулевую шестнадцатеричную битовую карту ("0x0000" означает устаревшую прошивку). Запишите UID для учёта инвентаря.

Шаг 2.2 — провизионирование I2 (0x50 → 0x51 через двухфазную фиксацию)

Отключите UI1 от шины (иначе будет конфликт адресов). Подключите модуль I2. Прошейте обновлённый YAML:

YAML
rbamp:
  - id: provisioning_target
    address: 0x50            # virgin address
    new_address: 0x51        # ⚠ two-phase commit — production-OK on v1.3
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]
    fleet_gc_enable: true
    group_id: 1

Что происходит при загрузке:

Text
[I][rbamp:xxx]: provisioning_target: probe at 0x50 → OK (variant=I2)
[I][rbamp:xxx]: provisioning_target: new_address=0x51 requested
[I][rbamp:xxx]: provisioning_target: two-phase address change supported → production path
[D][rbamp:xxx]: provisioning_target: stage REG_I2C_ADDRESS=0x51
[D][rbamp:xxx]: provisioning_target: write REG_ADDR_COMMIT_MAGIC=0xA5
[D][rbamp:xxx]: provisioning_target: send CMD_COMMIT_ADDR → wait 700ms
[I][rbamp:xxx]: provisioning_target: re-probe 0x51 → OK, re-enumeration complete
[I][rbamp:xxx]: provisioning_target: i2c address handle updated to 0x51

После успеха: обновите YAML на address: 0x51 и удалите new_address:. Следующая загрузка не запустит процедуру смены.

Шаг 2.3 — провизионирование I3 (0x50 → 0x52) + повтор для остальных

То же, что в 2.2: отключите I2, подключите девственный I3, прошейте YAML с new_address: 0x52, дождитесь повторного перечисления и обновите YAML до address: 0x52.

Примечание

🛑 ОБЯЗАТЕЛЬНО: на шине одновременно только один девственный модуль. Если два девственных модуля оба находятся на 0x50, оба ответят в фазе адреса и начнут тянуть SDA друг против друга → неопределённое состояние, и никакая процедура провизионирования не сработает.

Шаг 2.4 — соберите парк

Когда настройка всех модулей завершена, обновите YAML до итоговой конфигурации парка (см. сценарий §1 выше), отключите внутренние подтяжки на всех модулях (3 модуля = разрезать все) и добавьте одну внешнюю пару 2.7–3.3 кОм на ESP32 — см. таблицу подтяжек в 04_hardware.md. Прошейте итоговый YAML — все модули должны быть обнаружены:

Text
[D][i2c:136]: Found i2c device at address 0x50
[D][i2c:136]: Found i2c device at address 0x51
[D][i2c:136]: Found i2c device at address 0x52

Режимы отказа (provisioning)

Симптом Причина Восстановление
Probe failed at 0x50 после прошивки Модуль без питания или плохой контакт Проверьте связь VCC + GND + SDA + SCL
[W] двухфазная смена адреса не поддерживается Модуль на устаревшей прошивке (v1.0-v1.2) Однофазный запасной путь требует режима заводского провизионирования (см. 04_hardware.md)
[E] address change committed but re-probe at 0x51 failed Пограничная шина или прерванная фиксация Повторите загрузку; если повторяется, внешняя подтяжка слишком слабая или есть всплеск EMI
[W] WARN_FACTORY_MODE_REQUIRED Устаревшая прошивка без двухфазной смены адреса Поставщик включает заводской режим (вне рамок библиотеки)

3 · Смешанный CT на нескольких каналах (UI3 с разными клещами)

Цель: показать, что CT-модели на разных каналах одного модуля можно смешивать в соответствии с характером нагрузки. Компонент привязывает каналы по одному; порядок не важен.

YAML
rbamp:
  - id: panel_meter
    address: 0x52
    sensor_class: SCT_013
    # Mixed-CT: small/medium/large on channels 0/1/2
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    # The component binds channels one by one; the order does not matter.
    # Each channel keeps its own model: ch0 = 5 A, ch1 = 30 A, ch2 = 20 A
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: panel_meter
    current:    { name: "Panel Lighting (5A CT)" }       # ch0
    current_1:  { name: "Panel Appliances (30A CT)" }    # ch1
    current_2:  { name: "Panel Boiler (20A CT)" }        # ch2
    # No voltage / power — this is an I3 SKU, current-only

text_sensor:
  - platform: template
    name: "Panel last error"
    update_interval: 30s
    lambda: 'return id(panel_meter).get_last_error_str();'
    # → "OK" in a healthy state; "ERR_PARAM" if a CT model code is rejected

Проверьте привязку CT при загрузке

После прошивки и загрузки в логе:

Text
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH0 mirror = 1 (SCT_013_005)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH1 mirror = 3 (SCT_013_030)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH2 mirror = 6 (SCT_013_020)
[I][rbamp:xxx]: panel_meter: CT binding verified, all mirrors match YAML request
[C][component:246]: Setup panel_meter took ~2100ms (cold install: 3 × 700ms flash + verify)

При тёплой загрузке (зеркала совпадают) без записи во флеш:

Text
[I][rbamp:xxx]: panel_meter: CT_MODEL[0..2] match YAML → SKIP flash erase
[C][component:246]: Setup panel_meter took 72ms (warm boot: read-compare only)

Наблюдаемое поведение

  • Смешанная привязка CT: коды [1, 3, 6] на трёхканальном модуле по адресу 0x52 сохраняются каждый на своём канале.
  • Отклонение недопустимого кода: попытка кода вне допустимого набора класса → esphome config отклоняет схему (cv.Invalid). Если YAML проскочит валидатор (ручная правка / старая сборка), прошивка возвращает REG_ERROR = 0xFE DEV_ERR_PARAM, а зеркало остаётся на предыдущем значении.

  • Время холодной установки: ~2.1 с на UI3 (3 × ~700 мс стирание флеша).

  • Тайминг тёплой загрузки: ~70 мс (чтение-сравнение-запись пропускает всё стирание флеша).
  • Задержка измерения: ~1.4 с от начала setup() до первой публикации (стенд).

4 · Синхронизация парка GC (жёсткая синхронность)

Цель: показать, что синхронизация парка 3/3 — не академическая задача, а реальное требование для многоабонентских установок (субучёт квартир на общем щитке) и для точного субучёта (ввод UI1 должен совпадать с суммой мощностей вспомогательных счётчиков с точностью до одного периода).

YAML
# Fleet config — all modules in one group for synchronized snapshots:
rbamp:
  - id: tenant1_mains
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

  - id: tenant1_panel
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    fleet_gc_enable: true
    group_id: 1

  - id: tenant2_mains       # Independent tenant (separate group)
    address: 0x52
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 2             # ⚠ different group → independent sync timeline

# Native API services for manual sync verification:
api:
  port: 6053
  services:
    - service: emit_gc_tenant1
      then:
        - lambda: 'id(tenant1_mains).transmit_gc_frame();'  # group = tenant1_mains group_id
    - service: emit_gc_tenant2
      then:
        - lambda: 'id(tenant2_mains).transmit_gc_frame();'  # group = tenant2_mains group_id
    - service: check_sync_all
      then:
        - lambda: |-
            uint16_t t1m = id(tenant1_mains).read_gc_tick_received();
            uint16_t t1p = id(tenant1_panel).read_gc_tick_received();
            uint16_t t2m = id(tenant2_mains).read_gc_tick_received();
            ESP_LOGI("rbamp", "GC tick state: tenant1[mains=%u, panel=%u]  tenant2[mains=%u]",
                     t1m, t1p, t2m);

text_sensor:
  - platform: template
    name: "Tenant1 GC tick (mains)"
    update_interval: 30s
    lambda: 'return std::to_string(id(tenant1_mains).read_gc_tick_received());'
  - platform: template
    name: "Tenant1 GC tick (panel)"
    update_interval: 30s
    lambda: 'return std::to_string(id(tenant1_panel).read_gc_tick_received());'

Пример вывода (тест синхронизации из 10 итераций)

Text
[I][rbamp:572]: GC frame emit: group=1, tick=42, all 2 tenant1 modules ACK'd
[I][rbamp:580]: check_sync: tenant1_mains.tick=42  tenant1_panel.tick=42  → 2/2 in_sync
[I][rbamp:572]: GC frame emit: group=2, tick=42, tenant2 module ACK'd
[I][rbamp:580]: check_sync: tenant2_mains.tick=42  → 1/1 in_sync (tenant2 isolated)

ROUND 0: GC tick=1   →  tenant1[1, 1]  tenant2[1]   → 3/3 in_sync
ROUND 1: GC tick=2   →  tenant1[2, 2]  tenant2[2]   → 3/3 in_sync
ROUND 2: GC tick=3   →  tenant1[3, 3]  tenant2[3]   → 3/3 in_sync
...
ROUND 9: GC tick=10  →  tenant1[10,10] tenant2[10]  → 3/3 in_sync

L8 soak: 180 cycles, 0 sync drops, 0 identity drops

Как group_id помогает в многоабонентских установках

Без group_id арендаторы не разделены — все модули реагируют на любой кадр GC. С group_id:

  • Модули арендатора 1 отвечают только на кадры GC с group=1 (или на общий вызов group=0)
  • Модули арендатора 2 отвечают только на кадры GC с group=2

Это позволяет мастеру выдавать отдельные кадры GC для арендаторов в независимые моменты — например, по периоду арендатора:

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
automation:
  - alias: "Tenant 1 period snapshot"
    trigger:
      platform: time_pattern
      seconds: "/60"            # every 60 s
    action:
      - service: esphome._emit_gc_tenant1

  - alias: "Tenant 2 period snapshot"
    trigger:
      platform: time_pattern
      seconds: "/15"            # every 15 s (high-resolution tenant)
    action:
      - service: esphome._emit_gc_tenant2

Проверка в промышленной эксплуатации

  • Датчик HA template"mains_minus_subsum" — индикатор расхождения:
    YAML
    sensor:
      - platform: template
        name: "Mains - SubSum (W)"
        update_interval: 60s
        unit_of_measurement: "W"
        lambda: |-
          // here the sub-meters are current-only, so this is a rough estimate:
          // mains_power - sum(sub_currents × V_mains)
          float v_mains = id(mains_voltage_state).state;
          float sub_i = id(sub_i0).state + id(sub_i1).state + id(sub_i2).state;
          return id(mains_power_state).state - sub_i * v_mains;
    

Расхождение < 1% от mains_power на стенде = синхронизация верна.

  • Интеграция по часам стенки — даже при синхронизации GC 3/3 модули BASIC интегрируются по собственным часам ESP32, поэтому небольшой перекос между модулями не искажает Вт·ч.

5 · UI1 — один канал (минимально)

Источник: ../example/ui1.yaml

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

YAML
esphome:
  name: rbamp-ui1

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"
    password: !secret ap_password

captive_portal:
api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz    # recommended on ESP32; 100 kHz causes periodic NACKs due to ESP-IDF i2c_master driver interaction;
                      # 50 kHz reduces them ~5-10× — see the chapter end link.
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  ct_model: SCT_013_030    # CT clamp model — change it to match yours

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Что демонстрирует: минимальную рабочую конфигурацию. Шесть датчиков покрывают базовый случай — учёт всего дома или одной нагрузки. У датчика energy уже заданы device_class: energy + state_class: total_increasing, поэтому он сразу попадает на панель энергии HA без дополнительной настройки. Протокол учёта по периодам (снимок / пауза 50 мс / чтение средней мощности, интегрируемой по часам мастера) описан в 09 · Справочник API.


6 · UI1 с настройкой — все стандартные ручки ESPHome

rbAmp — «добропорядочный» компонент ESPHome. Каждый слот (voltage, current, power, …) — обычный объект sensor: ESPHome. Работает весь стандартный набор свойств и фильтров. Не нужны ни lambda:, ни собственные шаблоны — всё, что вы делаете с pzemac / atm90e32 / cse7766, здесь работает точно так же. Пример показывает самые частые настройки в одном блоке:

YAML
esphome:
  name: rbamp-ui1-tuned

esp32:
  board: esp32dev
  framework:
    type: arduino

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 10s        # ↑ Poll once / 10 s instead of the default 60 s —
                              # a denser graph, ~6× the I²C traffic.
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1

    # ──────────── Customizing names + precision + filters ────────────
    voltage:
      name: "Mains voltage"              # Any name — it becomes the HA entity_id
      accuracy_decimals: 1               # 226.7 instead of the default 226.70
      filters:
        # Linear calibration against a reference multimeter:
        - calibrate_linear:
            - 0.0 -> 0.0
            - 230.0 -> 230.5
        # Smoothing of sharp spikes (standard ESPHome):
        - exponential_moving_average:
            alpha: 0.3
            send_every: 1

    current:
      name: "Load current"
      accuracy_decimals: 3               # 0.755 instead of 0.75
      filters:
        # Mask the noise floor — drop values below 50 mA (50 mW at 230 V).
        # The equivalent of the `noise_floor` option in pzemac / cse7766.
        - lambda: 'return x < 0.05 ? 0.0f : x;'

    power:
      name: "Power"
      accuracy_decimals: 1
      filters:
        # Throttle publications: no more than once / 30 s, even with update_interval 10 s.
        - throttle: 30s

    energy:
      name: "Energy (Wh)"
      # The standard device_class: energy + state_class: total_increasing
      # are already set by the component — the Energy dashboard works.
      filters:
        # Convert Wh → kWh for a more familiar scale in Lovelace.
        # (The HA Energy dashboard itself expects Wh, but if you want a graph in kWh,
        #  declare a second template sensor with a division rather than changing units here.)
        - multiply: 0.001
      unit_of_measurement: "kWh"         # ← overrides the default "Wh"
      accuracy_decimals: 3

    frequency:
      name: "Mains frequency"
      accuracy_decimals: 2

    power_factor:
      name: "Power factor"
      accuracy_decimals: 3
      # Optional: a filter to hide PF at zero load (P ~ 0)
      filters:
        - lambda: 'return isnan(x) ? 0.0f : x;'

Что это демонстрирует:

  • Пользовательские имена (name:) становятся entity_id в HA — например, sensor.rbamp_ui1_tuned_mains_voltage. Имена на любом языке, включая кириллицу, работают.

  • Точность вывода (accuracy_decimals:) не зависит от модуля; модуль возвращает float32 с максимальной точностью, а ESPHome обрезает его для интерфейса.

  • update_interval: не нужно менять для каждого датчика — это свойство компонента (PollingComponent), задаётся один раз в блоке rbamp:. Если нужны более редкие публикации отдельных датчиков, добавьте filters: - throttle: .

  • filters: — полный набор ESPHome:

  • calibrate_linear — калибровка по точкам относительно эталона (мультиметр, эталонный амперметр).

  • exponential_moving_average / sliding_window_moving_average — сглаживание.

  • lambda — произвольное преобразование (маска шумового порога, условный ноль).
  • multiply / offset — арифметика (например, Вт·ч → кВт·ч).
  • throttle / delta — снижение частоты публикаций.
  • unit_of_measurement: можно переопределить (например, на kWh с multiply: 0.001). HA автоматически подхватывает новую единицу.

  • Без lambda: для базовой работы — все расчёты RMS, мощности, частоты и PF выполняет модуль. ESP32 только переименовывает, форматирует и фильтрует.

Безопасность

⚠ Не переопределяйте device_class: для energy — панель энергии HA строго ожидает device_class: energy + state_class: total_increasing. Преобразование единиц через multiply + unit_of_measurement: сохраняет совместимость, но смена device_class сломает панель.

Полный список стандартных свойств и фильтров датчиков — в официальной документации ESPHome Sensor Component. Эта документация полностью применима к слотам rbAmp — отклонений от стандарта нет.


7 · UI3 — трёхканальный со смешанными клипсами

Исходник: ../example/ui3.yaml

У артикула UI3 один вход напряжения и три независимых канала тока. Каноничный сценарий — ставить разные модели клипс на разные каналы: маленькую клипсу на слабопотребляющие нагрузки (для максимального разрешения) и большую на главный ввод (запас по пиковым нагрузкам).

YAML
esphome:
  name: rbamp-ui3

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  # drdy_pin: GPIO15
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  # CH0=5A for standby consumers and LED lighting,
  # CH1=30A for the main household loads,
  # CH2=20A for the boiler / a medium-power branch (~3-5 kW)
  # For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A).

sensor:
  - platform: rbamp
    rbamp_id: meter1
    # Common (topology-independent)
    voltage:
      name: "Mains Voltage"
    frequency:
      name: "Mains Frequency"
    apparent_power:
      name: "CH0 Apparent Power"

    # Channel 0 — primary current input (small consumers, 5A)
    current:
      name: "CH0 Current"
    power:
      name: "CH0 Power"
    energy:
      name: "CH0 Energy"
    power_factor:
      name: "CH0 Power Factor"
    reactive_power:
      name: "CH0 Reactive Power"

    # Channel 1 — main loads (30A)
    current_1:
      name: "CH1 Current"
    power_1:
      name: "CH1 Power"
    energy_1:
      name: "CH1 Energy"
    power_factor_1:
      name: "CH1 Power Factor"
    reactive_power_1:
      name: "CH1 Reactive Power"

    # Channel 2 — boiler / medium-power branch (20A)
    current_2:
      name: "CH2 Current"
    power_2:
      name: "CH2 Power"
    energy_2:
      name: "CH2 Energy"
    power_factor_2:
      name: "CH2 Power Factor"
    reactive_power_2:
      name: "CH2 Reactive Power"

Что это демонстрирует: все три канала артикула UI3 плюс смешанные модели клипс через ct_models:. Валидатор схемы проверяет, что power_N и energy_N (и power_factor_N, reactive_power_N) требуют current_N и voltage — если вы объявите power_1 без current_1, сборка завершится с понятным сообщением. У каждого канала свой независимый накопитель energy_*, сохраняемый в NVS. Если все каналы используют одну модель клипсы, используйте общий ct_model: вместо ct_models:.


8 · Шина из нескольких модулей (три rbAmp на 0x50 / 0x51 / 0x52)

Исходник: ../example/multi_module.yaml

Три модуля на одной шине I²C — главный ввод дома, выход солнечной генерации и зарядка EV. У каждого свой блок rbamp: (в схеме компонента MULTI_CONF = True).

YAML
esphome:
  name: rbamp-multi

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz    # recommended: at 100 kHz the ESP-IDF i2c_master driver interaction causes periodic
                      # NACKs are almost inevitable on every cycle
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

# Three independent rbamp: blocks — MULTI_CONF = True in the schema.
# On v1.3 firmware the general-call snapshot is opt-in via fleet_gc_enable +
# group_id (capability-gated on the firmware side). Modules in the same
# group snapshot in a single transaction, with ~540 µs skew per module. On legacy
# firmware (v1.0..v1.2) the component falls back to a sequential snapshot
# and logs an informational line. (The old broadcast_latch: key is still
# accepted by the schema but has no effect.)
rbamp:
  - id: meter_house
    address: 0x50
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1

  - id: meter_solar
    address: 0x51
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1
    bidirectional: true     # needed for energy_exported_*; on BASIC it
                             # publishes 0, on STANDARD it is real export energy

  - id: meter_evcharger
    address: 0x52
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: meter_house
    voltage:
      name: "House Voltage"
    current:
      name: "House Current"
    power:
      name: "House Power"
    energy:
      name: "House Energy"
    frequency:
      name: "Mains Frequency"

  - platform: rbamp
    rbamp_id: meter_solar
    voltage:
      name: "Solar Voltage"
      internal: true        # hidden from HA — the same mains as House Voltage
    current:
      name: "Solar Current"
    power:
      name: "Solar Power"
    energy:
      name: "Solar Energy"
    energy_exported:
      name: "Solar Energy Exported"

  - platform: rbamp
    rbamp_id: meter_evcharger
    voltage:
      name: "EV Charger Voltage"
      internal: true
    current:
      name: "EV Charger Current"
    power:
      name: "EV Charger Power"
    energy:
      name: "EV Charger Energy"

Что демонстрирует: шаблон MULTI_CONF = True — объявите столько блоков rbamp:, сколько модулей на шине. Каждый ведёт свой накопитель NVS, ключ которого выводится из I²C-адреса, так что три счётчика остаются независимыми после перезагрузок. Флаг internal: true у дублирующих датчиков напряжения скрывает три почти одинаковых сетевых напряжения от HA, когда все модули измеряют одну фазу. Процедуру назначения адресов см. в примере 2 ниже.

Примечание

Семантика internal: true. Флаг не отключает чтение регистра с модуля — компонент по-прежнему читает напряжение с каждого модуля на каждом update_interval (это нужно для расчёта мощности). Флаг лишь скрывает датчик от API Home Assistant: сущность не создаётся, в Lovelace не появляется и в панели Energy не учитывается. Если хотите снизить трафик I²C, не объявляйте слот voltage: в sensor.platform: rbamp вовсе — тогда компонент не обращается к регистру. Если вы его объявляете, флаг internal: чисто косметический.

Второе ограничение касается уникальности адресов на шине:

Безопасность

⚠ Уникальность адресов — ответственность конфигурации. Схема компонента (MULTI_CONF = True) не проверяет пересечения значений address: между блоками rbamp:. Если два блока задают один и тот же address: 0x50, обе декларации принимаются, и на шине оба объекта ответят одновременно — ожидайте конфликтов I²C, искажённых ответов или симптомов, похожих на отсутствующий модуль. Перед фиксацией YAML убедитесь, что все значения address: уникальны (и не совпадают с другими устройствами I²C на шине). После каждого назначения new_address: обновляйте секцию rbamp: на новый адрес — старая запись сама не аннулируется.

Подтяжки на шине из нескольких модулей

Все три модуля поставляются с заводскими подтяжками 4.7 кОм. На шине из трёх модулей параллельное сочетание — ~1.6 кОм: выше потребление тока и хуже целостность сигнала на 50 кГц. Разрежьте перемычки подтяжки на всех трёх модулях и установите одну внешнюю пару 2.7–3.3 кОм рядом с ESP32 (строка для 3 модулей в таблице из 04_hardware.md).

Продвинутый вариант: раздельная частота снимков для парков из нескольких модулей (v1.4+)

Парки из нескольких модулей платят за цикл снимка на каждый модуль в каждом цикле: на шине из 3 модулей при опросе update_interval: 10s это 3× запись снимка + 3× окно стабилизации 50 мс каждые 10 с — плюс чтения блока RT сверху. На хостах ESP8266 (одно ядро; ISR Wi-Fi конкурируют за CPU во время транзакций I²C) или на общих шинах I²C с другими устройствами эти накладные расходы становятся заметны как сбои Wi-Fi или устаревшие показания на сущностях, не относящихся к rbAmp.

latch_interval: (доступен с v1.4, модули BASIC) разделяет два цикла: чтение RT-блока (V/I/P/PF/Q) остаётся на update_interval: — читатель видит свежие значения на дашборде, — а переход снимок → интеграция Вт·ч выполняется только каждые latch_interval:. Интеграция использует реальное время между событиями снимка, поэтому снимок каждые 60 с просто даёт шаги интеграции шириной 60 с (и по-прежнему корректные). latch_interval должен быть ≥ update_interval.

YAML
rbamp:
  - id: mod_mains
    address: 0x50
    update_interval: 10s     # dashboard: fresh V/I/P/PF every 10 s
    latch_interval: 60s      # bus: snapshot + Wh integration once a minute
    ct_models: [SCT_013_050, SCT_013_030, SCT_013_030]
    fleet_gc_enable: true
    group_id: 1
  - id: mod_branches
    address: 0x51
    update_interval: 10s
    latch_interval: 60s
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
    fleet_gc_enable: true
    group_id: 1

Снижение нагрузки на шину по сравнению с тем же парком без latch_interval:: при update_interval: 10s каждый модуль добавляет ~15 мс чтения RT и ~65 мс снимка+стабилизации за цикл → ~80 мс на модуль за цикл. С latch_interval: 60s снимок+стабилизация срабатывает только раз в минуту → чтения RT остаются дешёвыми каждые 10 с плюс одна короткая серия снимков каждые 60 с, примерно в 3 раза меньше средней загрузки шины. У больших парков экономия пропорционально выше.

Когда опускать latch_interval:: установки из одного модуля на хостах ESP32, где базовая нагрузка ничего не стоит — стандартный одноцикловый режим v1.3 проще и так же корректен.


9 · Однократная смена I²C-адреса (0x50 → 0x51)

Источник: ../example/address_change.yaml

Все модули rbAmp поставляются с завода с адресом 0x50. Чтобы разместить несколько модулей на одной шине, перепрошейте каждый на собственный уникальный адрес до параллельного подключения.

YAML
esphome:
  name: rbamp-addr-change

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG    # DEBUG shows the address-change lines

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50          # current address — before the change
  new_address: 0x51      # one-time target — DELETE this line after success

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "rbAmp Voltage (post-relocate)"
    current:
      name: "rbAmp Current (post-relocate)"

Что демонстрирует: однократный процесс смены адреса. Прошивка этого YAML заставляет компонент выполнить процедуру один раз при загрузке:

  1. Опросите 0x50. Если 0x50 молчит, а 0x51 уже отвечает, смена была применена при предыдущей загрузке; компонент адаптируется и пишет предупреждение с просьбой очистить YAML.

  2. Проверьте, что модуль готов принять операцию провизионирования.

  3. Запишите новый адрес во флеш (~700 мс), мягкий сброс (~300 мс) и повторная синхронизация с циклом переменного тока.

  4. Подтвердите новый адрес. При успехе — строка в логе Address change confirmed at 0x51 и IMPORTANT: update YAML to address: 0x51 and remove new_address:.

Совместимость прошивки: на прошивке v1.3+ смена адреса пригодна для производства — компонент использует протокол двухфазной фиксации (этап → взведение → фиксация → перезагрузка) без специального режима. На устаревшей прошивке (v1.0–v1.2) однофазный запасной путь требует режима заводского провизионирования; уточните процедуру временного включения в документации модуля или у поставщика.

После успеха: измените YAML на address: 0x51 и удалите строку new_address: 0x51. Прошейте снова. Начиная со следующей загрузки компонент использует 0x51 штатно, а процедура смены больше не выполняется.

Контрольный список отката после успешного провизионирования

Чтобы не оставлять «висящий» вариант настройки в репозитории (две альтернативы, никогда не вставляйте оба в один файл):

YAML
# BEFORE (provisioning):
rbamp:
  id: meter1
  address: 0x50               # the module's current address
  new_address: 0x51           # the provisioning target
  update_interval: 60s
YAML
# AFTER (production — applied next flash):
rbamp:
  id: meter1
  address: 0x51               # ← replaced with the new address
  # new_address: 0x51         # ← DELETE the line (do not comment it out)
  update_interval: 60s

Ровно три правки:

  1. Измените значение address: со старого на новое.
  2. Удалите (не комментируйте) строку new_address:.
  3. Перепрошейте по OTA или USB.

После шага 3 в журнале должна появиться обычная строка dump_config без предупреждения address change requested but current address matches new_address — это значит, что откат выполнен верно. См. также 10_troubleshooting §4 «OTA сразу после назначения new_address: не загружается», если первая OTA после отката не стартует.


10 · Стендовая конфигурация с secrets

Исходник: ../example/bench-ui1.yaml

Шаблон bench-*.yaml предназначен для рабочих машин разработчика, где учётные данные Wi-Fi нужны в конфигурации, но не должны попасть в коммит. example/.gitignore исключает bench-*.yaml и secrets.yaml из системы контроля версий.

YAML
esphome:
  name: rbamp-ui1

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"
    password: !secret ap_password

captive_portal:
api:
ota:
  - platform: esphome

web_server:
  port: 80
  version: 3           # optional: a local HTTP UI — handy for bench testing

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Соответствующий secrets.yaml (в example/, не отслеживается):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Что это демонстрирует: отделение учётных данных времени компиляции от YAML под контролем версий через !secret ESPHome. Перечисление bench-*.yaml в .gitignore позволяет держать сколько угодно стендовых вариантов без риска утечки. Используйте esphome run --device 192.168.0.173 example/bench-ui1.yaml для OTA после первого сетевого подключения или esphome run --device COM6 example/bench-ui1.yaml для первой прошивки по USB.


11 · Просадка и потеря сети

При пропадании сети изолированный аналоговый фронтенд модуля перестаёт получать сигнал. Регистр напряжения падает до 0.0 V — это корректное конечное float IEEE 754, которое проходит санитарный фильтр компонента isfinite(). Политика фильтра компонента намеренна:

Безопасность

НИКАКИХ физических нижних границ — просадка (U=0 В при отключении сети), провал напряжения, испытания вне сети / ИБП и срабатывание автомата ОБЯЗАНЫ проходить в HA, чтобы пользователь видел реальное состояние.

Специальный YAML для обнаружения пропадания сети не нужен — сам датчик voltage показывает 0.0 V.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"    # reads 0.0 V when mains is disconnected
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"

Автоматизация HA: оповещение о пропадании сети

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
# configuration.yaml or the Automations UI
automation:
  - alias: "rbAmp mains loss alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_voltage
        below: 10          # U < 10 V = mains disconnected or a severe brownout
        for:
          seconds: 5       # debounce: sustained, not transient
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Mains power lost"
          message: >
            Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V
            at {{ now().strftime('%H:%M:%S') }}.

Что это демонстрирует: использование поведения пропуска 0 V как источника события «пропадание сети». Поскольку компонент публикует 0.0 V, а не пропускает публикацию, автоматизации HA и панель Energy видят событие просадки в реальном времени. Условие for: 5 seconds блокирует ложные срабатывания во время разогрева ~250 мс после загрузки (когда регистры читают 0 до первого корректного измерения).


12 · Панель Energy в HA

Датчик energy (и energy_1, energy_2, energy_exported и т. д.) автоматически настроен с device_class: energy и state_class: total_increasing — именно то, что ожидает панель Energy в HA для накопительных датчиков потребления. Дополнительный YAML не нужен.

После обнаружения:

  1. Настройки → Дашборды → Энергия.
  2. Добавьте потребление → выберите «Mains Energy» (или сущность учёта импорта, которую хотите).

  3. Если у вас солнечная станция — Add Production → выберите Solar Energy (из meter_solar в примере с несколькими модулями).

Значения энергии в Вт·ч. HA сам переводит их в кВт·ч для отображения. Сохранение в NVS в компоненте гарантирует, что накопитель переживает перезагрузку ESP32 без ложного «сброса счётчика» в статистике HA.

YAML
# Example: consumption + solar export for the HA Energy dashboard
# (assumes the rbamp: blocks meter_house and meter_solar from the multi-module example)
# energy / energy_exported need voltage AND current in the same block;
# internal: true keeps them out of Home Assistant.
sensor:
  - platform: rbamp
    rbamp_id: meter_house
    voltage:
      name: "House Voltage"
      internal: true
    current:
      name: "House Current"
      internal: true
    energy:
      name: "House Grid Import"    # → HA Energy: grid consumption

  - platform: rbamp
    rbamp_id: meter_solar
    voltage:
      name: "Solar Voltage"
      internal: true
    current:
      name: "Solar Current"
      internal: true
    energy:
      name: "Solar Production"     # → HA Energy: solar production
    energy_exported:
      name: "Solar Grid Export"    # → HA Energy: return to grid
                                   # needs bidirectional: true in rbamp:;
                                   # real values on STANDARD (STD) modules,
                                   # reads 0 on BASIC

13 · Автоматизации HA на датчиках rbAmp

Сброс нагрузки: реле выключается при превышении порога

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
automation:
  - alias: "Load shedding — turn off non-critical loads at 3 kW"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_multi_house_power
        above: 3000        # 3 kW threshold
        for:
          seconds: 10
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.ev_charger_relay   # the non-critical load relay

  - alias: "Load shedding — restore when it drops below 2 kW"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_multi_house_power
        below: 2000
        for:
          seconds: 30
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.ev_charger_relay

Напоминание о коррекции коэффициента мощности

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
automation:
  - alias: "Poor power factor notification"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_power_factor
        below: 0.7
        for:
          minutes: 5
    action:
      - service: persistent_notification.create
        data:
          title: "Low power factor"
          message: >
            Power factor is {{ states('sensor.rbamp_ui1_mains_power_factor') }}.
            Check for large inductive loads (motors, old lighting ballasts).

Оповещение о превышении дневного бюджета

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
automation:
  - alias: "Daily energy budget — warning at 10 kWh"
    trigger:
      - platform: template
        value_template: >
          {{ states('sensor.energy_daily') | float(0) > 10000 }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "Daily energy usage exceeded 10 kWh."

14 · Карточки Lovelace

Датчик — текущая мощность

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 3600
name: "Live Power"
segments:
  - from: 0
    color: green
  - from: 1500
    color: orange
  - from: 2500
    color: red

Apex Charts — мощность во времени

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
type: custom:apexcharts-card
header:
  title: "Power (W)"
  show: true
graph_span: 4h
series:
  - entity: sensor.rbamp_ui1_mains_power
    name: Power
    stroke_width: 2
    curve: smooth

Apex Charts — сравнение энергии по трём каналам

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
type: custom:apexcharts-card
header:
  title: "Channel Energy (Wh)"
  show: true
graph_span: 24h
series:
  - entity: sensor.rbamp_ui3_ch0_energy
    name: CH0
  - entity: sensor.rbamp_ui3_ch1_energy
    name: CH1
  - entity: sensor.rbamp_ui3_ch2_energy
    name: CH2

Мини-график — напряжение

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
type: custom:mini-graph-card
entities:
  - sensor.rbamp_ui1_mains_voltage
name: "Mains Voltage"
hours_to_show: 12
points_per_hour: 4
line_width: 2

15 · Счётчик коммунальных услуг — агрегация по дням / неделям / месяцам

ESPHome публикует накопленные суммы в Вт·ч. Интеграция HA utility_meter сбрасывает счётчик с заданным интервалом и публикует разность отдельным датчиком — удобно для разбивки по дням или месяцам.

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
# configuration.yaml
utility_meter:
  energy_daily:
    source: sensor.rbamp_ui1_mains_energy
    cycle: daily
    name: "Daily Energy"

  energy_monthly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: monthly
    name: "Monthly Energy"

  energy_weekly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: weekly
    name: "Weekly Energy"

HA создаёт три сущности: sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Каждая сбрасывается в 0 в начале своего периода и накапливает приращение от исходного датчика total_increasing.

Производный датчик кВт·ч/сутки

utility_meter по умолчанию выводит Вт·ч. Чтобы показать в кВт·ч, добавьте датчик template:

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
template:
  - sensor:
      - name: "Daily Energy kWh"
        unit_of_measurement: "kWh"
        state_class: total_increasing
        device_class: energy
        state: >
          {{ (states('sensor.energy_daily') | float(0) / 1000) | round(3) }}

Датчик дневной стоимости

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
template:
  - sensor:
      - name: "Daily Energy Cost"
        unit_of_measurement: "EUR"
        icon: mdi:currency-eur
        state: >
          {% set kwh = states('sensor.energy_daily') | float(0) / 1000 %}
          {% set rate = 0.28 %}    # EUR/kWh — set your own tariff
          {{ (kwh * rate) | round(2) }}

16 · Учёт по каждой нагрузке (3 модуля на 0x50 / 0x51 / 0x52)

Установка трёх модулей rbAmp на распределительном щитке позволяет вести учёт энергии по отдельным цепям без умного щитка и дополнительного оборудования.

Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.

YAML
# Extending the multi-module example with per-circuit utility meters

utility_meter:
  kitchen_daily:
    source: sensor.rbamp_multi_house_energy
    cycle: daily
    name: "Kitchen Circuit Daily"

  solar_monthly:
    source: sensor.rbamp_multi_solar_energy
    cycle: monthly
    name: "Solar Production Monthly"

  ev_daily:
    source: sensor.rbamp_multi_ev_charger_energy
    cycle: daily
    name: "EV Charging Daily"

В сочетании с панелью энергии HA вы получаете ежемесячные отчёты по каждой цепи без дополнительных расчётов кВт·ч × тариф.


17 · rbAmp + реле — управление с обратной связью

Бойлер с управлением реле

YAML
# ESPHome YAML on the same ESP32 as rbAmp
switch:
  - platform: gpio
    pin: GPIO5
    id: heater_relay
    name: "Water Heater"

С rbAmp и реле на одном ESP32 можно собрать замкнутый контур прямо в ESPHome (через Lambda или on_value) без обхода через HA:

Предполагается, что у вас уже есть запись switch: с идентификатором, использованным ниже.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    power:
      name: "House Power"
      on_value:
        then:
          - if:
              condition:
                lambda: 'return x > 3000.0f;'
              then:
                - switch.turn_off: heater_relay
              else:
                - switch.turn_on: heater_relay

Что это демонстрирует: использование обратного вызова on_value датчика rbAmp для управления реле без участия HA. Обратный вызов срабатывает на ESP32 каждые update_interval (60 с) и обновляет состояние реле по последнему показанию мощности. Для более жёсткого управления (контур < 60 с) уменьшите update_interval до 10s — это пропорционально увеличивает нагрузку на шину I²C. Более полный пример управления с обратной связью для бойлера — в 07_diy_integrations.md.


18 · Интеграция DRDY

Открыто-стоковый вывод DRDY модуля даёт импульс LOW ~10 мкс каждые ~100 мс после обновления мгновенных регистров. Его можно подключить к GPIO ESP32. Компонент логирует пин DRDY; чтение управляется таймером (update_interval).

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s        # energy integration still happens every 60 s
  drdy_pin:
    number: GPIO15
    mode:
      input: true
      pullup: true            # DRDY is open-drain; it needs a pull-up
    inverted: true            # the DRDY pulse is LOW; inverted=true gives a rising edge
Примечание

: в текущей прошивке компонент логирует drdy_pin в dump_config, но не реализует чтение RT по прерыванию — update_interval по-прежнему задаёт частоту опроса.


19 · Фазовые датчики (варианты split-phase / трёхфазные)

Для модулей с более чем одним входом напряжения компонент предлагает группу фазовых датчиков (voltage_a/b/c, current_a/b/c, power_a/b/c, energy_a/b/c, power_factor_a/b/c, reactive_power_a/b/c, power_total, плюс voltage_angle_b/c). Слот публикуется только тогда, когда подключённый модуль сообщает соответствующий канал; на однофазном модуле фазовые слоты остаются без значения. Схема проверяет, что одиночные и фазовые группы не смешаны в одном блоке sensor:.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage_a:
      name: "Phase A Voltage"
    voltage_b:
      name: "Phase B Voltage"
    voltage_c:
      name: "Phase C Voltage"
    current_a:
      name: "Phase A Current"
    current_b:
      name: "Phase B Current"
    current_c:
      name: "Phase C Current"
    power_a:
      name: "Phase A Power"
    power_b:
      name: "Phase B Power"
    power_c:
      name: "Phase C Power"
    power_total:
      name: "Total Power"
    voltage_angle_b:
      name: "Phase B Angle"        # degrees vs phase A
    voltage_angle_c:
      name: "Phase C Angle"
    phase_sequence:
      name: "Phase Sequence"       # 1 forward, 2 reverse, 3 abnormal
    frequency:
      name: "Grid Frequency"

Что демонстрирует: группу фазовых полей. Смешивание одиночных и фазовых полей в одном блоке sensor: даёт ошибку на этапе компиляции — выберите группу, соответствующую вашему модулю. Подробности — в 09 · Справочник API §2.2.


20 · Миграция с других компонентов учёта ESPHome

Из pzem004t

Платформа pzem004t экспортирует те же имена полей, что и rbamp, для основных величин переменного тока. Замена — блок-в-блок с одинаковыми именами датчиков:

YAML
# Before (pzem004t, UART)
uart:
  rx_pin: GPIO16
  tx_pin: GPIO17
  baud_rate: 9600

sensor:
  - platform: pzem004t
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"
YAML
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz

rbamp:
  id: meter1
  address: 0x50
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Одинаковые поля name: дают одинаковые entity ID в HA. История панели энергии сохраняется при замене: датчик total_increasing продолжает с того места, где остановился. Удалите блок uart:, если он не используется другим компонентом.

Из cse7766 (Sonoff POW R2)

Тот же шаблон. cse7766 даёт voltage, current, power, energy, power_factor, apparent_power — все они есть в rbamp. Замените platform: cse7766 на platform: rbamp, добавьте rbamp_id: meter1, удалите uart: и добавьте i2c: и блок rbamp:.


21 · Модуль STANDARD — итоги энергии на устройстве

На модуле STANDARD компонент накапливает собственные счётчики энергии модуля. Суммы переживают перезапуски и ESP32, и модуля и остаются монотонными. Тот же YAML работает и на модуле BASIC, за исключением того, что ключи суммарного итога там никогда не публикуются.

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 30s
  bidirectional: true          # per-channel energy_exported
  start_current_ua: 400        # no energy counted below 400 µA per channel

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy_total:
      name: "Energy Imported"          # all channels, total_increasing
    energy_exported_total:
      name: "Energy Exported"          # all channels, total_increasing
    energy_net:
      name: "Energy Net"               # import - export, may decrease
    reactive_energy:
      name: "Reactive Energy Imported" # varh
    reactive_energy_exported:
      name: "Reactive Energy Exported"

Что демонстрирует: датчики суммарного итога, которым не нужна парная декларация current/voltage; start_current_ua: (0 = выкл., иначе 10..2540 с шагом 10), чтобы шум без нагрузки не попадал в счётчики импорта и экспорта (мгновенные показания не затрагиваются). Для панели энергии HA используйте energy_total как потребление из сети и energy_exported_total как возврат в сеть.


22 · Переключение номинала SCT и служебная перезапись

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010      # module was delivered with the SCT-013-030

Показания остаются точными после переключения: на прошивке модуля до 1.4.19 компонент завершает запись модели требуемым перезапуском модуля (видно в журнале) и масштабирует ток, мощность и энергию под выбранный датчик; более новая прошивка делает это на модуле. Значение, уже хранящееся в модуле, никогда не перезаписывается, а на модуле, поставленном откалиброванным вместе с собственным встроенным датчиком (sensor_class: WIRED_CT / BUILTIN_CT), изменение отклоняется с записью в журнал. Только для осознанного повторного применения пресета:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010
  ct_model_force: true       # one-off service option; remove both lines afterwards

Сводка правил валидации YAML

Правило Обеспечивается
power / energy / power_factor / reactive_power требуют current Валидатор схемы (_SINGLE_SLOT_DEPS)
P/Q/PF/E для любого канала требуют voltage Валидатор схемы
Одиночные и фазовые группы не смешиваются в одном sensor: _validate_topology_consistency
new_address ≠ address _validate_new_address
address в диапазоне 0x08..0x77 cv.i2c_address
update_interval, минимум 1s, соблюдается Валидатор схемы
latch_interval ≥ update_interval Валидатор схемы
ct_model: и ct_models: взаимно исключают друг друга Валидатор схемы
ct_models: содержит 1..16 записей Валидатор схемы
ct_model_force: true требует ct_model: или ct_models: Валидатор схемы
start_current_ua — это 0 или 10..2540 с шагом 10 Валидатор схемы
Код модели CT допустим для закреплённого sensor_class Валидатор схемы

Ошибки валидации выводятся при esphome compile с понятным сообщением, указывающим на проблемный ключ. Прошивать железо, чтобы найти ошибку конфигурации, не нужно.


Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/06_examples.md (v1.9.1)