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

09 · Справочник схемы YAML

Карта регистров rbAmp — адресное пространство страницы 0 (0x00..0xFF)

Атомарный снимок периода — одна запись закрывает период и открывает следующий

Эта глава — полный справочник по схеме YAML внешнего компонента rbamp для ESPHome. Если ключа здесь нет, его нет в схеме.

Один YAML для обеих линеек модулей. При загрузке компонент определяет, какая линейка модулей подключена (BASIC или STANDARD (STD)), и адаптируется автоматически: число каналов, вариант и доступные функции берутся из самого модуля, поэтому ключ topology: и переключение уровня в YAML не нужны. Ключи, относящиеся только к одному поколению, отмечены ниже; ключ, который подключённый модуль не может выполнить, игнорируется с записью в лог, а не приводит к жёсткой ошибке.

Contents:

  1. Блок компонента — rbamp:
  2. Платформа датчиков — sensor.platform: rbamp
  3. Поток данных и тайминг
  4. Настройки шины I²C

1. Блок компонента — rbamp:

Блок верхнего уровня rbamp: регистрирует экземпляр компонента. Он наследует PollingComponent (обеспечивает update_interval) и i2c.I2CDevice (обеспечивает address и дескриптор шины I²C). MULTI_CONF: True означает, что любое число блоков rbamp: может сосуществовать в одном YAML, каждый со своим I²C-ведомым.

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  drdy_pin: GPIO4
  sensor_class: SCT_013
  ct_model: SCT_013_030
  # or, for a UI3 with mixed clamps:
  # ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  bidirectional: false
  new_address: 0x51
  fleet_gc_enable: false
  group_id: 0
  latch_interval: 60s
  start_current_ua: 400     # STANDARD only, see below
  # ct_model_force: true    # service option, see below

Каждый ключ необязателен. topology: и broadcast_latch: по-прежнему принимаются для обратной совместимости (см. их записи).


id

Атрибут Значение
Тип id (идентификатор ESPHome)
По умолчанию Генерируется автоматически
Обязательно Нет

Присваивает стабильный идентификатор экземпляру. Датчики ссылаются на него через rbamp_id: meter1. При нескольких блоках rbamp: явный id обязателен.

YAML
rbamp:
  id: kitchen_meter

address

Атрибут Значение
Тип i2c_address (7-битный, 0x08..0x77)
По умолчанию 0x50
Обязательно Нет

Текущий I²C-адрес модуля rbAmp. Заводской адрес по умолчанию — 0x50. После смены адреса (через new_address) обновите этот ключ на новое значение и удалите new_address.

Допустимый диапазон: 0x08..0x77 (зарезервированные 7-битные адреса I²C исключены).

YAML
rbamp:
  address: 0x52   # three modules on the bus: 0x50, 0x51, 0x52

Перекрёстная ссылка: протокол шины I²C в справочнике API; смена адреса во время работы — для смены адреса после загрузки.


update_interval

Атрибут Значение
Тип time (строка длительности ESPHome)
По умолчанию 60s
Обязательно Нет

Как часто выполняется update(). Каждый вызов:

  1. Отправляет команду снимка и запускает неблокирующий таймаут 50 мс для чтения снимка периода (модули BASIC; на модулях STANDARD энергия берётся из собственных счётчиков модуля, см. energy_total).
  2. Проверяет регистр состояния; если модуль готов, публикует все привязанные датчики мгновенных значений.

Значение по умолчанию 60 с разумно: модуль внутри обновляет среднюю мощность периода примерно каждые ~100 мс, но интеграция энергии на стороне мастера требует достаточно длинного окна для корректности. При 60 с и средней нагрузке 60 Вт пропущенный снимок теряет ≤ 1 Вт·ч.

Минимально допустимое значение — 1s: схема отклоняет меньшие значения, а esphome config выдаёт диагностику. Значения ниже 5–10 с не дают выгоды для жёсткой синхронизации и лишь засоряют шину.

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

Атрибут Значение
Тип time (строка длительности ESPHome)
По умолчанию То же, что update_interval
Обязательно Нет
С v1.4

Как часто компонент отправляет команду снимка и интегрирует выборку в Вт·ч. Если задано, цикл снимков отделяется от частоты чтения RT-данных — update_interval: по-прежнему управляет тем, как часто регистры V/I/P/PF/Q читаются и публикуются, а latch_interval: управляет тем, как часто накопитель периода снимается и интегрируется Вт·ч.

Интеграция энергии не добавляет собственной погрешности сверх точности активной мощности модуля, независимо от соотношения: интеграция на стороне мастера использует реальный dt по часам между соседними событиями снимка, поэтому более длинные интервалы снимков дают лишь более грубые шаги интеграции.

Должно быть >= update_interval (короче — отклоняется при проверке конфигурации: лишние снимки не дали бы наблюдаемых данных).

Если не задано, снимок выполняется при каждом вызове update() (поведение v1.3 с одним циклом, обратно совместимое).

YAML
rbamp:
  update_interval: 3s        # RT V/I/P/PF refreshed every 3 s
  latch_interval: 60s        # snapshot + Wh integration once a minute

Полезно, когда важны загрузка шины или конкуренция за CPU на стороне мастера — парки из нескольких модулей, хосты ESP8266 (одноядерные; ISR Wi-Fi конкурируют за CPU во время транзакций I²C) или общие шины I²C с другими устройствами.


drdy_pin

Атрибут Значение
Тип gpio_input_pin_schema
По умолчанию Нет (необязательно)
Обязательно Нет

Подключает выход DRDY модуля с открытым стоком к GPIO ESP32. При указании пин настраивается в setup() при загрузке.

Примечание

Пин записывается в dump_config, но не используется как триггер чтения — мгновенные регистры опрашиваются по update_interval. Объявление пина поведение не меняет.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

Атрибут Значение
Тип enum (SCT_013, WIRED_CT, BUILTIN_CT)
По умолчанию SCT_013
Обязательно Нет

Фиксирует семейство токовых датчиков на стороне модуля. На прошивке v1.2+ значение записывается во флеш и становится обязательным условием для записи модели ТТ: модуль откажется записать модель, если класс не задан. На более ранних прошивках значение принимается схемой и применяется автоматически при обновлении.

