rbAmp
RU
Магазин
Документация

09 · Справочник API

Карта регистров модуля: адресное пространство страницы 0 от 0x00 до 0xFF.

Атомарный снимок периода: одна запись закрывает текущий период и открывает следующий.

Публичный API библиотеки RbAmp для Arduino по состоянию на v1.6.1. Один класс обслуживает обе линейки модулей — BASIC и STANDARD (STD): begin() определяет линию, и каждый вызов маршрутизируется внутри. Вызовы, существующие только на одной линии, помечены; вызов без аналога на определённой линии завершается с RB_ERR_NOT_IMPLEMENTED. Источник истины — заголовочные файлы src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (два последних генерируются автоматически и не должны редактироваться вручную).

Эта глава — справочник: сигнатуры, возвращаемые значения, побочные эффекты, крайние случаи. Рабочие примеры — в 06 · Примеры; для быстрого старта — 05 · Быстрый старт.

Заголовочные файлы

Включить Что он даёт
Все публичные типы (подключает остальные)
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent и структуры RbAmpStd* линии STD
RbAmpEnergy
Сгенерированный реестр моделей датчиков — коды моделей RBAMP_CT_* и rbamp_sensor_model_lookup()
Автогенерируемые константы протокола — RB_OK, RB_ERR_*, SETTLE_MS_*

Пользовательскому скетчу обычно достаточно #include — остальные файлы подтягиваются транзитивно.

На какой линии работает вызов?

Группа BASIC STD
Жизненный цикл, чтения в реальном времени (readVoltage … readAll), учёт по периодам, energy() да да
readReactivePower(), readApparentPower() нет (RB_ERR_NOT_IMPLEMENTED) да
Сеттеры класса датчика / модели ТТ, saveUserConfig(), смена адреса, reset() да да (модель CT — метка на STD, см. ниже)
factoryReset(), хелперы General-Call, хелперы меток, readCapability(), readCommitSeq(), readPeriodLatchMs() да нет (RB_ERR_NOT_IMPLEMENTED)
Линия готовности данных и события (setDrdyPin(), waitDataReady(), setEventMask() …) да да (зависит от образа модуля, см. ниже)
вызовы std* (API линейки STD) нет (RB_ERR_NOT_IMPLEMENTED) да
Коррекция номинала SCT-013 (sctRating*()) да (класс SCT-013, старые прошивки BASIC) никогда не применялось (масштаб 1)

Некоторые возможности STD зависят от версии образа модуля: микроэнергетические счётчики, стартовый ток для энергии, фазовые углы напряжения и порядок фаз требуют образ не ниже 0x0001007B (stdReadImageVersion()). На более старом образе библиотека сообщает о них как «недоступно» (флаг valid равен false, производное значение или RB_ERR_NOT_IMPLEMENTED) — но никогда как неверное число.

Класс RbAmp

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

Конструктор

C++
explicit RbAmp(TwoWire& bus,
               uint8_t addr = 0x50,
               RbAmpTopology hint = RbAmpTopology::Single) noexcept;
Параметр Описание
bus Ссылка на шину TwoWire (обычно Wire). Вызывающий код должен вызвать bus.begin() ДО begin().
addr 7-битный адрес ведомого. Диапазон 0x08..0x77, по умолчанию 0x50.
hint Подсказка топологии: число токовых каналов (1/2/3). На прошивке старше v1.3 begin() не может надёжно определить вариант, поэтому подсказка используется как запасной вариант для многоканальных артикулов. По умолчанию Single — безопасное значение, которое не вызывает ложных чтений отсутствующих каналов. Для многоканальных модулей на прошивке старше v1.3 передавайте соответствующую подсказку явно.

Конструктор не генерирует трафика I²C.

Методы жизненного цикла

bool begin() noexcept

Опросить устройство, определить его линейку продуктов и вариант, подготовить снимок.

Sequence:

  1. Сначала проверка идентичности STD. Если модуль отвечает как модуль STD, число каналов берётся из самого модуля, банк снимков 0 взводится и подготавливается, и begin() возвращается — шаги BASIC ниже пропускаются.

  2. Прочитайте REG_VERSION (0x03). Если устройство не подтвердило (ACK) — false с RB_ERR_NACK. Если вернуло 0x00 / 0xFF — false с RB_ERR_VERSION.

  3. Кэшируйте топологию: байт варианта модуля на прошивке, которая его отдаёт, иначе подсказка конструктора hint. После этого topology() / channels() возвращают корректные значения без обращения к шине. Число каналов никогда не превышает RBAMP_MAX_CHANNELS (7); каналы сверх этого не открываются, и обращение к ним возвращает RB_ERR_PARAM.

  4. Прочитайте U_rms, чтобы определить, есть ли датчик напряжения (порог 1.0 В).

  5. Запишите CMD_LATCH_PERIOD как праймер и ждите 50 мс. Первый снимок после включения отбрасывается (он не передаётся пользовательскому коду — в нём смешаны данные до включения).

  6. Сохраните millis() для последующего интегрирования энергии.

  7. На модуле BASIC с классом SCT-013 прочитайте поканальную коррекцию номинала (см. коррекция номинала SCT-013). Если модуль находится в состоянии, требующем перезапуска для применения правильного усиления, begin() перезапустит его один раз.

Идемпотентно: безопасно вызывать повторно.

Возвращает: true при успехе; иначе false — подробности см. в lastError().

bool probe() noexcept

Лёгкая проверка работоспособности. Одно чтение REG_VERSION без побочных эффектов.

Возвращает: true, если ведомый подтвердил (ACK) и сообщил поддерживаемую версию (не 0 и не 0xFF).

bool waitReady(uint32_t timeout_ms = 1000) noexcept

Опрашивает флаг готовности модуля, пока не установится бит 0. Полезно после включения питания — модулю может понадобиться до одного окна измерения (100 мс), чтобы зафиксировать первые данные.

Возвращает: true, если бит был замечен до истечения timeout_ms; иначе false с RB_ERR_TIMEOUT.

uint8_t firmwareVersion() noexcept

Возвращает: байт REG_VERSION (0x03). Известные значения BASIC: 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. Более поздние прошивки BASIC сообщают большие значения. 0 или 0xFF означают ошибку I²C (см. lastError()).

RbAmpLine line() const noexcept

Нативный протокол

BASIC или STD? (initialization)

Возвращает: линейку, которую определил begin() — RbAmpLine::Basic (значение до запуска begin()) или RbAmpLine::Std. Обращения к шине нет.

RbAmpTopology topology() const noexcept

Возвращает: закэшированную топологию. Обращения к шине нет.

uint8_t channels() const noexcept

Возвращает: число токовых каналов, 1..RBAMP_MAX_CHANNELS (7). На линейке STD число — то, что сообщает модуль, ограниченное RBAMP_MAX_CHANNELS.

bool hasVoltageHw() const noexcept

Возвращает: true, если датчик напряжения обнаружен при begin(). Кэшировано, без трафика.

uint8_t address() const noexcept

Возвращает: текущий 7-битный адрес I²C. Обновляется после успешного commitAddressChange().

uint8_t rawTopology() noexcept

Прямое чтение REG_TOPOLOGY (0x24). В отличие от topology(), это делает транзакцию I²C.

Returns:

  • 1/2/3 — SINGLE/SPLIT_PHASE/THREE_PHASE.
  • 0xFF — ошибка I²C.
Примечание

Для полного определения артикула используйте readVariant() (читает REG_HW_VARIANT 0x55) — см. Идентификация и настройка.

Чтения реального времени (блок RT, обновление 100 мс)

Синхронизация окон реального времени: окна по 100 мс подряд, один короткий импульс DRDY на окно и блок результата, прочитанный одной пачкой.

Все методы возвращают float. При ошибке возвращают NAN и выставляют lastError(). Для устойчивости к редким сбоям на линии ESP-IDF под капотом используется повтор и фильтр корректности (см. диагностические счётчики ниже). Модуль публикует новые значения один раз за окно измерения: 100 мс (прошивка BASIC до v1.2 и образы STD до 0x7B: 200 мс).

float readVoltage(uint8_t phase = 0) noexcept

Мгновенное среднеквадратичное напряжение. phase равна 0 на линейке BASIC; на линейке STD это 0 .. n_voltage-1 (см. stdInfo()). Фаза вне диапазона возвращает NAN с RB_ERR_PARAM.

float readVoltagePeak(uint8_t phase = 0) noexcept

Пиковое напряжение за окно RT. То же правило для phase.

float readCurrent(uint8_t ch = 0) noexcept

Мгновенный действующий ток на канале. ch должен быть меньше channels(), иначе NAN с RB_ERR_PARAM. Сюда входит любой канал, начиная с RBAMP_MAX_CHANNELS (7) и выше.

float readCurrentPeak(uint8_t ch = 0) noexcept

Пиковый ток на канале за окно RT.

float readPower(uint8_t ch = 0) noexcept

Мгновенная активная мощность на канале. Знаковая — отрицательное значение означает экспорт (нагрузка отдаёт мощность обратно в сеть, актуально для PV / двунаправленных установок).

float readPowerFactor(uint8_t ch = 0) noexcept

Коэффициент мощности на канале. Безразмерный, диапазон −1..+1.

float readReactivePower(uint8_t ch = 0) noexcept — только STD

Реактивная мощность канала, в var, со знаком. На BASIC реактивная мощность этой библиотекой не выводится: вызов возвращает NAN с RB_ERR_NOT_IMPLEMENTED.

float readApparentPower(uint8_t ch = 0) noexcept — только STD

Полная мощность на канале, в ВА. На модуле BASIC возвращает NAN с RB_ERR_NOT_IMPLEMENTED.

float readFrequency() noexcept

Частота сети, в Гц.

bool readAll(RbAmpSnapshot& out) noexcept

Полный блок RT одним вызовом в структуру RbAmpSnapshot. Эквивалентен последовательным вызовам readVoltage() + readVoltagePeak()

  • readCurrent(0..N) + readCurrentPeak(0..N) + readPower(0..N) + readPowerFactor(0..N) + readFrequency(). Неиспользуемые каналы (за пределами channels()) заполняются нулями.

Одно поле, которое прочитано, но не проходит физический фильтр корректности, устанавливается в NAN и помечается в out.implausible (биты RBAMP_FIELD_*); остальной снимок остаётся пригодным.

Возвращает: true, если чтение транспорта не отказало; иначе false, а lastError() хранит код первой ошибки.

Периодический учёт

Общую картину см. в 01 · Обзор, минимальный шаблон — в шаге 5 05 · Быстрый старт.

bool latchPeriod() noexcept

Записывает CMD_LATCH_PERIOD (0x27) в REG_COMMAND. Не ждёт: вызывающий код сам должен выдержать установление 50 мс и проверить isPeriodValid() перед чтением.

Для большинства задач используйте readPeriodSnapshot() — он инкапсулирует всю последовательность.

Возвращает: true при успешной записи.

bool isPeriodValid() noexcept

Читает бит готовности снимка. true, если последний снимок свежий и готов к чтению.

float readPeriodAvgPower(uint8_t ch = 0) noexcept

Средняя активная мощность канала за закрытый период. Вызывается после latchPeriod() + 50 мс установления + проверки готовности.

float readPeriodMaxPower() noexcept

Пиковая мгновенная мощность на канале 0 за закрытый период.

uint32_t readPeriodLatchMs() noexcept

Длительность периода с точки зрения устройства, в мс.

Диагностическое значение.

latch_ms — диагностический таймер модуля; не используйте его для энергии, берите часы мастера (master_dt_ms из RbAmpPeriodSnapshot).

bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept

Рекомендуемая точка входа для учёта по периодам. Полная последовательность внутри:

  1. Если skip_latch == true — записи команды снимка пропускаются (применяется после broadcastLatch() или ручной серии команд снимка).

  2. Иначе — запишите CMD_LATCH_PERIOD.

  3. Снимите millis(), чтобы вычислить master_dt_ms.
  4. delay(settle_ms) — по умолчанию 50 мс согласно спецификации протокола.

  5. Проверьте флаг готовности снимка. Если 0 — установите RB_ERR_STALE и запишите метку времени (чтобы следующий снимок не задвоил учёт на dt).

  6. Прочитайте avg_p[0..channels-1] + max_p + latch_ms.

  7. Обновите отметку времени и вызовите energy().tick(out, channels_) для автоматического интегрирования Wh.
Параметр Описание
out Структура вывода.
settle_ms Ожидание после команды снимка, по умолчанию 50.
skip_latch Если true — не отправляйте команду снимка, только читайте (для синхронизированной сцены из нескольких плат).

