01 · Обзор
Что такое rbAmp
rbAmp — компактный аппаратный модуль для прецизионного измерения параметров сети переменного тока по интерфейсу I²C. Имеет встроенный изолированный аналоговый тракт и заводскую калибровку, хранящуюся во флеш.
С точки зрения интегратора модуль ведёт себя как стандартное ведомое устройство I²C: подключите питание, читайте регистры, и вы получите готовые значения в физических единицах. Обработка сигнала на стороне мастера не требуется.
Главное назначение библиотеки — мониторинг нескольких нагрузок
Библиотека RbAmp Arduino создана для работы с группой модулей одновременно на одной шине I²C, а не для управления одним устройством. Типичный сценарий — один главный модуль на вводе сети плюс N модулей на отдельных нагрузках, все на одной шине, под управлением одного Arduino/ESP32. Библиотека предоставляет класс RbAmpFleet — один объект, через который вы сканируете шину, опрашиваете все модули одним вызовом, получаете суммарную потребляемую мощность и баланс «ввод − Σ(нагрузки)», отлавливаете ошибки каждого модуля и при необходимости синхронизируете снимки периодов широковещательной командой.
Многоканальные модули тоже поддерживаются — только ток I2 / I3 (два или три ТТ) и модули с напряжением UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 токовых каналов, с мощностью, PF и Wh по каждому каналу). У каждого канала своя модель датчика. Это типично для субщита, где одна точка установки контролирует несколько фидеров.
Работа с одним модулем — минимальный случай той же библиотеки: класс RbAmp — строительный блок, поверх которого надстроен RbAmpFleet. Если на шине один модуль, используйте тот же дескриптор напрямую — API флота не нужен.
Сценарий 80% — ввод сети + N субнагрузок
- 1 модуль на вводе в сеть — общее потребление и качество сети.
- N модулей на отдельных нагрузках — поканальный учёт.
- Многоканальные модули тоже подходят для этого случая: один
UI2/UI3/UI5/UI7(илиI2/I3) может учитывать несколько нагрузок, каждую на своём канале — N модулей не обязательно означают N нагрузок. -
Один вызов
fleet.pollAll()опрашивает всё; балансmains − Σ(sub_loads)показывает «остальное» (фоновое потребление, неучтённые нагрузки, утечки). -
Общая метка времени мастера → корректный учёт Wh без дрейфа между модулями (см. 02_tiers.md и раздел о часах мастера в 09_api_reference.md).
Важная архитектурная деталь. Варианты I (I1/I2/I3) измеряют только ток — у них нет напряжения, активной мощности и PF. Активная энергия (Wh) и мощность считаются только на UI-вариантах (у которых есть входной каскад напряжения). В каноническом развёртывании роль «счётчика сети» (учёт по тарифам и периодам) играет один UI1 на вводе в сеть; роль суб-счётчика (детализация тока по нагрузкам) — модули I2/I3 (или UI2 / UI3 / UI5 / UI7, когда нужны мощность и Wh по каждой нагрузке).
Подробности — в главе 06 · Примеры, сценарий 1 («Сеть + N поднагрузок — канон 80%»). Для API — в главе 09 · Справочник API, раздел «Fleet manager».
Что измеряет rbAmp
| Величина | Тип | Диапазон |
|---|---|---|
| Действующее напряжение U_rms | float32, V | 0…300 V |
| Пиковое напряжение U_peak | float32, V | 0…450 V |
| Действующий ток I_rms | float32, A | зависит от выбранного датчика — см. 03_sensor_selection.md |
| Пиковый ток I_peak | float32, A | зависит от выбранного датчика |
| Активная мощность P (знаковая в RT) | float32, W | зависит от выбранного датчика |
| Коэффициент мощности PF | float32 | −1…+1 |
| Частота сети | uint8, Гц | 50 / 60 Гц (определяется) |
| Усреднённая за период P | float32, W | как для P |
Значение RT активной мощности P всегда знаковое на любом уровне модуля (отрицательное означает экспорт в сеть). Поведение усреднённого за период значения (PERIOD_AVG_P_W) зависит от уровня модуля — см. раздел «Уровни модулей» ниже и 02_tiers.md.
Подключение
Модуль подключается к мастеру четырьмя проводами на низковольтной стороне; всё, что касается сети, остаётся внутри корпуса.
| Провод | Цель |
|---|---|
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), на 100 кГц (UNO / Mega / STM32 / RP2040) или 50 кГц (ESP32 / ESP8266); не используйте 400 кГц. Холодный старт до первого корректного измерения — около 250 мс.
Полные правила (длина шины, рекомендации по подтяжкам на шине из нескольких модулей, схемы проводки для разных хостов) — в главе 04 · Подключение.
Уровни модулей (краткая шпаргалка)
Уровень BASIC реализует односторонний (только потребление) учёт по логике классического механического счётчика; линейка STANDARD (STD) — вторая выпускаемая линейка модулей со знаковой (импорт / экспорт) энергией:
| Уровень | Мощность RT P |
Накопитель за период PERIOD_AVG_P_W |
Счётчик Wh библиотеки |
|---|---|---|---|
| BASIC | со знаком (отрицательное = экспорт в сеть, видно в реальном времени) | каждое 100-мс окно средней P ограничивается снизу значением max(P, 0) перед добавлением к накопителю периода |
монотонно — учитывает только потребление |
| STANDARD (STD) | знаковое | импорт и экспорт учитываются раздельно (банки снимков или сохранённые счётчики модуля за весь срок) | чистая энергия = импорт − экспорт (wh_net, stdReadEnergy()) |
Подробности — в главе 02 · Уровни модулей. На уровне библиотеки используется один и тот же класс RbAmp независимо от уровня; различия проявляются в значениях, которые возвращает модуль.
Двунаправленный учёт на BASIC: dev.energy().wh(ch) библиотеки на уровне BASIC даёт только потребление. Если экспорт нужно учитывать отдельно, снимайте мощность RT dev.readPower(0) примерно с 10 Гц и разделяйте положительные и отрицательные отсчёты по двум переменным-накопителям самостоятельно. Пример — в 06_examples.md (сценарий BidirectionalEnergy).
Что делает эта библиотека
Главная задача — скрыть протокольный обмен и избавить пользовательский скетч от рутины работы с регистрами, порядком байт и временами установления после команд. Кроме того, библиотека вычисляет энергию (Wh): модуль отдаёт только усреднённую за период мощность, интегрирование мастер делает по своим часам.
Собираете для ESPHome? Используйте внешний компонент вместо этой библиотеки напрямую — он нативно встраивает протокол rbAmp в конвейер ESPHome YAML.
Без библиотеки (прямой доступ к регистрам)
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);
С библиотекой
float u_rms = dev.readVoltage();
Чтение периода — без библиотеки
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27); // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50); // settling time after the command
Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
// snapshot is stale — t_latch_ms must STILL be recorded,
// otherwise the next snapshot will count Wh over two periods
t_prev_latch_ms = t_latch_ms; // <-- this line is easy to forget
return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
// float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
// E_Wh += avg_p × dt_s / 3600.0f;
Чтение периода — с библиотекой
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
// snap.avg_p[0] is filled,
// dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
// master_dt_ms is accounted for and saved for the next cycle.
}
Внутри библиотека гарантирует:
-
Время установления 50 мс после
CMD_LATCH_PERIODи корректное чтение снимка (атомарный снимок на стороне модуля). -
Проверка флага
PERIOD_VALIDперед чтением. -
Фиксация времени по часам мастера даже при устаревшем снимке (защищает от двойного учёта Wh в следующем периоде).
-
Побканальное накопление Wh с двойной точностью.
- Автоматическая загрузка коэффициентов калибровки при выборе токового датчика через
setSensorClass(class)+setCTModel(code)— пользователю не нужно знать о регистрах NF/GAIN.
Когда использовать библиотеку, а когда прямой доступ к регистрам
| Задача | Библиотека | Прямой доступ к регистрам |
|---|---|---|
| Чтение U / I / P / PF / частоты | ✅ | только для отладки на логическом анализаторе |
| Учёт энергии за период | ✅ | только если Wh хранятся вне библиотеки (например, в базе данных на стороне мастера) |
| Несколько модулей на одной шине | ✅ | — |
| Двунаправленный учёт на BASIC | ✅ (через чтения RT — см. 06_examples.md) | альтернатива — собственный цикл чтений RT и ручное интегрирование |
| Перенос на платформу, отличную от Arduino | n/a | ✅ — см. 09 · Справочник API, раздел «Детали протокола провода» |
| Жёсткий предел ОЗУ (AVR Uno) | ~42 Б на каждый экземпляр RbAmp + 63 Б на снимок; реализуемо, но тесно на многомодульной системе (3 модуля × ~42 Б + 3 × 63 Б ≈ 315 Б уже заметно занимают бюджет RAM приложения) |
✅ если экземпляр библиотеки не помещается |
Для всех типовых задач из первых строк таблицы библиотека подходит идеально.
Архитектура
Диаграммы взаимодействия
Ход begin()
Первый снимок — праймер (модуль возвращает всё накопленное с включения, что не подходит для тарифного учёта). Библиотека сама помечает, что этот снимок нужно отбросить — пользовательский код этого никогда не видит.
Поток readPeriodSnapshot(snap)
Атомарный снимок на стороне модуля гарантирует, что каждое измерение внутри периода попадает ровно в один снимок — без дублирования и без потерь на границе периода.
Соответствие прямому API регистров
Таблица для тех, кто переходит со своей разработки на прямом доступе:
| Прямой API | Эквивалент через библиотеку |
|---|---|
Ручное чтение 4 байт + memcpy |
dev.readVoltage() / dev.readPower(ch) |
Wire.write(0x01); Wire.write(0x27); delay(50) |
dev.latchPeriod(); delay(50) (или просто dev.readPeriodSnapshot()) |
Проверка Wire.read(0x07) & 1 |
dev.isPeriodValid() |
Ручная формула E_Wh += avg_p × dt_s / 3600 |
dev.energy().wh(0) — обновляется автоматически |
| Ручная настройка токового датчика через прямой API регистров | dev.setSensorClass(class) + dev.setCTModel(code) — заводские предустановки загружаются автоматически |
Что дальше
- 02 · Уровни модулей — какой уровень для какой задачи
- 04 · Подключение — подтяжки, длина шины, конфигурация с несколькими модулями
- 05 · Быстрый старт — первый рабочий скетч
- 06 · Примеры — обзор готовых скетчей
- 09 · Справочник API — каждый публичный метод
- 10 · Устранение неполадок — когда что-то не работает
Исходники и задачи: rb-amp/rbamp-arduino · эта страница в репозитории: docs/01_overview.md (v1.6.2)