rbAmp
RU
Магазин
Документация
Обновлено · Изменить на GitHub

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

Полный публичный API компонента rbamp для ESP-IDF. Источник — заголовочный файл include/rbamp.h с комментариями Doxygen; менеджер нескольких модулей — в include/rbamp_fleet.h, а тип накопителя Wh — в include/rbamp_energy.h.

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

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

#include "rbamp.h" — главный публичный заголовок. Он транзитивно подтягивает esp_err.h для esp_err_t и driver/i2c_master.h для типа i2c_master_bus_handle_t. Никаких дополнительных включений не требуется.

API обёрнут в блок extern "C" — совместим с вызывающими и на C, и на C++.

Общие идиомы

API следует стандартным шаблонам ESP-IDF:

  • Непрозрачный дескриптор: rbamp_handle_t — typedef для struct rbamp_obj_t *; пользователь не обращается к его внутренностям. Создаётся через rbamp_new(), освобождается через rbamp_del().

  • Возвраты esp_err_t — ESP_OK при успехе, один из кодов ESP_ERR_* при ошибке. Используйте ESP_ERROR_CHECK() для обработки с прерыванием, или проверяйте вручную.

  • Вывод через указатель: функции, возвращающие значение, принимают последним параметром указатель на буфер. Так один вызов возвращает и esp_err_t, и значение.

  • Строки ошибок для людей: rbamp_err_to_str(err) возвращает указатель на статическую строку. Никогда не возвращает NULL.

  • Один дескриптор, две линейки модулей: тот же дескриптор и тот же скалярный API обслуживают линейку BASIC и линейку STD; rbamp_begin() определяет линейку и направляет каждый вызов. Функции, существующие только на одной линейке, на другой возвращают ESP_ERR_NOT_SUPPORTED (см. rbamp_line_t и Линия STD).

  • Команды не повторяются. Запись команды (снимок, сброс, сохранение и т. д.) никогда не повторяется после ошибки транспорта — повтор мог бы доставить код операции дважды. Чтения и записи регистров данных сохраняют повтор при NACK.

  • Соответствие ошибок, используемое в API: ESP_ERR_NOT_SUPPORTED — функции или возможности нет на этой линии / прошивке / модуле; ESP_ERR_NOT_FOUND — модуль или запись отсутствует (никто не подтверждает, нет такой записи истории, нет сертификата); ESP_ERR_INVALID_STATE — предусловие или последовательность вызовов нарушена, либо модуль парного датчика защищён (см. Коды ошибок).

Типы

rbamp_handle_t

C
typedef struct rbamp_obj_t *rbamp_handle_t;

Непрозрачный дескриптор подчинённого устройства. У пользователя нет доступа к его полям. Создаётся через rbamp_new(), освобождается через rbamp_del().

rbamp_topology_t

C
typedef enum {
    RBAMP_TOPOLOGY_SINGLE      = 1,  /* 1 current channel (UI1 / I1) */
    RBAMP_TOPOLOGY_SPLIT_PHASE = 2,  /* 2 current channels (UI2 / I2) */
    RBAMP_TOPOLOGY_THREE_PHASE = 3,  /* 3 current channels (UI3 / I3) */
    RBAMP_TOPOLOGY_FIVE_CH     = 5,  /* 5 current channels (UI5)      */
    RBAMP_TOPOLOGY_SEVEN_CH    = 7,  /* 7 current channels (UI7)      */
} rbamp_topology_t;

Значение — число каналов. rbamp_begin() берёт его из варианта модуля; rbamp_new_with_topology() фиксирует его. Перечисление намеренно несплошное (нет 4 или 6): более крупные SKU идут 3 → 5 → 7.

Две константы задают размер ваших массивов:

Макрос Значение Значение
RBAMP_MAX_CHANNELS 7 Наибольшее число каналов, которое есть у любого SKU. Размер массивов каналов задавайте по нему.
RBAMP_SNAPSHOT_CHANNELS 3 Каналы, передаваемые в rbamp_snapshot_t (ch0–2). Каналы 3+ читаются через rbamp_read_channel() / rbamp_read_all_channels().

rbamp_sensor_class_t