Возвращает: true, если out.valid == true; false, если чтение не удалось или снимок устарел.

На линии STD установление после снимка поднимается до не менее 300 мс (модуль обслуживает снимок на следующей границе окна измерения), latch_ms равен 0, а master_dt_ms — это период. На модуле STD, который хранит сохранённые пожизненные счётчики вместо банков снимков, период — разность двух показаний счётчика по расписанию мастера; avg_p_total, wh_net и module_restarted снимка заполняются там.

Учёт энергии (накопитель на стороне мастера)

RbAmpEnergy& energy() noexcept

const RbAmpEnergy& energy() const noexcept

Доступ к поканальному накопителю Wh этого экземпляра RbAmp. Накопитель обновляется автоматически при каждом успешном readPeriodSnapshot(). Подробности — в разделе «Класс RbAmpEnergy» ниже.

double energyWh(uint8_t ch = 0) const noexcept

Текущий итог энергии канала, как energy().wh(ch), — за исключением модуля STD, который хранит сохранённые счётчики, но не публикует разбиение по каналам (больше одного канала, более старая карта регистров): запрос по каналу возвращает там NaN, а не 0, который читался бы как «ничего не потреблено». Для итога по всем каналам используйте RBAMP_ENERGY_CH_TOTAL как ch.

Конфигурация датчика

Двухшаговая последовательность: сначала класс датчика, затем модель. Оба шага обязательны на прошивке BASIC v1.2 и новее.

Подробное руководство по выбору модели — в 03 · Выбор токового датчика.

Примечание

Модель CT — функциональный пресет на BASIC, метка на STD. На модуле BASIC запись модели CT сразу применяет соответствующий пресет — показания тока меняются. Смена RbAmpSensorClass сбрасывает модели CT каналов в 0 на модуле. На модуле STD модель — только справочная (метка датчика): она не задаёт усиления, потому что модуль калибруется по каналам.

Чтение перед записью. Сеттеры сначала читают модуль. Запись класса или модели, которые модуль уже содержит, — пустая операция (true, без записи на шину и без цикла записи во флеш), поэтому сохранённую конфигурацию можно переприменять при каждой загрузке, не трогая калибровку модуля. Модуль класса WiredCT или BuiltinCT (поставляется и калибруется вместе со своим датчиком) не переконфигурируется: сеттер возвращает false с RB_ERR_MODE и ничего не пишет. Сервисный путь — setCTModelChForce().

Установка модели ТТ перезапускает модуль. На прошивке BASIC до 1.4.19 включительно с классом SCT-013 вызовы setCTModel() (обе формы) и configureChannels() перезапускают модуль после сохранения, чтобы новая модель вступила в силу (всего около секунды, блокирующе), затем заново считывается коррекция номинала. Не вызывайте их в цикле и не ждите показаний в это время.

bool setSensorClass(RbAmpSensorClass cls) noexcept

Задать класс токового датчика с сохранением во флеш.

Последовательность: прочитать текущий класс модуля (чтение перед записью) → записать REG_SENSOR_CLASS (0x25) → CMD_SAVE_USER_CONFIG (0x32) → ожидать 700 мс (стирание флеша). Блокирующе. Допустимо для production — SAVE_USER_CONFIG не ограничен.

Должен вызываться до setCTModel(). Иначе setCTModel() возвращает false с RB_ERR_PARAM. Также сбрасывает модели CT в 0 на стороне устройства, поэтому модели задавайте после. На линейке STD класс — метаданные, сохраняемые вместе с сохранением конфигурации модуля, и действуют те же правила «сначала чтение».

Аргумент Значение
RbAmpSensorClass::Sct013 Токовый клещ серии SCT-013, установленный пользователем; модель выбирает тип датчика
RbAmpSensorClass::WiredCT проводной ТТ, поставляемый вместе с модулем и откалиброванный вместе с ним — сеттерами не переписывается
RbAmpSensorClass::BuiltinCT встроенный CT, откалиброванный вместе с модулем — сеттерами не перезаписывается

Возвращает: true при успехе или если модуль уже держит cls. false с RB_ERR_MODE, если модуль класса WiredCT / BuiltinCT.

bool readSensorClass(uint8_t& out) noexcept

Нативный протокол

4.3 Система (0x20..0x25) (api-reference)

Читает класс токового датчика модуля (значение RbAmpSensorClass; 0 = не задан). Работает на обеих линейках.

Возвращает: true при успехе.

bool setCTModel(uint8_t code) noexcept

Форма с одним параметром — задаёт модель токового клеща только на канале 0. Удобна для одноканальных SKU (UI1/I1); на многоканальных эквивалентна setCTModel(0, code).

Последовательность: запись REG_CT_MODEL (0x05) → CMD_SET_CT_MODEL_CH0 (опкод 0x28) → установление 5 мс → CMD_SAVE_USER_CONFIG (опкод 0x32) → 700 мс. Допустимо для production — использует путь сохранения пользовательской конфигурации, без ограничения заводским режимом.

Назовите модель сгенерированным define RBAMP_CT_* (из RbAmpSensorModels.h), например RBAMP_CT_SCT013_030:

Определение code Модель
RBAMP_CT_SCT013_005 1 SCT-013-005
RBAMP_CT_SCT013_010 2 SCT-013-010
RBAMP_CT_SCT013_030 3 SCT-013-030
RBAMP_CT_SCT013_050 4 SCT-013-050
RBAMP_CT_SCT013_100 5 SCT-013-100
RBAMP_CT_SCT013_020 6 SCT-013-020
RBAMP_CT_SCT013_060 7 SCT-013-060

code, которого нет в реестре для класса модуля → false с RB_ERR_PARAM и без записи. Код, который есть в реестре, но который модуль не принимает, отвергается модулем с RB_ERR_PARAM; канал сохраняет предыдущую модель. Полный набор допустимых кодов по классам см. в 03 · Выбор токового датчика.

Для многоканальных модулей используйте поканальную форму ниже.

bool setCTModel(RbAmpCTModel model) noexcept

Перегрузка для семи кодов SCT-013 через перечисление (RbAmpCTModel::Sct013_030 …). Эквивалентна setCTModel(static_cast(model)). Оставлена для обратной совместимости; новый код передаёт сгенерированный define RBAMP_CT_* в форме uint8_t — это единственный способ назвать модель проводного ТТ.

bool setCTModel(uint8_t channel, uint8_t code) noexcept

Побканальная форма. Задаёт модель токового клеща на конкретном канале, 0 .. channels()-1 (каналы 3 и выше — каналы старших SKU; им нужна прошивка BASIC v1.4.18 или новее).

Под капотом: запись REG_CT_MODEL (0x05) → команда CMD_SET_CT_MODEL_CH0/1/2 (опкод 0x28/0x29/0x2A) в зависимости от channel → 5 мс установление → CMD_SAVE_USER_CONFIG (опкод 0x32) → 700 мс. Допустимо для production — путь сохранения пользовательской конфигурации является производственным каналом сохранения для ct_model / sensor_class / ТТ по каналам. Каналы 3 и выше привязываются через окно каналов и читаются обратно; модель, которую модуль отклонил, сообщается как RB_ERR_PARAM. На прошивке старше v1.2 вызов возвращает RB_ERR_VERSION.

Примечание

Порядок вызовов на v1.3 произвольный. Запись REG_CT_MODEL (0x05) лишь ставит значение в staging — оно не применяется автоматически к каналу 0. Применение происходит исключительно через побканальный опкод CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), который копирует staging-значение в свой канал. Каналы можно настраивать в любом порядке — по возрастанию, по убыванию или вперемешку — без затирания:

C++
dev.setCTModel(0, RBAMP_CT_SCT013_005);   // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030);   // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020);   // channel 2

После привязки по нескольким каналам подтвердите результат через readCTModelCh(). Для пакетной конфигурации всех каналов с одним сохранением предпочтительнее configureChannels().

Защита RB_ERR_PARAM для предусловия setSensorClass(), так же как в форме с одним параметром. Канал на или за пределом channels() (и, значит, любой канал за RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. Правило «сначала чтение» и отказ RB_ERR_MODE действуют, как описано выше. На линейке STD модель — метка, записываемая в побканальную запись, читаемая обратно и сохраняемая вместе с сохранением конфигурации модуля; побочного эффекта на канал 0 нет.

Возвращает: true при успехе или когда канал уже содержит code.

bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept

Перегрузка побканальной формы с типизированным enum (только коды SCT-013).

bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept

Сервисный путь. То же, что setCTModel(channel, code), но записывает независимо от класса модуля и от модели, которую канал держит сейчас. Заменяет парную калибровку канала общим пресетом модели — используйте только при перепривязке модуля к новому датчику в сервисе и после этого выполните калибровку. Код, которого нет в реестре, по-прежнему отвергается (RB_ERR_PARAM, без записи).

Возвращает: true при успехе.

bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept

Читает модель CT, фактически применённую к каналу (зеркало проверки привязанного пресета). Используйте, чтобы подтвердить, что привязка прошла. out = 0 означает «не задано».

Возвращает: true при успехе.

Реестр датчиков — sensorModel() / sensorModelRatedA()

Чистые поиски в сгенерированном реестре (RbAmpSensorModels.h). Обращений к шине нет. Совпадение в реестре не означает, что подключённый модуль примет код — это решает модуль при записи.

C++
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;

sensorModel() возвращает запись реестра или nullptr, если (class, code) нет в реестре. Запись (rbamp_sensor_model_info_t) содержит sensor_class, code, name, descriptor, status (characterized / reserved / legacy) и текущие пределы nominal_a (номинальный действующий ток), fs_a (действующий ток в момент начала клипирования для синуса) и peak_a (мгновенный предел клипирования). 0 в пределе = для этой модели неизвестно.

sensorModelRatedA() возвращает номинальный действующий ток в амперах (0 = неизвестно). Покрывает семейство SCT-013 и модели клещей с указанным номиналом; устаревшие модели тороидов и нагрузочных резисторов возвращают 0.

C++
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);

Коррекция номинала SCT-013

В прошивке BASIC до 1.4.19 включительно модуль класса SCT-013 калибруется по SCT-013-030 и после перезапуска применяет этот откалиброванный коэффициент независимо от того, какую модель показывает канал. Библиотека это компенсирует: begin() считывает модель и применённый коэффициент каждого канала и задаёт для канала масштаб. Масштаб применяется к readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() и readPeriodSnapshot(), а значит, и к энергии, вычисленной из них. Коэффициент мощности и напряжение не затрагиваются. Границы правдоподобности и setEventThresholds() выражены в истинных амперах и ваттах.

Поэтому смена номинала SCT-013 (например, с 030 на 050) автоматически корректирует ток, мощность и энергию; напряжение и PF не меняются. Прошивка 1.4.20 и новее корректирует себя сама — масштаб остаётся 1, а запись модели не требует перезапуска. Модули STD и проводные / встроенные классы CT никогда не масштабируются.

bool sctRatingRefresh() noexcept

Перечитывает состояние номинала каждого канала из модуля. Библиотека уже делает это после того, как readEventFlags() сообщает EVENT_RESET_OCCURRED; вызывайте сами после перезапуска модуля, который вы заметили иным способом.

Возвращает: true, если модуль удалось прочитать.

bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept

Состояние одного канала: model, applied_gain, noise_floor, scale и status.

Возвращает: true, если channel корректен.

RbAmpSctRatingStatus Значение
NotApplicable Линия STD, класс, отличный от SCT-013, прошивка, которая корректирует себя сама, или модель не задана — масштаб 1
Native канал показывает модель, на которой модуль был откалиброван (030) — исправлять нечего, масштаб 1
Corrected другая модель SCT-013 на старой прошивке BASIC — показания масштабируются
Uncalibrated модуль применяет общую предустановку без собственной подстройки — только номинальная коррекция
UnexpectedGain применённое усиление не то, что ожидает коррекция — ничего не предполагается, масштаб 1
Unknown состояние не удалось прочитать — масштаб 1
float sctRatingScale(uint8_t channel) const noexcept

Коэффициент, применяемый к показаниям тока / мощности этого канала (1.0, когда ничего не корректируется, и для индекса канала за пределами RBAMP_MAX_CHANNELS).

static float sctPresetGain(uint8_t model) noexcept

Расчётный коэффициент предустановленного усиления для кода модели SCT-013; 0, если неизвестен. В основном полезно для диагностики.

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

См. Конфигурация нескольких каналов.

bool saveGains() noexcept — только в заводском режиме на BASIC

