rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub (Edit on GitHub)

01 · Обзор

Схема сигнала от токового клеща через модуль rbAmp и I²C к мастеру, далее в облако или Home Assistant.

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

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

  • 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.

Без библиотеки (прямой доступ к регистрам)

C++
// 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);

С библиотекой

C++
float u_rms = dev.readVoltage();

Чтение периода — без библиотеки

C++
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;

Чтение периода — с библиотекой

C++
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 приложения) ✅ если экземпляр библиотеки не помещается

Для всех типовых задач из первых строк таблицы библиотека подходит идеально.

Архитектура

Схема: скетч, библиотека RbAmp, Wire (I²C) и модуль rbAmp по адресу по умолчанию 0x50.

Диаграммы взаимодействия

Ход begin()

Последовательность begin(): чтение версии, определение линейки, праймер-снимок (отбрасывается), затем готовность.

Первый снимок — праймер (модуль возвращает всё накопленное с включения, что не подходит для тарифного учёта). Библиотека сама помечает, что этот снимок нужно отбросить — пользовательский код этого никогда не видит.

Поток readPeriodSnapshot(snap)

Последовательность readPeriodSnapshot(): библиотека закрывает период на модуле, читает снимок, интегрирует энергию по часам мастера и возвращает результат скетчу.

Атомарный снимок на стороне модуля гарантирует, что каждое измерение внутри периода попадает ровно в один снимок — без дублирования и без потерь на границе периода.

Соответствие прямому 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) — заводские предустановки загружаются автоматически

Что дальше


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