C
typedef enum {
    RBAMP_SENSOR_UNSET      = 0,  /* Factory default */
    RBAMP_SENSOR_SCT013     = 1,  /* SCT-013 fitted by the user */
    RBAMP_SENSOR_WIRED_CT   = 2,  /* Wired CT shipped with the module, calibrated as a pair */
    RBAMP_SENSOR_BUILTIN_CT = 3,  /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;

Класс 1 — модуль, к которому пользователь подключает SCT-013 по своему выбору: модель CT определяет тип датчика. Классы 2 и 3 — модули, которые поставляются вместе с датчиком и калибруются вместе с ним. Библиотека не переписывает класс или модель такого модуля: rbamp_set_sensor_class() и rbamp_set_ct_model_ch() возвращают ESP_ERR_INVALID_STATE. Сервисная перепривязка выполняется через rbamp_set_ct_model_ch_force().

rbamp_variant_t

Вариант аппаратной сборки, возвращаемый rbamp_variant() и rbamp_read_variant():

Значение Перечисление Каналы Напряжение / мощность
0 RBAMP_VARIANT_UNKNOWN — ещё не прочитано / не опубликовано
1 RBAMP_VARIANT_UI1 1 да
2 RBAMP_VARIANT_UI2 2 да
3 RBAMP_VARIANT_UI3 3 да
4 RBAMP_VARIANT_I1 1 нет
5 RBAMP_VARIANT_I2 2 нет
6 RBAMP_VARIANT_I3 3 нет
7 RBAMP_VARIANT_UI5 5 да
8 RBAMP_VARIANT_UI7 7 да

rbamp_line_t

C
typedef enum {
    RBAMP_LINE_BASIC = 0,  /* default until rbamp_begin() has run */
    RBAMP_LINE_STD   = 1,
} rbamp_line_t;

Один тип дескриптора и один API обслуживают обе линейки модулей. rbamp_begin() определяет линейку по блоку идентификации модуля, и каждый последующий вызов направляется внутренне. Запрашивайте через rbamp_line(dev). Вызовы, у которых нет аналога на обнаруженной линейке, возвращают ESP_ERR_NOT_SUPPORTED — никогда не чтение неверного регистра. Всё, что предлагает только линия STD (реактивная / полная мощность, THD, знаковые счётчики энергии, банки снимков, история), собрано в Линия STD.

rbamp_snapshot_t

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

C
typedef struct {
    float voltage;          /* V — RMS voltage */
    float voltage_peak;     /* V — peak voltage */
    float current[3];       /* A — RMS current, ch0–2 */
    float current_peak[3];  /* A — peak current, ch0–2 */
    float power[3];         /* W — active power, ch0–2 (signed) */
    float power_factor[3];  /* dimensionless, −1..+1 */
    float frequency;        /* Hz — mains frequency */
    rbamp_topology_t topology;
    uint8_t channels;       /* the module's channel count: 1, 2, 3, 5 or 7 */
    bool has_voltage_hw;    /* true if a voltage sensor is present */
    uint8_t implausible;    /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;

Массивы содержат только каналы 0–2. На UI5/UI7 поле channels сообщает полное число (5 или 7); каналы 3+ читайте через rbamp_read_channel() / rbamp_read_all_channels().

Неправдоподобные поля. Одно поле вне границ не проваливает весь снимок: поле, нарушившее свою границу адекватности, устанавливается в NaN, а его бит класса поднимается в implausible; остальные остаются пригодными, и rbamp_read_all() по-прежнему возвращает ESP_OK. Проверяйте implausible (или isnan() по полю) перед использованием значения.

Бит Значение
RBAMP_FIELD_VOLTAGE voltage / voltage_peak отклонён
RBAMP_FIELD_CURRENT ток / current_peak отклонён
RBAMP_FIELD_POWER мощность отклонена
RBAMP_FIELD_PF power_factor отклонён
RBAMP_FIELD_FREQUENCY частота отклонена

Границы: RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 В, 150 А, 30 000 Вт, 1.5). Только реальный сбой транспорта заставляет rbamp_read_all() вернуть не-OK.

rbamp_channel_reading_t

Возвращается rbamp_read_channel() / rbamp_read_all_channels() — один канал, любой индекс.

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A */
    float   p_real;       /* W (signed) */
    float   pf;           /* −1..+1 */
    uint8_t implausible;  /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;

rbamp_period_snapshot_t

Возвращается rbamp_read_period_snapshot(). Примитив учёта энергии.

C
typedef struct {
    float    avg_p[3];          /* W — average active power over the period, ch0–2 */
    float    max_p;             /* W — peak power on channel 0 during the period */
    uint32_t latch_ms;          /* ms — module-reported duration; DIAGNOSTIC, not for energy */
    uint32_t master_dt_ms;      /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
    bool     valid;             /* the period was ready at read time */
    float    avg_p_total;       /* W — average active power summed over ALL channels (signed) */
    double   wh_net;            /* Wh — net energy of this period as the library accounted it (signed) */
    bool     module_restarted;  /* the module rebooted inside this period */
    uint32_t module_window_ms;  /* ms — the module's own length of the closed window (0 on STD) */
    uint16_t module_commit_ms;  /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
    uint32_t module_uptime_s;   /* s — module uptime read with the snapshot (0 if not published) */
    bool     window_from_boot;  /* the window started at the module's boot */
    bool     window_long;       /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
Поле Примечания
avg_p[3] Только каналы 0–2. На UI5/UI7 модуль делает снимок средней мощности для всех каналов атомарно; каналы 3+ читайте через rbamp_read_period_avg_power(), а их Wh — через rbamp_energy_wh() (накопитель интегрирует каждый канал).
max_p Глобальный пик, измеренный на канале 0.
latch_ms Только для диагностики; под нагрузкой может показывать меньше. Окно интегрирования энергии — master_dt_ms или module_window_ms.
master_dt_ms Окно, по которому библиотека интегрирует энергию: собственное время мастера по esp_timer между двумя последовательными учтёнными чтениями.
avg_p_total, wh_net Период, суммированный по всем каналам. wh_net — средняя мощность × master_dt_ms, или — на модулях, которые хранят энергию в самом устройстве, — разность собственного счётчика модуля.
module_window_ms, module_commit_ms Измерение модулем закрытого окна: коммиты, посчитанные по измерительным часам модуля, по 100 мс каждый в текущей прошивке и по 200 мс в прошивке старше v1.2 — библиотека определяет, какая именно, по тому же снимку. Обычно сверяется с master_dt_ms. На линии STD оба равны 0.
module_restarted Модуль перезагрузился внутри периода. Его настройки в RAM (часы, маска событий, пороги, поля дайджеста) нужно применить заново — библиотека заново применяет те, которыми владеет. На модуле BASIC это делается при первом снимке после rbamp_begin_resume(), когда окно началось с загрузки модуля.
module_uptime_s, window_from_boot window_from_boot равен true, когда окно снимка началось при загрузке модуля (перезапуск или первый снимок после загрузки). Всегда false, если прошивка не публикует аптайм (module_uptime_s = 0).
window_long Окно превышает 6 ч: среднее модуля теряет точность на очень длинных окнах — берите снимки чаще.
Безопасность

⚠ latch_ms — диагностика, не для энергии. Это собственная мера модуля для периода, и под нагрузкой она может показывать меньше. Не используйте её для интегрирования энергии. Каноничный dt для энергии — master_dt_ms (или ваша собственная разность esp_timer_get_time()), либо module_window_ms для первого снимка после rbamp_begin_resume().

Биты событий — rbamp_event_bit_t

Биты липкого байта EVENT_FLAGS с записью 1 для сброса (см. События):

Перечисление Значение
RBAMP_EVENT_PERIOD_READY Снимок периода был взят
RBAMP_EVENT_THRESH_I Пересечён порог тока
RBAMP_EVENT_THRESH_P Порог мощности превышен
RBAMP_EVENT_ERROR Индикатор устойчивой ошибки (см. Модель ошибок)
RBAMP_EVENT_CONFIG_CHANGED Сохранённая конфигурация изменилась
RBAMP_EVENT_RESET_OCCURRED Сброс модуля с момента последней очистки
RBAMP_EVENT_NVM_FAULT Только STD: неисправность накопителя энергии

rbamp_drdy_event_t

Заполняется rbamp_wait_data_ready() / rbamp_read_all_ready():

C
typedef struct {
    bool     fresh;        /* a new snapshot of THIS module is available (true on ESP_OK) */
    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: an unmasked event is pending on this module */
    uint8_t  event_flags;  /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
    uint32_t latency_us;   /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;

Типы дайджеста

C
typedef enum {
    RBAMP_DIGEST_I  = ..., /* RMS current per channel */
    RBAMP_DIGEST_U  = ..., /* RMS voltage (modules with voltage sensing only) */
    RBAMP_DIGEST_P  = ..., /* real power per channel, whole watts, signed */
    RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;

typedef struct {
    uint8_t status;     /* STATUS mirror at the moment of the publish */
    uint8_t seq;        /* window sequence (one step per published window, wraps 255→0) */
    uint8_t n_ch;       /* channels in the digest: min(module channels, 3) */
    uint8_t fields;     /* which rbamp_digest_field_t bits were read */
    float   i_a[3];     /* A; 0 when the field is off */
    float   u_v;        /* V; 0 when off or no voltage sensing */
    int16_t p_w[3];     /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
    float   pf[3];      /* |PF| 0..1; 0 when off */
} rbamp_digest_t;

Типы коррекции SCT-013

C
typedef enum {
    RBAMP_SCT_NONE,           /* no correction (scale 1) */
    RBAMP_SCT_CORRECTED,      /* scale applied to this channel */
    RBAMP_SCT_UNCALIBRATED,   /* after a reset the module applies the raw preset; scale 1, warning logged */
    RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
    RBAMP_SCT_UNKNOWN_MODEL,  /* model code without a known preset; scale 1, warning logged */
    RBAMP_SCT_PENDING,        /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;

typedef struct {
    rbamp_sct_status_t status;
    uint8_t model;        /* CT model the module reports for the channel */
    float   scale;        /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
    float   gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;

RBAMP_SCT_NONE сообщается на линии STD для класса датчика 2/3, без привязанной модели, при модели 3 (заводской датчик 30 А), на модуле, который исправляет себя сам (см. Коррекция номинала SCT-013), и когда CONFIG_RBAMP_SCT_RATING_CORRECTION выключен.

Типы линии STD (rbamp_std_info_t, rbamp_std_channel_t, ...) описаны вместе с их функциями в разделе Линия STD.

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

rbamp_new

C
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
                    uint8_t addr,
                    rbamp_handle_t *out);

Создаёт непрозрачный дескриптор для подчинённого устройства. Внутри создаёт i2c_master_dev_handle_t через i2c_master_bus_add_device().

Число каналов и наличие напряжения берутся от модуля в rbamp_begin(): UI1 сообщает 1 канал, UI3 — 3, UI7 — 7 и так далее, поэтому rbamp_channels(dev) корректен сразу после begin, а поканальный API (rbamp_set_ct_model_ch, ...) защищает от каналов, которых у модуля нет. Только если модуль не публикует свой вариант (прошивка старше v1.3), дескриптор переходит к RBAMP_TOPOLOGY_THREE_PHASE; завышенное определение там безвредно — неиспользуемые каналы показывают 0.0 A. Используйте rbamp_new_with_topology(), чтобы зафиксировать число независимо от того, что говорит модуль.

Параметр Описание
bus Дескриптор шины I²C, созданный через i2c_new_master_bus().
addr 7-битный адрес ведомого. Диапазон 0x08..0x77, по умолчанию 0x50.
out Куда записать новый дескриптор.

Возвращает: ESP_OK при успехе; ESP_ERR_NO_MEM, если память не удалось выделить; ESP_ERR_INVALID_ARG, если bus == NULL или out == NULL или addr вне диапазона; esp_err_t из i2c_master_bus_add_device() при ошибке драйвера шины.

rbamp_new_with_topology

C
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
                                  uint8_t addr,
                                  rbamp_topology_t topology,
                                  rbamp_handle_t *out);

То же, что и rbamp_new, но с явной топологией. Она фиксирует число каналов: rbamp_begin() сохраняет его, даже если модуль сообщает другое (в журнал пишется предупреждение). Вариант и наличие напряжения по-прежнему следуют за модулем. Нужно только для прошивки старше v1.3, которая не публикует свой вариант, или чтобы намеренно открыть меньше или больше каналов, чем есть у модуля.

rbamp_del

C
void rbamp_del(rbamp_handle_t dev);

Освобождает дескриптор и удаляет связанный i2c_master_dev_handle_t с шины. Безопасно вызывать с NULL — это пустая операция.

rbamp_begin

C
esp_err_t rbamp_begin(rbamp_handle_t dev);

Опрашивает устройство, определяет линию модуля, принимает число каналов и вариант и выполняет затравочный снимок.

Sequence:

  1. Прочитайте REG_VERSION (0x03). Если устройство не ответило ACK — ESP_FAIL. Если вернулось 0x00 / 0xFF — ESP_ERR_INVALID_RESPONSE.

  2. Определите линию изделия (BASIC / STD) по идентификационному блоку модуля и закэшируйте её (rbamp_line()). На линии STD идентичность тоже кэшируется (rbamp_std_info()), и выбирается механизм периода.

  3. Принимаются число каналов, вариант и наличие напряжения от модуля (если топология не закреплена через rbamp_new_with_topology).

  4. Оцените коррекцию номинала SCT-013 (см. Коррекция номинала SCT-013).

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

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

Идемпотентен, но не бесплатен: каждый вызов выполняет один затравочный снимок.

Возвращает: ESP_OK при успехе; иначе — коды ошибок выше.

rbamp_begin_resume

C
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);

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

Первый обработанный rbamp_read_period_snapshot() после этого интегрирует по собственному окну модуля (module_window_ms): wh_net = avg_p_total × module_window_ms, master_dt_ms задаётся равным module_window_ms, а module_restarted = window_from_boot. Все последующие снимки используют мастер-часы, как обычно. Первое устаревшее чтение (период не валиден, накопитель пуст) отбрасывается, как любое другое, и следующее валидное чтение по-прежнему использует окно модуля.

На прошивке, которая не публикует время работы, window_from_boot и module_restarted остаются false: восстановленное окно тогда может включать перезапуск модуля, который библиотека не видит. На модулях STD вызов полностью идентичен rbamp_begin() (их энергия хранится в счётчиках на модуле).

rbamp_begin_event_flags

C
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);

EVENT_FLAGS в том виде, как их нашёл rbamp_begin() (обе линии; 0, если их нельзя было прочитать). RBAMP_EVENT_RESET_OCCURRED здесь означает, что модуль перезагрузился до того, как библиотека его встретила — заново примените его настройки в RAM (часы, маску событий, пороги). Библиотека при begin ничего не сбрасывает. Без обращения к шине.

rbamp_probe

C
esp_err_t rbamp_probe(rbamp_handle_t dev);

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

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

rbamp_wait_ready

C
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);

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

Возвращает: ESP_OK, если бит замечен до истечения timeout_ms; иначе ESP_ERR_TIMEOUT.

Геттеры состояния дескриптора

C
uint8_t          rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology         (rbamp_handle_t dev);
uint8_t          rbamp_channels         (rbamp_handle_t dev);
rbamp_variant_t  rbamp_variant          (rbamp_handle_t dev);
bool             rbamp_has_voltage_hw   (rbamp_handle_t dev);
uint8_t          rbamp_address          (rbamp_handle_t dev);
rbamp_line_t     rbamp_line             (rbamp_handle_t dev);

Все возвращают кэшированные значения без обращения к шине.

Функция Возвращает
rbamp_firmware_version Байт REG_VERSION, кэшируемый после rbamp_begin() — на линии STD это версия карты регистров, а не версия образа прошивки (см. rbamp_std_read_image_version). 0 до rbamp_begin() или если он завершился с ошибкой.
rbamp_topology Перечисление числа каналов — от модуля после rbamp_begin() или как зафиксировано rbamp_new_with_topology(); THREE_PHASE до begin / на прошивке, которая не публикует свой вариант.
rbamp_channels Количество валидных токовых каналов (1, 2, 3, 5 или 7).
rbamp_variant Вариант, кэшируемый rbamp_begin(); RBAMP_VARIANT_UNKNOWN до begin или если модуль его не публикует. rbamp_read_variant() перечитывает регистр.
rbamp_has_voltage_hw true, если обнаружено аппаратное обеспечение измерения напряжения.
rbamp_address Текущий 7-битный адрес (обновляется после rbamp_commit_address_change()).
rbamp_line RBAMP_LINE_BASIC до выполнения rbamp_begin(), затем — обнаруженная линия.

rbamp_basic_fw_name

C
const char *rbamp_basic_fw_name(uint8_t version);

Чистый поиск (без обращения к шине): человекочитаемое имя прошивки для байта REG_VERSION BASIC, возвращаемого rbamp_firmware_version() — например, 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Любой другой байт → NULL (неизвестен или не модуль BASIC).

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

Все функции возвращают esp_err_t. При ESP_OK значение записывается в указатель out; при ошибке *out не определено. Внутри действует дисциплина повторов и проверок здравого смысла для устойчивости к редким сбоям связи в стеке I²C ESP-IDF.

Чтение по каналам

C
esp_err_t rbamp_read_voltage      (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current      (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power        (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_frequency    (rbamp_handle_t dev,                float *out);
Функция Возвращаемое значение Примечания
rbamp_read_voltage Среднеквадратичное напряжение, В phase = 0 на линии BASIC
rbamp_read_voltage_peak Амплитудное напряжение, В Читает 0 на модуле STD с картой 0x34 и ниже — используйте max_u / min_u из банка снимков
rbamp_read_current Действующий ток канала, А ch < rbamp_channels(dev); каналы 3+ (UI5 / UI7) прозрачно направляются через окно каналов
rbamp_read_current_peak Пиковый ток по каналу, А Читает 0 на модуле STD с картой 0x34 и ниже — используйте max_i из банка снимков
rbamp_read_power Активная мощность, Вт (знаковая) Отрицательное = экспорт (установки с PV / двунаправленные)
rbamp_read_power_factor Коэффициент мощности Безразмерная величина, от −1 до +1
rbamp_read_frequency Частота сети, Гц 50.0 или 60.0 в исправной сети. STD: значение модуля 0 (нет сети) возвращает ESP_ERR_INVALID_RESPONSE с *out = NaN

Если ch или phase вне диапазона, возвращает ESP_ERR_INVALID_ARG.

Однократное чтение всего блока RT

C
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);

Эквивалентно последовательным rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency. Неиспользуемые каналы (сверх rbamp_channels(dev)) заполняются нулями.

На модуле с более чем тремя каналами (UI5 / UI7) в структуру читаются только каналы 0–2 (RBAMP_SNAPSHOT_CHANNELS = 3); каналы 3+ не трогаются — читайте их через rbamp_read_channel() / rbamp_read_all_channels(). На линии STD блок напряжения и блок каждого канала читаются целиком (по одной транзакции на блок).

Поле, которое выходит за границу адекватности, не приводит к ошибке вызова: оно устанавливается в NaN и помечается в snap.implausible, а вызов по-прежнему возвращает ESP_OK (см. rbamp_snapshot_t).

Возвращает: ESP_OK при успехе (проверьте implausible); иначе — первая ошибка транспорта, и тогда содержимое out частичное и его нельзя использовать.

Реактивная и полная мощность

C
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);

Реактивная мощность канала ch в вар (знаковая) и полная мощность в ВА. Эти величины есть только на линии STD; на BASIC реактивная мощность этой библиотекой не выводится, и на дескрипторе BASIC обе функции возвращают ESP_ERR_NOT_SUPPORTED.

Доступ к каналам (каналы 3 и выше)

Каналы 0–2 находятся в плоском RT-блоке. На более крупных вариантах (UI5 / UI7) каналы 3+ доступны только через окно каналов модуля. Библиотека обрабатывает это прозрачно: rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() и rbamp_read_power_factor() принимают любой ch из 0..rbamp_channels(dev)-1 и направляют каналы 3+ через окно. Выбор окна — единый общий ресурс внутри модуля, а выбор и чтение — одна атомарная секция: не используйте один дескриптор из разных задач без собственного мьютекса.

C
esp_err_t rbamp_read_channel     (rbamp_handle_t dev, uint8_t ch,
                                  rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
                                  rbamp_channel_reading_t *out, uint8_t n);
  • rbamp_read_channel читает все четыре RT-поля одного канала в rbamp_channel_reading_t. Поле, вышедшее за границу проверки здравого смысла, равно NaN и помечено битом RBAMP_FIELD_* в implausible.

  • rbamp_read_all_channels заполняет out[] всеми заполненными каналами; n — ёмкость out (задавайте её через RBAMP_MAX_CHANNELS), вызов заполняет min(n, rbamp_channels(dev)) записей.

Возвращает: ESP_OK (проверьте implausible); ESP_ERR_INVALID_ARG при неверном канале или NULL; иначе — первая ошибка транспорта.

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

Примечание

rbamp_read_all() на UI5 / UI7 возвращает первые три канала (RBAMP_SNAPSHOT_CHANNELS = 3) и не трогает остальные; snap.channels по-прежнему показывает реальное число каналов модуля.

rbamp_read_commit_seq

C
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);

Читает байт последовательности дайджеста: uint8_t, который увеличивается раз в окно измерения (каждые 100 мс в текущей прошивке, 200 мс в образах до v1.2; переходит 255 → 0). Прочитайте его до и после многорегистрового опроса — неизменившееся значение доказывает, что все чтения взяты из одной фиксации. Дайджест не содержит CRC.

Готовность данных (DRDY)

Тайминг 100-мс окна реального времени, импульса готовности данных и атомарного чтения блока.
Каждый модуль управляет необязательной линией open-drainDRDYвыход: HIGH в покое (подтяжка мастера), импульс LOW ~10 мкс каждый раз, когда публикуется полный снимок измерения (каждые 100 мс во всём семействе; образы BASIC до v1.2 и STD до 0x7B: 200 мс). Несколько модулей могут делить одну линию монтажного ИЛИ. Модули BASIC также удерживают линию уверенно в LOW, пока висит необслуженное событие (тревога).

Библиотека превращает импульс в пробуждение, чтобы читатель никогда не читал один и тот же снимок дважды, не попадал на момент публикации и узнавал, сколько снимков пропустил. На модулях STD счётчик публикаций показывает, какой модуль выдал импульс на общей линии. Без провода DRDY те же вызовы работают опросом счётчика модуля каждые CONFIG_RBAMP_DRDY_POLL_MS. Модули STD старше образа 0x00010075 управляют линией иначе: библиотека считает, что линии DRDY у них нет, и опрашивает.

C
esp_err_t rbamp_set_drdy_gpio  (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq  (rbamp_handle_t dev, uint16_t *out);
Функция Описание
rbamp_set_drdy_gpio(dev, gpio) Подключает линию DRDY этого модуля или отключает её значением -1. GPIO настраивается как вход с подтяжкой и прерыванием по спадающему фронту; любое число дескрипторов может делить один GPIO. Вызывайте после rbamp_begin() (электрический контракт линии зависит от обнаруженного модуля). Возвращает ESP_ERR_NO_MEM, если используется более 4 различных линий или более 8 дескрипторов на линию.
rbamp_wait_data_ready(dev, timeout_ms, ev) Блокирует, пока модуль не опубликует снимок новее последнего, который вернул этот вызов (или последнее чтение через rbamp_read_all_ready), но не дольше timeout_ms. ev может быть NULL.
rbamp_read_all_ready(dev, timeout_ms, out, ev) rbamp_wait_data_ready(), затем rbamp_read_all(): одно согласованное чтение на каждый опубликованный снимок, никогда не один и тот же снимок дважды.
rbamp_read_data_seq(dev, &seq) Текущая последовательность снимков без ожидания.

Как работает ожидание с линией DRDY. Функция просыпается по спадающему фронту, затем проверяет, что последовательность модуля продвинулась (импульс на общей линии может принадлежать другому модулю — тогда вызов продолжает ждать). Если линия всё ещё LOW через 5 мс после фронта, на каком-то модуле линии ожидает необслуженное событие: читаются и сбрасываются флаги каждого модуля, подключённого к линии (запись 1 для сброса, что освобождает линию — удержанная линия скрыла бы импульсы других модулей). Флаги этого модуля возвращаются в ev с установленным alarm; флаги других модулей передаются их собственным дескрипторам и сообщаются при их следующем ожидании.

Возвращает (rbamp_wait_data_ready): ESP_OK (свежий снимок); ESP_ERR_TIMEOUT; ESP_ERR_NOT_SUPPORTED на модулях STD без счётчика публикаций (версия карты регистров ниже 0x36).

C
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
    rbamp_snapshot_t s;
    rbamp_drdy_event_t ev;
    if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
        if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
        /* use s — exactly one read per published snapshot */
    }
}

Дайджест BASIC

Дайджест — компактный блок, который модуль BASIC публикует с каждым окном. Он позволяет мастеру получить результат окна одной транзакцией I²C вместо одной на каждое поле.

C
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest      (rbamp_handle_t dev, rbamp_digest_t *out);
  • rbamp_set_digest_fields(dev, fields) выбирает поля, которые модуль упаковывает в дайджест: OR из RBAMP_DIGEST_I, _U, _P, _PF (не 0). По умолчанию, если не вызывалась, — ток + активная мощность, плюс напряжение на модулях с измерением напряжения. Выбор записывается в модуль при следующем rbamp_read_digest() (или сразу, когда дескриптор уже начат на модуле BASIC с возможностью дайджеста). Модуль хранит его только в RAM, поэтому библиотека записывает его заново после обнаруженного перезапуска модуля. Возвращает ESP_ERR_INVALID_ARG для 0, для неизвестных битов или когда модуль отклоняет поле, которого у него нет (напряжение на модуле только с током); ESP_ERR_NOT_SUPPORTED на линии STD или на прошивке без возможности дайджеста.

  • rbamp_read_digest(dev, &d) читает статус, номер окна и выбранные поля для каналов 0–2 одной транзакцией. Предназначено для чтения каждого опубликованного окна по DRDY: rbamp_wait_data_ready(), затем rbamp_read_digest() даёт знаковую активную мощность каждого окна за несколько байтов шины. Каналы 3+ в дайджесте не входят (используйте rbamp_read_channel()). Активная мощность — в целых ваттах; нагрузка ниже 1 Вт читается как 0. Возвращает ESP_OK; ESP_ERR_NOT_SUPPORTED на линии STD или на прошивке BASIC без возможности дайджеста; ошибки транспорта.