Голая запись CMD_SAVE_GAINS (0x26) — заводской путь сохранения коэффициентов калибровки (усиления / шумовой порог / фаза).

Безопасность

⚠ Только для заводской настройки на BASIC. ЗАБЛОКИРОВАНО в production. На производственном модуле BASIC CMD_SAVE_GAINS отвергается прошивкой — вызов возвращает false, REG_ERROR выставляется в DEV_ERR_PARAM (0xFE), а следующая перезагрузка откатывает записи только в RAM. Для всего пользовательского сохранения (класс датчика, модель ТТ по каналам, адрес, конфигурация флота, метка) используйте saveUserConfig() (CMD_SAVE_USER_CONFIG, опкод 0x32) — это допустимый для production путь сохранения. Пользовательский код в развёртывании не должен вызывать saveGains().

Линия STD: saveGains() выдаёт команду сохранения калибровки модуля, ждёт, пока модуль сообщит о завершении команды, и проверяет вердикт. Модуль пишет своё хранилище не чаще одного раза в 5 с; сохранение внутри этого окна повторяется один раз через 5 с.

Возвращает: true при успешной команде (производство BASIC: всегда false с RB_ERR_MODE).

bool prepareAddressChange(uint8_t new_addr) noexcept

Шаг 1 из 2 для смены I²C-адреса модуля. Безопасно для производства в текущей прошивке (двухфазный коммит v1.3, без ограничения по заводскому режиму для адреса).

Последовательность: проверьте диапазон new_addr (0x08..0x77, ≠ текущий) → запишите кандидата в REG_I2C_ADDRESS (0x30) в RAM → запишите магическое значение 0xA5 в REG_ADDR_COMMIT_MAGIC (0x31) — взведено. Вызывающий код должен вызвать commitAddressChange() в течение 5 секунд, иначе взведение истекает.

Возвращает: true, если взведение прошло успешно.

bool commitAddressChange() noexcept

Шаг 2 из 2. Должен быть вызван в течение 5 секунд после prepareAddressChange().

Последовательность: проверка свежести магически взведённого состояния → CMD_COMMIT_ADDR (opcode 0x30) → запись во флеш → CMD_RESET (0x01) → ~300 мс от загрузки до ответа → обновление внутреннего поля адреса. После этого все вызовы этого экземпляра адресуют новый адрес.

Безопасность

⚠ Повторное перечисление после коммита. После успешного коммита устройство перезагружается и перечисляется по НОВОМУ адресу. Последующие вызовы этого экземпляра RbAmp прозрачно адресуют новый адрес — но ЛЮБОЙ ДРУГОЙ мастер на шине (Python-скрипт, компонент ESP-IDF на другом MCU, отладочный зонд) будет считать, что устройство по-прежнему на старом адресе, пока его внутреннее состояние не обновят вручную.

⚠ Путь проверки (v1.3): после перезагрузки REG_I2C_ADDRESS (0x30) читает активный адрес. Скан шины по новому адресу тоже подтверждает фиксацию.

Смена адреса — это производственная операция (не только на заводе). Адрес I²C — документированный путь переконфигурации через заводской стенд (вне области библиотеки).

Дополнительное примечание для commitAddressChange():

Безопасность

⚠ Перезапуск и повторное перечисление после коммита. После успешного коммита устройство сбрасывается и перечисляется по НОВОМУ адресу. Последующие вызовы этого экземпляра RbAmp прозрачно адресуют новый адрес — но ЛЮБОЙ ДРУГОЙ мастер на шине (Python-скрипт, компонент ESP-IDF, отладочный зонд) будет считать, что устройство по-прежнему на старом адресе, пока его внутреннее состояние не обновят вручную.

Если окно взведения истекло, commitAddressChange() возвращает false с RB_ERR_TIMEOUT и сбрасывает флаг взведения — потребуется новый вызов prepareAddressChange().

Возвращает: true при успехе.

Линия STD: поле адреса записывается и сохраняется (вызов ждёт окончания сохранения; отклонённый адрес возвращает RB_ERR_PARAM, и модуль сохраняет прежний адрес), затем модуль сбрасывается. Экземпляр переключается на новый адрес только после того, как модуль ответит там (до 3 с). Если он вернётся на СТАРЫЙ адрес, экземпляр останется там и вернётся RB_ERR_NOT_READY.

bool factoryReset() noexcept

Команда CMD_FACTORY_RESET (0xAA) + ожидание 1500 мс.

Безопасность

⚠ Разрушающая операция. Стирает ВСЕ параметры флеша (модель ТТ, класс датчика, коэффициенты калибровки, адрес I²C). Модуль возвращается к заводским значениям: RbAmpSensorClass становится Unset, REG_CT_MODEL становится 0. Любая настройка, ранее заданная через setSensorClass() / setCTModel(), пропадает. Следующий пользователь ОБЯЗАН заново задать setSensorClass() и setCTModel(), прежде чем учёт снова заработает. Это не «мягкий перезапуск» — для него используйте reset(). factoryReset() предназначен для восстановления из заведомо плохого состояния или для передачи модуля другому пользователю или другой установке.

Возвращает: true при успешной записи команды.

Линия STD: аналога нет — вызов возвращает false с RB_ERR_NOT_IMPLEMENTED.

bool reset() noexcept

Команда CMD_RESET (0x01) + ожидание 100 мс. Мягкий перезапуск устройства без потери параметров из флеша.

Возвращает: true при успешной записи команды.

Линия STD: сначала ждёт завершения текущей команды (модуль никогда не перезагружается посреди сохранения), затем тихо ждёт (до 3 с), пока модуль снова ответит, и заново взводит путь периода.

Шина с несколькими модулями (статически)

static bool broadcastLatch(TwoWire& bus) noexcept

Отправляет широковещательный снимок I²C General-Call (A5 27 00 tick_lo tick_hi на адрес 0x00) — все модули с включённым GC одновременно берут снимок периода. В прошивке v1.3 GC поддерживается как опциональная возможность: включение по модулю через REG_FLEET_CONFIG.bit0 (по умолчанию выключено); карта возможностей модуля показывает, поддерживает ли он снимок General-Call. General-Call — функция линейки BASIC (помощники General-Call и меток возвращают RB_ERR_NOT_IMPLEMENTED на экземпляре STD).

Семантика возвратов:

  • Прошивка v1.3, GC включён хотя бы на одном модуле — возвращает true, флот снимает снимок синхронно (расхождение < 1 мс между модулями).

  • Прошивка v1.3, GC выключен на всех модулях — Wire.endTransmission() на 0x00 получает NACK на уровне шины → возвращает false. Исправление: включите GC по модулям через enableGc(true) (пишет FLEET_CONFIG.bit0 + SAVE_USER_CONFIG + сброс) или используйте RbAmpFleet::enableGcAll().

  • Устаревшая прошивка без поддержки General-Call — возвращает false, не обращаясь к шине. Переходите к последовательной серии latchPeriod() на каждом устройстве — см. 06 · Примеры, раздел про шину с несколькими модулями.

Диагностика

int8_t lastError() const noexcept

Возвращает: код последней ошибки — RB_OK (0) или одно из значений RB_ERR_* (отрицательное). Полная таблица — в разделе «Коды ошибок» ниже + 10 · Устранение неполадок.

static const char* errorString(int8_t code) noexcept

Возвращает: постоянную строку с понятным описанием кода ошибки. Никогда не возвращает NULL.

void setLogStream(Stream* stream) noexcept

Необязательный приёмник диагностики. Если задан, библиотека кратко логирует результаты probe(), устаревшие снимки и отказы режимов. Передайте nullptr, чтобы выключить. По умолчанию выключено.

Типичное использование:

C++
dev.setLogStream(&Serial);

uint32_t retryExhaustionCount() const noexcept

Сколько раз с момента включения (или последнего resetCounters()) цикл повторов исчерпался при однобайтовом чтении. Установившееся значение — 0. Ненулевое значение — признак проблем со связью (см. 10 · Устранение неполадок).

uint32_t sanityRejectCount() const noexcept

Сколько сырых значений float отбросил фильтр корректности (!isfinite(x) || |x| > 10000). В установившемся режиме — 0. Ненулевое значение после смягчения повторами обычно означает редкий артефакт стека I²C ESP-IDF, который пережил слой повторов.

void resetCounters() noexcept

Обнулите оба счётчика. Используйте в начале испытания на выносливость или окна регрессии, чтобы учитывать только события внутри окна.

const char* errorString() const noexcept

Экземплярная форма errorString(lastError()). Никогда не возвращает NULL.

bool readCommitSeq(uint8_t& out) noexcept — только BASIC

Читает байт порядкового номера фиксации модуля. Модуль увеличивает его один раз за каждое опубликованное окно измерения (100 мс на прошивке v1.2+, 200 мс раньше), с переходом 255→0. Снимайте его до и после многорегистрового чтения, чтобы обнаружить, что опубликованные значения сменились посреди чтения. Это только флаг изменения — CRC нет. На экземпляре STD вызов завершается с RB_ERR_NOT_IMPLEMENTED (используйте readDataSeq()).

Возвращает: true при успехе.

Идентификация и настройка (v1.3)

Эти методы позволяют мастеру точно понять, что именно подключено к шине (вариант, битовая карта возможностей, UID, метка), и подготовить новый или только что прошитый модуль к работе (настройка + сохранение конфигурации во флеш).

RbAmpVariant readVariant() noexcept

Читает регистр HW_VARIANT (0x55) модуля и возвращает RbAmpVariant:

Значение SKU каналы I Канал U
UI1 (1) UI1 1 да
UI2 (2) UI2 2 да
UI3 (3) UI3 3 да
I1 (4) I1 1 нет
I2 (5) I2 2 нет
I3 (6) I3 3 нет
UI5 (7) UI5 (старший SKU) 5 да
UI7 (8) UI7 (старший артикул) 7 да
Unknown (0) не определён (прошивка v1.0/v1.1, сбой I²C или не rbAmp) — —
Безопасность

Автоопределение варианта через readVariant() — рекомендуемый путь. Подсказка топологии в конструкторе остаётся запасным вариантом для прошивки старше v1.2 (где HW_VARIANT недоступен). Подсказка по умолчанию = RbAmpTopology::Single — безопасна, она не вызывает ложных чтений отсутствующих каналов на UI1/I1.

bool readCapability(uint16_t& out) noexcept — только BASIC

Читает 16-битную карту возможностей модуля. Ветвитесь по именованным константам возможностей из RbAmpRegistersV2.h (пространство имён rbamp::v2), а не по эвристике версии прошивки. Карта, среди прочего, показывает, есть ли у модуля входной каскад напряжения — если нет, он не считает P / PF / энергию, и эти значения читаются как 0 — и поддерживает ли он широковещательный снимок General-Call (см. broadcastLatch()). На экземпляре STD вызов возвращает false с RB_ERR_NOT_IMPLEMENTED; используйте там stdInfo().

uint8_t readProductId() noexcept

Читает PRODUCT_ID (0x54) — байтовый идентификатор семейства (датчик rbAmp = 0x01, rbDimmer = 0x02; 0 при ошибке). Сканер флота использует его, чтобы убедиться, что устройство по адресу действительно rbAmp, а не другой ведомый I²C, случайно ответивший на тот же адрес. Экземпляр STD сообщает семейство датчика.

bool readUid(uint8_t uid[12]) noexcept

Читает 96-битный уникальный идентификатор MCU из UID (0x5C..0x67) одной пакетной операцией. UID уникален для каждого модуля и не меняется при перепрошивке — удобно для серийных логов, проверок клонирования на стороне мастера и идентификации при замене модуля в развёрнутом флоте. Работает на обеих линейках.

bool readLabel(char out[9]) noexcept — только BASIC

Читает 8-байтную пользовательскую метку из LABEL (0x68..0x6F). ASCII, дополнено нулями; результат всегда завершается нулём (массив из 9 байт = 8 байт данных + завершающий \0). Пустая метка = не задана.

bool writeLabel(const char* label) noexcept — только BASIC

Записывает 8-байтовую метку. Принимает строку с нулевым завершением — лишние байты обрезаются, недостающие дополняются нулями. Запись выполняется побайтно для многобайтовых записей (протокол rbAmp автоматически инкрементирует адрес при чтении регистров в пачке, но не при записи регистров — см. Подробности протокола на линии ниже; библиотека делает цикл по байтам автоматически). После записи нужен dev.saveUserConfig(), чтобы метка пережила сброс.

Примечание