Значение Значение
SCT_013 Разъёмные клипсы SCT-013 — по умолчанию
WIRED_CT Модуль поставляется откалиброванным вместе со своим установленным датчиком
BUILTIN_CT Модуль, поставленный откалиброванным вместе с собственным встроенным датчиком

Защита записи. Компонент никогда не записывает класс, который модуль уже имеет (повторная загрузка ничего не записывает). На модуле, откалиброванном в паре со своим установленным датчиком (WIRED_CT / BUILTIN_CT), изменение класса или модели из YAML отклоняется с явной записью в лог — запись заменила бы индивидуальную калибровку общей настройкой. Оставьте sensor_class: и ct_model: вне YAML для таких модулей или см. ct_model_force.

YAML
rbamp:
  sensor_class: SCT_013   # default; may be omitted

Подробнее о выборе клещей и семейства см. 03_sensor_selection.md.


ct_model

Атрибут Значение
Тип enum (SCT_013_005, _010, _020, _030, _050)
По умолчанию Нет (необязательно)
Обязательно Нет

Записывает идентификатор модели токовых клещей во флеш модуля. На прошивке v1.2+ это автоматически загружает заводские коэффициенты выбранной модели — дополнительных шагов калибровки не требуется. Значение, равное уже имеющемуся в модуле, не записывается.

Значение в YAML Код Номинальный ток Статус v1.3
SCT_013_005 1 5 A production
SCT_013_010 2 10 A production
SCT_013_020 6 20 A производственный (новое в v1.3)
SCT_013_030 3 30 A production (артикул по умолчанию)
SCT_013_050 4 50 A production
Примечание

Набор допустимых значений для каждого класса SCT_013 — {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 — код 5, SCT_013_060 — код 7; порядок кодов не совпадает с порядком номиналов). Недопустимые значения отклоняются при esphome config через cv.Invalid. Подробнее — в 03 · Выбор токового датчика.

YAML
rbamp:
  ct_model: SCT_013_030

Применяется однократно в setup(). Каждая запись сопровождается записью во флеш ~700 мс (модуль отвечает NACK на все операции I²C в это время — компонент автоматически подаёт сигнал сторожевому таймеру).

Смена номинала SCT сохраняет точность. Каждый модуль SCT откалиброван на заводе под SCT-013-030. При выборе другого номинала ток, мощность и энергия остаются верными: на прошивке до 1.4.19 компонент завершает запись модели перезапуском модуля (это часть обычного процесса и видно в журнале), затем масштабирует показания под выбранный датчик; более новая прошивка делает переключение на самом модуле, и компонент не меняет показания. Напряжение и коэффициент мощности не затрагиваются. Изменений YAML для этого не требуется.

Защита записи. Равное значение никогда не записывается; на модуле с заводской парой (sensor_class: WIRED_CT / BUILTIN_CT) запись отклоняется с записью в журнале — см. sensor_class.

Взаимно исключают ct_models: — в одном блоке rbamp: можно использовать только один из двух.

Подробнее см. 03_sensor_selection.md. Перекрёстная ссылка: справочник ct_model.


ct_models

Атрибут Значение
Тип список из 1–16 значений перечисления
По умолчанию Нет (необязательно)
Обязательно Нет

Модели токовых клещей по каналам — для модулей со смешанными клещами на разных каналах. Принимает те же значения перечисления, что и ct_model:. Схема принимает от 1 до 16 записей; позиция в списке — индекс канала. Компонент применяет столько записей, сколько каналов у модуля (1 для UI1, 2 для UI2, 3 для UI3 и т. д.); лишние записи игнорируются с предупреждением.

YAML
rbamp:
  id: ui3_meter
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  # CH0=5A for standby loads (maximum resolution),
  # CH1=30A for main household loads,
  # CH2=20A for a water heater / medium-power branch (~3-5 kW)
  # For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)

На прошивке v1.2+ каждый канал получает собственный набор заводских коэффициентов независимо. Общее время настройки при загрузке ~2–3 секунды (~700 мс записи во флеш на канал).

Модули STANDARD. Модели по каналам сохраняют только модули, которые объявляют постоянное хранение по каналам. На модуле, который этого не делает, компонент громко отказывает (предупреждение, что ct_models: не поддерживается этим устройством, ключи игнорируются), вместо того чтобы записать значение, которое тихо откатится после отключения питания, — используйте там одиночный ct_model:.

Применяются те же защиты записи, что и для ct_model: (равные значения не записываются; модули, поставляемые в паре, отклоняют изменение).

Взаимно исключает ct_model:.


ct_model_force

Атрибут Значение
Тип bool
По умолчанию false
Обязательно Нет

Опция службы. Переопределяет защиту записи: компонент применяет пресет ct_model: / ct_models: даже если модуль имеет заводскую пару или уже хранит то же значение. Это заменяет индивидуальную калибровку модуля общим пресетом для этой модели, поэтому используйте осознанно, выполните один раз и удалите.

Схема отклоняет ct_model_force: true, если не задан также ct_model: или ct_models:, поэтому флаг не может висеть в YAML в ожидании более позднего выбора модели.

YAML
rbamp:
  ct_model: SCT_013_030
  ct_model_force: true   # one-off; remove both lines after the operation

start_current_ua

Атрибут Значение
Тип целое, микроамперы
Допустимые значения 0 (выкл.) или 10..2540 с шагом 10
По умолчанию Нет (действует значение модуля по умолчанию)
Обязательно Нет
Относится к Модули STANDARD со счётчиками энергии на устройстве; в других случаях игнорируются с предупреждением

Пусковой ток для учёта энергии. Пока ток канала ниже этого значения, модуль не учитывает энергию по этому каналу. Без него при нулевой нагрузке измеренная мощность — шум любого знака, который медленно попадает и в счётчик импорта, и в счётчик экспорта. Мгновенные показания (ток, мощность, ...) не затрагиваются — только счётчики энергии.

Значения вне допустимого набора (например, 15 или 3000) отклоняются схемой, поэтому недопустимое значение не попадает на шину. Настройка хранится в модуле и проверяется после записи; значение, равное сохранённому, не записывается повторно.