Учёт по периодам

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

rbamp_latch_period

C
esp_err_t rbamp_latch_period(rbamp_handle_t dev);

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

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

rbamp_is_period_valid

C
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);

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

rbamp_read_period_avg_power

C
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
                                      uint8_t ch, float *out);

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

rbamp_read_period_max_power

C
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);

Пиковая мгновенная мощность канала 0 за период снимка. ch=0 только на прошивке v1.

rbamp_read_period_latch_ms

C
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);

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

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

Время, сообщаемое модулем, под нагрузкой может быть занижено. Для интегрирования энергии используйте master_dt_ms (или module_window_ms) из rbamp_period_snapshot_t, а не это поле.

rbamp_read_period_snapshot

C
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
                                     rbamp_period_snapshot_t *out,
                                     uint16_t settle_ms,
                                     bool skip_latch);

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

  1. Если skip_latch == true — пропустить запись LATCH (используется после ручной серии команд снимка или широковещательного снимка для синхронизации нескольких модулей).

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

  3. Зафиксируйте esp_timer_get_time(), чтобы вычислить master_dt_ms.
  4. vTaskDelay(pdMS_TO_TICKS(settle_ms)) — по умолчанию 50 мс.
  5. Проверьте флаг готовности снимка. Если он 0 — установите ESP_ERR_INVALID_RESPONSE и запишите метку времени (чтобы следующий снимок не удвоил учёт dt).

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

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

Возвращает: ESP_OK, если out->valid == true; ESP_ERR_INVALID_RESPONSE, если снимок устарел (при устаревании энергия не интегрируется, а якорь сохраняется); ESP_ERR_NOT_SUPPORTED на модуле STD без банков снимков и без счётчиков; иначе — esp_err_t от операций на шине. Поведение STD см. в Вызовы периода на линии STD.

Энергия интегрируется за master_dt_ms — собственное окно мастера между последовательными учтёнными чтениями. После rbamp_begin_resume() первый учтённый снимок интегрирует вместо этого окно самого модуля.

Рекомендуемый темп.

Между вызовами снимков: 60 с — комфортно, 30 с — на грани, < 10 с гарантируют устаревшие чтения. Прошивка интегрирует периодический накопитель внутренне; вызов rbamp_read_period_snapshot() чаще, чем прошивка успевает подготовить следующий период, всегда вернёт устаревший снимок (ESP_ERR_INVALID_RESPONSE). Для телеметрии с высокой частотой используйте функции RT rbamp_read_power(ch) / rbamp_read_all() — они обновляются примерно с 10 Гц.

rbamp_read_uptime_s

C
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);

Секунды с момента загрузки модуля. Уменьшение значения между двумя чтениями означает, что модуль перезапустился. На прошивке BASIC, которая не публикует время работы, возвращает 0.

Вызовы периода на линии STD

Один и тот же API периодов работает на обеих линиях, но внутри всё зависит от того, что предлагает модуль STD (rbamp_std_info_t.period_source, определяется rbamp_begin()):

period_source Поведение rbamp_read_period_snapshot()
RBAMP_STD_PERIOD_LATCH Модуль имеет банки снимков. Библиотека использует банк 0 (взводится rbamp_begin()): фиксирует, ждёт не менее 300 мс независимо от меньшего settle_ms (модуль делает снимок на следующей границе окна измерения), читает банк и переводит его в энергию за master_dt_ms. С skip_latch временем управляет вызывающий: зафиксировать, ждать ≥ 300 мс, затем читать. Бит 0 оставляйте установленным в rbamp_std_arm_banks().
RBAMP_STD_PERIOD_COUNTERS Банков снимков нет, но есть сохраняемые счётчики за весь срок службы. Защёлка не отправляется, а settle_ms / skip_latch игнорируются: вызов читает счётчики и возвращает разность с предыдущим учтённым чтением в avg_p_total / wh_net. При перезапуске модуля ничего не теряется (module_restarted это отмечает).
RBAMP_STD_PERIOD_NONE Ни то, ни другое. Вызовы периода возвращают ESP_ERR_NOT_SUPPORTED, а не молча сообщают недопустимый период.

Для пути счётчиков: avg_p[] содержит период для одноканального модуля, разности счётчиков по каналам на модулях, публикующих счётчики по каналам, и NaN на многоканальных модулях, которые этого не делают; max_p равен NaN. На модулях со счётчиками без тонкой детализации выбирайте период, достаточно длинный, чтобы один шаг счётчика был малой долей от него (минуты, а не секунды). ESP_ERR_INVALID_RESPONSE переякоряет библиотеку (этот период отбрасывается), когда поколение счётчика модуля изменилось (его счётчики сброшены или приняты заново) или счётчик пошёл назад.

Прочие заметки по STD: rbamp_latch_period() фиксирует банк 0 (пустая операция, возвращающая ESP_OK, на модулях со счётчиками); rbamp_is_period_valid() истинна на модулях со счётчиками, как только библиотека держит якорь счётчика (всегда после rbamp_begin()); rbamp_read_period_avg_power() возвращает среднее за последний учтённый период для одноканальных модулей со счётчиками и ESP_ERR_NOT_SUPPORTED для многоканальных; rbamp_read_period_max_power() возвращает ESP_ERR_NOT_SUPPORTED на модулях со счётчиками; rbamp_read_period_snapshot() возвращает ESP_ERR_INVALID_RESPONSE, когда банк 0 сообщает, что окно не прошло — если сброс модуля очистил маску взвода банка, библиотека взводит банк 0 заново, снимает пробный снимок и перезапускает якорь часов (это одно окно не интегрируется, следующее снова полное).

Вспомогательная встроенная функция

C
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
                                  rbamp_period_snapshot_t *out);

Удобная обёртка с аргументами по умолчанию: settle_ms=50, skip_latch=false. Используйте для обычного периодического опроса.

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

Если компонент собран без CONFIG_RBAMP_DISABLE_ENERGY=y, доступны функции-аксессоры к накопителю Wh внутри дескриптора:

C
double rbamp_energy_wh        (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset     (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset_all (rbamp_handle_t dev);
void   rbamp_energy_disable   (rbamp_handle_t dev);
void   rbamp_energy_enable    (rbamp_handle_t dev);

Накопитель обновляется автоматически при каждом успешном rbamp_read_period_snapshot(). Значение знаковое — отрицательное означает чистый экспорт.

Функция Описание
rbamp_energy_wh(dev, ch) Текущий суммарный Wh по каналу. Если ch вне диапазона — 0.0.
rbamp_energy_reset(dev, ch) Обнуляет один канал.
rbamp_energy_reset_all(dev) Обнулить все каналы.
rbamp_energy_disable(dev) Отключить автоматическое интегрирование. Полезно, когда мастер ведёт собственное сохранение Wh (глубокий сон — см. 06 · Примеры, сценарий 9).
rbamp_energy_enable(dev) Снова включите автоматическое интегрирование.

rbamp_energy_wh() принимает либо индекс канала (0..rbamp_channels(dev)-1, до 6 на UI7), либо селектор RBAMP_ENERGY_CH_TOTAL (0xFF) для суммы по всем каналам. Значение знаковое — отрицательное означает чистый экспорт, — и 0, если ch вне диапазона или энергия отключена.

Модули STD без банков снимков (путь счётчиков): итог — сумма разностей собственных счётчиков модуля, точно, ничего не интегрируется на хосте. Значения по каналам берутся из поканальных счётчиков модуля, если он их публикует; это NaN на многоканальных модулях, которые их не публикуют, и совпадают с итогом на одноканальных модулях.

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

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

При сборке с CONFIG_RBAMP_DISABLE_ENERGY=y и функции (прототипы и хранилище) удаляются из бинарника через охраны #if — попытка вызвать rbamp_energy_wh() даёт ошибку линкера «unresolved external».

Тип накопителя (rbamp_energy.h)

Накопитель за дескриптором живёт в отдельном заголовке rbamp_energy.h. Заголовок описывает его как внутренний API — приложение обычно использует обёртки rbamp_energy_* выше и никогда не нуждается в этом. Он перечислен здесь, потому что символы видны:

C
typedef struct {
    double wh[RBAMP_ENERGY_MAX_CH];  /* per-channel running total, Wh (signed) */
    double wh_total;                 /* all-channel total, Wh (signed) */
    bool   enabled;                  /* false: tick() is a no-op */
} rbamp_energy_t;

void   rbamp_energy_init      (rbamp_energy_t *e);
void   rbamp_energy_tick      (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
                               uint32_t period_ms, bool valid);
double rbamp_energy_wh_get    (const rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_add_wh    (rbamp_energy_t *e, uint8_t ch, double wh);
void   rbamp_energy_reset_ch  (rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
Функция Описание
rbamp_energy_init Обнуляет счётчики; накопитель стартует включённым.
rbamp_energy_tick Проинтегрируйте один период: wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 для до RBAMP_ENERGY_MAX_CH (7) каналов. Пропускается без сообщения, если valid равно false, period_ms равно 0 или накопитель отключён. period_ms должен быть окном по часам мастера (master_dt_ms), а не latch_ms модуля.
rbamp_energy_wh_get Текущая сумма по одному каналу; 0, если индекс вне диапазона.
rbamp_energy_add_wh Добавляет уже измеренное количество (Wh, знаковое) к одному каналу или, с RBAMP_ENERGY_CH_TOTAL, к общей сумме по всем каналам. Используется, когда модуль сам публикует счётчики энергии. Без действия, пока отключено.
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch Обнуляет один канал / все каналы.
rbamp_energy_set_enabled Включить или выключить интегрирование. Пока выключено, tick() и add_wh() ничего не делают, а чтения продолжают возвращать замороженное значение.

Идентификация и провизионинг

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

rbamp_read_variant

C
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);

Читает регистр варианта и отображает его в перечисление rbamp_variant_t (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ...; отображается каждый известный код). Для совместимости со старым кодом, который читает «сырой» байт, его можно привести обратно к uint8_t. Значение, кэшированное при rbamp_begin(), доступно без обращения к шине как rbamp_variant(). Значения:

Код SKU каналы I Канал U
1 UI1 1 да
2 UI2 2 да
3 UI3 3 да
4 I1 1 нет
5 I2 2 нет
6 I3 3 нет
7 UI5 5 да
8 UI7 7 да

Значение только для чтения, хранится в ROM, меняется только при перепрошивке на заводе.

rbamp_read_capability

C
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);

Читает карту возможностей из регистров CAPABILITY (0x57/0x58), LE u16. Один флаг указывает на наличие входного каскада напряжения: если он сброшен, модуль не вычисляет P / PF / Q, а значения этих регистров равны 0.0f. См. раздел «CAPABILITY (0x57/0x58, u16 LE) — карта определения возможностей» ниже.

rbamp_has_voltage

C
bool rbamp_has_voltage(rbamp_handle_t dev);

Удобный помощник поверх rbamp_read_capability — возвращает true, если модуль имеет канал U (то есть (cap >> 8) & 1). Результат кешируется в дескрипторе при первом вызове; последующие вызовы не выполняют операцию I²C.

rbamp_read_product_id

C
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);

Читает PRODUCT_ID (0x54) — байтовый идентификатор семейства (rbAmp = 0x01). Используется сканером флота, чтобы подтвердить, что устройство по адресу действительно rbAmp, а не какой-то другой подчинённый I²C, который случайно ответил по тому же адресу.

rbamp_read_uid

C
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);

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

rbamp_is_provisioned

C
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);

Проверяет, прошёл ли модуль первичный провизионинг. Технически проверяется REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) на только что загрузившемся модуле — 0xFB выставляется прошивкой, когда блок пользовательской конфигурации пуст или повреждён. Модуль, только что с завода, возвращает false — ему нужен rbamp_save_user_config (или провизионинг через флот) после первичной настройки модели CT и адреса.

Примечание

В v1.3 этот код нормален для чистого модуля (не фатален). Не прерывайте провизионинг при первом появлении 0xFB.

Линия STD. Возвращает true, когда модуль сообщает, что его калибровочная страница действительна. Надёжно начиная с версии образа модуля 0x00010079; старые образы также ставят бит на заводских коэффициентах по умолчанию, поэтому «провизионирован» через этот вызов нельзя отличить от «не откалиброван» (вместо этого используйте источник калибровки в rbamp_std_read_health()). Начиная с версии образа модуля 0x0001007A бит берётся из маркера, который модуль пишет при сохранении калибровки: модуль, откалиброванный под более старой прошивкой, после обновления возвращает false, пока на нём не выполнен один rbamp_save_gains() (сама калибровка при этом сохранна).

rbamp_save_user_config

C
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);

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

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

Returns:

  • ESP_OK — конфигурация сохранена, переживает отключение питания.
  • ESP_ERR_TIMEOUT — модуль не ответил вовремя; питание могло просесть во время цикла записи во флеш. Перепроверьте сбросом и обратным чтением.

  • ESP_FAIL — модуль вернул REG_ERROR != OK после команды. Подробности — в rbamp_read_last_error.

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

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

rbamp_read_active_address

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

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

C
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);

Читает активный адрес I²C модуля. При загрузке этот регистр достоверен — он показывает адрес, активный во flash (переадресованный модуль читает свой новый адрес). После подготовки кандидата через rbamp_prepare_address_change() он повторяет кандидата до фиксации и сброса. Полезно для проверки двухфазной смены адреса после перезагрузки по фиксации. На линии STD читает сохранённый адрес (применяется при следующем сбросе).

Модель ошибок v1.3

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

Канал A — на стороне клиента, синхронно Канал B — со стороны DUT, долговременно и асинхронно
Где это живёт Проверка внутри компонента (lib) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Когда срабатывает До транзакции I²C (библиотека перехватывает) После того как прошивка приняла запись и отклонила её
Что видит мастер ESP_ERR_INVALID_ARG из сеттера; REG_ERROR остаётся 0x00 REG_ERROR = немедленный код отказа; bit3 фиксируется через несколько сотен миллисекунд после транзакции
Липкий нет (только код возврата) REG_ERROR — результат последней записи; bit3 залипающий, сбрасывается записью единицы (W1C)
Типичный путь Аргумент вне допустимых границ (канал ≥ rbamp_channels(dev), неизвестный класс, ...) Сырая запись регистра, которую компонент не проверяет заранее (пользовательская низкоуровневая запись); неизвестная модель CT, которую модуль сам отклоняет

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

Все сеттеры компонента (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels и др.) сначала проверяют аргументы по допустимым значениям. Если аргумент вне диапазона, сеттер возвращает ESP_ERR_INVALID_ARG без какой-либо транзакции I²C. Поэтому REG_ERROR на устройстве не затрагивается:

C
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG  (lib client-side validation) */

uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */

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

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

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

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

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

Вывод стенда (сырая запись DIGEST_CONFIG = 0xFF):

Text
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3):     immediate=0, +300 ms poll#1=1, poll#2=1
Безопасность

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

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

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