Модуль с завода может сообщить ошибку 0xFB (DEV_ERR_FLASH_PARAMS_BAD) при первом включении: блок пользовательской конфигурации ещё пуст. Это нормально (не фатально); saveUserConfig() его очищает. Не прерывайте provisioning при первом появлении 0xFB.

bool saveUserConfig() noexcept

Вызывает CMD_SAVE_USER_CONFIG (opcode 0x32) — сохраняет блок пользовательской конфигурации во флеш: SENSOR_CLASS, CT_MODEL по каналам, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Он не сохраняет параметры заводской калибровки — для них отдельная CMD_SAVE_GAINS, закрытая в производственном режиме.

Блокирует поток примерно на 700 мс (цикл стирания и записи флеша). На время вызова не пытайтесь обращаться к модулю из других задач.

Линия STD: выполняет сохранение конфигурации модуля (класс, опорный ТТ, уровень, адрес I²C; калибровка сохраняется), ждёт, пока модуль сообщит о завершении команды (без фиксированной паузы), и проверяет вердикт — недопустимое поле (например, адрес вне диапазона) возвращает RB_ERR_PARAM. Сохранение внутри ограничения частоты записи модуля (5 с) повторяется один раз через 5 с.

Обратное чтение ≠ сохранение

: подтверждение того, что значение записано во флеш, требует перезагрузки и повторного чтения. См. раздел «модель ошибок v1.3» ниже.

Модель ошибок v1.3 — два независимых канала

У ошибок есть два независимых канала, которые работают по-разному. Понимание различия критично для правильной интерпретации состояния модуля.

Канал A — на стороне клиента, синхронно Канал B — со стороны DUT, долговременно и асинхронно
Где это живёт Проверка внутри библиотеки (библиотека Arduino) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Когда срабатывает До транзакции I²C (библиотека её останавливает) После того как прошивка приняла запись и отвергла её
Что видит мастер сеттер возвращает false + lastError() == RB_ERR_PARAM; REG_ERROR на устройстве остаётся 0x00 REG_ERROR = код сбоя сразу; bit3 фиксируется через несколько сотен миллисекунд после транзакции
Липкий нет (просто возврат bool) REG_ERROR — результат последней записи; bit3 залипающий, сбрасывается записью единицы (W1C)
Типичный путь Аргумент вне допустимых границ (канал ∉ {0,1,2}, код ∉ характеризованного набора, sensor_class вне enum) Сырая запись регистра, которую библиотека не проверяет заранее (низкоуровневое использование writeReg() с недопустимой маской)

Канал A — проверка на стороне клиента (сеттеры библиотеки)

Все сеттеры библиотеки (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels и т. д.) сначала проверяют аргументы по допустимым значениям. Если аргумент вне диапазона, сеттер возвращает false и выставляет lastError() == RB_ERR_PARAM, не выполняя вообще никакой транзакции I²C. Поэтому REG_ERROR на устройстве не трогается:

C++
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) {       // client-side guard
    Serial.print(F("rejected: "));
    Serial.println(dev.lastError());                 // RB_ERR_PARAM (lib cached)
    uint8_t reg_err = dev.readLastError();           // device REG_ERROR byte
    Serial.println(reg_err, HEX);                    // 0x00 — REG_ERROR untouched
}
Примечание

lastError() и readLastError() — два разных канала, не синонимы. lastError() возвращает закэшированный на стороне библиотеки код RB_ERR_* от предыдущего вызова — без единой операции I²C. readLastError() выполняет одно чтение по шине регистра REG_ERROR (0x02) устройства — результат последней записи со стороны прошивки. В канале A (выше) lastError() = RB_ERR_PARAM, а readLastError() = 0x00 (библиотека так и не дошла до шины — REG_ERROR не тронут). В канале B (ниже) оба покажут код, но по-разному: lastError() — последняя закэшированная семантика библиотеки; readLastError() — точное значение байта REG_ERROR прямо сейчас.

Это значит: если вы хотите знать точно, почему сеттер отказал, надёжный источник — код возврата функции + lastError(). REG_ERROR на устройстве в этом сценарии ничего не скажет.

Канал B — отказ на стороне DUT (устойчивый асинхронный)

Если запись прошла по I²C (библиотека её не остановила, потому что аргумент выглядел корректным), но прошивка отклонила её, включается второй канал:

  • readLastError() сразу содержит код причины (например, 0xFE = DEV_ERR_PARAM). Это исход последней записи: любая следующая успешная запись его перезапишет. Читать его нужно сразу после записи, до любой другой транзакции.

  • hasError(out) — липкий индикатор W1C EVENT_FLAGS.bit3. Он не выставляется мгновенно: на стенде измерена задержка в несколько сотен миллисекунд между неудачной транзакцией и установкой bit3. Сразу после записи bit3 ещё false; через 300 мс он true. После этого bit3 держится при любом числе чтений.

Безопасность

⚠ Не используйте hasError() для проверки только что выполненной записи. Для исхода именно этой записи надёжен только readLastError(), читайте его сразу после записи, до любой другой транзакции (а также код возврата сеттера, если он есть). hasError() — асинхронный канал для мониторинга опросом вида «не было ли сбоя между двумя проверками», а не для синхронной проверки.

Сброс устойчивой ошибки — сбросьте обе (REG_ERROR и bit3)

bit3 прошивка подхватывает каждые несколько сотен миллисекунд из текущего состояния REG_ERROR. Поэтому простой clearEventFlags(1 << 3) не сработает — bit3 тут же снова установится из ещё не сброшенного REG_ERROR. Правильный порядок: сначала clearError() (сбрасывает REG_ERROR), затем clearEventFlags(1 << 3) (сбрасывает залипающую защёлку). Если нужна атомарность — между ними не должно быть отклонённой записи.

uint8_t readLastError() noexcept

Читает регистр устройства REG_ERROR (0x02) напрямую (одно чтение провода; возвращает 0x00 при успехе, 0xFA..0xFF для класса ошибки и 0xFF, если само чтение I²C не удалось) — итог последней транзакции, принятой шиной (записи или команды). Не липкий: любая следующая успешная запись перезаписывает его своим результатом. Используется в Канале B (отказ на стороне DUT) для расширенного кода причины. На линейке STD вердикт команды уже сопоставлен с lastError() (см. API линейки STD).

Примечание

Не путать с lastError(): это другой метод, который возвращает закэшированный библиотекой RB_ERR_* от предыдущего вызова библиотеки без какой-либо операции I²C. См. врезку в Канале A выше.

bool hasError(bool& out) noexcept

Вспомогательная функция поверх EVENT_FLAGS.bit3. Возвращает true в out, если bit3 установлен. Липкий W1C; не сбрасывается до явного сброса (с оговоркой — см. раздел «Сброс устойчивой ошибки» выше).

bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept

EVENT_FLAGS (0x2A) — байт липких флагов; конкретные биты описаны в спецификации (включая ERROR_OCCURRED, бит3). Сброс — запись единицы в бит (W1C): запишите маску с единицами в битах, которые хотите сбросить.

bool clearError() noexcept

Вызывает CMD_CLEAR_ERROR (opcode 0x31) — обнуляет REG_ERROR. Обязательно для сброса устойчивой ошибки вместе с clearEventFlags(1 << 3) (см. выше). Без clearError() простой clearEventFlags(1 << 3) оставит bit3 равным true через несколько сотен миллисекунд из-за повторной защёлки.

Конфигурация нескольких каналов (v1.3)

На многоканальных модулях у каждого токового канала своя модель CT-датчика. Атомарная утилита для массовой конфигурации — configureChannels().

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

Parameters:

  • cls — класс датчика, применяется первым. С RbAmpSensorClass::Sct013 модели привязываются; запрос привязать модели при WiredCT / BuiltinCT отклоняется заранее (false, RB_ERR_MODE, ничего не записано).

  • models — массив из n кодов моделей ТТ (сгенерированные define RBAMP_CT_*), по одному на канал. 0 оставляет существующую модель канала без изменений.

  • n — длина массива. Ограничивается значением channels(): лишние элементы массива игнорируются. Если n меньше — недостающие каналы не трогаются (они сохраняют прежнюю модель).

Внутри функция выполняет:

  1. setSensorClass(cls) один раз.
  2. Для каждого канала k < min(n, channels): поставить в staging REG_CT_MODEL = models[k] и выполнить CMD_SET_CT_MODEL_CHk.
  3. Одно сохранение в конце всей конфигурации — один цикл стирания и записи флеша вместо одного на канал (примерно в 3 раза меньше циклов износа на трёх каналах).

Правило «сначала чтение» действует: класс или модель, которые модуль уже держит, не перезаписываются, поэтому повторное применение той же конфигурации стоит только чтений и не расходует цикл флеша. На прошивке BASIC до 1.4.19 с классом SCT-013 модуль перезапускается после сохранения (см. Конфигурация датчика).

Return:

  • true — конфигурация применена и сохранена (или уже была установлена).
  • false + lastError() == RB_ERR_PARAM — недопустимый cls или models[k], которого нет в реестре (проверка на стороне клиента, см. «Модель ошибок» выше); пакет прерывается.

  • false + RB_ERR_MODE — модуль заводского парного класса.

  • false + другие коды — ошибка шины, таймаут и т. д.
Примечание

Допустимые коды для SCT_013: {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Подробнее — 03 · Выбор токового датчика.

bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept

Читает применённую (зеркало проверки) модель датчика тока на конкретном канале. Это обратное чтение из RAM, а не подтверждение сохранения; чтобы подтвердить сохранение во флеш, используйте dev.reset() и повторное чтение зеркала.

Линия готовности данных и события

Обе линии. Выход DRDY модуля — открытый сток, в покое HIGH (подтяжка на хосте), и каждый раз, когда публикуется новый полный снимок, опускается в LOW — раз за окно измерения (100 мс). Несколько модулей могут делить одну линию (монтажное ИЛИ). Модуль, у которого ожидает обработки замаскированное событие, держит линию постоянно LOW (уровень тревоги), пока флаги не сброшены. На линии STD блок событий есть у модулей, чей образ его предоставляет; на BASIC — начиная с прошивки v1.3. Подробности по аппаратной части — 04 · Подключение.

bool setDrdyPin(int pin) noexcept

Подключите линию DRDY этого модуля (или отключите её, передав pin < 0). Настраивает вывод как вход с внутренней подтяжкой и прерыванием по спадающему фронту; обработчик прерывания только считает и метит время фронта — обращений к шине там нет. До 4 различных линий и 8 модулей на линию. Модуль STD, образ которого не поддерживает контракт готовности данных, отказывает с RB_ERR_NOT_IMPLEMENTED; тогда waitDataReady() опрашивает последовательность. Без линии waitDataReady() тоже опрашивает.

bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept

Блокировать до публикации модулем нового снимка (или тревоги), не дольше timeout_ms (0 = одна неблокирующая проверка).

С линией: ожидает фронт, затем подтверждает, что фронт был от этого модуля, по его номеру снимка (импульс от другого модуля на общей линии игнорируется). Если линия остаётся LOW сразу после фронта, какой-то модуль на ней держит аварийный сигнал: флаги всех модулей с поддержкой аварий на линии читаются и сбрасываются; флаги этого модуля возвращаются в ev, флаги остальных откладываются в их экземплярах и выводятся при их следующем ожидании. Без линии опрашивает номер снимка каждые RBAMP_DRDY_POLL_MS (по умолчанию 20 мс; определите до подключения библиотеки, чтобы переопределить).

Возвращает: true с заполненным ev; false с RB_ERR_TIMEOUT, если ничего не пришло, RB_ERR_NOT_IMPLEMENTED на модуле STD, образ которого не имеет счётчика публикаций.

bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept

waitDataReady(), затем readAll(), так что всё чтение попадает в одно окно публикации: снимок никогда не читается дважды и никогда не разрывается публикацией.

bool readDataSeq(uint16_t& out) noexcept

Порядковый номер снимка модуля — счётчик публикаций на STD, порядковый номер фиксации на BASIC. Только для определения изменений.

uint8_t beginEventFlags() const noexcept

Флаги событий в том виде, в каком их нашёл begin(), до того как библиотека что-либо записала. EVENT_RESET_OCCURRED здесь означает, что модуль перезапустился до встречи с этим экземпляром. Доступа к шине нет.

bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept

Чтение / установка битов событий, при которых DRDY в LOW (биты rbamp::v2::EVENT_*). setEventMask() проверяет записанное обратным чтением. Маска хранится в RAM модуля: после сброса модуля примените её заново (EVENT_RESET_OCCURRED об этом сообщит).

bool setEventThresholds(float i_amps, float p_watts) noexcept

Задаёт пороги тока / мощности, на которых срабатывают EVENT_THRESH_I / EVENT_THRESH_P; значение <= 0 отключает порог. ОЗУ модуля.

  • BASIC сравнивает максимальный ток канала и знаковую сумму мощностей каналов — экспорт его никогда не срабатывает.

  • STD сравнивает ток любого канала и модуль суммарной мощности — не зависит от направления.

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

readEventFlags() / clearEventFlags() / hasError() описаны в разделе Модель ошибок.

RbAmpDrdyEvent

C++
struct RbAmpDrdyEvent {
    bool     fresh;        // a new snapshot of THIS module is available
    bool     by_edge;      // woken by the DRDY edge (false = found by polling)
    uint16_t seq;          // snapshot sequence now
    uint16_t missed;       // snapshots published since the previous call that were not read
    bool     alarm;        // the line was held LOW (masked event pending on this module)
    uint8_t  event_flags;  // event flags consumed from this module on an alarm, else 0
    uint32_t latency_us;   // edge to return, µs (0 when polling)
};
C++
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15);                       // optional: omit to poll
dev.setEventThresholds(0, 3000);          // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);

RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
    if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
    // use snap
}

Обзор возможностей

Сводки возможностей ниже перенесены сюда из README.

  • Конфигурация токового датчика — setSensorClass(class) выбирает семейство (SCT-013 ставите вы; проводные / встроенные модули CT поставляются откалиброванными вместе с датчиком и не перенастраиваются), затем setCTModel(code) — или configureChannels(class, models[], n) для многоканального модуля одним вызовом. Сеттеры сначала читают, потом пишут: класс или модель, которые модуль уже держит, не стоят записи в шину и цикла флеша, поэтому повторное применение сохранённой конфигурации при каждой загрузке безопасно. Принятый набор кодов SCT-013: {1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. Коэффициенты калибровки загружаются автоматически из заводской таблицы пресетов. Модули BASIC до прошивки 1.4.19 откалиброваны на SCT-013-030: при выборе другой модели SCT-013 библиотека перезапускает модуль после сохранения и далее масштабирует показания тока и мощности относительно усиления, которое применяет модуль (см. sctRating()); коэффициент мощности и напряжение не затрагиваются, а модуль, сообщающий бит возможности самокоррекции (прошивка 1.4.20+), не нуждается ни в чём.
  • Менеджер RbAmpFleet — для нескольких модулей на одной шине: scan() находит и принимает их (с обнаружением коллизий), pollAll() читает их за один проход, totalPower() / totalEnergyWh() агрегируют, а путь General-Call (enableGcAll() → gcLatch(tick) → checkSync()) берёт снимок периода у каждого модуля одновременно с обнаружением пропущенных кадров по модулям. provision() / assignAddress() переводят модули «с завода» на шину по разным адресам.
  • Обе линейки продуктов, один API — begin() определяет, работает ли модуль с регистровой моделью BASIC (8 бит) или STD (16 бит, фиксированная точка), и направляет каждый вызов внутри себя; line() сообщает, какая именно. На модуле STD работают те же вызовы readVoltage(phase) / readCurrent(ch) / readPower(ch) / readPeriodSnapshot(), числа каналов берутся из модуля (трёхфазные модули — просто N > 1), а дополнительные возможности только STD доступны как readReactivePower(ch) / readApparentPower(ch), stdReadChannel(ch) (одна пачка: I / P / Q / S / PF / пик / знаковая энергия / гармоники), stdReadVoltage(v), stdReadHealth(), а также восемь банков снимков с таймингом по мастеру (stdArmBanks() → stdLatch(bank) → stdReadLatch(bank) → stdLatchWh()). Модули, которые хранят сохранённые пожизненные счётчики вместо банков снимков, обслуживаются теми же вызовами readPeriodSnapshot() / energy() (период — это разность двух показаний счётчика; stdReadEnergy() отдаёт сырые счётчики), а также часами модуля (stdSetTime()), историей и журналом событий (stdHistRead(), stdEventRead()), идентификацией (stdIdentify(), RbAmp::stdProbe()), вводом в эксплуатацию по UID (RbAmp::stdSetAddressByUid()) и обновлением прошивки по I2C (stdOtaWritePreparedImage(), образы готовятся на сборочном хосте производителя). Каждая команда ждёт, пока модуль сообщит о завершении, и только потом читается вердикт; многобайтовые блоки читаются одной транзакцией, поэтому счётчики не разрываются. Модули, публикующие микроразрешённые счётчики, заполняют поля *_uwh / *_uvarh структуры RbAmpStdEnergy (fine == true; в остальных случаях они выводятся из грубых счётчиков, так что поля всегда пригодны к использованию), принимают стартовый ток, ниже которого канал не учитывает энергию (stdSetEnergyStartCurrent()), и сообщают фазовые углы напряжения (angle_deg в stdReadVoltage()) и порядок фаз (stdReadPhaseSequence()). Если ваш скетч сохраняет RbAmpStdEnergy (NVS, EEPROM, файл), храните нужные поля в собственном фиксированном формате, а не структуру целиком как сырой блок: структура получает новые поля между версиями библиотеки, и старый блок не совпадёт по размеру.
  • Линия готовности данных и события — setDrdyPin(pin) слушает выход DRDY модуля; waitDataReady() / readAllReady() возвращаются сразу после того, как модуль публикует новый снимок (несколько модулей могут делить одну линию), а модуль, удерживающий линию, сигнализирует замаскированное событие (setEventMask(), setEventThresholds()), которое ожидание читает и сбрасывает за вас. Без линии те же вызовы опрашивают.

API линейки STD

Линейка модулей STANDARD (STD) определяется begin() (dev.line() == RbAmpLine::Std). Скалярный API выше (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), сеттеры конфигурации, reset(), смена адреса) работает на обеих линейках. Вызовы std* ниже добавляют блочные чтения целиком и функции, которые есть только у линейки STD.

  • Каждый вызов std* завершается с RB_ERR_NOT_IMPLEMENTED на экземпляре BASIC.
  • Доступность возможностей зависит от образа модуля: проверяйте stdReadImageVersion() и флаги valid / fine возвращаемых структур. Возможность, которой нет у модуля, сообщается как «недоступно» — она никогда не возвращает выдуманное значение.

  • begin() выполняет определение линии и обнаружение каналов. Соответствующие внутренние хелперы не входят в публичный API; вызывайте begin(), readAll() и readPeriodSnapshot().

  • Каждая команда ждёт, пока модуль сообщит о её завершении, и затем проверяет его вердикт. Отвергнутое значение возвращает RB_ERR_PARAM и оставляет модуль без изменений.

  • Примитивы на 8 бит отказывают на экземпляре STD, поэтому путь только для BASIC никогда не выполнит транзакцию с неверным регистром на модуле STD.

C++
if (dev.begin() && dev.line() == RbAmpLine::Std) {
    RbAmpStdChannel c;
    if (dev.stdReadChannel(0, c)) {
        Serial.printf("P=%.1f W  Q=%.1f var  S=%.1f VA  PF=%.2f\n", c.p, c.q, c.s, c.pf);
    }
}

Источник энергии и минимальная версия библиотеки

readPeriodSnapshot() и energy() берут период из одного из двух источников, выбранного один раз функцией begin() по битам возможностей модуля и отображаемого в stdInfo().period_source:

Модуль сообщает period_source Период / энергия берутся из
сохранённые счётчики энергии (бит 13), с банками или без них Counters счётчики модуля (период — разность двух показаний)
только банки снимков (бит 8) Latch банк 0
ни один None вызовы отказываются с RB_ERR_NOT_IMPLEMENTED

Серийный образ STD 0x7E сообщает оба бита. Для получения энергии из счётчиков модуля нужна библиотека 1.6.2 или новее. Библиотека 1.6.1 и старше читает период из банка 0 на этом образе, то есть энергия интегрируется на хосте, а не по собственным счётчикам модуля; обновите библиотеку, чтобы получить значения по счётчикам. Банки на 0x7E остаются доступны через вызовы из раздела Банки снимков периода.

Идентичность

bool stdInfo(RbAmpStdInfo& out) noexcept

Кэшированная идентичность из begin() — без обращения к шине. Завершается с RB_ERR_NOT_IMPLEMENTED на экземпляре BASIC или до begin().

C++
struct RbAmpStdInfo {
    uint8_t  map_version;   // register-map version
    uint16_t capabilities;  // feature bitmap of the module
    uint8_t  status;        // status bits at begin() time (live: stdReadHealth())
    uint8_t  n_voltage;     // populated voltage channels
    uint8_t  n_current;     // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
    uint8_t  variant;       // raw variant byte (also mapped into readVariant())
    uint32_t active_bank;   // running firmware bank (firmware update), 0 if none
    uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
    RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};

RbAmpStdPeriodSource: Latch (у модуля есть банки снимков; банк 0 обслуживает readPeriodSnapshot()), Counters (нет банков снимков, но есть сохранённые пожизненные счётчики энергии — период это разность двух показаний счётчика; вызовы банков отказывают без обращения к шине) или None (вызовы периода и энергии завершаются с RB_ERR_NOT_IMPLEMENTED).

bool stdIdentify(RbAmpStdIdentity& out) noexcept

Идентичность модуля: закэшированные данные begin() плюс UID, версия работающего образа и board id (последние два — там, где модуль их сообщает; иначе 0).

C++
struct RbAmpStdIdentity {
    uint8_t  i2c_addr;      // 7-bit address the module answered on
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];       // chip UID — the module's identity in a database
    uint32_t fw_version;    // running image version (0 if unknown)
    uint32_t board_id;      // board id (0 if unknown)
};

static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept

Определяет, что отвечает по addr без экземпляра (сканирование шины). Одна попытка на чтение, без слоя повторов — NACK и есть ответ.

Возвращает: RB_OK; RB_ERR_NACK — никто не подтвердил по этому адресу; RB_ERR_VERSION — там не модуль STD; RB_ERR_PARAM — адрес вне 0x08..0x77; RB_ERR_IO — позднее чтение не удалось.

bool stdReadImageVersion(uint32_t& out) noexcept

Версия работающего образа (не версия карты регистров); 0, если модуль её не сообщает. Используйте её, чтобы понять, есть ли функция, требующая свежего образа (энергия микроразрешения, пусковой ток, фазовые углы и порядок фаз требуют образа не ниже 0x0001007B).

bool stdReadBoardId(uint32_t& out) noexcept

Board id работающего образа.

Блочное чтение

bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept

Один токовый канал (0 .. channels()-1) одним пакетом: I, P, Q, S, PF, пик, сырые накопители энергии со знаком и поля гармоник.

bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept

Сводный блок: k = 0 общий итог (все токовые каналы), k = 1..3 итоги по фазам A / B / C (на однофазном модуле k = 1 равно каналу 0, а k = 2, 3 читаются как 0). Только I / P / Q / S / PF / пик — на модулях со счётчиками за весь срок поля энергии здесь читаются как 0; энергия берётся из stdReadEnergy().