YAML
rbamp:
  start_current_ua: 400

Сохранённое значение можно прочитать из lambda через id(meter1).read_start_current_ua() (возвращает 65535, если недоступно).


period_banks

Атрибут Значение
Тип список записей банка
Записей в списке 1..8, каждый bank: (0..7) указан один раз
По умолчанию Нет
Обязательно Нет
Относится к Модули STANDARD, которые объявляют банки снимков (образ 0x7E и новее); на любом другом модуле записи остаются недоступными, а лог сообщает об этом один раз при загрузке

Модуль хранит восемь независимых банков снимков. Каждая запись измеряет один период — время между двумя фиксациями одного банка, отсчитанное по часам ESP32, — и публикует средние значения периода, пики и энергию. Используйте для «энергии за час», «пикового тока с последнего нажатия» и подобных вопросов, на которые не отвечают суммарные итоги.

Ключ Значение
bank Номер банка 0..7. Банк 0 свободен на модулях со счётчиками энергии на устройстве; на модуле без счётчиков компонент использует сам банк 0, а запись игнорируется с предупреждением.
interval Необязательный автоматический цикл фиксации, не менее 1s. Без него банк фиксируется только действием rbamp.latch_bank.
power, reactive_power, apparent_power Среднее за период.
energy, energy_exported Вт·ч импортировано / экспортировано за период (не счётчики — у них state_class: measurement).
max_power, max_current, max_voltage, min_voltage Экстремумы внутри периода.
period_length Длина периода в секундах, как измерено ESP32.
channels Необязательный список, по одной записи на канал тока (первая запись = канал 0), каждая с power, energy, energy_exported.

Первая фиксация банка после загрузки или перезапуска модуля только запускает период; её значения отбрасываются, а датчики публикуют начиная со следующей фиксации. Фиксации разных банков разделены не менее чем 150 мс.

YAML
rbamp:
  id: meter1
  period_banks:
    - bank: 1
      interval: 1h
      power: {name: "Hour average power"}
      energy: {name: "Hour energy"}
      max_current: {name: "Hour peak current"}
    - bank: 2                    # latched by hand
      energy: {name: "Energy since last press"}
      period_length: {name: "Since last press, s"}

button:
  - platform: template
    name: "Latch bank 2"
    on_press:
      - rbamp.latch_bank:
          id: meter1
          bank: 2

Полный пример: example/std_banks.yaml.


bidirectional

Атрибут Значение
Тип bool
По умолчанию false
Обязательно Нет

Включает путь учёта энергии выдачи по каналам (energy_exported, energy_exported_1, energy_exported_2). При true энергия выдачи накапливается отдельно от энергии потребления.

На модуле STANDARD энергия экспорта берётся из собственных счётчиков модуля, поэтому переживает перезапуски и монотонна. На модуле BASIC линия однонаправленная: датчики energy_exported_* принимаются схемой, но публикуют 0.

Объявляйте energy_exported (или _1 / _2) в sensor.platform: rbamp только при bidirectional: true. Датчики общих итогов energy_exported_total и energy_net этот ключ не требуют.

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

Атрибут Значение
Тип i2c_address (0x08..0x77)
По умолчанию Нет (необязательно)
Обязательно Нет

Запускает однократную смену адреса I²C при загрузке. Он должен отличаться от address — валидатор выдаёт ошибку при равенстве.

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

Прошивка Поведение
Объявляет двухфазную фиксацию адреса (v1.3+) Производственный путь — подготовленная запись, явное подтверждение, фиксация, повторное перечисление.
Не объявляет (устаревшая v1.0–v1.2) Устаревший путь — однофазная запись, требует режима заводской настройки. Записывает WARN_FACTORY_MODE_REQUIRED, если модуль не в режиме provisioning.

Модули STANDARD тоже поддерживают new_address:; компонент применяет его и переподключается к новому адресу так же.

Полный поток выполняется один раз в setup():

  1. Опросите текущий address. Если модуль там не отвечает, но отвечает по new_address, компонент адаптируется к новому адресу с предупреждением (предполагая, что предыдущая загрузка уже применила изменение) и пропускает запись.
  2. Проверьте, объявляет ли прошивка двухфазную фиксацию. Да → производственный путь (см. ниже). Нет → устаревший путь с проверкой режима provisioning.
  3. Производственный путь (v1.3): подготовьте новый адрес, подтвердите, зафиксируйте → подождите ~700 мс → повторно опросите new_address. Проверка заводского режима не требуется.
  4. Устаревший путь (v1.0–v1.2): однофазная запись, требуется режим заводского провизионирования на стороне модуля.
  5. Компонент переключает свой внутренний I²C-адрес через i2c::I2CDevice::set_i2c_address() на new_address и проверяет, что модуль отвечает.
  6. Если модуль не отвечает после смены, компонент вызывает mark_failed() и останавливается.

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

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

⚠ Только в заводском режиме на устаревшей прошивке (v1.0-v1.2).

Серийные модули на устаревшей прошивке поставлялись с отключённым режимом provisioning. Запись new_address: в такой модуль без заводского режима будет отклонена (предупреждение WARN_FACTORY_MODE_REQUIRED). На прошивке v1.3 это ограничение снято — компонент сам определяет путь для серийных модулей.

⚠ Повторное перечисление после фиксации. После успешной фиксации модуль сбрасывается и заново перечисляется на новом адресе. Последующие вызовы в том же setup() прозрачно направляются на новый адрес, но любой другой мастер на шине (сырой инструмент I²C, отладочный зонд, другой ESP32) по-прежнему считает модуль на старом адресе, пока не обновит своё состояние.

YAML
rbamp:
  address: 0x50
  new_address: 0x51   # remove this line after the first successful boot

Восстановление: если смена адреса применена, но модуль не отвечает, см. 10_troubleshooting.md → «Address changed, but the module doesn't respond».

Перекрёстная ссылка: справочник по смене адреса во время работы.


fleet_gc_enable (v1.3, НОВОЕ)

