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Ω).
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)
[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_intervalESP32 отправляет кадр 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)
# 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:
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
Что происходит при загрузке:
[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 — все модули должны быть обнаружены:
[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-модели на разных каналах одного модуля можно смешивать в соответствии с характером нагрузки. Компонент привязывает каналы по одному; порядок не важен.
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 при загрузке
После прошивки и загрузки в логе:
[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)
При тёплой загрузке (зеркала совпадают) без записи во флеш:
[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 должен совпадать с суммой мощностей вспомогательных счётчиков с точностью до одного периода).
# 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 итераций)
[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 узла.
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
Простейшая полезная конфигурация: один канал напряжения, один канал тока и шесть производных величин из них. Отправная точка для любого нового развёртывания — при необходимости расширяйте дополнительными полями.
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, здесь работает точно так же. Пример показывает самые частые настройки в одном блоке:
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 один вход напряжения и три независимых канала тока. Каноничный сценарий — ставить разные модели клипс на разные каналы: маленькую клипсу на слабопотребляющие нагрузки (для максимального разрешения) и большую на главный ввод (запас по пиковым нагрузкам).
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).
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.
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. Чтобы разместить несколько модулей на одной шине, перепрошейте каждый на собственный уникальный адрес до параллельного подключения.
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 заставляет компонент выполнить процедуру один раз при загрузке:
-
Опросите
0x50. Если0x50молчит, а0x51уже отвечает, смена была применена при предыдущей загрузке; компонент адаптируется и пишет предупреждение с просьбой очистить YAML. -
Проверьте, что модуль готов принять операцию провизионирования.
-
Запишите новый адрес во флеш (~700 мс), мягкий сброс (~300 мс) и повторная синхронизация с циклом переменного тока.
-
Подтвердите новый адрес. При успехе — строка в логе
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 штатно, а процедура смены больше не выполняется.
Контрольный список отката после успешного провизионирования
Чтобы не оставлять «висящий» вариант настройки в репозитории (две альтернативы, никогда не вставляйте оба в один файл):
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# 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
Ровно три правки:
- Измените значение
address:со старого на новое. - Удалите (не комментируйте) строку
new_address:. - Перепрошейте по 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 из системы контроля версий.
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/, не отслеживается):
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.
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 узла.
# 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 не нужен.
После обнаружения:
- Настройки → Дашборды → Энергия.
-
Добавьте потребление → выберите «Mains Energy» (или сущность учёта импорта, которую хотите).
-
Если у вас солнечная станция — Add Production → выберите Solar Energy (из
meter_solarв примере с несколькими модулями).
Значения энергии в Вт·ч. HA сам переводит их в кВт·ч для отображения. Сохранение в NVS в компоненте гарантирует, что накопитель переживает перезагрузку ESP32 без ложного «сброса счётчика» в статистике HA.
# 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
8.8 Поток событий по порогам — запись порога → срабатывание → сброс W1C (api-reference)
Сброс нагрузки: реле выключается при превышении порога
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в 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 узла.
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 узла.
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 узла.
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 узла.
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 узла.
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 узла.
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 узла.
# 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 узла.
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 узла.
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 узла.
# 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 + реле — управление с обратной связью
Бойлер с управлением реле
# 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: с идентификатором, использованным ниже.
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).
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:.
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, для основных величин переменного тока. Замена — блок-в-блок с одинаковыми именами датчиков:
# 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"
# 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, за исключением того, что ключи суммарного итога там никогда не публикуются.
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 и служебная перезапись
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), изменение отклоняется с записью в журнал. Только для осознанного повторного применения пресета:
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)