Text
state: REG_ERROR=0xFE, bit3=1

clear_event_flags(1<<3)          → bit3=1 still (re-latched from REG_ERROR=0xFE)

clear_error  +  clear_event_flags(1<<3)
                                  → bit3=0 (cleared cleanly)

Правильный порядок: сначала rbamp_clear_error() (сбрасывает REG_ERROR), затем rbamp_clear_event_flags(1<<3) (сбрасывает липкую защёлку). Если нужна атомарность, между ними не должно быть отклонённой записи.

rbamp_read_last_error

C
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);

Читает REG_ERROR (0x02) напрямую — результат последней транзакции, успешно принятой шиной (запись или команда). Не «липкий»: любая последующая успешная запись перезаписывает его своим результатом.

Используется в канале B (отказ на стороне DUT) для расширенного кода причины.

rbamp_has_error

C
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);

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

Используется для опроса в стиле «была ли неисправность» — например, в долгих циклах, где промежуточные записи могли затереть REG_ERROR, но bit3 сохраняет факт, что хотя бы одна из них была отклонена.

rbamp_read_event_flags / rbamp_clear_event_flags

C
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);

EVENT_FLAGS (0x2A) — байт липких флагов (RBAMP_EVENT_*, см. Биты событий, включая RBAMP_EVENT_ERROR = bit3). Сброс — записью 1: запишите маску с единицами в битах, которые хотите сбросить. Флаги работают на обеих линиях; на линии STD им нужна версия карты регистров 0x36 или новее (ниже — ESP_ERR_NOT_SUPPORTED).

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

rbamp_clear_error

C
esp_err_t rbamp_clear_error(rbamp_handle_t dev);

Выполняет CMD_CLEAR_ERROR (код операции 0x31) — обнуляет REG_ERROR. Нужен для сброса устойчивой ошибки вместе с clear_event_flags(1<<3) (см. выше). Без clear_error простой clear_event_flags(1<<3) оставит bit3 в 1 через несколько сотен миллисекунд из-за повторного защёлкивания.

События и линия тревоги

События — одна модель на обеих линиях: липкие флаги (RBAMP_EVENT_*), сбрасываемые записью 1. Флаги, которые также выставлены в маске событий, удерживают линию DRDY в LOW (тревога), пока их не сбросят или не снимут маску. Маска и пороги живут в RAM модуля — заново взводите их после каждого сброса модуля (RBAMP_EVENT_RESET_OCCURRED сообщает об этом; см. также rbamp_begin_event_flags()).

C
esp_err_t rbamp_read_event_mask     (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask      (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
Функция Описание
rbamp_read_event_mask Какие флаги удерживают линию DRDY в LOW (класс тревоги).
rbamp_set_event_mask Установить маску (RAM на модуле; 0 = линия никогда не удерживается). Запись читается обратно и проверяется.
rbamp_set_event_thresholds Задайте пороги (RAM модуля): самый мощный токовый канал выше i_amps задаёт RBAMP_EVENT_THRESH_I, суммарная активная мощность выше p_watts задаёт RBAMP_EVENT_THRESH_P. Значение <= 0 или NaN отключает порог. Возвращает ESP_ERR_NOT_SUPPORTED на модуле STD с версией карты регистров ниже 0x36.

Сравнение различается по линиям. Линия STD сравнивает абсолютную суммарную мощность (направление не важно). Линия BASIC сравнивает знаковую сумму мощностей каналов, поэтому экспорт никогда не вызывает порог мощности; значения, которые не помещаются в кодировку BASIC, считаются «выключено». На STD rbamp_read_event_flags() требует версию карты регистров 0x36 или новее (иначе ESP_ERR_NOT_SUPPORTED).

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

На многоканальных модулях (I2, I3, UI2, UI3, а также более крупные UI5 / UI7) каждый токовый канал имеет собственную модель датчика CT. Атомарная утилита для пакетной конфигурации — rbamp_configure_channels.

rbamp_configure_channels

C
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
                                   rbamp_sensor_class_t cls,
                                   const uint8_t *models,
                                   uint8_t n);

Parameters:

  • cls — класс датчика, применяемый первым через rbamp_set_sensor_class().
  • models — массив из n кодов моделей CT, по одному на канал.
  • n — длина массива. Ограничение по варианту: если n больше числа каналов этого варианта (например, n=3 на I2), функция ограничивает его фактическим числом каналов; лишние элементы массива игнорируются. Если n меньше числа каналов, отсутствующие каналы не трогаются (сохраняют прежнюю модель). Элемент 0 в models пропускает канал. Вызов охватывает все каналы модуля, включая каналы 3+ на UI5 / UI7.

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

  1. set_sensor_class(cls) один раз.
  2. Для каждого канала k < min(n, n_channels): привязать models[k]; каждая привязка проверяется синхронно и подтверждается обратным чтением.

  3. Одно завершающее сохранение пользовательской конфигурации в конце (плюс то, что внутри set_sensor_class) — то есть два цикла стирания и записи флеша на всю конфигурацию вместо 1 + n. Это и есть свойство «бережно для флеша».

Сначала чтение, потом запись. Весь запрос решается до первой записи. Класс или модель, которые модуль уже держит, не перезаписываются, поэтому повторное применение той же конфигурации стоит только чтений и не расходует цикл flash. На модуле класса 2 или 3 запрос, который изменил бы класс или любую запрошенную модель, отклоняется заранее с ESP_ERR_INVALID_STATE, и ничего не записывается. На модуле класса 1 со старой прошивкой (до 1.4.19) конфигурация, меняющая модель, завершается одним перезапуском модуля (см. rbamp_set_ct_model_ch).

Returns:

  • ESP_OK — конфигурация применена и сохранена.
  • ESP_ERR_INVALID_ARG — неверный cls или models[k] (проверка на шаге привязки, см. раздел «Модель ошибок» выше).

  • ESP_ERR_INVALID_STATE — не удалось привязать канал, либо модуль откалиброван под установленный датчик (класс 2 / 3).

  • Прочие коды ESP-IDF — ошибка шины, таймаут и т. д.

rbamp_read_ct_model_ch

C
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
                                 uint8_t channel,
                                 uint8_t *out);

Читает модель датчика тока, фактически применённую к конкретному каналу (0 = не задана). Используйте для проверки привязки после rbamp_set_ct_model_ch(). Каналы 0–2 читают плоские зеркала (0x51 / 0x52 / 0x53); каналы 3+ (UI5 / UI7) читаются через окно канала. Это чтение из RAM, а не подтверждение сохранения — для подтверждения записи во flash используйте перезагрузку и повторное чтение. На линии STD читает запись карты канала.

Менеджер флота — управление несколькими модулями

Fleet API — основная высокоуровневая поверхность библиотеки. Он управляет набором модулей на общей шине I²C: обнаружение, подготовка, агрегация опросов, агрегация ошибок, синхронные снимки.

Все функции флота потокобезопасны через внутренний мьютекс; параллельные вызовы из разных задач сериализуются. Один владелец fleet из одной задачи плюс доступ только для чтения (например, _count, _get) из других допустим, но сложные многошаговые операции координируйте явно.

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

C
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
                             rbamp_fleet_t *out);
void      rbamp_fleet_destroy(rbamp_fleet_t fleet);

create принимает шину и возвращает пустой флот. destroy освобождает все управляемые дескрипторы и сам флот — после вызова любые указатели дескрипторов, полученные через rbamp_fleet_get, недействительны.

Обнаружение — rbamp_fleet_scan

C
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
                           bool match_product,
                           size_t *added);

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

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

  2. Запускает детектор конфликтов (два независимых сигнала; см. 10 · Устранение неполадок, раздел «Парк: модуль оказался в excluded»). Подозрительные адреса попадают в список excluded, а не в парк.

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

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

Вывод на стенде (проверено на оборудовании на разнородном флоте UI1+I2+I3 с внешними подтяжками 4.7 кОм):

Text
rbamp_fleet_scan() → 3 module(s), 0 excluded
  module[0] @0x50  channels=1  voltage=yes   (UI1 — mains)
  module[1] @0x51  channels=2  voltage=no    (I2 — sub-meter)
  module[2] @0x52  channels=3  voltage=no    (I3 — sub-meter)
rbamp_fleet_count()          = 3
rbamp_fleet_excluded_count() = 0

В этом сценарии конфликт адресов попал бы в список исключённых (excluded_count > 0), а зависшая шина привела бы к ESP_ERR_INVALID_STATE с пустым флотом (см. 10 · Устранение неполадок).

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

C
size_t          rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t  rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t  rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t       rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);

size_t          rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t       rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
                                          size_t index,
                                          uint8_t *out);

_get возвращает NULL при выходе за диапазон; _find возвращает NULL, если адреса нет во флоте (например, потому что он попал в исключённые). _add позволяет вручную добавить дескриптор, созданный отдельно (например, после ручного провизионинга).

Опрос — rbamp_fleet_poll_all

C
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
                               rbamp_snapshot_t *snaps,
                               rbamp_fleet_poll_t *status,
                               size_t capacity,
                               size_t *n_ok);

Опрашивает все модули парка одним вызовом. Для каждого модуля выполняется полное RT-чтение (rbamp_read_all), результат помещается в соответствующий элемент snaps[i]. Параллельно status[i] получает результат по каждому модулю: ESP_OK, ESP_ERR_TIMEOUT (модуль молчит), ESP_FAIL (отклонение по здравому смыслу) и т. д.

После возврата *n_ok — число модулей, для которых получен корректный снимок (status[i] == ESP_OK).

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

Агрегация

C
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
                                  uint32_t *error_mask,
                                  size_t *n_errors);

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

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

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

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

C
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
                                     rbamp_handle_t dev,
                                     uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
                                     uint8_t addr,
                                     bool *collision);

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

_check_conflict — лучшая попытка проверки только чтением для конкретного адреса: вызывайте один раз на каждый интересующий адрес. Функция читает идентичность (PRODUCT_ID / HW_VARIANT / CAPABILITY) и сравнивает с кешированным состоянием флота. Если обнаружено несоответствие (два устройства отвечают по одному адресу «слитыми» байтами; идентичность отличается от кешированного состояния) — *collision = true. Чтобы проверить все известные адреса, перебирайте флот сами: for i in 0..count, check_conflict(fleet, addr, &col). Она не гарантирует обнаружение одинаковых модулей — см. дисциплину провизионинга.

Провизионинг — rbamp_provision

C
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
                          uint8_t desired_addr,
                          bool save_config,
                          rbamp_handle_t *out);

Вводит в эксплуатацию ровно один новый модуль (на заводском 0x50) по указанному адресу. Внутри:

  1. Проверяет наличие ответа по 0x50 (ESP_ERR_NOT_FOUND, если его нет).

  2. Проверяет, что никого нет по desired_addr (ESP_ERR_INVALID_STATE, если занят).

  3. Выполняет двухфазную фиксацию адреса.

  4. Сбрасывает модуль и ждёт его появления по desired_addr в окне загрузки (ESP_ERR_TIMEOUT, если он не появился).

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

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

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

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

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

C
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
                                    uint8_t group,
                                    size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
                              uint8_t group,
                              uint16_t tick,
                              uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
                                 uint16_t expected_tick,
                                 rbamp_fleet_sync_t *status,
                                 size_t status_cap,
                                 size_t *n_missed);

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

  1. _enable_gc_all задаёт 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. _check_sync читает GC_TICK (0x59) на каждом модуле в rbamp_fleet_sync_t status[status_cap]. Результат по модулю:

C
typedef struct {
    uint8_t  addr;        /* module I²C address */
    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 */
} rbamp_fleet_sync_t;

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

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

Не путайте: поканальный rbamp_broadcast_latch (см. раздел «Шина нескольких модулей» ниже) — это один кадр на всю шину; синхронизация GC флота — тот же кадр, но API флота дополнительно предоставляет контрольную проверку (что кадр дошёл до всех ожидаемых модулей). См. также 04 · Подключение о предусловиях GC.

Конфигурация парка по устройствам

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

rbamp_enable_gc / rbamp_read_fleet_config

C
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);

enable_gc(dev, true) записывает 1 в FLEET_CONFIG.bit0 (0x27) — модуль начнёт принимать снимки GC после следующего CMD_SAVE_USER_CONFIG + сброса. enable_gc(dev, false) делает обратное — сбрасывает бит (модуль перестаёт принимать GC после сброса). read_fleet_config возвращает текущий байт конфигурации — полезно для подтверждения обратным чтением.

rbamp_set_group_id / rbamp_read_group_id

C
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);

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

rbamp_read_gc_tick

C
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);

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

rbamp_read_label / rbamp_write_label

C
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);

LABEL (0x68..0x6F) — пользовательская метка из 8 байт (ASCII, дополнение нулями). Помогает различать модули во флоте — например, «MAINS», «BOILER», «AC1». read_label всегда возвращает массив из 9 байт (8 байт данных + завершающий \0). write_label принимает строку с нулевым завершением — лишние байты обрезаются.

Примечание

Запись ведётся побайтно (автоинкремента при записи нет — см. «Записи регистров» ниже). После записи нужен rbamp_save_user_config, чтобы метка пережила сброс.

rbamp_broadcast_latch_group

C
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
                                      uint8_t group_id,
                                      uint16_t tick);

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

rbamp_reset_counters

C
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);

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

Настройка датчика

Двухшаговая последовательность: сначала класс датчика, затем модель. Оба шага обязательны для модуля с датчиком, установленным пользователем (класс 1). Модули, которые поставляются с датчиком (класс 2 / 3), приходят уже настроенными и защищены от случайной перезаписи — см. примечания о защите «сначала чтение, потом запись» ниже.

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

rbamp_set_sensor_class

C
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
                                 rbamp_sensor_class_t cls);

Задаёт класс датчика и сохраняет его.

Сначала чтение, потом запись. Функция сначала читает класс, который держит модуль. Запись уже имеющегося значения — пустая операция без записи по шине (ESP_OK): на модуле любая запись класса, даже неизменённая, очищает модели CT всех каналов и форму их калибровки, поэтому лишняя запись ухудшила бы показания. Модуль, класс которого 2 или 3 (откалиброван вместе со своим датчиком), не перезаписывается: ESP_ERR_INVALID_STATE.

Иначе записывает класс, проверяет, что модуль его принял, и сохраняет его сохранением пользовательской конфигурации (~700 мс, блокирующе). Установка класса также очищает модели CT на модуле, поэтому задайте модели после этого.

На прошивке v1.2+ установленный класс — предусловие для rbamp_set_ct_model() и rbamp_set_ct_model_ch(): вызов любого из них, пока класс всё ещё RBAMP_SENSOR_UNSET, возвращает ESP_ERR_INVALID_STATE. См. 10 · Устранение неполадок, раздел «Текущие показания нулевые», про симптом «случайно записали UNSET».

Возвращает: ESP_OK при успехе или когда модуль уже имеет этот класс; ESP_ERR_INVALID_ARG при dev == NULL, нераспознанном cls или когда модуль отклоняет запись; ESP_ERR_INVALID_STATE, когда текущий класс модуля 2 или 3; коды ошибок I²C при сбое связи.