Атрибут Значение
Тип bool
По умолчанию false
Обязательно Нет
Относится к Модули BASIC с поддержкой снимка общим вызовом (прошивка v1.3+); на STANDARD игнорируется с записью в лог

Включается по выбору: разрешает приём широковещательного снимка General-Call от мастера. Когда ESP32 отправляет 5-байтный кадр GC на адрес 0x00, все модули с fleet_gc_enable: true (и совпадающим group_id:) атомарно фиксируют накопители периода в один момент на проводе. Это обеспечивает жёсткую синхронизацию между субсчётчиками.

Поведение по возможностям: при загрузке компонент проверяет, объявляет ли прошивка снимок общим вызовом. Если нет → предупреждение + пропуск без применения:

Text
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).

Сохранение: при применении компонент записывает REG_FLEET_CONFIG.bit0, сохраняет во флеш через CMD_SAVE_USER_CONFIG и СБРАСЫВАЕТ устройство — режим GC задаётся при инициализации, переключить его на лету нельзя. При чтении-сравнении-записи это происходит один раз при первой загрузке; при последующих загрузках пропускается.

YAML
rbamp:
  - id: mains
    fleet_gc_enable: true     # opt-in, capability-gated
    group_id: 1               # see below
  - id: boiler
    fleet_gc_enable: true
    group_id: 1               # same group → synchronized

Перекрёстная ссылка: справочник Fleet Group-Commit, 04_hardware.md, раздел Multi-module fleet.


group_id (v1.3, НОВОЕ)

Атрибут Значение
Тип uint8_t (0..255)
По умолчанию 0
Обязательно Нет
Относится к модули BASIC; на STANDARD игнорируются с записью в журнал

Идентификатор кластера для выборочного снимка GC. Модуль принимает кадр GC, только если поле группы в кадре совпадает с этим group_id, ИЛИ равно 0x00 (общий вызов).

Сценарии использования:

  • Многопользовательский режим: один ESP32 управляет несколькими независимыми кластерами модулей (например, 3 квартиры в одном щитке). Кластер 1 = group_id: 1, кластер 2 = group_id: 2. Мастер отправляет кадр GC с group=1 → снимок делает только кластер 1.

  • Один абонент: оставьте group_id: 0 (общий вызов) или задайте group_id: 1 как метку — поведение одинаковое, все модули снимают снимок.

Сохранение: записывается в REG_GROUP_ID и сохраняется во флеш через чтение-сравнение-запись. Изменение требует загрузки.

YAML
rbamp:
  - id: apt1_mains
    group_id: 1
  - id: apt2_mains
    group_id: 2

broadcast_latch (устарел, legacy v0.4.0)

Атрибут Значение
Тип bool
По умолчанию false
Обязательно Нет
Статус Устарело — заменено на fleet_gc_enable: (v1.3+).

Устаревший псевдоним широковещательного снимка General-Call. В v1.3 схема принимает этот ключ как пустую операцию (для беспроблемной миграции с YAML v0.4.0), но он не действует. Для нового кода используйте fleet_gc_enable: — он работает по возможностям и поддерживается на прошивке v1.3.

Она будет удалена в одном из будущих минорных релизов; в логе появится предупреждение об устаревании:

Text
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.

Перекрёстная ссылка: справочник Fleet Group-Commit.


topology

Атрибут Значение
Тип enum (SINGLE, SPLIT_PHASE, THREE_PHASE)
По умолчанию SINGLE
Обязательно Нет

Необязательная подсказка, сохранена для обратной совместимости. На модулях STANDARD она не нужна: компонент сам считывает число каналов, вариант и возможности из модуля и по ним формирует набор сущностей. На модулях BASIC число каналов выводится из объявленных вами слотов current[_1/_2], а topology: меняет только строку, которую печатает dump_config.

YAML
rbamp:
  topology: SINGLE         # cosmetic; may be omitted

2. Платформа датчиков — sensor.platform: rbamp

Каждый блок sensor: объявляет набор именованных датчиков, привязанных к родительскому компоненту rbamp:. Единственный обязательный ключ в блоке — rbamp_id.

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

Все поля в блоке sensor: необязательны, с одним правилом: power, energy, power_factor, reactive_power и apparent_power требуют, чтобы voltage И current были объявлены в том же блоке (пронумерованные датчики каналов power_N, energy_N, power_factor_N, reactive_power_N требуют current_N и voltage); иначе esphome config завершится с ошибкой «power requires current to also be declared». Добавьте internal: true к обязательному датчику, который не должен быть сущностью Home Assistant. Объявляйте только величины, нужные вашему сценарию: компонент читает только те регистры, которые соответствуют объявленным датчикам.

rbamp_id

Атрибут Значение
Тип use_id(RbAmpComponent)
Обязательно Да

Ссылается на блок rbamp:, к которому привязана эта группа датчиков.


2.1 Одиночные поля

Используется для модулей одного напряжения (UI1, UI2, UI3, I1, I2, I3 и варианты с большим числом каналов). Все поля необязательны. Смешивание с фазовыми полями (voltage_a, voltage_angle_b и т. д.) вызывает ошибку проверки.

Слоты есть для до семи каналов тока: current и current_1 ... current_6, а также power, energy и power_factor с такими же суффиксами (power_3, energy_5, ...). energy_exported есть для каналов 0..2 (energy_exported, energy_exported_1, energy_exported_2). Слот сверх числа каналов, которое сообщает модуль, никогда не публикуется. reactive_power есть только для каналов 0..2 (reactive_power, reactive_power_1, reactive_power_2); reactive_power_3 ... reactive_power_6 схема принимает, но они никогда не публикуются.

Каждое поле принимает стандартные подключи ESPHome sensor.sensor_schema: name, id, filters, unit_of_measurement, accuracy_decimals, icon и так далее.

voltage

Атрибут Значение
Единица V
device_class voltage
state_class measurement
accuracy_decimals 1
Источник Сетевое напряжение RMS (мгновенный регистр модуля)

Среднеквадратичное (RMS) сетевое напряжение. Читается при каждом update() после готовности модуля. 4-байтовое значение float читается с повтором для каждого байта (3 попытки × 5 мс) и проходит проверку std::isfinite() плюс |val| < 10000.

