02 · Уровни модулей
Что такое линейка модулей
Проверьте метку на вашем модуле; dev.line() выводит линию после begin().
rbAmp выпускается линейками модулей: BASIC и STANDARD (STD). Линейка модуля — полная пара ревизии аппаратуры и прошивки, а не программный флаг. Переход между линейками требует физической смены SKU, а не обновления прошивки.
С точки зрения библиотеки и вашего кода: один класс RbAmp обслуживает обе выпускаемые линейки. begin() определяет, является ли модуль BASIC или STANDARD (STD), и направляет каждый вызов внутри себя; общие методы (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) работают на обеих. Линия STD добавляет собственные вызовы: реактивная и полная мощность, поканальное чтение блоков, знаковые счётчики энергии за весь срок службы; см. 09 · Справочник API.
Текущее состояние
Уровень BASIC и линейка STANDARD (STD) — выпускаемые линейки модулей; эта библиотека поддерживает обе (STANDARD (STD) — с библиотеки 1.6.0, см. README).
| Уровень | Серийная |
|---|---|
| BASIC | ✅ да |
| STANDARD (STD) | ✅ да (библиотека 1.6.0+) |
BASIC — базовый уровень для бытового учёта
Аппаратное обеспечение
Экономичный аналоговый тракт для типичных бытовых нагрузок. Модуль включает изолированный аналоговый фронтенд, встроенный стабилизатор питания и заводскую калибровку, хранящуюся во флеш.
Поведение прошивки
Логика классического механического дискового счётчика — счёт идёт только вперёд; экспорт в сеть не вычитается.
Три "слоя" значений активной мощности ведут себя по-разному:
| Сигнал | Значение | Поведение на BASIC |
|---|---|---|
dev.readPower(ch) |
мгновенная мощность RT, обновляется примерно каждые 100 мс | знаковая — отрицательное значение видно в реальном времени (экспорт) |
PERIOD_AVG_P_W (внутри readPeriodSnapshot) |
средняя мощность за период | среднее P каждого окна 100 мс обрезается до max(P, 0) перед добавлением в накопитель периода |
dev.energy().wh(ch) |
Wh, накопленный библиотекой | монотонно — только потребление; экспорт не учитывается |
Иными словами: пользователь видит экспорт в показаниях RT, но в счётчике Wh библиотеки на BASIC его нет.
Типичные сценарии использования
-
Домохозяйства без собственной генерации (без солнечных панелей, ветрогенераторов или аккумуляторных систем)
-
Счётчики для чисто потребляющих нагрузок (водонагреватели, двигатели, бытовая техника)
-
Система мониторинга потребления, где двунаправленный учёт не нужен
Двунаправленный учёт на BASIC (на стороне мастера)
Если нужно отдельно учитывать экспорт в сеть на модуле BASIC, делайте это на стороне мастера. Мощность RT dev.readPower(0) знаковая, поэтому:
double consume_wh = 0.0;
double export_wh = 0.0;
uint32_t t_prev_ms = millis();
void loop() {
// Sample RT power at 10 Hz — matches the firmware-commit cadence
// (100 ms per channel). Faster gives empty repeat reads; slower
// loses resolution on abrupt load transitions.
//
// delay() blocks the loop — incompatible with concurrent work
// (LCD refresh, MQTT, networking). For sketches with other tasks,
// replace it with a non-blocking millis() / scheduler pattern.
delay(100);
uint32_t t_now_ms = millis();
float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
t_prev_ms = t_now_ms;
float p = dev.readPower(0);
if (isnan(p)) return;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0) consume_wh += dwh;
else export_wh += -dwh;
}
Полный рабочий пример — в 06_examples.md (сценарий BidirectionalEnergy) и в examples/06_BidirectionalEnergy/.
STANDARD (STD) — двунаправленная линия
Модули STANDARD (STD) — выпускаемая линейка модулей. Библиотека определяет их в begin() (dev.line() == RbAmpLine::Std) и использует ту же проводку и тот же общий API, что и BASIC (см. 04 · Подключение).
Что добавляет линия STD
На модуле STD с сохранёнными счётчиками API периода/снимков и энергия берутся из собственных счётчиков модуля (старые образы STD используют банки снимков модуля); класс модели CT на STD — только метка и не задаёт усиления.
-
Знаковая энергия: импорт и экспорт учитываются раздельно. На модулях, которые хранят сохранённые пожизненные счётчики,
dev.energy()иreadPeriodSnapshot()берут собственные значения модуля (wh_net= импорт − экспорт), аstdReadEnergy()отдаёт сырые счётчики (Wh, mWh и, на образах, которые их предоставляют, µWh / µvarh). -
Больше величин (на BASIC реактивная мощность этой библиотекой не выводится):
readReactivePower(ch),readApparentPower(ch),stdReadChannel(ch)(I / P / Q / S / PF / пик одним пакетом) и, если включены, величины на основе гармоник (THD, коэффициент смещения). -
Модули с несколькими токовыми каналами / несколькими напряжениями: число каналов берётся из модуля;
stdReadVoltage(v), итоги по фазам —stdReadTotals(k). -
Диагностика и обслуживание:
stdReadHealth(), часы модуля, история и журнал событий, идентификация по UID, обновление прошивки по I²C.
Всё это перечислено вызов за вызовом в 09 · Справочник API § API линейки STD.
Некоторые функции STD зависят от версии образа модуля: счётчики энергии микроразрешения, пусковой ток для энергии, фазовые углы напряжения и порядок фаз требуют версии образа не ниже 0x0001007B (dev.stdReadImageVersion()); на более старом образе они сообщаются как «недоступно». Вызовы только для STD на модуле BASIC возвращают RB_ERR_NOT_IMPLEMENTED.
Типичные сценарии использования
- Дома с солнечной генерацией на крыше
- Дома с ветрогенераторами
- Системы накопления энергии в батареях
- Регенеративные нагрузки
- Зарядка электромобилей V2G (vehicle-to-grid)
Как определить линию во время работы
if (!dev.begin()) { /* see dev.errorString() */ }
// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line(); // RbAmpLine::Basic / RbAmpLine::Std
// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();
// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();
// Number of current channels
uint8_t channels = dev.channels();
// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant(); // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
: line() сообщает BASIC или STANDARD (STD). Остальные показатели (версия прошивки, число каналов, датчик напряжения, SKU) описывают аппаратную часть. Этикетка SKU на корпусе модуля остаётся источником истины о продукте.
Где в документации помечены пункты, зависящие от класса модуля
По всему тексту библиотеки и каноническим документам возможности, зависящие от уровня, отмечены явно, например:
— этого нет на модуле BASIC.
Или, наоборот, поведение, специфичное для BASIC:
: счётчик dev.energy().wh(ch) монотонный — экспорт в сеть не учитывается. Для двунаправленного учёта см. пример BidirectionalEnergy или используйте модуль STANDARD (STD).
Что дальше
-
03 · Выбор токового датчика — какой SCT-013 для какой задачи
-
04 · Подключение — подробности по аппаратной части
-
06 · Примеры — сценарии для BASIC, включая двунаправленный учёт на стороне мастера
-
09 · Справочник API — полный публичный API
Исходный код и задачи: rb-amp/rbamp-arduino · эта страница в репозитории: docs/02_tiers.md (v1.6.2)