01 · Обзор
Что такое rbAmp
rbAmp — компактный аппаратный модуль для точного измерения параметров сетевого переменного тока. С точки зрения интегратора это обычный I²C-ведомый: подайте питание, прочитайте регистр — и получите готовое значение в физических единицах. Обработка сигнала на стороне мастера не нужна. Заводская калибровка выполняется один раз на производстве и хранится во флеше модуля; пользователю остаётся выбрать модель токовых клещей (см. 03_sensor_selection.md) и подключить шину.
Поток данных (в одну строку)
Главное преимущество: физические величины приходят из модуля уже готовыми. На стороне ESP32 нет обработки сигнала, таблиц калибровки и математики RMS/мощности. Компонент ESPHome — тонкий клиент I²C + накопитель энергии + слой публикации в HA. Для базовой работы математика lambda: не нужна.
rbAmp в экосистеме ESPHome
Если вы уже использовали встроенные счётчики энергии (pzemac по UART, atm90e32 по SPI, cse7766 по UART), структура та же. Компонент rbamp — «добропорядочный» компонент ESPHome: использует стандартный транспорт i2c:, стандартный синтаксис sensor.platform: rbamp, стандартные слоты датчиков с device_class / state_class / unit_of_measurement, и поддерживает весь стандартный набор фильтров и свойств датчиков.
Сравните анатомию (ментальная модель та же):
# ATM90E32 (SPI meter) — shown for comparison only, not part of an rbAmp config:
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: atm90e32
cs_pin: GPIO5
voltage_a:
name: "Mains Voltage"
power_a:
name: "Mains Power"
# rbAmp (I²C meter) — a separate file, do not paste both:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current: # power needs voltage AND current declared
name: "Mains Current"
power:
name: "Mains Power"
Различия только в транспорте (i2c: вместо spi:) и в том, что rbamp: объявляется отдельным блоком (ему нужны id: и address: для шины с несколькими модулями). Всё остальное — обычный ESPHome: имена слотов (voltage, current, power, energy, frequency, power_factor) узнаваемы, а настройка (name, update_interval, accuracy_decimals, filters:) работает как обычно. Подробный пример настройки см. в 06_examples.md §1.1 «UI1 с настройкой — все стандартные ручки ESPHome».
Каноническое развёртывание — парк из нескольких модулей
Основной сценарий применения rbAmp в ESPHome — мониторинг нескольких нагрузок с одного мастера ESP32. В доме, мастерской или щитке обычно один ввод сети и несколько ответвлений: бойлер, кондиционер, EV, отдельные комнаты. Один rbAmp UI1 ставится на ввод и считает общую мощность и энергию; несколько модулей rbAmp I2/I3 ставятся на ответвления и считают только токи на каждом канале.
Все модули находятся на одной шине I²C ESP32 — у каждого свой адрес из диапазона 0x50..0x77. Компонент поддерживает MULTI_CONF = True, поэтому один YAML-файл может объявить несколько блоков rbamp: и публиковать их все как независимые наборы сущностей в Home Assistant.
В этом сценарии ESP32 — единственный мастер: он отправляет общий широковещательный снимок General-Call при fleet_gc_enable: true, и все модули атомарно начинают новый период накопления в один момент на проводе. Это даёт жёсткую синхронизацию между субсчётчиками — суммы по каналам совпадают с суммой ввода с точностью до одного периода.
Конфигурация из одного модуля (UI1 на сети, без субсчётчиков) — минимальный случай, а не канон. На v1.3 допустимы оба варианта; многомодульная установка рекомендована прямо в первой главе документации, потому что 80% полевых развёртываний — именно такие.
Что вы измеряете
| Величина | Слот YAML | Диапазон | Типичная точность |
|---|---|---|---|
| Действующее напряжение (RMS) | voltage |
0..300 V | ±0.5% |
| RMS-ток (по каналам) | current / current_1 / current_2 |
0..100 А (зависит от артикула) | ±0.5..1% (модуль) |
| Активная мощность (знаковая) | power / power_1 / power_2 |
±23 kW | ±1% (модуль) |
| Коэффициент мощности (со знаком) | power_factor / power_factor_1 / power_factor_2 |
−1..+1 | ±0.01 при PF ≈ 1 (резистивная нагрузка) с датчиками SCT-013 номиналом 10 А и выше; собственный фазовый сдвиг датчика 5 А добавляет до ~0.015 ошибки показания — чисто резистивная нагрузка показывает ~0.985–0.993 |
| Реактивная мощность (без знака, √(S² − P²), учитывает искажения; точность не заявлена) | reactive_power / reactive_power_1 / reactive_power_2 |
как P | — |
| Полная мощность | apparent_power (только CH0; для CH1/CH2 используйте шаблонный датчик HA, см. DIY Integrations §6) |
как P | ±2% |
| Частота сети | frequency |
50 / 60 Гц (определяется на BASIC) | — |
| Накопленная энергия (Вт·ч) | energy / energy_1 / ... (по каналам); energy_total / energy_exported_total / energy_net (STANDARD (STD), все каналы) |
64-bit | зависит от точности P |
| Реактивная энергия (varh) | reactive_energy / reactive_energy_exported (STANDARD) |
64-bit | — |
Это собственные показатели модуля. Вы читаете показания модуля плюс установленный датчик, поэтому итог зависит от датчика и его номинала: пороги обнаружения, пороги считывания и классы точности для семейства SCT-013 по каждому номиналу опубликованы в таблице точности BASIC. Модули с заводски парным датчиком CT и модули STD описаны там отдельно.
Слоты есть для до семи каналов тока (current_3 ... current_6 и соответствующие power_N, energy_N, power_factor_N на вариантах с большим числом каналов).
Все мгновенные величины модуль обновляет автономно с шагом ~100 мс. На модулях BASIC накопление Вт·ч выполняет ESP32 по средней мощности, которую модуль возвращает за интервал между двумя вызовами update(); на модулях STANDARD компонент накапливает собственные счётчики энергии модуля. Компонент ESPHome скрывает эти протоколы — пользователь видит только готовые сущности датчиков в Home Assistant.
Что добавляет компонент ESPHome
- Готовые датчики HA — у каждого слота уже заданы
device_class,state_classи единицы. Датчикenergyсразу появляется на панели энергии без ручной настройки. - Один YAML для обеих линеек модулей — при загрузке компонент определяет, подключён BASIC или STANDARD, и берёт число каналов, вариант и функции из самого модуля.
topology:не нужен. Ключи, относящиеся только к одному поколению, игнорируются с записью в журнал на другом. - Энергия на устройстве (STANDARD) — модуль ведёт собственные накопительные счётчики; компонент их накапливает, поэтому итоги переживают перезапуски и ESP32, и модуля, и остаются монотонными. Датчики общих итогов:
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported.start_current_ua:задаёт ток, ниже которого канал не учитывает энергию. - Сохранение Вт·ч в NVS — суммарная энергия записывается во флеш ESP32 каждые 5 минут (и при чистом выключении, чтобы перезагрузка или OTA не теряли последний интервал) и восстанавливается до первого
publish_state. Home Assistant никогда не видит мгновенного нуля после перезагрузки и не принимает его за сброс счётчика. - Декларативная конфигурация датчика — две строки YAML (
sensor_class:+ct_models:для UI3 илиct_model:для UI1) закрепляют семейство и модель ТТ для каждого канала. Заводские коэффициенты загружаются модулем автоматически — шагов калибровки при загрузке нет. - Расписание опроса через
PollingComponent::update()с настраиваемымupdate_interval(по умолчанию 60 с). - Раздельные циклы чтения RT и снимков (v1.4+) — необязательный ключ
latch_interval:позволяет циклу снимок → интеграция Вт·ч работать в собственном темпе, аupdate_interval:по-прежнему определяет, как часто компонент ESPHome читает блок реального времени V/I/P/PF/Q. Типичный случай:update_interval: 3s+latch_interval: 60s— свежие значения на панели каждые 3 с, нагрузка снимков на шину раз в минуту. Интеграция энергии не добавляет собственной погрешности сверх точности активной мощности модуля (интеграция на стороне мастера использует фактический интервал dt по часам между событиями снимка). - Устойчивость к NACK — реализована трёхуровневая дисциплина: 50 kHz по умолчанию, повтор по байтам и санитарный фильтр для NaN/Inf. Подробности ниже.
- Однократное назначение адреса — ключ
new_address:меняет I²C-адрес модуля за один цикл загрузки. На прошивке v1.3 он работает в производственном режиме без ограничения заводской настройкой (двухфазная фиксация адреса, определяется автоматически). Удобно для массовой настройки партии устройств после установки в щиток. - Шина с несколькими модулями —
MULTI_CONF = Trueпозволяет объявить несколько блоковrbamp:на одном ESP32 и опрашивать их по очереди. - Синхронизация парка общим вызовом (General Call, v1.3) — ключ
fleet_gc_enable: trueвключает приём широковещательного снимка GC от ESP32. Все модули с этим флагом и совпадающимgroup_id:одновременно начинают новый период. Зависит от возможностей; на устаревшей прошивке пишет предупреждение и пропускает без применения. Только модули BASIC. - Поверхность идентичности (v1.3) — публичные методы
get_variant_str()/get_capability_hex()/get_uid_hex()/get_firmware_version()/get_last_error_str()доступны изlambda:и через шаблонныйtext_sensor.platform: template. Они позволяют вывести в HA текущий вариант модуля (UI1/UI3/I2…), битовую карту возможностей, UID и версию прошивки. - Загрузка с чтением-сравнением-записью (v1.3) —
sensor_class:/ct_model:/ct_models:записываются во флеш, только если запрошенное значение отличается от сохранённого. Обратная запись конфигурации при загрузке сокращается с ~2.8 с (первая установка UI3) до ~0 мс при стабильной конфигурации. Старый совет «удалитьct_model:из YAML после проверки» устарел — конфигурация идемпотентна. - Защита заводской калибровки (v1.8.1+) — на модуле, откалиброванном в паре с собственным встроенным датчиком (
WIRED_CT/BUILTIN_CT), изменение класса или модели из YAML отклоняется с записью в журнале. Опция службыct_model_force: trueпереопределяет это осознанно. - Переключение номинала SCT сохраняет точность (v1.9) — выбор другого номинала SCT-013 через
ct_model:сохраняет заводскую индивидуальную калибровку: на прошивке до 1.4.19 компонент завершает переключение требуемым перезапуском модуля и масштабирует показания; более новая прошивка делает это на модуле.
Архитектура
Модуль измерения находится в самом модуле; ESP32 служит мостом к HA. На модулях BASIC Вт·ч интегрируются на ESP32 по его собственным часам, что обеспечивает согласованное накопление по нескольким модулям. Модули STANDARD сами ведут накопительные счётчики энергии, которые ESP32 суммирует.
Поток данных внутри одного update()
Описание ниже — поток для BASIC. На модуле STANDARD мгновенная ветвь та же; ветвь периода заменяется одним согласованным чтением счётчиков энергии модуля, разность с предыдущим снимком прибавляется к суммам (шага снимка нет).
Каждый вызов update() на модуле BASIC запускает две параллельные ветви:
Ветвь 1 — мгновенные значения (блок RT)
- Проверьте регистр состояния. Если модуль занят (загрузка, окно записи во флеш), пропустите без записи.
- Для каждого объявленного датчика RT прочитайте float32 из соответствующего регистра.
- Санитарный фильтр
std::isfinite()— отбрасывает NaN/Inf, которые могут возникнуть при разрывах чтения неатомарных регистров. sensor->publish_state(val).
На прошивке v1.3 блок мгновенных значений (U / I / P / PF / Q для всех объявленных каналов) получается одним пакетным чтением с автоинкрементом READ — одна фаза адреса и затем байты блока. Если пакетное чтение не удалось или прошивка не поддерживает возможность, компонент переходит к чтению отдельных регистров (4 транзакции на float, каждая со своей фазой адреса). Автоинкремент WRITE не поддерживается; отдельные записи в регистры всегда идут побайтно.
Ветвь 2 — учёт по периодам (накопление энергии)
- Запишите
t_latch = millis(). - Отправьте команду снимка — она закрывает текущий период накопления и сразу открывает следующий. Одна транзакция и закрывает, и открывает; на границе выборка не теряется.
- Через 50 мс (неблокирующий таймаут) читается флаг валидности. Если модуль ещё не закончил интеграцию (опрос чаще периода интеграции или устаревший снимок), пропуск — следующий цикл подберёт пропущенный интервал.
- Прочитайте среднюю активную мощность за период по каждому каналу.
E_Wh[ch] += avg_p_W[ch] × (t_latch − last_latch_ms_) / 3_600_000.- Обновляйте
last_latch_ms_только после успеха на всех каналах. - Сохранить в NVS, если с последнего сохранения прошло более 5 минут.
Первый снимок после загрузки сбрасывает накопитель модуля и калибрует тактовый генератор мастера; его результат отбрасывается через флаг primed_.
Сохранение энергии в NVS
Накопленные значения хранятся в структуре RbAmpPrefData (итог по каналам до семи каналов + экспорт по каналам 0..2):
struct RbAmpPrefData {
double energy_total_wh[7];
double energy_export_wh[3];
} __attribute__((packed));
На модулях STANDARD итоговые и реактивные накопители (energy_total, energy_exported_total, reactive_energy*) хранятся во втором, отдельном слоте NVS, поэтому значения по каналам не затрагиваются обновлением. Оба слота записываются каждые 5 минут и при чистом выключении (перезагрузка / OTA).
Ключ NVS выводится из ID компонента, XOR-ом с RBAMP_PREF_VERSION (0x52424D31 = "RBM1"). Если структура когда-либо изменится, увеличение константы версии молча отбрасывает устаревшие данные вместо их неверного толкования.
При загрузке setup() восстанавливает итоги до первого update(). Если бы компонент сначала опубликовал 0 Wh, а затем скачок к сохранённому значению, Home Assistant принял бы скачок за сброс счётчика и начал новый сегмент истории. Восстановление до первой публикации этого не допускает.
Частота сохранения определяется двумя условиями:
- По времени — каждые 5 минут (
SAVE_INTERVAL_MS = 300000). - По событию — после каждого успешного полного цикла интеграции (все каналы прочитаны без NACK) и при чистом выключении.
Худший случай потери данных при внезапном отключении питания ESP32 — 5 минут накопленной энергии. При средней нагрузке 60 Вт это 5 Вт·ч — ниже разрешения дневного столбца панели энергии.
Износ NVS — может ли флеш «износиться»?
Каждая запись сохраняет ~16 байт в раздел NVS ESP32. Слой ESP-IDF NVS объединяет мелкие записи в один блок и стирает страницу (4 КБ) только тогда, когда блок заполнен. При цикле 5 минут:
| Метрика | Значение |
|---|---|
| Экономия в день | 288 |
| Сохранений в год | ~105120 |
| Размер записи | ~16 байт |
| Размер страницы NVS | 4096 байт |
| Циклов стирания страниц в год | ~411 (≈ 105120 × 16 ÷ 4096) |
| Лимит циклов стирания (даташит NOR-флеш ESP32) | 100000 циклов |
| Время до отказа (TTF) | ~240 лет на страницу NVS |
ESP-IDF NVS дополнительно выравнивает износ по доступным страницам NVS (в разделе по умолчанию 4 страницы), что умножает TTF примерно в ~4×. Практический вывод: износ NVS при цикле сохранения каждые 5 минут не является ограничивающим фактором — раньше устареет само железо.
Когда стоит снижать частоту: если пользователь принудительно задаёт SAVE_INTERVAL_MS ниже значения по умолчанию (например, 30 с) собственным кодом, пересчитайте TTF той же формулой. Безопасная нижняя граница для 10 лет работы — ~30 с.
Дисциплина NACK
Платы ESP32 с драйвером ESP-IDF v5 i2c_master (его используют ESPHome, arduino-esp32 v3.x и MicroPython на ESP32) периодически отвечают NACK на чтения модуля на 100 kHz — примерно в 20% транзакций. Тот же модуль с другим мастером (например, другим 32-битным MCU или Raspberry Pi) даёт 0% NACK. Значит, проблема на стороне мастера, а не модуля. Подробнее в справочнике API, раздел «I²C electrical discipline».
Есть и второе осложнение: когда i2c_master_transmit_receive() возвращает ESP_FAIL из-за NACK, драйвер IDF v5 не обнуляет пользовательский буфер. Данные предыдущей транзакции остаются. Некоторые из таких устаревших шаблонов похожи на правдоподобные float (например, 0x3C 0x2F 0xFB 0x3F → 1.962 V) и проходят наивную проверку isfinite().
Компонент реализует три уровня смягчения:
| Слой | Реализация | Эффект |
|---|---|---|
| Шина 50 kHz по умолчанию | frequency: 50kHz в YAML-блоке i2c: |
Снижает частоту NACK примерно в 5× эмпирически |
| Повтор по байтам | 3 попытки, пауза 5 мс, на каждый байт каждого float32 | Устраняет переходный NACK до использования данных |
| Мягкий фильтр корректности | std::isfinite() без жёстких физических границ |
Отлавливает NaN/Inf/денормалы из устаревшего буфера; пропускает корректные граничные значения (просадка, обрыв) |
Со всеми тремя уровнями защиты компонент на стенде даёт > 99% корректных чтений при рекомендуемых 50 кГц. Прошивки v1.1 и v1.3 укрепили окно восстановления I²C модуля, но 50 кГц остаётся рекомендуемой настройкой на мастерах на базе ESP-IDF, так как взаимодействие драйвера по времени сохраняется на 100 кГц.
Семейство библиотек rbAmp
Этот компонент — один из членов кроссплатформенного семейства клиентских библиотек rbAmp. Все они реализуют один и тот же протокол на проводе (справочник API).
| Платформа | Репозиторий |
|---|---|
| ESPHome (этот компонент) | rb-amp/rbamp-esphome |
| Arduino / arduino-esp32 | rb-amp/rbamp-arduino |
| ESP-IDF | rb-amp/rbamp-esp-idf |
| Python (CPython + MicroPython) | rb-amp/rbamp-python |
Все библиотеки используют одни и те же соглашения о проводе — побайтовую запись с необязательным пакетным READ, одну и ту же конечную машину снимков учёта периодов, одно и то же определение варианта артикула при загрузке и одни и те же коды REG_ERROR. Код с любой из этих платформ переносится на другую механическим переводом синтаксиса — логика протокола идентична. Канонической картой регистров служит 09 · Справочник API.
Поддерживаемые артикулы
| Вариант | Канал напряжения | Токовые каналы | Мощность | Доступные слоты ESPHome |
|---|---|---|---|---|
| UI1 | да | 1 | да | voltage, current, power, energy, frequency, power_factor, reactive_power, apparent_power |
| UI2 | да | 2 | да | + current_1, power_1, energy_1, power_factor_1, reactive_power_1 |
| UI3 | да | 3 | да | + current_2, power_2, energy_2, power_factor_2, reactive_power_2 |
| I1 | нет | 1 | нет | current, frequency |
| I2 | нет | 2 | нет | + current_1 |
| I3 | нет | 3 | нет | + current_2 |
Модули с более чем одним входом напряжения используют фазовые слоты (voltage_a/b/c, current_a/b/c, ...) — см. 09 §2.2; две группы нельзя смешивать в одном блоке sensor:.
На вариантах только с I слоты power, energy и power_factor требуют объявленного слота voltage (проверяется валидатором схемы) — объявляйте их только на артикулах UI*.
Что дальше
- 02_tiers.md — линейки модулей BASIC / STANDARD (STD) и какие ключи YAML доступны на каждой
- 03_sensor_selection.md — выбор клипсы CT и поведение ключей
ct_model:/ct_models: - 04_hardware.md — распиновка GPIO, подтяжки, шина из нескольких модулей
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/01_overview.md (v1.9.1)