Ноль — допустимое значение для публикации: событие пропадания сети или просадки даёт U ≈ 0 В и передаётся в HA без фильтрации — санитарный фильтр отбрасывает только NaN/Inf, но не законные нули.

YAML
voltage:
  name: "Mains Voltage"
  filters:
    - sliding_window_moving_average:
        window_size: 3
        send_every: 1

current / current_1 ... current_6

Атрибут Значение
Единица A
device_class current
state_class measurement
accuracy_decimals 3

RMS-ток для каналов 0, 1, 2, ... Канал 0 — главная клипса CT; каналы 1 и 2 есть на вариантах UI2 / UI3 и I2 / I3, каналы 3..6 — на вариантах с большим числом каналов.

На модуле BASIC число активных каналов выводится из количества объявленных слотов: если объявлен только current, компонент использует 1 канал; с current и current_1 — 2; добавление current_2 даёт 3. На модуле STANDARD число каналов берётся из самого модуля; объявленные сверх него слоты просто не публикуются.

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

Атрибут Значение
Единица W
device_class power
state_class measurement
accuracy_decimals 1
Зависимости power требует current + voltage; power_N требует current_N + voltage

Активная мощность в ваттах, со знаком. Отрицательные значения = обратный поток (генерация в сеть) на модулях STANDARD. На BASIC отрицательные мгновенные значения внутри окна периода на уровне прошивки ограничиваются значением 0 — средняя за период мощность ≥ 0. Мгновенная активная мощность в момент генерации может всё же показывать отрицательное значение.

Объявление power без current + voltage вызывает ошибку валидации: power requires current to also be declared.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

Атрибут Значение
Единица Вт·ч
device_class energy
state_class total_increasing
accuracy_decimals 3
Зависимости energy требует current + voltage; energy_N требует current_N + voltage

Накопленная потреблённая (импортная) энергия в Вт·ч для канала.

  • Модули STANDARD — компонент накапливает собственные счётчики энергии модуля. Итоги переживают перезапуски и ESP32, и модуля и монотонны (не откатываются назад при перезапуске модуля или сбросе счётчика).
  • Модули BASIC — вычисляются на ESP32 из средней мощности периода, которую модуль возвращает после каждого снимка:
Text
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600

В обоих случаях значение сохраняется во флеш ESP32 (NVS) каждые 5 минут и при чистом выключении (перезагрузка / OTA), а при загрузке восстанавливается до первого publish_state — это не даёт панели Energy в HA принять мгновенный 0 за сброс счётчика. На BASIC внезапное отключение питания теряет не более последних 5 минут энергии (≈ 5 Вт·ч при средней нагрузке 60 Вт). При изменении разметки NVS (повышение версии) счётчик начинается с 0.

state_class: total_increasing обязателен для панели Energy в HA. Значение растёт монотонно и при нормальной работе не уменьшается.

YAML
energy:
  name: "Mains Energy"

energy_exported / energy_exported_1 / energy_exported_2

Атрибут Значение
Единица Вт·ч
device_class energy
state_class total_increasing
accuracy_decimals 3
Зависимости Требует current + voltage + bidirectional: true

Экспортная (генерационная) энергия в Вт·ч для каналов 0..2, накапливаемая отдельно от energy. Задайте bidirectional: true в блоке rbamp: при объявлении этих датчиков. На модулях STANDARD значения берутся из счётчиков модуля (постоянные, монотонные). На модулях BASIC датчики принимаются, но публикуют 0.

power_factor / power_factor_1 ... power_factor_6

Атрибут Значение
Единица (dimensionless)
device_class power_factor
state_class measurement
accuracy_decimals 3
Зависимости Требует current + voltage для соответствующего слота

Коэффициент мощности в диапазоне −1..+1. Отрицательный PF означает опережающую или отстающую нагрузку; знак определяется прошивкой. Санитарный фильтр (§B.5) отбрасывает значения вне |pf| > 10000; нижней границы нет.

YAML
power_factor:
  name: "Power Factor"

reactive_power / reactive_power_1 / reactive_power_2

Атрибут Значение
Единица ВАр
device_class reactive_power
state_class measurement
accuracy_decimals 1
Зависимости Требует current + voltage для соответствующего слота

Реактивная мощность в вар. Без знака (≥ 0), вычисляется как √(S² − P²), включает искажения; точность не указана. Индуктивная и ёмкостная нагрузки не различаются. Читается из модуля при каждом цикле update(); публикуется только для каналов 0..2 (reactive_power_3 ... reactive_power_6 схема принимает, но никогда не публикует). Точность реактивной мощности не указана.

YAML
reactive_power:
  name: "Reactive Power"
Примечание

Примечание о device_class: reactive_power — ESPHome принимает его (константа DEVICE_CLASS_REACTIVE_POWER), значение передаётся в Home Assistant. Однако официальный список device_class в HA со временем менялся: в одних версиях reactive_power доступен в интерфейсе и работает с единицей VAr, в других датчик отображается как общий, без специального значка и пересчёта единиц. Сами данные публикуются всегда (это просто state); вопрос лишь в том, как HA выводит датчик в Lovelace. Если в вашей версии HA датчик показывает unknown, это косметика, а не поломка. Удалите ключ reactive_power: из YAML, если датчик не используется.

apparent_power

Атрибут Значение
Единица VA
device_class apparent_power
state_class measurement
accuracy_decimals 1
Источник Вычисляется на мастере: S = V_rms × I_rms[0]
Зависимости Требует current + voltage

Полная мощность в ВА. Вычисляется компонентом из значений U_rms и I0_rms, прочитанных в том же цикле update() — отдельный регистр не читается. Оба чтения должны пройти в одном цикле; если хотя бы одно не удалось (повторы исчерпаны), в этом цикле ничего не публикуется, и в HA сохраняется последнее значение.

apparent_power входит в SHARED_FIELDS и работает с любой топологией, но зависит от voltage и current для расчёта V × I.

YAML
apparent_power:
  name: "Apparent Power"

2.2 Фазовые поля (варианты с несколькими напряжениями)

