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

02 · Уровни модулей

Две линейки модулей rbAmp, BASIC и STANDARD (STD), и где энергия вычисляется в каждой.

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 (мастер читает накопительные счётчики модуля).

Матрица возможностей

Возможность 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).

YAML
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: — закрепить семейство датчиков

YAML
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

Один общий профиль для всех каналов:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Или профиль по каналам (для UI3 со смешанными клещами):

YAML
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-адреса

YAML
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: — синхронный снимок для шины с несколькими модулями

YAML
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: — подсказка топологии

YAML
rbamp:
  id: meter1
  topology: SINGLE      # SINGLE / SPLIT_PHASE / THREE_PHASE

Необязательно и не нужно на модулях STANDARD, где число каналов и вариант берутся из самого модуля. На модулях BASIC компонент выводит число каналов из объявленных слотов датчиков (если объявлен current_1, каналов как минимум 2). Ключ косметический и попадает в строку лога dump_config.

drdy_pin: — необязательное прерывание готовности данных

YAML
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)