01 · Обзор
rbAmp — компактный аппаратный модуль для прецизионного измерения параметров сетевого переменного тока по интерфейсу I²C. Построен на микроконтроллере с интегрированным изолированным аналоговым входным каскадом и заводской калибровкой, хранимой во флеше.
Что такое rbAmp
Главное назначение библиотеки — мониторинг нескольких нагрузок
components/rbamp спроектирован для работы с группой модулей на одной шине I²C одновременно, а не для управления одним устройством. Канонический сценарий — основной модуль на вводе сети плюс N модулей на отдельных нагрузках, все на одной шине и под управлением одного ESP32. Библиотека предоставляет дескриптор парка: единый объект, через который вы сканируете шину, опрашиваете все модули одним вызовом, получаете суммарную потребляемую мощность и баланс «ввод − Σ(нагрузки)», отлавливаете ошибки по модулям и — при необходимости — синхронизируете снимки периодов широковещательной командой.
Модули с несколькими каналами также поддерживаются — только токовые I2 / I3 (2 / 3 токовых канала) и с измерением напряжения UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 токовых каналов, с мощностью, PF и Wh по каждому каналу). У каждого канала своя модель токового датчика CT. Это типично для распределительного подщитка, где одна точка установки контролирует несколько фидеров: один модуль даёт разбивку по каналам без отдельного модуля на каждом.
Важная архитектурная деталь. Мощность и Wh требуют варианта UI; баланс «сеть минус сумма нагрузок» требует модуля UI на каждой нагрузке. Варианты I (I1/I2/I3) измеряют только ток — у них нет напряжения, активной мощности и PF. Активная энергия (Wh) и мощность вычисляются только на вариантах UI (у которых есть входной каскад напряжения). В каноничной схеме роль «счётчика сети» (полная энергия) выполняет один UI1 на вводе сети, а роль субсчётчика (детализация тока по нагрузкам) — модули I2/I3 (или UI2 / UI3 / UI5 / UI7, если нужны мощность и Wh по каждой нагрузке).
Работа с одним модулем — минимальный случай той же библиотеки: rbamp_handle_t — строительный блок, на котором построен флот. Если на шине один модуль, используйте тот же дескриптор напрямую — API флота не нужен.
Сценарий 80% — ввод сети + N субнагрузок
- 1 модуль на вводе (сеть) — общее потребление и качество сети.
- N модулей на отдельных нагрузках — учёт по каналам.
- Многоканальные модули подходят и для этого случая: один UI2 / UI3 / UI5 / UI7 (или I2 / I3) может учитывать несколько нагрузок, каждую на своём канале — N модулей не обязаны означать N нагрузок.
-
Один вызов флота
rbamp_fleet_poll_all()опрашивает всё; балансmains − Σ(sub_loads)показывает «остальное» (фоновое потребление, неучтённые нагрузки, утечки). -
Одна общая метка времени мастера → корректный учёт Wh без дрейфа между модулями (см. 02_tiers.md и раздел о часах мастера в 09_api_reference.md).
Подробности — в главе 06 · Примеры, сценарий 1 («Сеть + N поднагрузок — канон 80%»). Для API — в главе 09 · Справочник API, раздел «Fleet manager».
Что измеряет rbAmp
| Величина | Тип | Диапазон |
|---|---|---|
| Действующее напряжение U_rms | float, В | 0…300 V |
| Пиковое напряжение U_peak | float, В | 0…450 V |
| Действующий ток I_rms | float, А | зависит от выбранного датчика — см. 03_sensor_selection.md |
| Пиковый ток I_peak | float, А | зависит от выбранного датчика |
| Активная мощность P (знаковая в RT) | float, Вт | зависит от выбранного датчика |
| Коэффициент мощности PF | float | −1…+1 |
| Частота сети | uint8, Гц | 50 / 60 Гц (определяется) |
| P, усреднённая за период | float, Вт | как P |
Мгновенное значение активной мощности P всегда знаковое на любой линии модулей (отрицательное = экспорт в сеть). Поведение усреднённого за период значения (avg_p[ch] в rbamp_period_snapshot_t) зависит от линии модулей — см. раздел «Линии модулей» ниже и 02_tiers.md.
Подключение
Модуль подключается к мастеру четырьмя проводами на низковольтной стороне. Единственный опорный сигнал сети (вход напряжения L/N на вариантах UI*) находится за гальванически изолированным делителем, а клещи CT связаны магнитно, без электрического контакта; см. 04 · Проводка, «Подключение сети и CT» (сетевое напряжение опасно для жизни — сначала прочитайте предупреждение там).
| Провод | Цель |
|---|---|
VCC |
+5 В (4.5..5.5 В), ~15 мА, пик ~25 мА. Встроенный стабилизатор и фильтрация |
GND |
общий с мастером (обязательно) |
SDA, SCL |
I²C, логика 3.3 В, терпимость к 5 В. Встроенные подтяжки 4.7 кОм к 3.3 В |
DRDY |
необязательно, открытый сток LOW ~10 мкс каждые ~100 мс |
Адрес по умолчанию — 0x50 (7-битный, настраиваемый диапазон 0x08..0x77), рекомендуемая скорость на ESP32 — 50 кГц (см. раздел о дисциплине повтора и фильтра адекватности ниже). Холодный старт до первого корректного измерения — ~250 мс.
Полные правила (длина шины, рекомендации по подтяжкам на шине из нескольких модулей, схемы подключения для разных целей ESP32) — в главе 04 · Подключение.
Линии модулей (краткая шпаргалка)
BASIC и STANDARD (STD) модули выпускаются. BASIC следует логике классического механического счётчика — однонаправленный учёт (только потребление); STD хранит знаковые счётчики энергии:
| Уровень | Мощность RT P |
Накопитель периода на каждый канал avg_p[ch] |
Счётчик Wh компонента |
|---|---|---|---|
| BASIC | со знаком (отрицательное = экспорт в сеть, видно в реальном времени) | каждое окно 100 мс средней P ограничивается до max(P, 0), прежде чем добавляется в накопитель периода |
monotonic — учёт только потребления |
| STANDARD (STD) | знаковое; также реактивная и полная мощность | банки снимков или разности счётчиков — экспорт сохраняется (импорт и экспорт учитываются отдельно) | Знаковое чистое значение (отрицательное = чистый экспорт) |
Подробности — в главе 02 · Линейки модулей. На уровне компонента используется один и тот же дескриптор rbamp_handle_t независимо от линейки — rbamp_begin() определяет линейку модуля (rbamp_line()); различия видны в значениях, которые возвращает модуль, и в дополнительных вызовах rbamp_std_*, которые предлагает модуль STD.
Двунаправленный учёт на BASIC: rbamp_energy_wh(dev, ch) на линейке BASIC даёт только потребление. Если нужно учитывать экспорт отдельно, опрашивайте мощность RT rbamp_read_power(dev, 0, &p) примерно с 10 Гц и разделяйте положительные и отрицательные отсчёты по двум переменным-накопителям самостоятельно. Пример — в 06_examples.md (сценарий 9, «Двунаправленный учёт на стороне мастера»).
Что делает этот компонент
esp_timer_get_time().
Компонент также берёт на себя учёт периодов: он делает снимок, ждёт установления модуля, проверяет валидность снимка и интегрирует Wh по часам мастера (rbamp_read_period_snapshot() и rbamp_energy_wh(), см. 05 · Быстрый старт, шаг 5). Сравнение на уровне регистров («без компонента»), диаграмма архитектуры, диаграммы взаимодействия и таблица соответствия — в 09 · Справочник API, приложение «Под капотом».
Журналирование и Kconfig
В отличие от библиотеки Arduino, где поток журнала настраивается во время работы (setLogStream(&Serial)), здесь используется стандартный шаблон ESP-IDF: компонент пишет в журнал под тегом "rbamp" через esp_log. Уровень журнала задаётся при сборке через выбор Kconfig CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, по умолчанию INFO). На NONE строки журнала полностью удаляются из бинарного файла.
Фильтрация во время работы тоже работает (через esp_log_level_set("rbamp", ...)), но сверху её ограничивает уровень, заданный на этапе компиляции.
Шесть символов CONFIG_RBAMP_* доступны в idf.py menuconfig → Component config → rbAmp client:
| Символ | Цель | По умолчанию |
|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
Частота SCL для общей шины | 50000 (50 кГц) |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
таймаут передачи/приёма | 100 мс |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
попыток повтора на одно однобайтовое чтение | 3 |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
пауза между попытками повтора | 5 мс |
CONFIG_RBAMP_DISABLE_ENERGY |
убрать накопитель Wh из сборки | n |
CONFIG_RBAMP_LOG_LEVEL_* |
уровень строк журнала, заданный при сборке | INFO |
Подробнее см. в 09 · Справочник API, раздел «Конфигурация на этапе компиляции».
Что дальше
- 02 · Линейки модулей — какая линейка для какой задачи
- 04 · Подключение — подтяжки, длина шины, распиновка семейства ESP32
- 05 · Быстрый старт — ваш первый рабочий проект
- 06 · Примеры — разборы готовых проектов IDF
- 09 · Справочник API — каждая публичная функция
- 10 · Устранение неполадок — когда что-то не работает
Исходный код и вопросы: rb-amp/rbamp-esp-idf · эта страница в репозитории: docs/01_overview.md (v1.7.3)