Для модулей с более чем одним входом напряжения (варианты split-phase и трёхфазные) датчики объявляются по фазам. Схема принимает фазовую группу на любом модуле; слот публикуется, только если подключённый модуль действительно сообщает соответствующий канал, иначе остаётся без значения.

Одиночные и фазовые поля взаимно исключают друг друга в одном блоке sensor:. Валидатор выдаёт ошибку:

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).

Все фазовые поля используют те же значения по умолчанию sensor_schema, что и однофазные аналоги (те же единицы, device_class, state_class, accuracy_decimals).

Поле Единица device_class
voltage_a / _b / _c V напряжение
current_a / _b / _c A ток
power_a / _b / _c W power
power_total W power
energy_a / _b / _c Вт·ч energy
energy_exported_a / _b / _c Вт·ч energy
power_factor_a / _b / _c — power_factor
reactive_power_a / _b / _c ВАр reactive_power
voltage_angle_b / _c ° —

voltage_angle_b и voltage_angle_c публикуют фазовый угол напряжений B и C в градусах относительно фазы A (фаза A — опорная 0°, поэтому voltage_angle_a нет). Нужна прошивка модуля, которая их предоставляет; на старой прошивке компонент пишет предупреждение при загрузке, и датчики не публикуют значения. Пока угол не определён, значение — «unknown».

Примечание

Проверка зависимостей по фазам не применяется к фазовым полям (только _SINGLE_SLOT_DEPS для однофазных).

Example:

YAML
rbamp:
  id: panel_meter
  address: 0x50

sensor:
  - platform: rbamp
    rbamp_id: panel_meter
    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_total:
      name: "Total Active Power"
    voltage_angle_b:
      name: "Phase B Angle"
    voltage_angle_c:
      name: "Phase C Angle"

2.3 Общие поля (не зависят от топологии)

Эти поля работают в любой группе топологии, в том числе когда ни один однофазный или фазовый токовый датчик не объявлен (развёртывание только с напряжением или только с частотой).

frequency

Атрибут Значение
Единица Hz
device_class frequency
state_class measurement
accuracy_decimals 0

Частота сети. Недостоверные значения (модуль сообщает «ещё не измерено») отбрасываются без публикации, что исключает переход «Unknown» → 0 Гц → 50 Гц у сущности HA во время прогрева.

YAML
frequency:
  name: "Mains Frequency"

apparent_power

См. запись под одиночными полями выше. apparent_power требует current и voltage, поэтому его место в блоке однофазного датчика.

energy_total / energy_exported_total / energy_net

Датчик Единица state_class Значение
energy_total Вт·ч total_increasing Импортированная энергия, все каналы модуля
energy_exported_total Вт·ч total_increasing Экспортированная энергия, все каналы модуля
energy_net Вт·ч total Импорт минус экспорт. Может уменьшаться.

Общие итоги по всем каналам модуля, взятые из собственных счётчиков энергии модуля (модули STANDARD). Они переживают перезапуски ESP32 и модуля, монотонны при перезапусках модуля и сбросах счётчиков (кроме energy_net, который является разностью двух монотонных значений), а также сохраняются в NVS каждые 5 минут и при чистом выключении. Им не нужны ключ bidirectional: и сопутствующее объявление current/voltage.

На модуле без счётчиков энергии на устройстве (BASIC) эти ключи проходят валидацию, но не публикуются; компонент пишет предупреждение при загрузке. Используйте там датчики energy по каналам.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    energy_total:
      name: "Energy Imported"
    energy_exported_total:
      name: "Energy Exported"
    energy_net:
      name: "Energy Net"

reactive_energy / reactive_energy_exported

Атрибут Значение
Единица varh
state_class total_increasing
accuracy_decimals 3

Реактивная энергия (импорт / экспорт) по всем каналам, из тех же собственных счётчиков устройства и с тем же сохранением, что и energy_total. Только модули STANDARD; на других ключи проходят проверку, но никогда не публикуются.

phase_sequence

Атрибут Значение
Единица —
accuracy_decimals 0

Порядок фаз трёхвольтового модуля: 1 = прямой, 2 = обратный, 3 = аномальный. «Unknown», пока нельзя определить (меньше трёх активных входов напряжения). Требуется прошивка модуля, которая его предоставляет; иначе компонент пишет предупреждение при загрузке, и датчик никогда не публикуется. В lambda id(meter1).get_phase_sequence_str() возвращает "forward", "reverse", "abnormal", "n/a" или "unavailable".


2.4 Правила проверки схемы

Python-валидатор _validate_topology_consistency применяет два класса правил во время esphome config / сборки — до выполнения любого кода C++.

Взаимное исключение топологий

Одиночные поля (voltage, current, current_1 и т. д.) и фазовые поля (voltage_a, voltage_b и т. д.) не могут сосуществовать в одном блоке sensor:. Попытка их смешать:

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.

Фазовая группа включает voltage_angle_b / voltage_angle_c.

Требования к сопутствующим слотам (только однофазные)

Каждой производной величине нужны входные поля, которые модуль использует для её расчёта:

Объявленное поле Обязательные сопутствующие параметры
power / _1 ... _6 current (или _1 ... _6, тот же суффикс) + voltage
energy / _1 ... _6 current (или _1 ... _6, тот же суффикс) + voltage
power_factor / _1 ... _6 current (или _1 ... _6, тот же суффикс) + voltage
reactive_power / _1 / _2 current (или _1 ... _6, тот же суффикс) + voltage
apparent_power current + voltage

energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* и phase_sequence не имеют требований к сопутствующим схемам.

Отсутствие сопутствующего параметра вызывает:

Text
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.

Прочие правила на уровне блока rbamp:

Правило Описание
ct_model: ↔ ct_models: взаимно исключают друг друга В одном блоке rbamp: можно использовать только один из двух — иначе ошибка проверки.
new_address ≠ address Если совпадают — cv.Invalid.
address в диапазоне 0x08..0x77 Применяется cv.i2c_address.
update_interval ≥ 1s Более короткие интервалы отклоняются.
latch_interval ≥ update_interval Более короткая частота снимков отклоняется.
ct_models: содержит 1..16 записей Более длинные списки отклоняются.
group_id — 0..255 Значения вне диапазона отклоняются.
start_current_ua — это 0 или 10..2540 с шагом 10 Любое другое значение отклоняется.
ct_model_force: true требует ct_model: или ct_models: Отклоняется само по себе.
period_banks: — каждый bank один раз, interval ≥ 1s Дублирующийся банк, банк вне 0..7 или более короткий интервал отклоняются.
Код модели CT допустим для закреплённого sensor_class Код, не допустимый для класса, отклоняется с перечнем допустимых значений.

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