Линия STD. Записывает класс как метаданные (у линии STD нет таблицы пресетов) и сохраняет его; вердикт команды модуля проверяется.

rbamp_set_ct_model

C
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);

Форма с одним параметром — задаёт модель датчика тока только на канале 0 (эквивалентна rbamp_set_ct_model_ch(dev, 0, code); на линии STD это и есть этот вызов). Блокирующий, ~700 мс при записи.

Допустимый набор моделей для активного класса — истина прошивки во время выполнения; библиотека не хранит клиентского списка кодов. Неизвестная пара (класс, модель) отклоняется модулем и передаётся как ESP_ERR_INVALID_STATE (или ESP_ERR_INVALID_ARG из синхронной проверки записи). Коды и названия моделей — в сгенерированном rbamp_sensor_models.h (rbamp_sensor_model_lookup()); для класса 1:

code Модель
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060

(Все семь кодов SCT-013 выбираемы; допустимый набор — {1, 2, 3, 4, 5, 6, 7}.)

Preconditions.

Сначала должен быть вызван rbamp_set_sensor_class() (иначе ESP_ERR_INVALID_STATE, запись не выполняется). Действует и защита «сначала чтение, потом запись» у rbamp_set_ct_model_ch().

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

rbamp_set_ct_model_ch

C
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
                                uint8_t channel, uint8_t code);

Поканальная форма. Один публичный вызов для любого канала; маршрутизация внутренняя: каналы 0–2 подготавливают модель и применяют её поканальной командой, каналы 3+ (UI5 / UI7, прошивка v1.4.18+) применяют её через окно каналов. В любом случае применённая модель подтверждается обратным чтением и затем сохраняется (~700 мс). channel проверяется по фактическому числу каналов модуля.

Примечание

Порядок привязки произвольный (канон v1.3). Привязка CT — чистая подготовка: каждое поканальное применение привязывает только свой канал, поэтому каналы можно настраивать в любом порядке — по возрастанию, по убыванию или вперемежку — без взаимного затирания:

C
rbamp_set_ct_model_ch(dev, 0, 1);  /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3);  /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6);  /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3);  /* channel 4 (UI5 / UI7) */

Защита «сначала чтение, потом запись». Применение модели заменяет любую калибровку, которую несёт блок для этого канала, общим заводским пресетом модели, и модуль делает это даже тогда, когда модель не меняется. Поэтому:

  • модель, которую канал уже держит (см. rbamp_read_ct_model_ch()), — пустая операция без записи по шине: повторное применение сохранённой конфигурации при каждом переподключении безопасно и не вызывает лишнего перезапуска модуля;

  • модуль класса 2 или 3 возвращает ESP_ERR_INVALID_STATE; rbamp_set_ct_model_ch_force() — сервисный путь.

Перезапуск модуля на старой прошивке класса 1. На модуле BASIC класса 1 без возможности самокоррекции (прошивка до 1.4.19) вызов, который действительно меняет модель, завершается одним перезапуском модуля (около секунды, тот же UID проверяется): это единственный способ, которым модуль возвращается к своему калиброванному усилению после записи модели. Затем библиотека вычисляет коррекцию номинала (rbamp_sct_correction()) и масштабирует показания по усилению, которое применяет модуль. Состояние RAM модуля (поля дайджеста, маска событий, пороги) заново применяет библиотека там, где она им владеет; накопители периода перезапускаются, как после любого сброса модуля.

Возвращает: ESP_OK; ESP_ERR_INVALID_ARG при dev == NULL или channel >= rbamp_channels(dev); ESP_ERR_NOT_SUPPORTED на прошивке старше v1.2 (каналы 0–2) или на модуле STD, который не сохраняет модель CT по каналам; ESP_ERR_INVALID_STATE, если класс UNSET, модуль отклоняет пару (class, model), применённая модель не проходит подтверждение обратным чтением, или модуль класса 2 / 3; ESP_FAIL / ESP_ERR_TIMEOUT при сбое транспорта.

Линия STD. Модель CT — только справочная (метаданные SKU): усиление она не задаёт — модуль несёт собственную калибровку каждого канала. На текущей прошивке одноканального модуля модель сохраняется после сброса только для канала 0.

rbamp_set_ct_model_ch_force

C
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
                                      uint8_t channel, uint8_t code);

Сервисный путь: как rbamp_set_ct_model_ch(), но записывает независимо от класса модуля и текущей модели. Заменяет парную калибровку этого канала общим пресетом модели — используйте только при повторном сопряжении модуля с новым датчиком на объекте и затем выполняйте калибровку.

rbamp_read_sensor_class

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

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

C
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);

Текущий класс датчика модуля как значение rbamp_sensor_class_t (BASIC: регистр класса; STD: поле конфигурации класса).

Пределы моделей датчиков

C
bool  rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
                                 float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);

Чисто табличные поиски в сгенерированном реестре моделей (rbamp_sensor_models.h) — без трафика по шине.

  • rbamp_sensor_model_limits заполняет (любой выход может быть NULL): nominal_a — номинальный действующий ток, А; fs_a — действующий ток, при котором синусоида начинает клиппировать, А; peak_a — мгновенный потолок ограничения, А (искажённая нагрузка клиппирует при peak_a, делённом на её пик-фактор). 0 означает неизвестно для этой модели (устаревшие коды тороидов / нагрузок). Возвращает true, если пара (class, code) есть в реестре, иначе false (выходы тогда равны 0).

  • rbamp_sensor_model_rated_a — сокращение для nominal_a. Это номинал датчика, который может отличаться от ампер в названии модели (клещи «5 А» рассчитаны на 4.6 А). Для названия модели используйте rbamp_sensor_model_lookup().

Совпадение в реестре не означает, что подключённый модуль принимает этот код — истина определяется во время работы.

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

Модуль BASIC класса 1 откалиброван на заводе датчиком 30 А (модель 3). В прошивке до 1.4.19 переключение на другую модель оставляет модуль применяющим калибровку 30 А после перезапуска, поэтому датчик большего номинала показывает занижение. Модуль, который сообщает о возможности самокоррекции (прошивка 1.4.20 и новее), исправляет себя сам и ничего из этого не требует.

Для более старой прошивки библиотека читает коэффициент усиления, который модуль на самом деле применяет, — при rbamp_begin(), после записи модели и после каждого обнаруженного перезапуска модуля — и масштабирует ток, пиковый ток, активную мощность, среднюю мощность периода, интегрированную энергию, дайджест и пороги событий по этому коэффициенту и выбранной модели. Напряжение и коэффициент мощности не масштабируются. Результат по каждому каналу — rbamp_sct_status_t (см. Типы). Коэффициент, всё ещё равный сырому пресету (модель переключена в этой загрузке без перезапуска), вызывает один перезапуск модуля; неожиданный применённый коэффициент, неизвестная модель или сырой пресет, переживший перезапуск, оставляют показания без масштабирования с предупреждением в журнале. CONFIG_RBAMP_SCT_RATING_CORRECTION (по умолчанию включено) отключает механизм, и тогда возвращаются сырые значения модуля.

C
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
                               rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh   (rbamp_handle_t dev);
Функция Описание
rbamp_sct_correction(dev, ch, &c) Кэшированная поправка канала ch — без обращения к шине. Вычисляется в rbamp_begin(), в rbamp_set_ct_model*() и после обнаруженного перезапуска модуля (сброшенный RESET_OCCURRED, ожидающий RESET в дайджесте, уменьшившийся uptime). ESP_ERR_NOT_SUPPORTED на линии STD.
rbamp_sct_refresh(dev) Заново прочитайте класс, модели и применённые коэффициенты и пересчитайте масштабы. Выполняет один перезапуск модуля (и повторно опрашивает модуль, UID совпадает) если применённый коэффициент канала всё ещё является сырым пресетом модели, отличной от модели 30 А. Вызывается внутренне там, где нужно; открыт для хоста, который знает о перезапуске модуля другим способом. Для линейки STD и для модуля, исправляющего себя сам, — пустая операция с возвратом ESP_OK.

rbamp_save_gains

C
esp_err_t rbamp_save_gains(rbamp_handle_t dev);

Одиночная запись CMD_SAVE_GAINS без сопутствующих изменений регистров.

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

⚠ Обычно вызывается внутри компонента. Голый rbamp_save_gains() уместен ТОЛЬКО если вызывающий вручную записал в непубличные регистры калибровки через сырой доступ к шине — это операция вне гарантии, она обходит таблицу пресетов по SKU. Неверные значения дадут неверные показания тока и мощности без явных предупреждений. Каждый вызов выполняет цикл стирания и записи flash (~700 мс); ресурс flash ограничен (~10000 циклов на страницу) — не вызывайте в цикле.

Линия STD. Выполняет сохранение калибровки (сохраняет блок калибровки: коэффициенты усиления, пороги шума и THD) и проверяет вердикт команды.

rbamp_prepare_address_change / rbamp_commit_address_change

Смена I²C-адреса модуля выполняется через двухфазную фиксацию в производственном режиме. Прошивка намеренно исключает адрес из общего потока CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS — для изменения нужна отдельная последовательность с взводом магическим кодом.

C
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
                                       uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);

Проводной протокол под капотом:

  1. prepare: проверьте диапазон new_addr (0x08..0x77, ≠ текущий) → запишите new_addr в REG_I2C_ADDRESS (0x30) — значение попадает в RAM.

  2. prepare: запишите 0xA5 в REG_ADDR_COMMIT_MAGIC (0x31) — это «взводит» фиксацию. Окно взведённого состояния — 5 секунд.

  3. commit: проверить свежесть взвода → отправить CMD_COMMIT_ADDR (код операции 0x30) → записать во flash → CMD_RESET

  4. ~400 мс загрузки → обновите внутреннее поле адреса дескриптора.

После успешного commit все вызовы этого экземпляра дескриптора адресуются к новому адресу. Операция работает в производственном режиме (без ограничений), что поддерживает замену модулей в полевых условиях из запасных производственных экземпляров.

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

⚠ Если окно взвода (5 с) истекло — commit возвращает ESP_ERR_TIMEOUT, флаг взвода сбрасывается, и нужно начинать заново с prepare.

Линия STD. Смена адреса синхронна, и дескриптор переключается только после того, как модуль ответит по новому адресу — см. rbamp_commit_address_change на линии STD. При неудаче дескриптор сохраняет старый адрес (ESP_ERR_NOT_FOUND).

⚠ Сохранность подтверждается только после сброса. До сброса rbamp_read_* может вернуть новые значения из RAM, но запись во flash могла не завершиться. Компонент сам выполняет встроенный CMD_RESET + ожидание загрузки внутри commit, поэтому после успешного возврата состояние гарантированно сохранено.

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

rbamp_factory_reset

C
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);

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

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

⚠ Деструктивная операция. Стирает ВСЕ параметры flash (модель CT, класс датчика, коэффициенты калибровки, I²C-адрес). Модуль возвращается к заводским значениям — rbamp_sensor_class_t становится RBAMP_SENSOR_UNSET, REG_CT_MODEL становится 0. Любая настройка, ранее заданная через rbamp_set_sensor_class() / rbamp_set_ct_model*(), пропадает. Следующий пользователь ДОЛЖЕН заново применить rbamp_set_sensor_class() и rbamp_set_ct_model*(), прежде чем учёт снова заработает. Это не «мягкий перезапуск» — для мягкого перезапуска используйте rbamp_reset(). rbamp_factory_reset() предназначен для восстановления из заведомо неисправного состояния или передачи модуля другому пользователю / установке.

Линия STD. Там нет команды заводского сброса: rbamp_factory_reset() возвращает ESP_ERR_NOT_SUPPORTED.

rbamp_reset

C
esp_err_t rbamp_reset(rbamp_handle_t dev);

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

Шина с несколькими модулями

rbamp_broadcast_latch

C
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
                                uint32_t timeout_ms);

На прошивке v1.3 (REG_VERSION = 0x04) это канонический путь синхронизации флота, как только General-Call включён на всём флоте через rbamp_fleet_enable_gc_all(). Кадр General-Call из 5 байт A5 27 заставляет каждый модуль взять снимок в своей группе в один и тот же момент на проводе, обеспечивая жёсткую синхронизацию между субсчётчиками. Функция использует только шину: она передаёт кадр (ESP_OK означает, что драйвер хоста не выдал ошибку; General Call — только запись, ни один модуль не отвечает ACK; ESP_ERR_INVALID_ARG при NULL-шине). Модули без поддержки General-Call или с выключенной ею просто игнорируют кадр — проверяйте контрольной проверкой по модулю (ниже) и используйте последовательный запасной путь, если снимок не был взят. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) — то же с явным фильтром группы и тиком флота.

Последовательный запасной вариант (устаревшая прошивка или если GC оставлен выключенным): серия rbamp_latch_period() по каждому устройству, общая задержка 50 мс и по каждому устройству rbamp_read_period_snapshot(skip_latch=true) — см. 06 · Примеры, сценарий «Мониторинг нескольких модулей».

Линия STD

Линия модулей STD говорит на другой модели регистров за тем же дескриптором. rbamp_begin() её определяет; скалярный API из предыдущих глав работает на обеих линиях без изменений (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, вызовы конфигурации, …). Функции этой главы — дополнения только для STD: целые каналы одним пакетом, величины, которые измеряет только эта линия (реактивная / полная мощность, THD, знаковые счётчики энергии), банки снимков, часы модуля, история, состояние, обновление прошивки. Каждая функция rbamp_std_* возвращает ESP_ERR_NOT_SUPPORTED на дескрипторе BASIC.

Многим функциям нужна минимальная версия карты регистров модуля (ниже обозначается как «карта 0x35+» и подобные). Ограничение функций зависит от возможностей и версии карты, которые сообщает модуль (rbamp_std_info()), никогда не от догадок; если модуль слишком старый, функция возвращает ESP_ERR_NOT_SUPPORTED — в большинстве случаев без какого-либо обмена по шине. Рабочий пример — examples/std_meter/.

Идентификация и обнаружение

C
typedef struct {
    uint8_t  map_version;
    uint16_t capabilities;      /* RBAMP_STD_CAP_* bitmap */
    uint8_t  status;            /* RBAMP_STD_ST_* bits at begin() time */
    uint8_t  n_voltage;         /* populated voltage channels */
    uint8_t  n_current;         /* populated current channels */
    uint8_t  variant;           /* raw RBAMP_STD_VARIANT_* byte */
    uint32_t active_bank;       /* running firmware bank, 0 without OTA capability */
    uint32_t ota_bank_size;     /* flash bank size, 0 if none */
    rbamp_std_period_source_t period_source;
} rbamp_std_info_t;

