02 · Уровни модулей
rbAmp выпускается в двух линейках модулей: BASIC и STANDARD (STD). Каждый уровень — полная комбинация ревизии аппаратуры и сборки прошивки, а не просто флаг в прошивке. Переход между уровнями требует физической замены модуля, а не обновления прошивки.
Компонент ESPHome работает с обеими линейками модулей из одного YAML: схема общая, а компонент сам определяет подключённую линейку (BASIC или STANDARD (STD)) при загрузке. Различия — в том, какие данные модуль реально экспортирует и какие ключи YAML имеют смысл на каждой линейке.
Уровни
BASIC — базовый уровень
Прошивка сохраняет однонаправленный учёт потребления: средняя активная мощность за период никогда не бывает отрицательной — обратные участки внутри окна обнуляются до интегрирования. По поведению это напоминает классический механический дисковый счётчик.
- Энергия интегрируется на ESP32 из средней мощности периода, которую модуль возвращает после каждого снимка, и сохраняется во флеш ESP32 (NVS).
- Датчик
energy_exportedсуществует в схеме YAML (для совместимости конфигурации), но на BASIC он всегда публикует0. - Датчики суммарной энергии (
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported) проходят валидацию, но на BASIC никогда не публикуются. - Типичные применения: квартиры без собственной генерации, субучёт отдельных нагрузок (водонагреватели, двигатели, бытовая техника, HVAC).
STANDARD (STD) — двунаправленный, энергия на устройстве
STANDARD (STD) — текущая линейка модулей. Она измеряет импорт и экспорт раздельно и хранит собственные накопительные счётчики энергии внутри модуля.
- Тот же YAML. Компонент распознаёт модуль STANDARD (STD) при загрузке и берёт число каналов, вариант и доступные функции из модуля. Уровень задавать не нужно, и
topology:не требуется. - Энергия из счётчиков модуля. Компонент накапливает счётчики модуля вместо собственного интегрирования мощности, поэтому итоги переживают перезапуски и ESP32, и модуля, остаются монотонными при перезапусках модуля и сбросах счётчиков и не дрейфуют. Значения дополнительно сохраняются во флеш ESP32 (NVS) каждые 5 минут и при чистом выключении (перезагрузка / OTA).
- Новые датчики:
energy_total,energy_exported_total,energy_net(импорт − экспорт, может уменьшаться),reactive_energy,reactive_energy_exported— общие итоги по всем каналам; на трёхвольтовых вариантах такжеvoltage_angle_b,voltage_angle_cиphase_sequence. - Энергия по каналам
energyиenergy_exported(сbidirectional: true) берутся из тех же счётчиков. start_current_ua:задаёт пусковой ток, ниже которого канал не учитывает энергию, чтобы шум без нагрузки не накапливался в счётчиках.- Типичные применения: дома с солнечной / ветровой генерацией, накопители, зарядные станции EV, любая установка, где импорт и экспорт нужно учитывать раздельно, и установки, где итоги энергии должны переживать перезапуски.
На модуле STD энергия берётся из собственных счётчиков модуля; latch_interval применяется только к BASIC.
Ключи, существующие только для линейки BASIC (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: для пути энергии на стороне мастера), игнорируются на модуле STANDARD с записью в журнал.
Матрица возможностей
| Возможность | BASIC | STANDARD |
|---|---|---|
| Действующее напряжение (RMS) | да | да |
| RMS-ток (1..3 канала, больше на вариантах с большим числом каналов) | да | да |
| Активная мощность (знаковое float) | да | да |
| Коэффициент мощности | да | да |
| Реактивная мощность (из модуля, каналы 0..2; без знака, вычисляется как √(S² − P²), включает искажения; точность не указана) | да | да |
| Полная мощность (только CH0) | да (U × I[0], вычисляется на ESP32) |
да (из модуля) |
| Частота сети | да | да |
Датчик energy (импорт Вт·ч), сохраняется в NVS |
да (встроено в ESP32) | да (из счётчиков на устройстве) |
Датчик energy_exported (нужен bidirectional: true) |
всегда 0 | да |
| Энергия переживает перезапуски ESP32 и модуля | Только ESP32 | да |
Общие итоги: energy_total, energy_exported_total, energy_net |
нет | да |
Реактивная энергия: reactive_energy, reactive_energy_exported |
нет | да |
start_current_ua: |
нет | да |
voltage_angle_b/_c, phase_sequence (варианты с тремя напряжениями) |
нет | да |
Модели ct_models: для каждого канала |
да | только если модуль хранит модели по каналам; иначе отклоняется с записью в лог |
fleet_gc_enable: / group_id: синхронизация общим вызовом (General-Call) |
да (прошивка v1.3+) | игнорируется |
Компонент читает только то, что объявлено датчиками, — необъявленный регистр никогда не запрашивается.
Ключи YAML по уровням
bidirectional: (по умолчанию false)
Включает датчики экспортной энергии по каналам (energy_exported, energy_exported_1, energy_exported_2).
rbamp:
id: solar_meter
address: 0x51
bidirectional: true # meaningful on STANDARD; on BASIC the export sensors read 0
На STANDARD экспортная энергия берётся из счётчиков модуля. На BASIC ключ схема принимает без ошибки, но energy_exported всегда возвращает 0. Датчики общих итогов energy_exported_total и energy_net этот ключ не требуют.
sensor_class: — закрепить семейство датчиков
rbamp:
id: meter1
sensor_class: SCT_013 # default SCT_013
Принимается на обеих линейках модулей. На прошивке v1.2+ значение записывается во флеш и становится обязательным условием для записи модели ТТ: модуль не запишет модель, если класс не задан. Значение, которое модуль уже имеет, повторно не записывается.
Значения перечисления: SCT_013 (разъёмные клещи SCT-013, по умолчанию), WIRED_CT и BUILTIN_CT (модули, поставляемые откалиброванными вместе с собственным встроенным датчиком). На таком модуле с заводской парой изменение класса или модели из YAML отклоняется с записью в журнал, чтобы защитить индивидуальную калибровку.
ct_model: / ct_models: — модель клипсы CT
Один общий профиль для всех каналов:
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
Или профиль по каналам (для UI3 со смешанными клещами):
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
Принимается на обеих линейках модулей, взаимно исключают друг друга. На прошивке v1.2+ модуль сам загружает заводские коэффициенты для выбранной модели — дополнительные шаги калибровки не нужны. На более ранней прошивке значение сохраняется как маркер модели.
- Переключение номинала SCT сохраняет заводскую точность: компонент завершает переключение (перезапуск модуля в процессе нормален на прошивке до 1.4.19; более новая прошивка выполняет коррекцию на модуле) и масштабирует показания под выбранный датчик.
- Защиты записи: равное значение не записывается; на модуле, поставляемом в паре, изменение отклоняется с записью в лог.
ct_model_force: true(служебная опция, допустима только вместе сct_model:/ct_models:) сознательно её обходит. - Модели
ct_models:по каналам на модуле STANDARD требуют, чтобы модуль сохранял модели по каналам; иначе компонент громко отказывает (предупреждение, ключи игнорируются) — используйтеct_model:.
Подробнее о выборе модели см. 03_sensor_selection.md.
new_address: — однократное назначение I²C-адреса
rbamp:
id: meter1
address: 0x50
new_address: 0x51 # one-shot; remove after a successful boot
Принимается на обеих линейках модулей. На прошивке v1.3+ смена адреса производственно-готова — компонент использует протокол двухфазной фиксации (подготовка → взведение → фиксация → перезагрузка) без специального режима. На устаревшей прошивке (v1.0-v1.2) однофазный откат требует режима заводской настройки; для процедуры включения обратитесь к документации модуля или поставщику. Режим заводской настройки всё ещё требуется на всех версиях прошивки для операций калибровки (saveGains) и сброса к заводским.
Ход выполнения за одну загрузку: компонент опрашивает текущий адрес, записывает новый адрес и сохраняет его во флеш, сбрасывает модуль и проверяет ответ по новому адресу. После успеха обновите YAML на address: 0x51 и удалите new_address:. Если компонент видит, что старый адрес молчит, а новый отвечает, он адаптируется автоматически с предупреждением в журнале (на случай, если предыдущая загрузка уже применила смену).
fleet_gc_enable: / group_id: — синхронный снимок для шины с несколькими модулями
rbamp:
- id: meter1
fleet_gc_enable: true # v1.3 production path — recommended
group_id: 1 # cluster id (modules in the same group snapshot together)
Если включено, компонент отправляет 5-байтный кадр общего вызова на широковещательный I²C-адрес — синхронизируя снимок периода у всех модулей с одним group_id одной транзакцией.
На прошивке v1.3 BASIC снимок общим вызовом (General-Call) — по выбору и зависит от возможностей. Компонент проверяет при загрузке, объявляет ли прошивка эту функцию, и включает путь автоматически, когда ключ YAML и прошивка совпадают. На старой прошивке (v1.0..v1.2) она не объявляется; компонент переходит к последовательному снимку для каждого модуля отдельно и пишет информационную строку в лог. На модуле STANDARD эти ключи игнорируются с записью в лог.
Устаревший ключ broadcast_latch: всё ещё принимается схемой для обратной совместимости, но не действует. Используйте fleet_gc_enable: + group_id:.
Перекос между модулями на шине 50 кГц составляет порядка ~540 мкс × N, что меньше 0.003% периода 60 секунд. На суточных итогах HA эта неравномерность незаметна.
topology: — подсказка топологии
rbamp:
id: meter1
topology: SINGLE # SINGLE / SPLIT_PHASE / THREE_PHASE
Необязательно и не нужно на модулях STANDARD, где число каналов и вариант берутся из самого модуля. На модулях BASIC компонент выводит число каналов из объявленных слотов датчиков (если объявлен current_1, каналов как минимум 2). Ключ косметический и попадает в строку лога dump_config.
drdy_pin: — необязательное прерывание готовности данных
rbamp:
id: meter1
drdy_pin: GPIO15
Принимается на обеих линейках модулей. Подключается к необязательному выходу DRDY с открытым стоком. Пин настраивается и записывается в журнал, но мгновенные регистры опрашиваются по update_interval независимо от него. При типичном update_interval: 60s ключ можно опустить.
Нужен подтягивающий резистор 10 кОм на GPIO мастера к 3.3 В (выход с открытым стоком; внутреннего подтягивания на стороне модуля нет). См. 04_hardware.md.
Сводная таблица — ключ YAML × линейка модулей
| Ключ YAML | BASIC | STANDARD | Примечания |
|---|---|---|---|
address: |
да | да | — |
update_interval: |
да | да | Минимум 1s |
latch_interval: |
да | n/a | Отделяет цикл снимков/энергии от цикла чтения; STANDARD читает свои счётчики при каждом update() |
drdy_pin: |
да | да | Необязательно, нужна подтяжка 10 kΩ; не используется как триггер чтения |
topology: |
да | не нужно | Информационная подсказка |
sensor_class: |
да | да | Не перезаписывается при равенстве; отклоняется на модулях, поставляемых в паре |
ct_model: / ct_models: |
да | да | Взаимно исключают друг друга; список по каналам на STANDARD требует модуля, который его хранит |
ct_model_force: |
да | да | Опция службы; схема требует ключ модели |
bidirectional: |
принимается (экспорт показывает 0) | работает | Нужно для поканальных датчиков energy_exported* |
start_current_ua: |
игнорируется с предупреждением | работает | 0 или 10..2540 с шагом 10 |
new_address: |
да | да | Production-OK на прошивке v1.3+ BASIC; однократно |
fleet_gc_enable: / group_id: / broadcast_latch: |
да | игнорируется | Синхронизация общим вызовом (General-Call) — функция линейки BASIC |
Датчик energy_exported |
всегда 0 | работает | Нужен bidirectional: true |
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] |
никогда не публиковать | работает | Общие итоги с собственных счётчиков устройства |
voltage_angle_b/_c, phase_sequence |
никогда не публиковать | работает на трёхвольтовых вариантах с прошивкой, которая их предоставляет | См. 09 §2.2–2.3 |
Фазовые датчики (voltage_a/b/c, current_a/b/c, …) |
нет значений | публиковать для каналов, которые сообщает модуль | Подробнее в 09 §2.2 |
Что дальше
- 03_sensor_selection.md — выбор токовых клещей и поведение
ct_model:/ct_models: - 04_hardware.md — физический монтаж, выбор GPIO
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/02_tiers.md (v1.9.1)