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

01 · Обзор

rbAmp — компактный аппаратный модуль для прецизионного измерения параметров сетевого переменного тока по интерфейсу I²C. Построен на микроконтроллере с интегрированным изолированным аналоговым входным каскадом и заводской калибровкой, хранимой во флеше.

Что такое 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 субнагрузок

Один мастер на общей шине I²C с модулем сети на вводе и модулями субнагрузок на отдельных ветвях, по одному клещу на модуль.

  • 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, «Двунаправленный учёт на стороне мастера»).

Что делает этот компонент

Временная шкала последовательных окон измерения по 100 мс, необязательных импульсов готовности данных и снимка периода по команде мастера.
Его главная задача — скрыть обмен по протоколу и избавить пользовательское приложение от рутины работы с регистрами, порядком байтов и временами установления после команд. Кроме того, компонентвычисляет энергию (Wh)— модуль возвращает только усреднённую за период мощность, а интегрирование выполняет мастер через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, раздел «Конфигурация на этапе компиляции».

Что дальше


Исходный код и вопросы: rb-amp/rbamp-esp-idf · эта страница в репозитории: docs/01_overview.md (v1.7.3)