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

02 · Уровни модулей

Линейки модулей BASIC и STANDARD (STD) бок о бок: энергия на мастере для BASIC, на модуле для STD.

Что такое линейка модулей

Проверьте метку на вашем модуле; 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 (потребление на модуле, экспорт интегрируется на мастере) и на STANDARD (STD) (счётчики импорта, экспорта и нетто на модуле).

Если нужно отдельно учитывать экспорт в сеть на модуле BASIC, делайте это на стороне мастера. Мощность RT dev.readPower(0) знаковая, поэтому:

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

Как определить линию во время работы

Как узнать, какая линия модулей у вас: прочитайте метку или вызовите line() после begin().

C++
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 на корпусе модуля остаётся источником истины о продукте.

Где в документации помечены пункты, зависящие от класса модуля

По всему тексту библиотеки и каноническим документам возможности, зависящие от уровня, отмечены явно, например:

Только STANDARD (STD)

— этого нет на модуле BASIC.

Или, наоборот, поведение, специфичное для BASIC:

BASIC

: счётчик dev.energy().wh(ch) монотонный — экспорт в сеть не учитывается. Для двунаправленного учёта см. пример BidirectionalEnergy или используйте модуль STANDARD (STD).

Что дальше


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