typedef struct {
    uint8_t  i2c_addr;
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];           /* chip UID — the identity; addresses can change */
    uint32_t fw_version;        /* running image version (map 0x35+; 0 if unknown) */
    uint32_t board_id;          /* map 0x36+; 0 below */
} rbamp_std_identity_t;
Функция Описание
rbamp_std_info(dev, &info) Идентичность, кэшированная rbamp_begin() — без обращения к шине. Возвращает ESP_ERR_NOT_SUPPORTED на дескрипторе BASIC или до rbamp_begin(). Ограничение каналов идёт по n_voltage / n_current: регистры каналов сверх этих чисел не определены, и библиотека отказывается их читать.
rbamp_std_identify(dev, &id) Всё, что нужно мастеру для распознавания модуля за дескриптором (два–четыре коротких чтения).
rbamp_std_probe(bus, addr, &id) Проверяет один адрес на шине без дескриптора — строительный блок сканирования. Быстро: без повторов, NACK и есть ответ. ESP_OK с заполненным id; ESP_ERR_NOT_FOUND, если никто не подтверждает; ESP_ERR_INVALID_RESPONSE, если отвечает кто-то, кто не является модулем STD (модуль BASIC, другой чип).
rbamp_std_read_image_version(dev, &v) Версия работающего образа прошивки (u32, например 0x00010072). Отличается от rbamp_firmware_version(), которая возвращает версию карты регистров этой линейки. 0, если модуль не может сообщить.
rbamp_std_read_board_id(dev, &id) Идентификатор платы запущенного образа (карта 0x36+): слово, кодирующее аппаратуру, для которой собран образ. Образ прошивки принимается только тогда, когда его слово платы совпадает (см. rbamp_std_ota_board_ok).
rbamp_std_locate(dev) Мигайте светодиодами модуля около 10 с, чтобы человек мог его найти.
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) Дайте одному модулю на общем адресе собственный адрес, выбранный по UID (карта 0x36+). На shared_addr могут находиться несколько модулей (например, заводской адрес по умолчанию); только тот, чей UID совпадает, принимает new_addr, сохраняет его и перезапускается, остальные игнорируют команду. Дескриптор не нужен. После перезапуска библиотека опрашивает new_addr и проверяет там UID. restart_ms 0 = 1500 мс. ESP_ERR_NOT_FOUND, если по new_addr никто не отвечает; ESP_ERR_INVALID_RESPONSE, если модуль отвечает там, но его UID другой.

Как модуль STD отдаёт энергию за период

C
typedef enum {
    RBAMP_STD_PERIOD_NONE     = 0,
    RBAMP_STD_PERIOD_LATCH    = 1,
    RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;

Определяется rbamp_begin() по возможностям модуля и отображается в rbamp_std_info_t.period_source:

  • LATCH — модуль имеет банки снимков. Период — это от снимка до снимка на банке 0; средние и поканальная энергия берутся из банка. См. Банки снимков.

  • COUNTERS — без банков снимков, но с сохраняемыми счётчиками за весь срок службы. Период — это разность двух показаний счётчика, снятых по расписанию мастера; команды снимка нет, взводить нечего, и при перезапуске модуля ничего не теряется. См. Счётчики энергии за весь срок службы.

  • NONE — ни одного: вызовы периода и энергии возвращают ESP_ERR_NOT_SUPPORTED.

Блоки реального времени

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A — reads 0 on module map 0x34 and earlier */
    float   p, q, s;      /* W (signed), var (signed), VA */
    float   pf;           /* −1..+1 */
    float   thd_i;        /* % — 0 while harmonics are off */
    float   pf1;          /* displacement power factor — 0 while harmonics are off */
    float   q1;           /* fundamental reactive power, var — 0 while harmonics are off */
    int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
    int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
    uint8_t implausible;  /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;

typedef struct {
    float   u_rms, u_peak, thd_u;  /* V, V (0 on map 0x34 and earlier), % */
    uint8_t implausible;
    float   angle_deg;             /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
    bool    angle_valid;           /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
Функция Описание
rbamp_std_read_channel(dev, ch, &c) Один блок токового канала (I / P / Q / S / PF / пик / накопители энергии / гармоники) одним пакетом; ch — от 0..rbamp_channels(dev)-1. Поля согласованы настолько, насколько их публикует модуль (в пределах окна публикации); для строго атомарного многополевого снимка используйте снимок периода. Поле, нарушившее границу адекватности, — NaN, а его бит RBAMP_FIELD_* выставляется в implausible.
rbamp_std_read_totals(dev, k, &c) Агрегатный блок: k = 0 — общий итог (сумма всех токовых каналов), k = 1..3 — итоги по фазам A/B/C (только многофазные модули). Итоги по фазам публикуются из карты 0x36 — на однофазном модуле k = 1 равно каналу 0, а k = 2/3 читаются как 0; ниже 0x36 возвращается ESP_ERR_NOT_SUPPORTED (k = 0 работает всегда). Поля энергии (e_import_mws / e_export_mws) у агрегатных блоков не заполняются и читаются как 0 — энергия берётся из постоянных счётчиков (rbamp_std_read_energy).
rbamp_std_read_voltage(dev, v, &u) Один блок канала напряжения (RMS / пик / THD / угол фазы) одним пакетом; v — от 0..n_voltage-1. angle_deg / angle_valid публикуются трёхфазными модулями с версией образа 0x0001007A или новее; иначе angle_valid — false, а остальная часть блока не затрагивается. На трёхфазном модуле с прямой последовательностью вход 1 показывает около −120°, вход 2 — около +120°.
rbamp_std_read_phase_seq(dev, &seq) Порядок входов напряжения, который модуль выводит из углов: RBAMP_STD_PHASE_SEQ_NA (меньше трёх входов или вход слишком низкий), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (нет картины 120°, например два входа подключены к одной фазе). Возвращает ESP_ERR_NOT_SUPPORTED (и *seq = NA) на версии образа модуля ниже 0x0001007A, без трафика шины.
Примечание

thd_i, pf1, q1 и thd_u читаются как 0, если не включено извлечение гармоник — см. Конфигурация. e_import_mws / e_export_mws — сырые накопители модуля в мВт·отсчёты; у модуля нет часов, поэтому перевод в Wh требует числа отсчётов и вашего собственного учёта времени периода (используйте путь снимков или счётчики за весь срок службы). Для контроля интегрируйте p за ваш интервал опроса.

rbamp_read_all() на модуле STD читает блок напряжения и блок каждого канала целиком (по одной транзакции на блок), а не поле за полем. rbamp_read_frequency() на модуле STD возвращает ESP_ERR_INVALID_RESPONSE с *out = NaN, когда модуль публикует 0 (нет сети); тогда rbamp_read_all() выставляет RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() на карте модуля 0x34 и ниже читают 0 — для пика за период используйте max_u / min_u / max_i из банка снимков.

Состояние

C
typedef struct {
    uint8_t  status;        /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
    uint32_t frame_count;   /* sensor frame counter — must grow between polls */
    uint32_t crc_errors;    /* sensor frame CRC error counter */
    bool     time_valid;    /* the module clock is set; false after every module reset */
    bool     nvm_fault;     /* energy store fault or corrupt (details in lta_status) */
    uint8_t  lta_status;    /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
    uint8_t  lta_src;       /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
    uint8_t  cal_src;       /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
    uint32_t lost_frames;   /* sensor frames lost since boot — should stay flat */
    uint16_t ring_drop;     /* acquisition ring overruns since boot — should stay flat */
    uint32_t uptime_s;      /* seconds since the module booted */
    bool     maint;         /* maintenance mode active */
    uint8_t  group_status;  /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
    uint16_t legal_noen;    /* metering-relevant operations executed outside maintenance mode */
    uint8_t  reset_cause;   /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
    uint16_t boot_count;    /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;

rbamp_std_read_health(dev, &h) читает текущее состояние. Считайте показания валидными, когда в status есть RBAMP_STD_ST_SENSOR_OK и frame_count растёт между двумя опросами. Поля после crc_errors есть на модулях карты 0x35+, на более старых они равны нулю / false.

Тревога при: nvm_fault или lta_status >= 2 (накопитель энергии); cal_src == 3 (сохранённая калибровка относится к другому диапазону, используются значения по умолчанию, cal_ok тоже сброшен); растут lost_frames / ring_drop; time_valid = false (установите часы); uptime_s уменьшается (модуль перезапустился). reset_cause несёт биты RBAMP_STD_RST_* (pin, power, software = reset / activate / address change, сторожевые таймеры, low-power, байт опций); бит pin сопровождает большинство внутренних сбросов, поэтому судите по другим битам.

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

C
typedef struct {
    uint8_t  sensor_class;  /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
    uint8_t  ct_model;      /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
    uint8_t  tier;          /* 0 or 1. 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) */
    uint16_t start_ua;      /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
    bool     start_ua_supported;  /* the module has the starting-current setting */
} rbamp_std_config_t;
Функция Описание
rbamp_std_read_config(dev, &cfg) Блок конфигурации (один пакетный обмен, плюс регистр стартового тока там, где он есть у модуля).
rbamp_std_set_harmonics(dev, enable) Включить или выключить извлечение базовых гармоник (THD, коэффициент мощности смещения, Q1). По умолчанию выключено на обычном уровне (экономит CPU модуля); поля гармоник читаются как 0, пока выключено. Только RAM: сбрасывается в выключенное состояние при перезагрузке модуля. Читается обратно и подтверждается. ESP_ERR_NOT_SUPPORTED без возможности THD.
rbamp_std_cal_thd_floor(dev) Калибровка порога THD цепи датчика: фиксирует текущий сглаженный сырой THD как порог, сохраняет его и применяет сразу. Предусловие: чистая сеть и БЕЗ нагрузки на CT — зафиксированное значение вычитается из всех последующих показаний THD. Блокирует на время сохранения; вердикт — по регистру ошибок модуля (карта 0x34+). ESP_ERR_NOT_SUPPORTED без возможности THD.
rbamp_std_get_start_current(dev, &ua) Стартовый ток для энергии, в мкА (0 = выключено). Ниже этого тока канала модуль не учитывает энергию по этому каналу (импорт или экспорт, общий итог и по каналам); сами показания не затрагиваются. ESP_ERR_NOT_SUPPORTED без трафика шины на модуле без этой настройки (версия образа модуля ниже 0x0001007B).
rbamp_std_set_start_current(dev, ua) Установка: 0 = выключено, иначе значение из набора шагов, которые принимает модуль. Применяется сразу; rbamp_save_user_config() сохраняет его. Читается обратно и подтверждается. ESP_ERR_INVALID_ARG для значения вне допустимого набора — ничего не записывается; ESP_ERR_NOT_SUPPORTED как выше; ESP_ERR_INVALID_STATE, если модуль не принял значение.

Скалярные вызовы конфигурации (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) работают на обеих линиях; у каждого есть примечание «линия STD» в его разделе. Два отличия, которые стоит знать: rbamp_factory_reset() возвращает ESP_ERR_NOT_SUPPORTED (такой команды на этой линии нет), а rbamp_save_gains() сохраняет блок калибровки.

rbamp_commit_address_change() на линии STD синхронен: сохранение конфигурации ждёт модуль и читает вердикт (адрес вне диапазона → ESP_ERR_INVALID_ARG; ограничение частоты записи флеша модуля → ESP_ERR_NOT_FINISHED — подготовьте заново и повторите примерно через 5 с; в обоих случаях ничего не меняется), затем перезапускает модуль и переключает дескриптор только после того, как модуль ответит по новому адресу (в пределах примерно 3 с). Если там никто не отвечает, — ESP_ERR_NOT_FOUND, а дескриптор сохраняет старый адрес. rbamp_read_active_address() читает сохранённый адрес.

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

Для модуля, который хранит сохраняемые счётчики энергии на устройстве (RBAMP_STD_CAP_ONDEVICE_ENERGY).

C
typedef struct {
    int64_t  act_import_wh, act_export_wh, act_net_wh;   /* Wh; net = import − export */
    int64_t  rea_import_varh, rea_export_varh;           /* varh */
    uint32_t generation;       /* changes when the counters were reset or adopted */
    uint32_t uptime_s;         /* module uptime */
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
    uint8_t  channels;         /* valid entries in the per-channel arrays (map 0x36+) */
    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, fine_reactive;
    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];
} rbamp_std_energy_t;

Счётчики выражаются в целых единицах, монотонны и сохраняются при потере питания. Импорт и экспорт — отдельные величины. Энергия периода — это разность двух показаний.

  • generation меняется, когда счётчики были сброшены или приняты на модуле — никогда не берите через это разность.

  • Уменьшение uptime_s означает, что модуль перезапустился. Счётчики сохраняются, поэтому разность всё ещё верна, но часы модуля и настройки RAM потеряны.

  • После отключения питания счётчик может продолжить чуть ниже вашего последнего показания (доля секунды энергии); rbamp_std_energy_delta() ограничивает такую разность значением 0 и сохраняет интервал.

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

  • channels > 0 (карта 0x36+): канал c — токовый канал c; на трёхфазном модуле — фаза c.

Сохранение структуры.

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

Функция Описание
rbamp_std_read_energy(dev, &e) Читает счётчики. Каждый декодированный блок — одна транзакция (модуль отдаёт его из согласованного снимка). ESP_ERR_NOT_SUPPORTED, если модуль не сообщает о возможности энергии в самом устройстве; ESP_ERR_INVALID_RESPONSE, если блок читается как не запрограммированный.
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) Энергия между двумя показаниями с применёнными правилами непрерывности. delta = now − prev по каждому счётчику (величины импорта / экспорта, чистая, реактивная; generation и uptime_s копируются из now); restarted = true, если uptime_s уменьшился. Любой из выходов может быть NULL. Счётчик, который уменьшился, ограничивается разностью 0 — и по каналам, и на каждом уровне разрешения; каждое чистое поле — разность импорта минус разность экспорта. Разности по каналам формируются, когда оба показания содержат одинаковое число каналов, иначе delta->channels равно 0. ESP_ERR_INVALID_STATE, если поколение различается — не учитывайте этот интервал; начните заново с now.

Банки снимков

Модуль хранит 8 независимых банков (только у модулей с возможностью мультиснимков, period_source == RBAMP_STD_PERIOD_LATCH). Банк накапливает, пока его бит установлен в маске взвода; rbamp_std_latch() снимает снимок и сбрасывает банк на следующей границе окна измерения модуля. Поэтому период — это интервал между двумя снимками одного банка, измеряемый по часам мастера (у модуля их нет). Банк 0 также используют rbamp_read_period_snapshot() и rbamp_energy_wh(). Три вызова банков возвращают ESP_ERR_NOT_SUPPORTED без трафика шины на любом другом модуле — там используйте rbamp_std_read_energy() / rbamp_std_energy_delta().

Типичное использование: взведите банки один раз, затем по каждому банку по собственному расписанию rbamp_std_latch(bank) → подождите ≥ 300 мс (безопасная верхняя граница одного окна измерения на каждом образе) → rbamp_std_read_latch() → rbamp_std_latch_wh() с dt, измеренным мастером с предыдущего снимка.

C
typedef struct {
    float    p_avg, q_avg, s_avg;       /* average P / Q / S over the period */
    float    max_p, max_i, max_u, min_u;/* peaks in the period */
    int64_t  e_import_mws, e_export_mws;/* energy, mW·samples */
    uint32_t nsamp;                     /* sensor samples in the period */
    uint32_t win_count;                 /* measurement windows in the period (0 = not armed / nothing elapsed) */
    uint8_t  channels;                  /* valid entries in the per-channel arrays */
    uint8_t  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];
} rbamp_std_latch_t;
Функция Описание
rbamp_std_arm_banks(dev, mask) Задайте маску накопления: бит b = банк b накапливает (вновь взведённые банки стартуют чистыми; снятые со взвода замирают и хранят последний снимок). Бит 0 должен оставаться установленным, если используется rbamp_read_period_snapshot(). Маска находится в RAM модуля: любой сброс модуля её очищает, а снимок невзведённого банка возвращает пустой снимок. Библиотека сама взводит банк 0 заново (в rbamp_begin(), после собственных сбросов и когда снимок периода возвращается пустым). Для собственных банков rbamp_std_read_latch() обнаруживает потерю взвода, взводит заново и снимает пробный снимок.
rbamp_std_latch(dev, bank) Запросить снимок + сброс bank на следующей границе окна. Не ждёт — читайте через ≥ 300 мс.
rbamp_std_read_latch(dev, bank, &l) Читает последний снимок bank (одним пакетом: итоги и энергия по каждому каналу для всех заполненных каналов). ESP_ERR_INVALID_RESPONSE, если модуль ни разу не фиксировал этот банк (остальные поля обнулены). ESP_ERR_INVALID_STATE, если снимок пуст, потому что банк снят со взвода сбросом модуля — библиотека заново взвела и сделала праймерную фиксацию: отбросьте этот период и перезапустите якорь dt. Читайте банк не раньше чем через одно окно измерения после фиксации; win_count == 0 означает, что банк не был взведён или окно не прошло.
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) Переводит энергетические корзины снимка в Wh за период dt_ms, измеренный по часам мастера (время между предыдущим и текущим снимком банка). ch — индекс канала или RBAMP_STD_TOTAL (0xFF) для итогов банка. Wh = E[мВт·отсчёты] / 1000 / 3600 × (dt / nsamp): число отсчётов и dt мастера нормируют результат. Импорт ≥ 0, экспорт ≤ 0; любой выход может быть NULL. ESP_ERR_INVALID_STATE, если nsamp равен 0.