C++
struct RbAmpStdChannel {
    float   i_rms, i_peak;   // A
    float   p;               // W, signed
    float   q;               // var, signed
    float   s;               // VA
    float   pf;              // power factor, −1..+1
    float   thd_i;           // current THD, % — 0 unless harmonics are enabled
    float   pf1;             // displacement power factor — 0 unless harmonics are enabled
    float   q1;              // fundamental reactive power, var — 0 unless harmonics are enabled
    int64_t e_import_mws;    // raw import energy accumulator (>= 0), see stdLatchWh()
    int64_t e_export_mws;    // raw export energy accumulator (<= 0)
    uint8_t implausible;     // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

Для мониторинга интегрируйте p самостоятельно или используйте stdReadEnergy(); сырые накопители существуют для пути банков снимков.

bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept

Один канал напряжения (0 .. n_voltage-1).

C++
struct RbAmpStdVoltage {
    float   u_rms, u_peak;   // V
    float   thd_u;           // voltage THD, % — 0 unless harmonics are enabled
    float   angle_deg;       // phase angle vs voltage 0, degrees; 0 when angle_valid is false
    bool    angle_valid;     // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
    uint8_t implausible;
};

bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept

Порядок фаз трёхфазного модуля по напряжения, вычисленный самим модулем по углам напряжений. Возвращает true с NotAvailable — без обращения к шине — на образе, который его не публикует; сам модуль сообщает NotAvailable при менее чем трёх входах напряжения или когда вход слишком мал для измерения.

RbAmpStdPhaseSeq: NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (нет трёхфазного паттерна, например два входа на одной фазе).

bool stdReadHealth(RbAmpStdHealth& out) noexcept

Состояние модуля в реальном времени. Считайте показания корректными, когда в status установлен бит «датчик в порядке», а frame_count растёт между двумя опросами.

C++
struct RbAmpStdHealth {
    uint8_t  status;       // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
    uint32_t frame_count;  // sensor frame counter — must grow between polls (liveness)
    uint32_t crc_errors;   // sensor frame error counter
    bool     time_valid;   // the module clock was set since its last restart — see stdSetTime()
    bool     nvm_fault;    // energy store unusable
    bool     maint;        // maintenance mode
    uint8_t  lta_status;   // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
    uint8_t  lta_src;      // where the life-time counters were restored from
    uint8_t  cal_src;      // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
    uint8_t  group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    uint16_t legal_noen, ring_drop;  // module diagnostics (ring_drop should stay 0)
    uint32_t lost_frames;  // should stay flat
    uint32_t uptime_s;     // seconds since the module's last restart
    uint8_t  reset_cause;  // cause of this boot (image-dependent; 0 below)
    uint16_t boot_count;   // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};

Поля, помеченные «зависит от образа», или документированные для новых карт регистров, возвращают 0 / false на модулях, которые их не предоставляют. cal_ok может быть 0 у модуля, откалиброванного по старому образу, пока saveGains() не выполнен хотя бы раз; сами показания при этом не затрагиваются.

Банки снимков периода

Модуль STD, сообщающий о банках снимков (бит возможности 8), ведёт восемь независимых периодов с таймингом по мастеру. Типичное использование: взведите нужные банки один раз; затем для каждого банка по своему расписанию: stdLatch(bank) → ожидание не менее 300 мс → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) с измеренным мастером dt с предыдущего снимка этого банка. Банки — самостоятельный инструмент: они доступны независимо от источника энергии модуля (см. Источник энергии и минимальная версия библиотеки). На модуле без банков stdArmBanks(), stdLatch() и stdReadLatch() отказывают с RB_ERR_NOT_IMPLEMENTED и ничего не пишут. Банк 0 обслуживает readPeriodSnapshot() и energy() только на модуле, у которого есть банки и нет сохранённых счётчиков.

bool stdArmBanks(uint8_t mask) noexcept

Задайте маску накопления: бит b = банк b накапливает (только что взведённые банки начинают с нуля; снятые с взвода банки замораживаются и сохраняют последний снимок). Держите бит 0 установленным, если используете readPeriodSnapshot(). Маска живёт в ОЗУ модуля и теряется при сбросе модуля; библиотека перевзводит банк, когда чтение находит пустой снимок на снятом с взвода банке (см. stdReadLatch()).

bool stdLatch(uint8_t bank) noexcept

Запросите снимок и сброс bank на следующей границе окна модуля. Не ждёт; читайте не раньше чем через 300 мс.

bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept

Читает последний снимок bank одним пакетом (итоги и энергия по каждому каналу для всех заполненных каналов).

Возвращает: false с RB_ERR_STALE, если модуль никогда не снимал снимок этого банка (out.valid == false), либо если снимок пуст (win_count == 0), потому что банк потерял взведение после сброса модуля. В последнем случае библиотека перевзводит банк и берёт праймер-снимок: отбросьте этот период и перезапустите свой якорь dt (интервал простоя данных не несёт).

C++
struct RbAmpStdLatch {
    float    p_avg, q_avg, s_avg;    // average W / var / VA over the period
    float    max_p, max_i;           // peak power (W) and peak RMS current (A)
    float    max_u, min_u;           // peak / minimum RMS voltage (V)
    int64_t  e_import_mws, e_export_mws;   // raw energy accumulators over the period
    uint32_t nsamp;                  // conversion divisor used by stdLatchWh()
    uint32_t win_count;              // measurement windows in the period (0 = not armed / nothing elapsed)
    uint8_t  channels, bank;
    bool     valid;                  // the bank has EVER been snapshotted (not a freshness signal)
    float    p_avg_ch[RBAMP_MAX_CHANNELS];
    int64_t  e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};

static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept

Пересчитывает сырые накопители энергии снимка в Wh за интервал по часам мастера dt_ms (время между предыдущим и текущим снимком банка). ch — индекс канала или RBAMP_STD_TOTAL для итогов банка. wh_import равен >= 0, wh_export равен <= 0.

Возвращает: false, если ch вне диапазона или ничего не накоплено.

Пожизненные счётчики энергии

Модули, которые хранят сохранённые счётчики энергии, сохраняют их при потере питания; они монотонны, с раздельным учётом импорта / экспорта со знаком.

bool stdReadEnergy(RbAmpStdEnergy& out) noexcept

Прочитайте пожизненные счётчики модуля. Каждый блок читается одной транзакцией, поэтому 64-битный счётчик не может разорваться на границе публикации.

Возвращает: false с RB_ERR_NOT_IMPLEMENTED, если модуль не хранит энергию на устройстве; RB_ERR_NOT_READY, если блок не запрограммирован.

C++
struct RbAmpStdEnergy {
    int64_t  act_import_wh, act_export_wh, act_net_wh;     // active energy, Wh (export is a magnitude)
    int64_t  rea_import_varh, rea_export_varh;             // reactive energy, varh
    uint32_t generation;       // steps when the counters were reset or adopted — never take a delta across a change
    uint32_t uptime_s;         // module uptime at the reading (a drop = the module restarted)
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;  // mWh (0 on modules without them)
    uint8_t  channels;         // valid entries in the per-channel arrays (0 on modules without them)
    uint8_t  group_status;     // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    int64_t  ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
    bool     fine;             // true: the µWh / µvarh fields are the module's own micro-resolution counters
    int64_t  act_import_uwh, act_export_uwh, act_net_uwh;  // µWh
    int64_t  rea_import_uvarh, rea_export_uvarh;           // µvarh
    int64_t  ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};

Поля *_uwh / *_uvarh всегда заполнены, поэтому их можно использовать на любом модуле: при fine == true это собственные микроразрешённые счётчики модуля (образ 0x0001007B или новее); иначе они выводятся из грубых счётчиков и меняются шагами в этих единицах. Если ваш скетч сохраняет RbAmpStdEnergy, храните нужные поля в собственном фиксированном формате, а не структуру целиком как сырой блок — структура получает новые поля между версиями библиотеки.

static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept

Энергия между двумя показаниями: now − prev, каждый счётчик ограничивается снизу значением 0 (после перезапуска модуля счётчик может возобновиться чуть ниже последнего показания); нетто пересчитывается как импорт − экспорт ограниченных разностей. delta и module_restarted могут быть nullptr; delta->fine равно true только тогда, когда оба показания были корректны; *module_restarted равно true, когда время работы в now меньше, чем в prev.

Возвращает: false, если generation изменился между показаниями (сброс или принятие счётчиков за весь срок) — этот интервал не учитывайте.

bool stdSetEnergyStartCurrent(uint16_t ua) noexcept

Задаёт пусковой ток для подсчёта энергии в µA: ниже этого тока канала модуль не считает энергию для канала (импорт или экспорт, общий и по каналу). Без нагрузки измеряемая мощность — шум любого знака, и без порога он попал бы в оба счётчика. Показания (I / P / Q) не затрагиваются. Применяется сразу, с проверкой обратным чтением; сохраните через saveUserConfig(). 0 — выключает; иначе значение должно быть кратно 10 µA и лежать в диапазоне, который принимает модуль, — иначе возвращается RB_ERR_PARAM без записи в шину.

Возвращает: false с RB_ERR_NOT_IMPLEMENTED, если у модуля нет пускового тока (нет энергии микроразрешения или более старый образ).

bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept

Текущий пусковой ток для подсчёта энергии в µA (0 = выключено).

Конфигурация

bool stdReadConfig(RbAmpStdConfig& out) noexcept

Блок конфигурации одним пакетом.

C++
struct RbAmpStdConfig {
    uint8_t  sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
    uint8_t  ct_model;     // CT model reference for channel 0 (label only, sets no gain). Persisted.
    uint8_t  tier;         // module tier code. Persisted.
    uint8_t  i2c_addr;     // persisted 7-bit address (applies on reset)
    uint16_t rate_ms;      // report-rate hint, ms (RAM only)
    bool     harmonics;    // base-harmonics extraction enabled (RAM only)
};

bool stdSetHarmonics(bool enable) noexcept

Включение / выключение извлечения базовых гармоник (THD, коэффициент мощности смещения, реактивная мощность основной гармоники). Только RAM (не сохраняется), с проверкой обратным чтением. Требует возможности THD у модуля — иначе RB_ERR_NOT_IMPLEMENTED.

bool stdCalThdFloor() noexcept

Снимите сырой THD без нагрузки как порог датчика и сохраните его (около 700 мс). Выполняйте на чистой сети и без нагрузки; после этого показания THD корректируются на порог датчика. Требуется возможность THD.

Часы

Часы модуля теряются при каждом перезапуске модуля. Задавайте их после begin() и всякий раз, когда RbAmpStdHealth::time_valid равно false; без них модуль не ведёт историю.

bool stdSetTime(uint32_t unix_epoch) noexcept

Установить часы модуля (эпоха Unix, UTC). Возвращает false с RB_ERR_PARAM, если модуль отвергает эпоху (до 2020), и RB_ERR_NOT_READY, если он принял значение, но не сообщил часы действительными в течение 300 мс.

bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept

Часы модуля и то, устанавливались ли они с последнего перезапуска модуля.

Команды и ввод в эксплуатацию

bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept

Выполните любую команду модуля и дождитесь вердикта: ожидает, пока модуль свободен (команда, записанная во время занятости, отбрасывается), записывает опкод, опрашивает состояние команды, пока модуль не сообщит о завершении, затем читает вердикт. settle_ms ограничивает только первый опрос. timeout_ms = 0 означает 1000 мс; не менее 1000.

Возвращает: false с вердиктом, сопоставленным коду ошибки — PARAM, NOT_IMPLEMENTED (неизвестная команда), CHECKSUM (проверка значения), MODE (ключ / шлюз), NOT_READY (ограничение частоты / повтор), TIMEOUT, IO (ошибка хранилища модуля).

bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept

Ждать, пока модуль не сообщит, что команда не выполняется (0 = 1000 мс).

bool stdLocate() noexcept

Мигните светодиодами модуля примерно 10 с — найдите его в шкафу.

static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept

Задайте одному из нескольких модулей на общем адресе собственный адрес, выбранный по UID (ввод в эксплуатацию). Это только запись по общему адресу (отвечать может несколько модулей, поэтому там ничего не читается). Адресуемый модуль сохраняет новый адрес и перезапускается; затем вызов проверяет новый адрес и сверяет UID. Повторите begin() на экземпляре, привязанном к новому адресу. restart_ms = 0 означает 1500 мс.

Возвращает: RB_OK; RB_ERR_PARAM — адрес вне диапазона; RB_ERR_NACK — ни один модуль не подтвердил общий адрес; RB_ERR_NOT_READY — после этого по новому адресу никто не отвечает; RB_ERR_VERSION — модуль там не тот, что адресовался (UID не совпадает).

История и журнал событий

Записи существуют только за периоды, когда часы модуля были действительны (см. stdSetTime()).

C++
enum class RbAmpStdHistPeriod : uint8_t {
    Min15  = 0,  // 15-minute energy records — RAM only (the last record survives no restart)
    Hour   = 1,  // hourly energy records — persistent ring (the one to backfill from)
    Events = 2,  // event log (read with stdEventRead())
};

bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept

Сводка кольца: count, capacity, record_size, oldest_ts, newest_ts (Unix-время). Записи извлекаются от новых к старым по индексу back.

bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept

Читает и декодирует одну запись журнала энергии по периоду (Min15 или Hour; back = 0 — самая новая). Возвращает false с RB_ERR_NOT_READY, если такой записи нет (пустое кольцо или back за его пределами); RB_ERR_PARAM для кольца событий (используйте stdEventRead()).

C++
struct RbAmpStdHistRecord {
    uint32_t ts;           // Unix time at the end of the period
    uint16_t flags;        // partial / power-up / clock / life-time-jump bits
    uint16_t n;            // measurement windows in the period
    bool     from_ram;     // served from RAM (not yet persisted)
    float    v_rms, i_total, p_avg, q_avg, s_avg, pf;
    float    p_min, p_max, i_min, i_max;
    uint64_t e_import_wh, e_export_wh;   // life-time ABSOLUTE counters at the end of the period
    uint8_t  phases;                     // valid entries in the per-phase arrays (0..3)
    double   ph_import_wh[3], ph_export_wh[3];  // THIS period's energy per phase
};

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

bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept

Читает одну нераскодированную запись любого кольца в rec; flags (необязательный) получает флаги записи модуля.

bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept

Читает и декодирует одну запись журнала событий (back = 0 — самая новая); RB_ERR_NOT_READY = такой записи нет.

C++
struct RbAmpStdEvent {
    uint32_t ts;         // Unix time (0 if the clock was not set)
    uint32_t uptime_s;   // module uptime at the event
    uint8_t  type;       // record type
    uint8_t  flags;
    uint16_t boot;       // boot counter at the event
    uint32_t a_before, a_after;          // event-specific values
    uint64_t e_before_wh, e_after_wh;    // life-time energy before / after, Wh
};

bool stdHistFlush() noexcept

Попросите модуль записать сейчас свои накопители энергии в хранилище.

Обновление прошивки по I²C

Двухфазное обновление: stdOtaBegin() → stdOtaWritePage() для каждой страницы → stdOtaCommit() (проверяет образ и взводит переключение; без перезагрузки) → stdOtaActivate() (перезагружает в новый образ, когда вы готовы). На практике используйте stdOtaWritePreparedImage(), который делает begin + страницы + commit одним вызовом, а затем stdOtaActivate(). Модули принимают только образы, подготовленные производителем; плохой образ откатывается самим модулем, и калибровка сохраняется. Каждый шаг ждёт, пока модуль сообщит о завершении команды (без фиксированных пауз). Все вызовы завершаются с RB_ERR_NOT_IMPLEMENTED, если модуль не сообщает о возможности обновления.

C++
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
Вызов Описание
bool stdOtaStatus(uint8_t& out) Состояние обновления модуля (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE).
bool stdOtaBegin(uint32_t timeout_ms = 0) Стереть неактивный банк и дождаться, пока модуль сообщит о готовности. 0 = по умолчанию (5 с). false с RB_ERR_TIMEOUT, если не дождались.
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) Запишите одну страницу по 256 байт с индексом page_idx. false с RB_ERR_CHECKSUM, если полезная нагрузка пришла повреждённой (отправьте ту же страницу повторно), RB_ERR_IO, если модуль не принял страницу, RB_ERR_NOT_READY, если сессия уже закрыта — в последних двух случаях начните заново с stdOtaBegin() (см. stdOtaDiag()).
bool stdOtaCommit(uint32_t timeout_ms = 0) Проверяет записанный образ и взводит переключение банка. 0 = по умолчанию (3 с). RB_ERR_CHECKSUM — плохой образ; RB_ERR_VERSION — образ старше работающего (отклонён); RB_ERR_TIMEOUT.
bool stdOtaActivate() Перезагрузитесь во взведённый образ, дождитесь возвращения модуля, заново обнаружьте его, убедитесь, что запущенный банк сменился, и дождитесь подтверждения нового образа. Блокирует на всю последовательность (около 12 с). Экземпляр остаётся привязанным, а stdInfo() отражает новую прошивку. false с RB_ERR_NOT_READY, если ничего не было взведено, модуль вернулся на предыдущий банк или не подтвердил новый образ; RB_ERR_VERSION, если запущенный после этого образ не тот, что был подготовлен (откат).
static uint32_t stdCrc32(const uint8_t* data, size_t len) CRC-32 (совместимый с zlib) — контрольная сумма страницы, которую проверяет модуль.
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Потоковая запись подготовленного образа банка (begin + страницы + commit; без activate). len должен совпадать с размером банка модуля, иначе RB_ERR_PARAM. Страницы идут по возрастанию, пустые страницы пропускаются, страница, которую модуль сообщает как повреждённую, переотправляется один раз.
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Потоковая форма — одна страница в RAM.
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Передайте оба образа для каждого банка; библиотека выберет тот, который не запущен. RB_ERR_NOT_IMPLEMENTED, если модуль не сообщает свой запущенный банк.
bool stdOtaActiveBank(uint8_t& out) Id текущего банка: 0 = A, 1 = B.
bool stdOtaStagedVersion(uint32_t& out) Версия взведённого (зафиксированного, но ещё не активированного) образа; 0, когда ничего не взведено.
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) Причина последнего сбоя обновления от модуля плюс низкоуровневый байт статуса. Читайте после неудачного коммита или записи страницы.
bool stdOtaAbort() Закройте сессию обновления / отмените взведённый образ без перезагрузки.
bool stdOtaBoardOk(uint32_t image_board_word) Отклоняет образ, собранный для другой платы, до отправки: сравнивает board id модуля с board word образа (из манифеста образа). Несовпадение возвращает RB_ERR_PARAM; RB_ERR_NOT_IMPLEMENTED на модулях, которые board id не сообщают.
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) и форма Stream& Оставлено только для совместимости с исходным кодом: возвращает false с RB_ERR_NOT_IMPLEMENTED, не трогая модуль. Используйте stdOtaWritePreparedImage().

