09 · Справочник схемы YAML
Эта глава — полный справочник по схеме YAML внешнего компонента rbamp для ESPHome. Если ключа здесь нет, его нет в схеме.
Один YAML для обеих линеек модулей. При загрузке компонент определяет, какая линейка модулей подключена (BASIC или STANDARD (STD)), и адаптируется автоматически: число каналов, вариант и доступные функции берутся из самого модуля, поэтому ключ topology: и переключение уровня в YAML не нужны. Ключи, относящиеся только к одному поколению, отмечены ниже; ключ, который подключённый модуль не может выполнить, игнорируется с записью в лог, а не приводит к жёсткой ошибке.
Contents:
- Блок компонента —
rbamp: - Платформа датчиков —
sensor.platform: rbamp - Поток данных и тайминг
- Настройки шины I²C
1. Блок компонента — rbamp:
Настройка нескольких модулей (initialization) · Опрос нескольких модулей — три стратегии (realtime-polling) · Проблемы с несколькими модулями (troubleshooting)
Блок верхнего уровня rbamp: регистрирует экземпляр компонента. Он наследует PollingComponent (обеспечивает update_interval) и i2c.I2CDevice (обеспечивает address и дескриптор шины I²C). MULTI_CONF: True означает, что любое число блоков rbamp: может сосуществовать в одном YAML, каждый со своим I²C-ведомым.
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 обязателен.
rbamp:
id: kitchen_meter
address
02 · Инициализация и запуск (initialization) · 3.6 Канонический алгоритм обнаружения (api-reference) · 6 · Последовательности протокола (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | i2c_address (7-битный, 0x08..0x77) |
| По умолчанию | 0x50 |
| Обязательно | Нет |
Текущий I²C-адрес модуля rbAmp. Заводской адрес по умолчанию — 0x50. После смены адреса (через new_address) обновите этот ключ на новое значение и удалите new_address.
Допустимый диапазон: 0x08..0x77 (зарезервированные 7-битные адреса I²C исключены).
rbamp:
address: 0x52 # three modules on the bus: 0x50, 0x51, 0x52
Перекрёстная ссылка: протокол шины I²C в справочнике API; смена адреса во время работы — для смены адреса после загрузки.
update_interval
04 · Учёт по периодам и тарифный учёт (period-metering) · Непрерывный цикл опроса (рекомендуется) (period-metering) · Регистры снимка периода (period-metering)
| Атрибут | Значение |
|---|---|
| Тип | time (строка длительности ESPHome) |
| По умолчанию | 60s |
| Обязательно | Нет |
Как часто выполняется update(). Каждый вызов:
- Отправляет команду снимка и запускает неблокирующий таймаут 50 мс для чтения снимка периода (модули BASIC; на модулях STANDARD энергия берётся из собственных счётчиков модуля, см.
energy_total). - Проверяет регистр состояния; если модуль готов, публикует все привязанные датчики мгновенных значений.
Значение по умолчанию 60 с разумно: модуль внутри обновляет среднюю мощность периода примерно каждые ~100 мс, но интеграция энергии на стороне мастера требует достаточно длинного окна для корректности. При 60 с и средней нагрузке 60 Вт пропущенный снимок теряет ≤ 1 Вт·ч.
Минимально допустимое значение — 1s: схема отклоняет меньшие значения, а esphome config выдаёт диагностику. Значения ниже 5–10 с не дают выгоды для жёсткой синхронизации и лишь засоряют шину.
rbamp:
update_interval: 30s # more frequent dashboard updates, more traffic
latch_interval
Непрерывный цикл опроса (рекомендуется) (period-metering) · 4.11 Блок периода V03 (0xBE..0xCF) (api-reference) · 6.4 Синхронизация периодов — две стратегии (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | time (строка длительности ESPHome) |
| По умолчанию | То же, что update_interval |
| Обязательно | Нет |
| С | v1.4 |
Как часто компонент отправляет команду снимка и интегрирует выборку в Вт·ч. Если задано, цикл снимков отделяется от частоты чтения RT-данных — update_interval: по-прежнему управляет тем, как часто регистры V/I/P/PF/Q читаются и публикуются, а latch_interval: управляет тем, как часто накопитель периода снимается и интегрируется Вт·ч.
Интеграция энергии не добавляет собственной погрешности сверх точности активной мощности модуля, независимо от соотношения: интеграция на стороне мастера использует реальный dt по часам между соседними событиями снимка, поэтому более длинные интервалы снимков дают лишь более грубые шаги интеграции.
Должно быть >= update_interval (короче — отклоняется при проверке конфигурации: лишние снимки не дали бы наблюдаемых данных).
Если не задано, снимок выполняется при каждом вызове update() (поведение v1.3 с одним циклом, обратно совместимое).
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
01 · Аппаратное подключение (hardware-connection) · 03 · Опрос в реальном времени (realtime-polling)
| Атрибут | Значение |
|---|---|
| Тип | gpio_input_pin_schema |
| По умолчанию | Нет (необязательно) |
| Обязательно | Нет |
Подключает выход DRDY модуля с открытым стоком к GPIO ESP32. При указании пин настраивается в setup() при загрузке.
Пин записывается в dump_config, но не используется как триггер чтения — мгновенные регистры опрашиваются по update_interval. Объявление пина поведение не меняет.
rbamp:
drdy_pin: GPIO4
sensor_class
Настройка класса датчика и модели ТТ (initialization) · 4.3 Система (0x20..0x25) (api-reference) · 6.2 Привязка модели ТТ — чистая подготовка + поканальная команда CMD (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | 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.
rbamp:
sensor_class: SCT_013 # default; may be omitted
Подробнее о выборе клещей и семейства см. 03_sensor_selection.md.
ct_model
Настройка класса датчика и модели ТТ (initialization) · 6.2 Привязка модели ТТ — чистая подготовка + команда по каналам (api-reference) · 8.6 Настройка после первой прошивки (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | 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 · Выбор токового датчика.
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 и т. д.); лишние записи игнорируются с предупреждением.
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 в ожидании более позднего выбора модели.
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) отклоняются схемой, поэтому недопустимое значение не попадает на шину. Настройка хранится в модуле и проверяется после записи; значение, равное сохранённому, не записывается повторно.
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 мс.
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 этот ключ не требуют.
rbamp:
bidirectional: true # needed for the per-channel energy_exported* sensors
new_address
Смена адреса (initialization) · 4.5 Адрес (0x30..0x31) (api-reference) · 6.1 Смена адреса — двухфазная фиксация (допустимо в production) (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | i2c_address (0x08..0x77) |
| По умолчанию | Нет (необязательно) |
| Обязательно | Нет |
Запускает однократную смену адреса I²C при загрузке. Он должен отличаться от address — валидатор выдаёт ошибку при равенстве.
На прошивке v1.3 используется двухфазная фиксация — производственный режим без ограничения заводской настройкой. Поведение совместимости:
| Прошивка | Поведение |
|---|---|
| Объявляет двухфазную фиксацию адреса (v1.3+) | Производственный путь — подготовленная запись, явное подтверждение, фиксация, повторное перечисление. |
| Не объявляет (устаревшая v1.0–v1.2) | Устаревший путь — однофазная запись, требует режима заводской настройки. Записывает WARN_FACTORY_MODE_REQUIRED, если модуль не в режиме provisioning. |
Модули STANDARD тоже поддерживают new_address:; компонент применяет его и переподключается к новому адресу так же.
Полный поток выполняется один раз в setup():
- Опросите текущий
address. Если модуль там не отвечает, но отвечает поnew_address, компонент адаптируется к новому адресу с предупреждением (предполагая, что предыдущая загрузка уже применила изменение) и пропускает запись. - Проверьте, объявляет ли прошивка двухфазную фиксацию. Да → производственный путь (см. ниже). Нет → устаревший путь с проверкой режима provisioning.
- Производственный путь (v1.3): подготовьте новый адрес, подтвердите, зафиксируйте → подождите ~700 мс → повторно опросите
new_address. Проверка заводского режима не требуется. - Устаревший путь (v1.0–v1.2): однофазная запись, требуется режим заводского провизионирования на стороне модуля.
- Компонент переключает свой внутренний I²C-адрес через
i2c::I2CDevice::set_i2c_address()наnew_addressи проверяет, что модуль отвечает. - Если модуль не отвечает после смены, компонент вызывает
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) по-прежнему считает модуль на старом адресе, пока не обновит своё состояние.
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, НОВОЕ)
General Call (широковещание по адресу 0x00) (initialization) · Несколько модулей — одновременный снимок (period-metering) · 4.4 Конфигурация парка (0x27..0x2F) (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | bool |
| По умолчанию | false |
| Обязательно | Нет |
| Относится к | Модули BASIC с поддержкой снимка общим вызовом (прошивка v1.3+); на STANDARD игнорируется с записью в лог |
Включается по выбору: разрешает приём широковещательного снимка General-Call от мастера. Когда ESP32 отправляет 5-байтный кадр GC на адрес 0x00, все модули с fleet_gc_enable: true (и совпадающим group_id:) атомарно фиксируют накопители периода в один момент на проводе. Это обеспечивает жёсткую синхронизацию между субсчётчиками.
Поведение по возможностям: при загрузке компонент проверяет, объявляет ли прошивка снимок общим вызовом. Если нет → предупреждение + пропуск без применения:
[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 задаётся при инициализации, переключить его на лету нельзя. При чтении-сравнении-записи это происходит один раз при первой загрузке; при последующих загрузках пропускается.
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, НОВОЕ)
General Call (широковещание по адресу 0x00) (initialization) · Несколько модулей — одновременный снимок (period-metering) · 4.4 Конфигурация парка (0x27..0x2F) (api-reference)
| Атрибут | Значение |
|---|---|
| Тип | 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 и сохраняется во флеш через чтение-сравнение-запись. Изменение требует загрузки.
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.
Она будет удалена в одном из будущих минорных релизов; в логе появится предупреждение об устаревании:
[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.
rbamp:
topology: SINGLE # cosmetic; may be omitted
2. Платформа датчиков — sensor.platform: rbamp
Каждый блок sensor: объявляет набор именованных датчиков, привязанных к родительскому компоненту rbamp:. Единственный обязательный ключ в блоке — rbamp_id.
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 Одиночные поля
Многоканальный ток (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Окно доступа к каналам (0x32 + 0x3C..0x3F) (api-reference)
Используется для модулей одного напряжения (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
Справочник регистров RT (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
| Атрибут | Значение |
|---|---|
| Единица | 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, но не законные нули.
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 число каналов берётся из самого модуля; объявленные сверх него слоты просто не публикуются.
current:
name: "Phase Current"
current_1:
name: "Load 1 Current"
current_2:
name: "Load 2 Current"
power / power_1 ... power_6
Справочник регистров RT (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
| Атрибут | Значение |
|---|---|
| Единица | 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.
power:
name: "Active Power"
energy / energy_1 ... energy_6
Алгоритм на стороне мастера (period-metering) · 7 · Семантика (api-reference)
| Атрибут | Значение |
|---|---|
| Единица | Вт·ч |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Зависимости | energy требует current + voltage; energy_N требует current_N + voltage |
Накопленная потреблённая (импортная) энергия в Вт·ч для канала.
- Модули STANDARD — компонент накапливает собственные счётчики энергии модуля. Итоги переживают перезапуски и ESP32, и модуля и монотонны (не откатываются назад при перезапуске модуля или сбросе счётчика).
- Модули BASIC — вычисляются на ESP32 из средней мощности периода, которую модуль возвращает после каждого снимка:
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. Значение растёт монотонно и при нормальной работе не уменьшается.
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; нижней границы нет.
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 схема принимает, но никогда не публикует). Точность реактивной мощности не указана.
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.
apparent_power:
name: "Apparent Power"
2.2 Фазовые поля (варианты с несколькими напряжениями)
Для модулей с более чем одним входом напряжения (варианты split-phase и трёхфазные) датчики объявляются по фазам. Схема принимает фазовую группу на любом модуле; слот публикуется, только если подключённый модуль действительно сообщает соответствующий канал, иначе остаётся без значения.
Одиночные и фазовые поля взаимно исключают друг друга в одном блоке sensor:. Валидатор выдаёт ошибку:
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:
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 во время прогрева.
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 по каналам.
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:. Попытка их смешать:
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 не имеют требований к сопутствующим схемам.
Отсутствие сопутствующего параметра вызывает:
`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. Поток данных и тайминг
Опрос — один модуль (realtime-polling) · 3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · 4 · Карта регистров (производственная v1.3) (api-reference)
Общая схема одного цикла update():
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:. Рекомендуемые настройки для текущей прошивки:
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++
Автоопределение варианта модуля (initialization) · 3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · Коды ошибок (REG_ERROR = 0x02) (troubleshooting)
Компонент 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
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: в автоматизациях
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
bool transmit_gc_frame();
Отправляет 5-байтный кадр снимка General-Call на адрес шины 0x00. Байт группы — это group_id: экземпляра, а метка времени — автоинкрементный счётчик; метод возвращает true, если запись на шину прошла успешно. Только для модулей BASIC — на модуле STANDARD пишет предупреждение и ничего не делает:
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() — принудительно повторить чтение-сравнение-запись
bool fleet_apply_now();
Принудительно повторяет чтение-сравнение-запись для настроек парка: заново читает конфигурацию парка и group id модуля, сравнивает их с fleet_gc_enable: / group_id: из YAML и записывает разницу. Возвращает false (и ничего не делает) на модуле STANDARD.
Сценарий: после сброса модуля к умолчаниям инструментом отладки или для проверки после OTA, что конфигурация парка применилась.
7. Сервисы нативного API (v1.3 НОВОЕ) — автоматизации восстановления
Коды ошибок (REG_ERROR = 0x02) (troubleshooting) · 6.7 Восстановление из состояния ошибки — дерево решений (api-reference)
Компонент v1.3 не регистрирует сервисы автоматически — это делает YAML. Но публичные методы write_clear_error() / write_reset() / transmit_gc_frame() предназначены для использования через шаблон api: services:. Канонические рецепты:
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 может вызывать службы из автоматизаций:
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() (одна операция сбрасывает оба) |
Шаблон чтения
// 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:
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");
}
Для полного восстановления:
- Устраните причину (исправьте код модели CT в YAML, корректно задайте sensor_class).
write_clear_error()— сбрасывает REG_ERROR + бит3 EVENT_FLAGS.- Проверьте через
get_event_flags()примерно через 300 мс, что bit3 не возникает снова.
См. 10_troubleshooting.md §6 Ошибки и восстановление.
Исходники и задачи: rb-amp/rbamp-esphome · эта страница в репозитории: docs/09_api_reference.md (v1.9.1)