Часы, команды и сервис

Модуль хранит часы в RAM: они становятся недействительными после каждого сброса модуля. Без действительных часов модуль не записывает историю.

Функция Описание
rbamp_std_set_time(dev, unix_epoch) Установить часы модуля (unix-секунды) и дождаться завершения. Вызывайте после rbamp_begin() и всякий раз, когда rbamp_std_health_t.time_valid ложно (или период сообщает module_restarted). Первая установка после сброса закрывает текущий интервал истории, не перенося его. ESP_ERR_INVALID_ARG, если модуль отклоняет эпоху (до 2020 г.); ESP_ERR_INVALID_STATE, если часы не стали валидными; ESP_ERR_NOT_SUPPORTED ниже карты 0x35.
rbamp_std_read_time(dev, &epoch, &valid) Чтение часов модуля и признака их действительности.
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) Записывает один код команды и ждёт её завершения: сначала ждёт простоя модуля (команда, записанная во время занятости, пропадает), спит settle_ms, ждёт снятия BUSY, затем читает вердикт. timeout_ms 0 = 1 с. Вердикты: ESP_ERR_INVALID_ARG (неверный параметр), ESP_ERR_NOT_SUPPORTED (неизвестная команда), ESP_ERR_INVALID_CRC (проверка значения), ESP_ERR_NOT_FINISHED (запись во флеш ограничена по частоте — повторите примерно через 5 с), ESP_ERR_NOT_ALLOWED (ключ или шлюз обслуживания), ESP_ERR_TIMEOUT (всё ещё занят).
rbamp_std_wait_idle(dev, timeout_ms) Ждать, пока модуль закончит выполняемую команду. Каждая команда, выданная через эту библиотеку, уже ждёт; используйте это только вокруг команд, которые вы сами пишете в регистр команд — команда, записанная во время BUSY, теряется. На модулях без регистра состояния команд возвращается сразу.
rbamp_std_hist_flush(dev) Записать накопители энергии во flash сейчас (также подразумевается при сбросе / фиксации прошивки).

Запись команды никогда не повторяется при ошибке транспорта (повтор мог бы доставить код операции дважды); чтение и запись регистров данных повтор сохраняют.

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

Модуль хранит последнюю 15-минутную запись в RAM (теряется при сбросе модуля — это индикатор текущего состояния, а не история) и часовой кольцевой буфер во флеш-памяти, который переживает сбросы и служит источником для догрузки пропусков; оба записываются только тогда, когда часы модуля действительны. Журнал событий, который никогда не стирается, фиксирует изменения, важные для учёта. В каждой часовой записи счётчики за весь срок службы хранятся абсолютными на конец периода: энергия периода — это разность двух соседних записей (сбросы и пропуски остаются видимыми). Догрузка после отказа мастера: идите back от 0 (самая новая) до меток времени, которые у вас уже есть.

C
typedef enum {
    RBAMP_STD_HIST_MIN15  = 0,  /* 15-minute records (RAM, lost at module reset) */
    RBAMP_STD_HIST_HOUR   = 1,  /* hourly records (flash ring) */
    RBAMP_STD_HIST_EVENTS = 2,  /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;

typedef struct {
    uint16_t count;        /* records available (0 while the ring is being cleared) */
    uint16_t capacity;     /* ring depth */
    uint16_t record_size;  /* bytes per record */
    uint32_t oldest_ts, newest_ts;  /* unix */
} rbamp_std_hist_info_t;

typedef struct {
    uint32_t ts;           /* period start, unix */
    uint16_t flags;        /* RBAMP_STD_HF_* bits */
    uint16_t n;            /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
    bool     from_ram;     /* record came from the RAM ring (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 counters ABSOLUTE at period end */
    uint8_t  phases;                     /* valid entries in the per-phase arrays */
    double   ph_import_wh[3], ph_export_wh[3];  /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;

typedef struct {
    uint32_t ts;           /* unix time (0 = clock was not set) */
    uint32_t uptime_s;     /* module uptime at the event */
    uint8_t  type;         /* RBAMP_STD_EV_* */
    uint8_t  flags;        /* RBAMP_STD_EVF_* (maintenance mode was active) */
    uint16_t boot;         /* boot counter (low 16 bits) */
    uint32_t a_before, a_after;        /* type-specific values before / after the change */
    uint64_t e_before_wh, e_after_wh;  /* grand import counter before / after, Wh */
} rbamp_std_event_t;
Функция Описание
rbamp_std_hist_info(dev, period, &info) Состояние кольца одного периода истории (также выбирает его на модуле).
rbamp_std_hist_read(dev, period, back, &rec) Загружает и декодирует запись back (0 = самая новая) для MIN15 или HOUR. ESP_ERR_NOT_FOUND, если такой записи нет. Энергию периода берите из двух соседних записей, только если их метки времени отличаются ровно на один период и ни одна не несёт флаг RBAMP_STD_HF_LTA_JUMP.
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) Та же запись без декодирования: rec (буфер RBAMP_STD_REG_HIST_REC_SIZE; значимая длина — record_size) получает байты записи модуля, flags — флаги записи модуля.
rbamp_std_event_read(dev, back, &ev) Получите и декодируйте запись журнала событий back (0 = самая новая). ESP_ERR_NOT_FOUND, если записей нет. Типы событий — сгенерированные константы RBAMP_STD_EV_* (сброс / принятие счётчика срока службы, сохранение калибровки, фиксация прошивки, очистка истории и т. д.).

Подлинность

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

C
typedef struct {
    uint8_t  raw[RBAMP_STD_REG_SEC_CERT_SIZE];  /* certificate bytes as read */
    uint8_t  state;          /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
    uint8_t  version, variant, hw_rev;
    uint8_t  uid[12];        /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
    uint32_t batch, issued;  /* production batch; issue time, unix */
    uint8_t  device_pubkey[32];
    uint32_t mfr_key_id;
} rbamp_std_certificate_t;

typedef struct {
    uint8_t  signature[64];  /* signature over the attested message */
    uint8_t  data[24];       /* attested data exactly as signed */
    uint32_t fw_version, generation;   /* from data */
    int64_t  e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
Функция Описание
rbamp_std_read_certificate(dev, &cert) Прочитать сертификат устройства. ESP_ERR_NOT_FOUND, если его нет у модуля (не провизионирован; state всё равно заполняется); ESP_ERR_NOT_SUPPORTED ниже карты 0x35.
rbamp_std_attest(dev, challenge, &att) Передайте модулю 32 случайных байта по вашему выбору (сохраните свою копию — модуль перезаписывает область вызова подписью) и получите подписанный ответ (около 60 мс). Заверенные данные связывают версию прошивки и счётчики срока службы с ключом устройства. ESP_ERR_NOT_FOUND, если у модуля нет ключа устройства; ESP_ERR_INVALID_STATE, если модуль не сообщил, что аттестация выполнена.

Обновление прошивки (OTA)

Двухфазное обновление по I²C. Каждая функция здесь возвращает ESP_ERR_NOT_SUPPORTED, если модуль не сообщает о возможности OTA (карта 0x33 или новее). Каждая команда завершается синхронно внутри библиотеки (она ждёт состояния команды модуля, а не фиксированной задержки).

Последовательность: rbamp_std_ota_begin → rbamp_std_ota_write_page × N (страницы по 256 байт; пустые страницы 0xFF можно пропускать) → rbamp_std_ota_commit (проверяет и взводит переключение, без перезагрузки) → rbamp_std_ota_activate (перезагружает в новый образ, когда вы готовы). Модуль несколько секунд отсутствует на шине, затем выполняет пробный запуск примерно 10 с до подтверждения образа. После каждой страницы сессия должна оставаться открытой, иначе вызов завершится с ESP_ERR_INVALID_STATE (перезапустите с begin). Неисправный образ модуль откатывает сам; калибровка сохраняется.

Принимаются только образы, подготовленные поставщиком. Релизные образы создаются инструментами производителя модуля (подписанные и, где требуется, зашифрованные); модуль отклоняет собранный на хосте заголовок при фиксации. Поэтому rbamp_std_ota_write_image() (образ, собранный на хосте, без подписи) возвращает ESP_ERR_NOT_SUPPORTED до обращения к модулю и сохранён только для совместимости ABI.

Функция Описание
rbamp_std_ota_status(dev, &st) Состояние OTA модуля (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE).
rbamp_std_ota_begin(dev, timeout_ms) Стереть неактивный банк и ждать, пока модуль сообщит READY. timeout_ms 0 = по умолчанию (5 с). ESP_ERR_TIMEOUT, если READY не был достигнут.
rbamp_std_ota_write_page(dev, page_idx, page) Запишите одну страницу по 256 байт с индексом page_idx (смещение / 256 внутри банка). ESP_ERR_INVALID_STATE, если модуль сообщает об ошибке записи.
rbamp_std_ota_commit(dev, timeout_ms) Проверяет записанный образ и взводит переключение банка. timeout_ms 0 = по умолчанию (3 с). ESP_OK взведено · ESP_ERR_INVALID_CRC плохой образ (CRC / заголовок) · ESP_ERR_INVALID_MAC аутентификация не пройдена · ESP_ERR_INVALID_VERSION образ старше запущенного · ESP_ERR_TIMEOUT.
rbamp_std_ota_diag(dev, &reason) Почему модуль отклонил последнюю страницу или фиксацию: байт причины из диагностики OTA (0 = нет). rbamp_std_ota_commit() уже сопоставляет причину с кодом ошибки выше и записывает её имя в журнал; вызывайте эту функцию, когда нужен сам код.
rbamp_std_ota_activate(dev) Перезагрузка в взведённый образ, ожидание возврата модуля (около 4 с), повторное обнаружение, затем удержание в пробном окне и подтверждение: изменился работающий банк, работающий образ — подготовленная версия, переключение больше не ожидает. Блокирует примерно на 10 с всего — не сбрасывайте и не выключайте модуль в это окно (загрузчик откатывает неподтверждённый образ). Дескриптор остаётся действительным, а rbamp_std_info() отражает новую прошивку. ESP_ERR_INVALID_STATE, если ничего не было взведено, если модуль вернулся на предыдущий образ (откат) или если переключение всё ещё ожидает после пробного окна.
rbamp_std_ota_staged_version(dev, &v) Версия взведённого (зафиксированного, но ещё не активированного) образа; 0, когда ничего не взведено (карта 0x35+).
rbamp_std_ota_abort(dev) Закрыть сессию обновления и разоружить взведённый образ; модуль продолжает работать с тем, что запущено (карта 0x35+).
rbamp_std_ota_board_ok(dev, image_board_word) Предварительная проверка перед потоковой передачей подготовленного образа: слово платы образа (поставляется рядом с файлом образа инструментами поставщика) должно совпадать с идентификатором платы модуля. ESP_OK, если совпадает; ESP_ERR_INVALID_ARG, если нет (записывается в журнал); ESP_ERR_NOT_SUPPORTED ниже карты 0x36.
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) Потоково передайте подготовленный образ банка как есть: начало, страницы по возрастанию (страница 0 всегда отправляется, остальные страницы из одних 0xFF пропускаются), фиксация. Библиотека ничего не патчит. Не активирует. size должен равняться размеру банка, который сообщает модуль (rbamp_std_info_t.ota_bank_size), — иначе ESP_ERR_INVALID_SIZE, и ничего не записывается. cb(done, total, ctx) — необязательный обратный вызов прогресса (rbamp_std_ota_progress_cb_t).
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) Как и выше, при наличии обоих образов банков: библиотека спрашивает у модуля, какой банк работает, и заливает другой. ESP_ERR_NOT_SUPPORTED на модулях, которые не сообщают работающий банк (карта ниже 0x35) — используйте rbamp_std_ota_write_prepared() и выбирайте по active_bank самостоятельно.
rbamp_std_crc32(data, len) CRC-32 (совместимый с zlib) — контрольная сумма, которую модуль проверяет при фиксации.
rbamp_std_ota_make_header(out, version, len, crc32) Формирует заголовок образа в порядке little-endian. Доступно только когда сгенерированный заголовок регистров определяет константы заголовка; оставлено для совместимости ABI.

Диагностика

rbamp_err_to_str

C
const char *rbamp_err_to_str(esp_err_t err);

Возвращает указатель на статическую строку с понятным описанием кода ошибки. Никогда не возвращает NULL. Для системных кодов использует стандартный esp_err_to_name(), а для семантики, специфичной для rbamp, расширяет описания (например, что ESP_ERR_INVALID_STATE означает в контексте set_ct_model_ch без set_sensor_class).

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

C
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}

rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count   (rbamp_handle_t dev);
void     rbamp_reset_counters        (rbamp_handle_t dev);

Публичные геттеры двух диагностических счётчиков (оба возвращают 0 при NULL-дескрипторе):

  • rbamp_retry_exhaustion_count(dev) — монотонный счётчик событий «бюджет повторов исчерпан». Каждое увеличение = одна однобайтовая транзакция, которая после CONFIG_RBAMP_NACK_RETRY_ATTEMPTS попыток так и не получила ACK от устройства.

  • rbamp_sanity_reject_count(dev) — монотонный счётчик отказов фильтра адекватности при чтениях чисел с плавающей точкой (NaN, Inf или абсолютное значение выше предела по величине — RBAMP_SANITY_LIMIT_V / _I / _P / _PF). Каждый инкремент = одно число, пришедшее по шине, которое сочли не похожим на физическое значение и отбросили; чтение возвращает ESP_ERR_INVALID_RESPONSE.