RbAmpFleet — управление несколькими модулями

Класс RbAmpFleet — главный высокоуровневый интерфейс библиотеки v1.3. Он управляет набором модулей на общей шине I²C: обнаружение, настройка, агрегация опроса, агрегация ошибок и синхронные снимки через широковещание General-Call.

Один флот привязан к одной шине TwoWire (обычно Wire); каждый добавленный модуль — принадлежащий флоту дескриптор RbAmp. Мягкий предел числа модулей — RBAMP_FLEET_MAX_MODULES = 16.

Жизненный цикл

C++
RbAmpFleet(TwoWire& bus);
~RbAmpFleet();              // releases all adopted handles

После ~RbAmpFleet() любые указатели на дескрипторы, полученные через get(idx), становятся недействительными.

Обнаружение — scan()

C++
bool scan(bool match_product, size_t& added);

Опрашивает шину в диапазоне 0x08..0x77, и для каждого адреса, который отвечает ACK:

  1. Проверяет идентичность (PRODUCT_ID, HW_VARIANT, CAPABILITY). Если match_product = true, требует совпадения с PRODUCT_ID rbAmp.

  2. Запускает детектор конфликтов по двум независимым признакам (согласованность идентичности + живое значение). Подозрительные адреса попадают в список excluded, а не во флот.

  3. Выполняет проверку «канарейкой» (Tier-2) на зависание шины: она обращается к адресу, где заведомо никого нет. Если канарейка получает ACK, возвращается false — шина зависла, а флот остаётся пустым (см. диагностику в гл. 10).

После успеха added содержит число модулей, добавленных во флот. excludedCount() (см. ниже) доступен через отдельный геттер.

Доступ к модулю

C++
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;

size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;

get возвращает nullptr при выходе за диапазон; find возвращает nullptr, если адреса нет во флоте (например, потому что он оказался исключён). add позволяет вручную добавить дескриптор, созданный отдельно (например, после ручной настройки).

Опрос — pollAll()

C++
bool pollAll(RbAmpSnapshot* snaps,
             RbAmpFleetPoll* status,
             size_t capacity,
             size_t& n_ok);

Опрашивает все модули флота одним вызовом. Для каждого модуля выполняется полное чтение RT (readAll()), результат прикрепляется к элементу snaps[i]. Параллельно status[i] получает результат по модулю (ok=true/false + addr + channels).

После возврата n_ok — число модулей, для которых получен корректный снимок.

Устойчивость к пропускам (MISS): один молчащий модуль не отменяет опрос остальных. Это важно для промышленного флота — потеря одного модуля (обрыв провода, выгорание) не должна гасить весь мониторинг.

Агрегация

C++
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;

totalPower суммирует активную мощность по всем каналам всех модулей. У вариантов I активной мощности нет → они дают 0. В каноническом развёртывании (UI1 на сети + I2/I3 суб-счётчики) результат — активная мощность модуля на сети.

totalEnergyWh аналогично суммирует накопители Wh дескрипторов. Работает корректно: варианты I дают 0, UI1 даёт энергию по каждой нагрузке.

pollErrors перебирает флот, вызывая hasError() у каждого модуля; error_mask — битовая маска модулей с флагом EVENT bit3 по их позиции (значимо для первых 32 модулей); n_errors — общее число модулей с флагом ошибки на момент опроса.

Адресация и проверка конфликтов

C++
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;

assignAddress переназначает адрес существующему модулю флота на новый: внутри — двухфазная фиксация + сброс; дескриптор во флоте обновляется автоматически (последующие вызовы продолжают работать).

checkConflict — лучшая попытка: проверка только чтения по конкретному адресу: читает идентичность (PRODUCT_ID / HW_VARIANT / CAPABILITY) и сравнивает с кэшированным состоянием флота. Если обнаружено несоответствие — collision = true. Чтобы обойти все известные адреса, переберите флот: for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). Она не гарантирует поимку одинаковых модулей — см. дисциплину provisioning.

Provisioning — provision() (статический)

C++
static bool provision(TwoWire& bus,
                      uint8_t desired_addr,
                      bool save_config,
                      RbAmp*& out_dev);

Принимает TwoWire& (обычно Wire) и out_dev как выходной параметр. При успехе out_dev принадлежит вызывающему коду — обычно его сразу передают в fleet.add(out_dev):

Provisioning ровно одного девственного модуля (на заводе 0x50) на заданный адрес. Внутри:

  1. Проверяет наличие ответа по адресу 0x50.
  2. Проверяет, что по desired_addr никого нет.
  3. Выполняет двухфазную фиксацию нового адреса.
  4. Сбрасывает модуль и ждёт его появления по desired_addr в пределах окна загрузки.

  5. Создаёт дескриптор; если save_config = true — вызывает saveUserConfig() (сохранение во флеш).

  6. Возвращает готовый дескриптор через out.

Безопасность

⚠ ОБЯЗАТЕЛЬНО: ровно один модуль в исходном состоянии на шине в момент вызова. Два модуля с адресом 0x50 одновременно физически неотличимы по I²C — их нельзя различить даже специальным оборудованием. Гарантия держится на операторе, а не на библиотеке. Восстановление — см. 10 · Устранение неполадок, раздел «Флот: сбой настройки».

Синхронизация GC флота — синхронные снимки по всему флоту

C++
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
               RbAmpFleetSync* status,
               size_t status_cap,
               size_t& n_missed);

Для плотной синхронизации снимков по всему флоту используется широковещательный снимок I²C General-Call.

  1. enableGcAll устанавливает FLEET_CONFIG.bit0 и GROUP_ID на всех модулях флота и выдаёт CMD_SAVE_USER_CONFIG на каждом (постоянно). Перезагрузка модулей после включения обязательна — выполняется автоматически. ok_count — число модулей, для которых включение прошло успешно.

  2. gcLatch отправляет кадр GC A5 27 group tick_lo tick_hi на адрес 0x00 — все модули с включённым GC и совпадающим group мгновенно выполняют команду снимка (LATCH_PERIOD). settle_ms — пауза после кадра (обычно 50 мс) до проверки.

  3. checkSync читает GC_TICK (0x59) на каждом модуле в RbAmpFleetSync status[status_cap]. Результат по модулю:

C++
struct RbAmpFleetSync {
    uint8_t  addr;        // I²C address of the module
    uint16_t gc_tick;     // REG_GC_TICK; 0xFFFF = never received a GC
    bool     in_sync;     // true if gc_tick == expected_tick
    bool     reachable;   // false if the read NACKed / timed out
};

n_missed — число модулей с in_sync = false (или просто не отвечающих). Если все модули в in_sync, то n_missed == 0.

Конфигурация флота по устройствам (v1.3)

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

bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept

enableGc(true) пишет 1 в FLEET_CONFIG.bit0 (0x27) + сохраняет во флеш + сброс — модуль начнёт принимать снимки GC после загрузки. enableGc(false) симметрично сбрасывает бит. Блокирует на ~1 секунду (установление SAVE_USER_CONFIG + установление сброса). readFleetConfig возвращает текущий байт конфигурации — удобно для подтверждения обратным чтением.

bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept

GROUP_ID (0x28) — фильтр кадров GC: модуль реагирует только на кадры GC с совпадающим group_id. По умолчанию = 0x00 (широковещание, реагирует на любой). Используется для шин с несколькими арендаторами — например, группа «фаза A» и группа «фаза B» на одной общей шине.

bool readGcTick(uint16_t& out) noexcept

Читает GC_TICK (0x59) — последнее значение тика, полученное из кадра GC. Используется для обнаружения пропущенных кадров (если у двух модулей разные тики, кто-то пропустил кадр). 0xFFFF = модуль не получал ни одного кадра GC с момента загрузки.