3. Поток данных и тайминг

Общая схема одного цикла update():

Text
Module (autonomous)                  ESP32 (ESPHome component)
─────────────────────────────────   ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
  ↓ (~100 ms per cycle)
Atomically publishes the block       update() fires every update_interval (60 s)
of instantaneous registers            ↓
  ↓                                 phase 1 — snapshot:
                                      write the snapshot command
Closes the period accumulator,        50 ms timeout (non-blocking)
opens a new one                       ↓ (main loop keeps running)
  ↓
  wait 50 ms                        phase 2 — period snapshot:
                                      read the valid flag
                                      read per-channel average powers
                                      E_Wh[ch] += avg_P × dt_s / 3600
                                      save to NVS if 5 minutes elapsed
                                      ↓
                                    phase 3 — instantaneous values:
                                      read the status register
                                      read U_rms, I[0..n]_rms, P[0..n],
                                            PF[0..n], Q[0..n], frequency
                                      publish all bound sensors
                                      ↓
                                    Push state to HA over the native API
Примечание

Диаграмма показывает поток на основе снимков BASIC. Модуль STANDARD ведёт собственные счётчики энергии: при каждом update() компонент читает мгновенные значения и счётчик (одной согласованной транзакцией) и прибавляет разность к своим суммам, поэтому шаг снимка для энергии не используется.

Характерные времена:

Событие Периодичность
Внутренняя фиксация блока мгновенных значений модулем ~100 мс
Вызов update() update_interval (по умолчанию 60 с)
Таймаут ожидания после команды снимка 50 мс (неблокирующий)
Сохранить в NVS Каждые 5 минут
Пауза между повторами по байтам 5 мс, до 3 попыток
Окно записи во флеш при записи модели ~700 мс (модуль всё это время отвечает NACK)

Неблокирующее ожидание стабилизации снимка — кооперативный планировщик ESPHome продолжает обслуживать Wi-Fi, API и другие компоненты во время 50 мс ожидания. Оставшиеся фазы update() (чтение мгновенных регистров) выполняются сразу после возврата из фазы снимка.

Предупреждение [W][component:522]: rbamp took a long time for an operation (XXX ms) ожидаемо и безвредно, если появляется. На прошивке v1.3 компонент читает блок мгновенных значений одним пакетным чтением (READ с автоинкрементом), поэтому исправный цикл укладывается заметно в 30 мс. Предупреждение появляется, когда пакетный путь откатывается к чтению по регистрам (4 транзакции на float, до 36 транзакций при 50 кГц, плюс повторы) — обычно из-за пограничной шины или устаревшей прошивки без возможности пакетного чтения.


4. Настройки шины I2C

Компонент rbamp наследует шину I²C, настроенную в блоке верхнего уровня i2c:. Рекомендуемые настройки для текущей прошивки:

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
  scan: true         # optional: logs the addresses found at boot

Скорость шины: используйте 50kHz на мастерах на базе ESP-IDF (ESP32 с ESPHome или Arduino). Модуль периодически отвечает NACK на 100 kHz (заметная доля транзакций) из-за известного взаимодействия с драйвером ESP-IDF i2c_master (подтверждено в esp-idf issue #9426, помечено Espressif как «Won't Do»). Прошивка v1.1/v1.3 укрепила сторону модуля, но взаимодействие с драйвером сохраняется — 50 kHz остаётся постоянной рекомендацией. Трёхуровневое смягчение компонента (повтор + санитарная проверка + 50 kHz) снижает эффективную долю плохих чтений ниже 1%.

Подтягивающие резисторы: рекомендуется 4.7 kΩ на 3.3 V на SDA и SCL. Большие значения (10 kΩ) увеличивают время нарастания и повышают долю NACK на 100 kHz.

Несколько устройств: шина I²C ESP32 поддерживает до 112 устройств с различными 7-битными адресами. Используйте address: и new_address:, чтобы назначить каждому модулю уникальный адрес. scan: true в блоке i2c: записывает в лог каждый адрес, который отвечает при загрузке, — проверьте, что каждый модуль обнаружен, прежде чем включать учёт по периодам.

Примечание

Полная карта регистров на уровне проводов и набор команд модуля — на публичной странице справочника API. Для типичного пользователя схемы YAML этой главы достаточно — каждый регистр скрыт за декларативным интерфейсом компонента.


5. Поверхность идентичности (v1.3, НОВОЕ) — публичные методы C++

Компонент v1.3 открывает геттеры идентичности и диагностики, доступные из YAML через lambda: и через платформу template. Все методы возвращают std::string (для совместимости с text_sensor) или примитивные типы — исключений нет, всё через кэшированное состояние.

Способ Тип возврата Источник Описание
get_variant_str() std::string REG_HW_VARIANT (0x55) "UI1"/"UI2"/"UI3"/"I1"/"I2"/"I3"/"UNK" — вариант модуля
get_capability_hex() std::string регистр возможностей (capability) "0xNNNN" — 16-битная битовая карта возможностей, для диагностики
get_uid_hex() std::string REG_UID (0x5C × 12 байт) 24 hex-символа (96-битный UID чипа)
get_last_error_str() std::string REG_ERROR (0x02) "OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC"
get_event_flags() uint8_t REG_EVENT_FLAGS (0x03) липкие биты: bit3=ERR_LATCH, bit5=ADDR_CHANGED и т. д.
get_firmware_version() uint8_t REG_VERSION (0x01) байт версии модуля (например, 0x04 на прошивке v1.3 BASIC)
get_std_image_version() uint32_t только STANDARD Версия образа прошивки модуля; 0 = неизвестна или BASIC
get_phase_sequence_str() std::string только STANDARD "forward"/"reverse"/"abnormal"/"n/a"/"unavailable"
read_start_current_ua() uint16_t только STANDARD Свежее чтение сохранённого пускового тока в мкА; 65535 = недоступно
read_gc_tick_received() uint16_t REG_GC_LAST_TICK (0x58) последнее захваченное значение метки из кадра GC
get_capability_cached() uint16_t кэшированная битовая карта возможностей битовая карта, прочитанная при загрузке, без транзакции на шине

Кэширование: variant / capability / uid / firmware_version читаются один раз в setup() и кэшируются — повторные вызовы не обращаются к шине. last_error_str() / event_flags() / gc_tick читаются при каждом вызове для актуальности.

Использование через template text_sensor

YAML
text_sensor:
  - platform: template
    name: "Mains variant"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_variant_str();'
    # → entity_id: sensor.mains_variant, value: "UI1"

  - platform: template
    name: "Mains capability"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_capability_hex();'
    # → the capability bitmap as hex, "0xNNNN" (diagnostics only)

  - platform: template
    name: "Mains UID"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_uid_hex();'

  - platform: template
    name: "Mains last error"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_last_error_str();'

  - platform: template
    name: "Mains firmware version"
    update_interval: 30s
    lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'

Эти text_sensor появляются в HA как sensor.mains_variant и т. д. — удобно для инвентаризации, отслеживания активов и проверки после прошивки.

Использование через lambda: в автоматизациях

YAML
sensor:
  - platform: rbamp
    rbamp_id: mains
    energy: { name: "Mains Energy" }

# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
  on_boot:
    then:
      - lambda: |-
          ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());