rbamp_reset_counters(dev) обнуляет оба счётчика на этом дескрипторе (пустая операция для NULL). Предназначено для тестовых сценариев, которым нужна чистая база. Для промышленного мониторинга предпочтителен канонический шаблон «скорость за интервал» — снимок + разность, устойчивая к пропущенным окнам сброса:

C
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }

Эти имена совпадают с кросс-платформенной библиотекой Arduino (dev.retryExhaustionCount() / dev.sanityRejectCount() — та же семантика, snake_case). Для практических нагрузок и порогов тревоги см. 10 · Устранение неполадок, раздел «Мониторинг счётчиков».

Журналирование через esp_log

Компонент пишет в журнал под тегом "rbamp". Уровень журнала вшивается через Kconfig — runtime-вызов esp_log_level_set("rbamp", ...) работает, но сверху ограничен уровнем, заданным при сборке.

C
esp_log_level_set("rbamp", ESP_LOG_DEBUG);   /* for debugging */

Коды ошибок

Функции rbamp_* возвращают стандартные значения esp_err_t. Конкретные коды и их смысл в контексте rbamp:

Код Когда Где искать
ESP_OK (0) Успех —
ESP_FAIL (-1) Транзакция I²C завершилась ошибкой после повторов проводка, питание, скорость шины — раздел «Модуль не отвечает по I²C» в 10 · Устранение неполадок
ESP_ERR_INVALID_ARG (0x102) Недопустимый аргумент: dev == NULL, channel или phase вне диапазона, нераспознанный cls, значение, которое модуль отклоняет (неизвестная модель CT, стартовый ток вне допустимого набора, часы раньше 2020 года) проверьте аргументы вызова
ESP_ERR_TIMEOUT (0x107) Истекли rbamp_wait_ready / rbamp_wait_data_ready; истекло окно rbamp_commit_address_change (5 с); команда STD или состояние OTA не завершились проверьте отклик через rbamp_probe()
ESP_ERR_INVALID_STATE (0x103) Нарушено предусловие или порядок вызовов: set_ct_model* вызван до set_sensor_class; модуль класса 2 / 3 (откалиброван вместе со своим датчиком — для сервиса используйте rbamp_set_ct_model_ch_force()); модуль отклонил пару (класс, модель); фиксация адреса не взведена; банк снимков STD взведён заново после сброса модуля (отбросьте этот период); счётчик энергии STD сменил поколение (rbamp_std_energy_delta); сессия OTA не открыта раздел «rbamp_set_* возвращает ESP_ERR_INVALID_STATE» в 10 · Устранение неполадок
ESP_ERR_NOT_SUPPORTED (0x106) Функция или возможность отсутствует на этой линии / прошивке / модуле: любой вызов rbamp_std_* на дескрипторе BASIC, реактивная / полная мощность на BASIC, rbamp_read_digest на STD или без возможности дайджеста, вызовы периода на модуле STD без банков снимков и без счётчиков, rbamp_factory_reset на STD, слишком старая версия карты регистров, OTA без соответствующей возможности проверьте rbamp_line(dev), rbamp_std_info() и rbamp_variant(dev)
ESP_ERR_NOT_FOUND Ничего не обнаружено: rbamp_std_probe — никто не подтверждает адрес; нет такой истории / записи события; нет сертификата или ключа устройства; фиксация адреса — по новому адресу никто не отвечает (дескриптор сохраняет старый) проверьте проводку / адрес; идите back только до rbamp_std_hist_info().count
ESP_ERR_INVALID_RESPONSE (0x108) Снимок периода устарел (флаг готовности = 0) или период пропущен (счётчики STD переякорены, банк взведён заново); REG_VERSION = 0/0xFF при rbamp_begin; значение с плавающей точкой не прошло фильтр адекватности; частота сети STD 0 (нет сети); rbamp_std_probe — отвечает что-то, что не является модулем STD раздел «Снимки периода всегда устарели» / «Не выйти из rbamp_begin» в 10 · Устранение неполадок
ESP_ERR_NO_MEM (0x101) Не удалось выделить память под дескриптор; больше 4 линий DRDY / 8 дескрипторов на линию проверьте бюджет кучи
ESP_ERR_NOT_FINISHED STD: запись во flash модуля ограничена по частоте повторить примерно через 5 с
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED Вердикты команд и OTA STD: значение или проверка образа не прошли, аутентификация не прошла, образ старше работающего, образ не помещается в банк, модуль отказался выполнить операцию (см. rbamp_std_command, rbamp_std_ota_commit) rbamp_std_ota_diag() — для выяснения причины

Все возвращаемые коды можно вывести в читаемом виде через rbamp_err_to_str().

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

Следующие символы CONFIG_RBAMP_* доступны в idf.py menuconfig → Component config → rbAmp client:

Символ Тип Диапазон / выбор По умолчанию Цель
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ int 50000–1000000 Гц 50000 Частота SCL. 50 кГц — требование текущей прошивки для ESP32.
CONFIG_RBAMP_I2C_TIMEOUT_MS int 10–1000 мс 100 Таймаут i2c_master_transmit/receive. Должен быть достаточно длинным, чтобы поглотить задержку модуля перед чтением.
CONFIG_RBAMP_I2C_SCL_WAIT_US int 2000–60000 µs 10000 Допуск растягивания тактов SCL: сколько периферия I²C позволяет модулю держать SCL в низком уровне, прежде чем она откажется от транзакции. Значение по умолчанию драйвера — 2 мс; модуль растягивает SCL дольше, пока стирает сектор флеша при обновлении прошивки, и каждое такое растягивание закончилось бы строкой журнала «I2C hardware timeout» и повтором. 10 мс покрывает стирание сектора. Исходный ESP32 не может ждать дольше примерно 13 мс (20-битный аппаратный счётчик); компонент ограничивает значение этим пределом на данной цели.
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS int 1–10 3 Попытки на одно однобайтовое чтение.
CONFIG_RBAMP_NACK_RETRY_GAP_MS int 1–100 мс 5 Пауза между попытками повтора.
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION bool n/y n Когда все повторы NACK транзакции провалены, вызовите i2c_master_bus_reset() один раз перед последней попыткой. Драйвер IDF и так сбрасывает свой автомат после каждой неудачной транзакции, а явный сброс не берёт блокировку шины: при нескольких задачах на шине он может прервать чужую транзакцию (на ESP32 он формирует STOP на выводах, что обработчик прерывания драйвера может принять за конец чтения). Не включайте, если мастер однозадачный и шина зависает после ошибок драйвера.
CONFIG_RBAMP_SCT_RATING_CORRECTION bool n/y y Корректирует показания SCT-013 на прошивке BASIC до 1.4.19, которая сохраняет калибровку на 30 А после того, как пользователь переключает канал на другую модель. Библиотека масштабирует ток, мощность, мощность периода, энергию и дайджест под выбранную модель (rbamp_sct_correction() сообщает результат по каждому каналу). Модуль, который корректирует себя сам (прошивка 1.4.20 и новее), не затрагивается. Отключите, чтобы читать сырые значения модуля. См. Коррекция номинала SCT-013.
CONFIG_RBAMP_DRDY_POLL_MS int 5–50 мс 20 Когда у дескриптора нет GPIO DRDY, rbamp_wait_data_ready() опрашивает счётчик публикаций модуля (STD) или последовательность фиксации (BASIC) с этим интервалом. Модуль публикует каждые 100 мс (старые образы: 200 мс).
CONFIG_RBAMP_DISABLE_ENERGY bool n/y n Полностью убирает накопитель Wh из сборки (и хранение, и API).
CONFIG_RBAMP_LOG_LEVEL_* выбор NONE / ERROR / WARN / INFO / DEBUG INFO Компиляционный LOG_LOCAL_LEVEL для тега rbamp. Определяет, компилируются ли строки журнала в бинарник вообще; не зависит от CONFIG_LOG_DEFAULT_LEVEL.

Пример sdkconfig.defaults для типичного производственного сценария:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)

Для стендового теста под сильной нагрузкой:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

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

Компонент использует следующие времена установления внутри при выполнении команд (для пользователя, работающего поверх низкоуровневого API через i2c_master_transmit_receive и желающего соблюдать те же тайминги):

Библиотека экспортирует небольшой набор констант времени установления (мс) для пользователей низкоуровневого API, которые отправляют команды устройству напрямую и должны дождаться, пока устройство закончит обработку, прежде чем читать затронутые регистры. Функции-обёртки компонента (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch и т. д.) выдерживают нужную задержку внутри себя — эти константы нужны только если вы обходите обёртки.

Макрос Цель мс
RBAMP_SETTLE_MS_LATCH_PERIOD После CMD_LATCH_PERIOD 50
RBAMP_SETTLE_MS_RESET После CMD_RESET 100
RBAMP_SETTLE_MS_SAVE_GAINS После CMD_SAVE_GAINS (стирание и запись флеша) 700
RBAMP_SETTLE_MS_FACTORY_RESET После CMD_FACTORY_RESET 1500
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 После CMD_SET_CT_MODEL_CH0 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 После CMD_SET_CT_MODEL_CH1 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 После CMD_SET_CT_MODEL_CH2 5

Источник истины — блок @defgroup rbamp_settle_ms в include/rbamp.h. Числа — спецификационные минимумы протокола rbAmp; короче нельзя, длиннее можно.

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

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

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

Пакетное чтение + N bytes возвращает N подряд идущих байт, начиная с addr. Пример: одна транзакция i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) читает 16 байт, начиная с 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK на UI1).

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

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

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

C
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100);   /* only 'M' lands */

/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
    uint8_t tx[2] = { 0x68 + i, label[i] };
    i2c_master_transmit(slave, tx, 2, 100);
}

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

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

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

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

Авторитетный байт SKU — регистр 0x55 (кешируется как rbamp_variant()):

значение 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)
0x08 UI7 (7× I + U)

rbamp_topology() вспомогательная; возвращает только число каналов (1/2/3/5/7) и не различает наличие U.

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

⚠ REG_SENSOR_CLASS (0x25) НЕ является признаком варианта (он задаётся пользовательской конфигурацией). Инвариант варианта = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) — оба только для чтения.

CAPABILITY (0x57/0x58, u16 LE) — карта определения возможностей

Карта возможностей устройства (например: присутствует фронтенд напряжения, поддерживается снимок General-Call, блок дайджеста, флаги событий, двухфазная смена адреса). Канонический способ определить возможности (вместо сравнения числовой версии). Проверяйте отдельные флаги возможностей через вспомогательные функции; набор флагов растёт вместе с прошивкой модуля.

has_voltage (без чтения HW_VARIANT):

C
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);

/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0;  /* voltage front-end flag */

Оба варианта равнозначны.

Согласованность HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 (UI) → флаг входного каскада напряжения установлен; HW_VARIANT 4..6 (I) → флаг сброшен. Несоответствие = аппаратная аномалия.

Атомарность / заморозка чтения (B1)

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

  • Блок V03 float RMS (0x86+: U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, freq) — защита чтения есть, пакетное чтение атомарно.
  • Блок дайджеста (0x70-0x85) — защита чтения есть.
  • GC_TICK (0x59) / зеркало адреса (0x30) / зеркала моделей CT (0x51-0x53) — защиты чтения нет; для надёжного чтения используйте шаблон «читать дважды и сверить» (прочитайте дважды, считайте значение годным, только если они совпали).

Семантика клипсы NF

I_RMS = 0x00000000 означает «сигнал ниже шумового порога» (прошивка вычисляет rms_corr² = max(0, raw² − nf²)), а НЕ «нет данных» / «ошибка». Это допустимое измерение для сценариев без нагрузки.

Регистры только напряжения на вариантах только с током

U_RMS, U_PEAK на I1/I2/I3 читаются как 0. Они валидны, только когда установлен флаг входного каскада напряжения в CAPABILITY. REG_AC_FREQ берётся из ZC и доступен на всех вариантах (включая I*).

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

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

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

Кадр только запускает снимок периода; он никогда не несёт деструктивных кодов операций.

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

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

Приложение — Под капотом

Перенесено из главы «Обзор»: сравнение на уровне регистров, архитектура и схемы взаимодействия.

Без компонента (прямой доступ через i2c_master_transmit_receive)

C
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
    .device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);

uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
                                /*xfer_timeout_ms=*/100) != ESP_OK) {
    return;   // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));

С компонентом

C
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));

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

C
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 };   // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));   // settle

uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
    // snapshot is stale — t_latch_us STILL must be recorded,
    // otherwise the next snapshot will count Wh over two periods
    return;
}

// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
//   double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
//   E_Wh += avg_p * dt_s / 3600.0;

Чтение периода — с компонентом

C
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
    // snap.avg_p[0] is populated,
    // rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
    // master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
    // snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}

Внутри компонент гарантирует:

  • Выдержка 50 мс после CMD_LATCH_PERIOD (настраивается параметром settle_ms), корректное чтение снимка (атомарный снимок на стороне модуля).

  • Проверка флага REG_V03_PERIOD_VALID перед чтением (поле snap.valid).

  • Запись времени по часам мастера даже при устаревшем снимке (защищает от двойного учёта Wh в следующем периоде).

  • Поканальное накопление Wh с двойной точностью (тип double внутри дескриптора).

  • Автоматическая загрузка калибровочных коэффициентов при выборе датчика тока через rbamp_set_sensor_class() + rbamp_set_ct_model() — пользователю не нужно знать о внутренних калибровочных регистрах.

Когда использовать компонент, а когда прямой доступ к шине

Задача Компонент Прямой доступ через i2c_master_*
Чтение U / I / P / PF / частоты ✅ только для отладки на логическом анализаторе
Учёт энергии по периодам ✅ только если Wh хранится вне компонента (например, в базе данных на стороне мастера)
Несколько модулей на одной шине ✅ (последовательный снимок + общая выдержка, см. 06_examples.md) —
Двунаправленный учёт на BASIC ✅ (через RT-чтения — см. 06_examples.md) альтернатива — собственный цикл RT-чтений и ручное интегрирование
Перенос на другую платформу n/a ✅ — см. 09 · Справочник API о деталях сетевого протокола
Жёсткий лимит RAM редко важно (~85 байт на дескриптор) ✅ если даже эти ~85 байт критичны

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

Архитектура

Слои от прикладной задачи через компонент rbamp и драйвер I²C до модуля rbAmp.

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

Ход rbamp_begin()

Последовательность транзакций на шине, выполняемых rbamp_begin().

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

Последовательность rbamp_read_period_snapshot(dev, &snap, 50, false)

Последовательность чтения снимка периода и интегрирования энергии на мастере.

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

Соответствие прямому API регистров

Таблица для тех, кто переходит со своего кода прямого доступа:

Прямой API (i2c_master_transmit_receive) Эквивалентно через компонент
Ручное чтение 4 байт + memcpy rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p)
tx([0x01, 0x27]); vTaskDelay(50) rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (или сразу rbamp_read_period_snapshot())
Проверка read_u8(0x07) & 1 поле snap.valid после rbamp_read_period_snapshot()
Ручная формула E_Wh += avg_p * dt_s / 3600 rbamp_energy_wh(dev, 0) — обновляется автоматически
Ручная настройка токового датчика через прямой API регистров rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code) — заводские пресеты загружаются автоматически

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