static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept

Низкоуровневая отправка кадра GC A5 27 group tick_lo tick_hi напрямую через bus (без флота). Полезно, если флот ещё не создан или нужен ручной контроль счётчика тиков.

bool readActiveAddress(uint8_t& out) noexcept

Нативный протокол

4.5 Адрес (0x30..0x31) (api-reference)

Читает REG_I2C_ADDRESS (0x30) — активный (рабочий) адрес модуля. На v1.3 при загрузке читается активный адрес, а не подготовленный кандидат. На линии STD возвращается сохранённое поле адреса (применяется при сбросе). Полезно для подтверждения обратным чтением после commitAddressChange().

Класс RbAmpEnergy

Накопитель Wh по каждому каналу. Принадлежит RbAmp, доступен через dev.energy(). Пользователь обычно не создаёт его напрямую.

Публичные методы

C++
double wh(uint8_t ch = 0) const noexcept;

Текущий итог Wh по каналу или по всем каналам через RBAMP_ENERGY_CH_TOTAL. Знаковый: отрицательное значение означает чистый экспорт. Если ch вне диапазона, возвращается 0.0. (На модуле STD без поканальных счётчиков используйте RbAmp::energyWh(), чтобы получить NaN вместо вводящего в заблуждение 0.)

C++
void addWh(uint8_t ch, double wh) noexcept;

Добавляет знаковую энергию к одному каналу или к суммарному итогу по всем каналам. Используется библиотекой на пути счётчиков STD; доступно и пользовательскому коду, который интегрирует энергию сам.

C++
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;

Обнулить один канал (или общий итог через RBAMP_ENERGY_CH_TOTAL) или все каналы.

C++
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;

Включение / выключение автоматического интегрирования. Пока интегрирование выключено, readPeriodSnapshot() продолжает работать, но не тикает накопитель — полезно, если мастер ведёт собственное постоянное хранилище Wh.

C++
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;

Диагностика: сколько тиков интегрирования было пропущено, потому что период мастера был длиннее предела санитарной проверки в один час.

Внутренний tick()

C++
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;

Вызывается автоматически из RbAmp::readPeriodSnapshot() при успехе. Пользовательский код его напрямую не вызывает. Идемпотентен: снимки с valid == false игнорируются.

Формула интеграции:

Text
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
         [W]              [milliseconds]              → [Wh]

Точность

Зависит от платформы — подробности см. в 04 · Аппаратная часть:

  • ESP32 / ESP8266 / STM32duino / SAMD / RP2040: 64-битный накопитель double.

  • Классический Arduino AVR (Uno, Mega, Nano): тулчейн определяет double как 32-битный float. Для долгих установок с длительным тестом периодически сбрасывайте накопитель (например, раз в сутки).

Структуры POD и перечисления

Структуры линии STD (RbAmpStd*) описаны вместе с вызовами, которые их возвращают, в разделе API линии STD.

RbAmpSnapshot

Возвращается readAll(). Все поля в единицах СИ. Неиспользуемые каналы (за пределами channels) заполняются нулями.

C++
#define RBAMP_MAX_CHANNELS 7                       // override before including to shrink the arrays

struct RbAmpSnapshot {
    float voltage;                                 // V — RMS voltage
    float voltage_peak;                            // V — peak voltage
    float current[RBAMP_MAX_CHANNELS];             // A — RMS current per channel
    float current_peak[RBAMP_MAX_CHANNELS];       // A — peak current per channel
    float power[RBAMP_MAX_CHANNELS];               // W — active power per channel (signed)
    float power_factor[RBAMP_MAX_CHANNELS];        // dimensionless, −1..+1
    float frequency;                               // Hz — grid frequency
    RbAmpTopology topology;                        // Single / SplitPhase / ThreePhase / Five / Seven
    uint8_t channels;                              // 1..RBAMP_MAX_CHANNELS — number of valid channels
    bool has_voltage_hw;                           // true if a voltage sensor is present
    uint8_t implausible;                           // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

Биты implausible: RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.

RbAmpPeriodSnapshot

Возвращается readPeriodSnapshot(). Базовый примитив учёта энергии.

C++
struct RbAmpPeriodSnapshot {
    float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
    float max_p;                     // W — peak instantaneous power on channel 0
    uint32_t latch_ms;               // ms — period duration (device's view, diagnostic; 0 on STD)
    uint32_t master_dt_ms;           // ms — master wall-clock dt since the last snapshot
    bool valid;                      // true if the snapshot ready flag was set
    float avg_p_total;               // W — average active power over the period, all channels
    double wh_net;                   // Wh — net energy of this period (import − export)
    bool module_restarted;           // the module restarted inside this period (STD counter path only)
};
Примечание

latch_ms — диагностический таймер модуля; не используйте его для энергии, берите часы мастера (master_dt_ms).

RbAmpTopology

C++
enum class RbAmpTopology : uint8_t {
    Single      = 1,   // 1 current channel (UI1 / I1)
    SplitPhase  = 2,   // 2 current channels (UI2 / I2)
    ThreePhase  = 3,   // 3 current channels (UI3 / I3)
    Five        = 5,   // 5 current channels (UI5) — senior SKU
    Seven       = 7,   // 7 current channels (UI7) — senior SKU
};

RbAmpLine

C++
enum class RbAmpLine : uint8_t {
    Basic = 0,   // 8-bit register map (the default until begin() runs)
    Std   = 1,   // STANDARD (STD) line: 16-bit register map
};

RbAmpVariant

Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — см. readVariant().

RbAmpSensorClass

C++
enum class RbAmpSensorClass : uint8_t {
    Unset     = 0,  // Factory default; setCTModel() will refuse
    Sct013    = 1,  // SCT-013 series clamp fitted by the user
    WiredCT   = 2,  // Wired CT shipped with the module and calibrated together with it
    BuiltinCT = 3,  // Built-in CT, calibrated together with the module
};

WiredCT и BuiltinCT описывают модули, которые поставляются и калибруются вместе со своим датчиком. Сеттеры никогда не перезаписывают такие модули (они возвращают false с RB_ERR_MODE); setCTModelChForce() — сервисный путь.

RbAmpCTModel

Замороженный enum для обратной совместимости для семи кодов SCT-013 (Sct013_005 … Sct013_060). Новый код передаёт сгенерированный define RBAMP_CT_* в перегрузки uint8_t.

RbAmpSctRating и RbAmpSctRatingStatus

См. Коррекция номинала SCT-013.

RbAmpDrdyEvent

См. Линия готовности данных и события.

Коды ошибок (пространство имён rbamp)

Определено в RbAmpRegisters.h, возвращается из lastError().

C++
namespace rbamp {
    constexpr int8_t RB_OK                  =  0;
    constexpr int8_t RB_ERR_IO              = -1;   // I²C transport error
    constexpr int8_t RB_ERR_NACK            = -2;   // retry exhausted, slave not responding
    constexpr int8_t RB_ERR_TIMEOUT         = -3;   // timeout (waitReady / waitDataReady / commit-addr window expired)
    constexpr int8_t RB_ERR_NOT_READY       = -4;   // module not ready / no such record / nothing armed
    constexpr int8_t RB_ERR_STALE           = -5;   // period snapshot not ready
    constexpr int8_t RB_ERR_PARAM           = -6;   // invalid channel / address / precondition; the module rejected a value
    constexpr int8_t RB_ERR_MODE            = -7;   // not allowed in the module's current mode (factory-paired class, factory-only command)
    constexpr int8_t RB_ERR_CHECKSUM        = -8;   // value check failed — checksum / signature / range
    constexpr int8_t RB_ERR_VERSION         = -9;   // unsupported firmware / image version
    constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10;  // no counterpart on this line or on this module image
    constexpr int8_t RB_ERR_NON_PHYSICAL    = -11;  // float rejected by the sanity filter
}

Диагностические рецепты для каждого кода — 10 · Устранение неполадок.

Диагностические рецепты для каждого кода — 10 · Устранение неполадок.

Конфигурация на этапе компиляции

Определите ДО #include , чтобы переопределить значения по умолчанию:

C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5    // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5      // pause between attempts, ms
#include 

Значения по умолчанию для платформ:

C++
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
#  define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
#  define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5

Подробнее о подсистеме устойчивости — 10 · Устранение неполадок.

Константы времени установления

Определены в RbAmpRegisters.h. Библиотека использует их внутри; они экспортированы для пользователей, которые хотят соблюдать те же тайминги при прямом доступе к шине:

C++
constexpr uint16_t SETTLE_MS_LATCH_PERIOD  =   50;  // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS    =  700;  // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET         =  300;  // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500;  // after CMD_FACTORY_RESET

Подробности протокола на линии

Безопасность

Этот раздел описывает 8-битный протокол регистров линейки BASIC. Линейка STD использует 16-битный указатель регистров с пакетным чтением с автоинкрементом; библиотека справляется с этим внутри (begin() определяет линейку), а физическая проводка та же шина I²C. Прикладному коду никогда не нужны детали проводки STD — используйте вызовы из API линейки STD.

Чтение регистров — автоинкремент

Пакетное чтение + N bytes возвращает N подряд идущих байт, начиная с addr. Методы библиотеки используют пакеты там, где это возможно (одна транзакция I²C = 4 байта float).

Запись регистров — побайтно (БЕЗ автоинкремента)

⚠ Записи НЕ инкрементируют адрес автоматически. Пачечная ЗАПИСЬ + N bytes записывает только первый байт — байты 1..N отбрасываются.

Многобайтовый регистр записывается по одному байту за раз — отдельная однобайтовая транзакция I²C на каждый адрес:

C++
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68);                  // start of LABEL
Wire.write(label, 8);              // burst — only 'M' lands
Wire.endTransmission();

// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
    Wire.beginTransmission(addr);
    Wire.write(0x68 + i);
    Wire.write(label[i]);
    Wire.endTransmission();
}

Затрагивает записываемые многобайтовые регистры: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, только на заводе), NF (u16), THRESH (u16). Чтение — пачкой допустимо.

Исключение: кадр широковещания GC (5 байт A5 27 g tl th на адрес 0x00) — это отдельный путь протокола на линии (приём general-call, а не запись регистра), отправляется одной транзакцией. См. сценарий 12 в 06 · Примеры.

Чтение нераспределённых регистров

Любое чтение с незамапленного адреса возвращает 0x00. Прошивка никогда не отвечает NACK на чтение регистров. Обнаружение отсутствия устройства идёт через ACK кадра адреса I²C, а не через опрос регистров.

Определение варианта

Авторитетный байт SKU — REG_HW_VARIANT (0x55) (метод readVariant()):

значение SKU
0x01 UI1 (1× I + U)
0x02 UI2 (2× I + U)
0x03 UI3 (3× I + U)
0x04 I1 (1× I, без U)
0x05 I2 (2× I, без U)
0x06 I3 (3× I, без U)
0x07 UI5 (5× I + U, старший SKU)
0x08 UI7 (7× I + U, старший SKU)

REG_TOPOLOGY (0x24) вспомогательный (сообщает только число каналов, не различает наличие U). На линии STD библиотека читает идентичность из собственной 16-битной карты модуля во время begin() и сопоставляет вариант с readVariant().

Широковещательный снимок General-Call (синхронизация нескольких модулей)

Включение для каждого модуля через REG_FLEET_CONFIG.bit0 — GC_ENABLE. По умолчанию ВЫКЛ. Включается через CMD_SAVE_USER_CONFIG + CMD_RESET (мягкий или жёсткий). После сброса модуль слушает широковещательный кадр по адресу 0x00:

Text
addr=0x00 | A5 27   
  • A5 — маркер; 27 — opcode CMD_LATCH_PERIOD.
  • — 0x00 = all-call, иначе должен совпасть с REG_GROUP_ID (0x28).
  • — 16-битный счётчик периода синхронизации мастера.

Кадр только берёт снимок; разрушающие опкоды по GC не передаются.

Обнаружение режима отказа (двухуровневое):

  1. NACK по адресу GC (сразу на уровне шины): если GC выключен на всём флоте — Wire.endTransmission() на 0x00 возвращает ненулевой код (NACK). Это жёсткая ошибка, а не тихий сброс. Библиотека трактует это как «GC не включён» (требуются предусловия: включение и сброс).
  2. Свидетель по модулю (после установления): если NACK не было — прочитайте REG_V03_PERIOD_VALID (0x07) на каждом ожидаемом модуле. 1 = снимок успешен; 0 = GC выключен на этом модуле или период пуст; !=1 → откат к защёлке по каждому устройству.

Ссылки


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