6. Парк и синхронизация GC (v1.3 НОВОЕ)

transmit_gc_frame() — программная отправка GC

C++
bool transmit_gc_frame();

Отправляет 5-байтный кадр снимка General-Call на адрес шины 0x00. Байт группы — это group_id: экземпляра, а метка времени — автоинкрементный счётчик; метод возвращает true, если запись на шину прошла успешно. Только для модулей BASIC — на модуле STANDARD пишет предупреждение и ничего не делает:

Text
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP

Все модули с fleet_gc_enable: true и совпадающим group_id: (или group_id: 0) делают снимок своих накопителей периода синхронно в один момент на шине. Значение метки сохраняется каждым модулем для проверки синхронности (read_gc_tick_received()).

Автоматическая отправка: компонент сам отправляет кадр GC в update(), если fleet_gc_enable: true и прошивка объявляет снимок общим вызовом. Ручная отправка нужна только для дополнительной синхронизации (например, по событию-триггеру со стороны HA).

Проверка возможностей: если прошивка не объявляет снимок общего вызова — предупреждение, без отправки.

fleet_apply_now() — принудительно повторить чтение-сравнение-запись

C++
bool fleet_apply_now();

Принудительно повторяет чтение-сравнение-запись для настроек парка: заново читает конфигурацию парка и group id модуля, сравнивает их с fleet_gc_enable: / group_id: из YAML и записывает разницу. Возвращает false (и ничего не делает) на модуле STANDARD.

Сценарий: после сброса модуля к умолчаниям инструментом отладки или для проверки после OTA, что конфигурация парка применилась.


7. Сервисы нативного API (v1.3 НОВОЕ) — автоматизации восстановления

Компонент v1.3 не регистрирует сервисы автоматически — это делает YAML. Но публичные методы write_clear_error() / write_reset() / transmit_gc_frame() предназначены для использования через шаблон api: services:. Канонические рецепты:

YAML
api:
  port: 6053

  services:
    # Recovery: clear REG_ERROR + EVENT_FLAGS bit3
    - service: mains_clear_error
      then:
        - lambda: 'id(mains).write_clear_error();'

    # Maintenance: soft reset (preserves flash)
    - service: mains_reset
      then:
        - lambda: 'id(mains).write_reset();'

    # Fleet: manual GC snapshot (beyond the auto-emit in update())
    - service: fleet_latch_now
      then:
        - lambda: 'id(mains).transmit_gc_frame();'   # group = this instance's group_id, tick auto-increments

    # Maintenance: force fleet-config re-apply (post-OTA verify)
    - service: mains_fleet_apply
      then:
        - lambda: 'id(mains).fleet_apply_now();'

После этого HA может вызывать службы из автоматизаций:

YAML
automation:
  - alias: "Auto-clear meter error on detection"
    trigger:
      platform: state
      entity_id: sensor.mains_last_error
      from: "OK"
    action:
      - delay: 60s   # wait one update_interval to confirm a persistent error
      - service: esphome._mains_clear_error
      - condition: state
        entity_id: sensor.mains_last_error
        state: "ERR_PARAM"
      - service: persistent_notification.create
        data:
          title: "Meter parameter error"
          message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."

8. Ошибки и восстановление (v1.3) — REG_ERROR против бита3 EVENT_FLAGS

В v1.3 модуль имеет два независимых канала ошибок:

Канал Регистр Семантика защёлки (latch) Очистка
Синхронизация (последняя запись) REG_ERROR (0x02) побеждает последняя запись, перезаписывается следующей операцией write_clear_error() или следующая успешная операция
Асинхронно, durable REG_EVENT_FLAGS бит3 (0x03) устойчиво, повторно фиксируется через несколько сотен миллисекунд, если первопричина не устранена write_clear_error() (одна операция сбрасывает оба)

Шаблон чтения

C++
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str();    // "ERR_PARAM" / "OK" / ...

// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;

Семантика восстановления

Одного сброса REG_ERROR недостаточно, если прошивка заново выставляет bit3:

C++
id(mains).write_clear_error();                       // clears REG_ERROR + EVENT bit3
delay(300);                                          // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
    // Root cause not resolved — firmware re-latched bit3
    ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}

Для полного восстановления:

  1. Устраните причину (исправьте код модели CT в YAML, корректно задайте sensor_class).
  2. write_clear_error() — сбрасывает REG_ERROR + бит3 EVENT_FLAGS.
  3. Проверьте через get_event_flags() примерно через 300 мс, что bit3 не возникает снова.

См. 10_troubleshooting.md §6 Ошибки и восстановление.


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