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
typedef struct rbamp_obj_t *rbamp_handle_t;
Непрозрачный дескриптор подчинённого устройства. У пользователя нет доступа к его полям. Создаётся через rbamp_new(), освобождается через rbamp_del().
rbamp_topology_t
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
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
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) заполнены нулями.
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() — один канал, любой индекс.
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(). Примитив учёта энергии.
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():
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;
Типы дайджеста
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
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
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
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
void rbamp_del(rbamp_handle_t dev);
Освобождает дескриптор и удаляет связанный i2c_master_dev_handle_t с шины. Безопасно вызывать с NULL — это пустая операция.
rbamp_begin
02 · Инициализация и запуск (initialization) · BASIC или STD? (initialization) · Непрерывный цикл опроса (рекомендуется) (period-metering)
esp_err_t rbamp_begin(rbamp_handle_t dev);
Опрашивает устройство, определяет линию модуля, принимает число каналов и вариант и выполняет затравочный снимок.
Sequence:
-
Прочитайте
REG_VERSION(0x03). Если устройство не ответило ACK —ESP_FAIL. Если вернулось0x00/0xFF—ESP_ERR_INVALID_RESPONSE. -
Определите линию изделия (BASIC / STD) по идентификационному блоку модуля и закэшируйте её (
rbamp_line()). На линии STD идентичность тоже кэшируется (rbamp_std_info()), и выбирается механизм периода. -
Принимаются число каналов, вариант и наличие напряжения от модуля (если топология не закреплена через
rbamp_new_with_topology). -
Оцените коррекцию номинала SCT-013 (см. Коррекция номинала SCT-013).
-
Запишите
CMD_LATCH_PERIODкак праймер и ждите 50 мс. Первый снимок после включения отбрасывается. (rbamp_begin_resume()этот шаг пропускает.) -
Сохраните
esp_timer_get_time()для последующего интегрирования энергии.
Идемпотентен, но не бесплатен: каждый вызов выполняет один затравочный снимок.
Возвращает: ESP_OK при успехе; иначе — коды ошибок выше.
rbamp_begin_resume
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
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);
EVENT_FLAGS в том виде, как их нашёл rbamp_begin() (обе линии; 0, если их нельзя было прочитать). RBAMP_EVENT_RESET_OCCURRED здесь означает, что модуль перезагрузился до того, как библиотека его встретила — заново примените его настройки в RAM (часы, маску событий, пороги). Библиотека при begin ничего не сбрасывает. Без обращения к шине.
rbamp_probe
esp_err_t rbamp_probe(rbamp_handle_t dev);
Лёгкая проверка работоспособности. Одно чтение REG_VERSION без побочных эффектов.
Возвращает: ESP_OK, если подчинённый ответил ACK и сообщил поддерживаемую версию (не 0 и не 0xFF); иначе ESP_FAIL.
rbamp_wait_ready
02 · Инициализация и запуск (initialization) · 3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · 4 · Карта регистров (production v1.3) (api-reference)
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);
Опрашивает флаг готовности модуля, пока бит 0 не установлен. Полезно после включения — модулю может понадобиться до 100 мс на первое окно RT.
Возвращает: ESP_OK, если бит замечен до истечения timeout_ms; иначе ESP_ERR_TIMEOUT.
Геттеры состояния дескриптора
BASIC или STD? (initialization) · Ток по нескольким каналам (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
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
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.
Чтение по каналам
Справочник регистров RT (realtime-polling) · Двунаправленный учёт (period-metering)
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
Справочник регистров RT (realtime-polling) · Опрос — один модуль (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
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 частичное и его нельзя использовать.
Реактивная и полная мощность
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 и выше)
Многоканальный ток (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Окно доступа к каналам (0x32 + 0x3C..0x3F) (api-reference)
Каналы 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+ через окно. Выбор окна — единый общий ресурс внутри модуля, а выбор и чтение — одна атомарная секция: не используйте один дескриптор из разных задач без собственного мьютекса.
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
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);
Читает байт последовательности дайджеста: uint8_t, который увеличивается раз в окно измерения (каждые 100 мс в текущей прошивке, 200 мс в образах до v1.2; переходит 255 → 0). Прочитайте его до и после многорегистрового опроса — неизменившееся значение доказывает, что все чтения взяты из одной фиксации. Дайджест не содержит CRC.
Готовность данных (DRDY)
01 · Подключение к железу (hardware-connection) · 03 · Опрос в реальном времени (realtime-polling) · Опрос — один модуль (realtime-polling)
DRDYвыход: HIGH в покое (подтяжка мастера), импульс LOW ~10 мкс каждый раз, когда публикуется полный снимок измерения (каждые 100 мс во всём семействе; образы BASIC до v1.2 и STD до 0x7B: 200 мс). Несколько модулей могут делить одну линию монтажного ИЛИ. Модули BASIC также удерживают линию уверенно в LOW, пока висит необслуженное событие (тревога).
Библиотека превращает импульс в пробуждение, чтобы читатель никогда не читал один и тот же снимок дважды, не попадал на момент публикации и узнавал, сколько снимков пропустил. На модулях STD счётчик публикаций показывает, какой модуль выдал импульс на общей линии. Без провода DRDY те же вызовы работают опросом счётчика модуля каждые CONFIG_RBAMP_DRDY_POLL_MS. Модули STD старше образа 0x00010075 управляют линией иначе: библиотека считает, что линии DRDY у них нет, и опрашивает.
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).
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
4.9 Digest window (0x70..0x85) (api-reference) · 8.7 DIGEST round-trip — configure + read (api-reference)
Дайджест — компактный блок, который модуль BASIC публикует с каждым окном. Он позволяет мастеру получить результат окна одной транзакцией I²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
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
04 · Периодический учёт и тарифный расчёт (period-metering) · Калибровка и точность (troubleshooting) · 7.5 Сохранение периода при неудачном снимке (api-reference)
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);
Читает бит готовности снимка. *out = true, если последний снимок свежий.
rbamp_read_period_avg_power
Регистры снимка периода (period-metering) · 4.11 Блок периода V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + период ch0 (0xD0..0xE3, производственная сборка) (api-reference)
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
Регистры снимка периода (period-metering) · 4.12 V03 Q + период ch0 (0xD0..0xE3, производственная сборка) (api-reference)
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);
Пиковая мгновенная мощность канала 0 за период снимка. ch=0 только на прошивке v1.
rbamp_read_period_latch_ms
13. Дрейф часов нескольких модулей в долгих тестах (troubleshooting) · 4.13 Диагностический dt на стороне микросхемы (0xEC) (api-reference)
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
Непрерывный цикл опроса (рекомендуется) (period-metering) · Несколько модулей — одновременный снимок (period-metering) · Калибровка и точность (troubleshooting)
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
rbamp_period_snapshot_t *out,
uint16_t settle_ms,
bool skip_latch);
Рекомендуемая точка входа для учёта по периодам. Полная последовательность внутри:
-
Если
skip_latch == true— пропустить запись LATCH (используется после ручной серии команд снимка или широковещательного снимка для синхронизации нескольких модулей). -
Иначе — запишите
CMD_LATCH_PERIOD. - Зафиксируйте
esp_timer_get_time(), чтобы вычислитьmaster_dt_ms. vTaskDelay(pdMS_TO_TICKS(settle_ms))— по умолчанию 50 мс.-
Проверьте флаг готовности снимка. Если он 0 — установите
ESP_ERR_INVALID_RESPONSEи запишите метку времени (чтобы следующий снимок не удвоил учётdt). -
Прочитайте
avg_p[0..channels-1]+max_p+latch_ms. - Обновите метку времени и вызовите интегратор энергии для всех каналов (если компонент собран без
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
Определение перезапуска модуля (period-metering) · 4.6 Состояние / диагностика (0x46..0x4F) (api-reference)
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 заново, снимает пробный снимок и перезапускает якорь часов (это одно окно не интегрируется, следующее снова полное).
Вспомогательная встроенная функция
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. Используйте для обычного периодического опроса.
Учёт энергии (накопитель на стороне мастера)
Алгоритм на стороне мастера (period-metering) · 7 · Семантика (api-reference)
Если компонент собран без CONFIG_RBAMP_DISABLE_ENERGY=y, доступны функции-аксессоры к накопителю Wh внутри дескриптора:
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 на многоканальных модулях, которые их не публикуют, и совпадают с итогом на одноканальных модулях.
Формула интегрирования:
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_* выше и никогда не нуждается в этом. Он перечислен здесь, потому что символы видны:
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
Автоопределение варианта модуля (initialization) · Справочник протокола провода rbAmp (v1.3) (api-reference) · 3.6 Канонический алгоритм обнаружения (api-reference)
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
Автоопределение варианта модуля (initialization) · 3.2 CAPABILITY (регистры 0x57/0x58, u16 LE, только чтение) (api-reference) · 8 · Примеры трассировки на линии (api-reference)
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
bool rbamp_has_voltage(rbamp_handle_t dev);
Удобный помощник поверх rbamp_read_capability — возвращает true, если модуль имеет канал U (то есть (cap >> 8) & 1). Результат кешируется в дескрипторе при первом вызове; последующие вызовы не выполняют операцию I²C.
rbamp_read_product_id
3.5 PRODUCT_ID (0x54, u8, только чтение) (api-reference) · 4.8 Идентичность (0x54..0x6F) (api-reference)
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
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);
Читает 96-битный уникальный идентификатор МК из UID (0x5C..0x67) одной пакетной операцией. UID уникален для каждого модуля и не меняется при перепрошивке — удобно для серийных журналов, проверок клонов на стороне мастера и идентификации при замене модуля в развёрнутом флоте.
rbamp_is_provisioned
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
6.5 Настройка — первичная прошивка + SAVE (api-reference) · 8.6 Настройка при первичной прошивке (api-reference)
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
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 на устройстве не затрагивается:
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):
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:
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
3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · Коды ошибок (REG_ERROR = 0x02) (troubleshooting) · 4 · Карта регистров (производство v1.3) (api-reference)
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);
Читает REG_ERROR (0x02) напрямую — результат последней транзакции, успешно принятой шиной (запись или команда). Не «липкий»: любая последующая успешная запись перезаписывает его своим результатом.
Используется в канале B (отказ на стороне DUT) для расширенного кода причины.
rbamp_has_error
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
8.8 Поток событий по порогам — запись порога → срабатывание → сброс W1C (api-reference)
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
Коды ошибок (REG_ERROR = 0x02) (troubleshooting) · 6.7 Восстановление из состояния ошибки — дерево решений (api-reference)
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 через несколько сотен миллисекунд из-за повторного защёлкивания.
События и линия тревоги
4.4 Конфигурация флота (0x27..0x2F) (api-reference) · 8.8 Поток событий по порогам — запись порога → срабатывание → сброс W1C (api-reference)
События — одна модель на обеих линиях: липкие флаги (RBAMP_EVENT_*), сбрасываемые записью 1. Флаги, которые также выставлены в маске событий, удерживают линию DRDY в LOW (тревога), пока их не сбросят или не снимут маску. Маска и пороги живут в RAM модуля — заново взводите их после каждого сброса модуля (RBAMP_EVENT_RESET_OCCURRED сообщает об этом; см. также rbamp_begin_event_flags()).
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
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.
Внутри функция выполняет:
set_sensor_class(cls)один раз.-
Для каждого канала
k < min(n, n_channels): привязатьmodels[k]; каждая привязка проверяется синхронно и подтверждается обратным чтением. -
Одно завершающее сохранение пользовательской конфигурации в конце (плюс то, что внутри
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
4.7 Зеркала проверки модели ТТ (0x51..0x53) (api-reference) · 8.10 Обратное чтение зеркала проверки модели ТТ (проверка после привязки) (api-reference)
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) из других допустим, но сложные многошаговые операции координируйте явно.
Жизненный цикл
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
Настройка нескольких модулей (initialization) · Опрос нескольких модулей — три стратегии (realtime-polling) · Проблемы с несколькими модулями (troubleshooting)
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
bool match_product,
size_t *added);
Опрашивает шину в диапазоне 0x08..0x77; для каждого адреса, который подтверждает (ACK):
-
Проверяет идентичность (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Еслиmatch_product = true, требует совпадения с PRODUCT_ID rbAmp. -
Запускает детектор конфликтов (два независимых сигнала; см. 10 · Устранение неполадок, раздел «Парк: модуль оказался в excluded»). Подозрительные адреса попадают в список
excluded, а не в парк. -
Выполняет контрольный канал «зависания» уровня 2: проверяет адрес, по которому гарантированно никого быть не должно. Если контрольный адрес получает ACK, возвращается
ESP_ERR_INVALID_STATE— шина зависла, флот остаётся пустым (см. диагностику в гл. 10).
После успеха *added содержит число модулей, добавленных во флот. excluded_count (см. ниже) доступен через отдельный геттер.
Вывод на стенде (проверено на оборудовании на разнородном флоте UI1+I2+I3 с внешними подтяжками 4.7 кОм):
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 · Устранение неполадок).
Доступ к модулю
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
Настройка нескольких модулей (initialization) · Опрос нескольких модулей — три стратегии (realtime-polling)
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).
Устойчив к пропускам: один молчащий модуль не отменяет опрос остальных. Это важно для промышленного парка — потеря одного модуля (сбой проводки, выгорание) не должна обрушить весь мониторинг.
Агрегация
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, если он не нужен.
Адресация и проверка конфликтов
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
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
uint8_t desired_addr,
bool save_config,
rbamp_handle_t *out);
Вводит в эксплуатацию ровно один новый модуль (на заводском 0x50) по указанному адресу. Внутри:
-
Проверяет наличие ответа по
0x50(ESP_ERR_NOT_FOUND, если его нет). -
Проверяет, что никого нет по
desired_addr(ESP_ERR_INVALID_STATE, если занят). -
Выполняет двухфазную фиксацию адреса.
-
Сбрасывает модуль и ждёт его появления по
desired_addrв окне загрузки (ESP_ERR_TIMEOUT, если он не появился). -
Создаёт дескриптор; если
save_config = true— вызываетrbamp_save_user_config(сохранение во флеш). -
Возвращает готовый дескриптор через
*out.
⚠ ОБЯЗАТЕЛЬНО: ровно один чистый модуль на шине в момент вызова. Два модуля на 0x50 одновременно физически неразличимы по I²C — их нельзя различить даже специальным оборудованием. Гарантия лежит на операторе, а не на библиотеке. Для восстановления см. 10 · Устранение неполадок, раздел «Флот: rbamp_provision вернул ошибку».
Синхронизация GC флота — синхронные снимки по всему флоту
General Call (широковещание по адресу 0x00) (initialization) · Несколько модулей — одновременный снимок (period-metering) · 6.3 Широковещательный снимок GC — опциональная синхронизация флота (api-reference)
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.
-
_enable_gc_allзадаётFLEET_CONFIG.bit0+GROUP_IDна всех модулях флота и выполняетCMD_SAVE_USER_CONFIGна каждом (постоянно). Перезагрузка модулей обязательна после включения — выполняется автоматически. Достаточно вызвать один раз при первоначальной настройке флота.*ok_count(необязательно) — число модулей, на которых включение прошло успешно. -
_gclatchотправляет кадр GCA5 27 group tick_lo tick_hiна адрес0x00— все модули с включённым GC и совпадающимgroupмгновенно делают снимок (LATCH_PERIOD).settle_ms— пауза после кадра (обычно 50 мс) до проверки. -
_check_syncчитаетGC_TICK (0x59)на каждом модуле вrbamp_fleet_sync_t status[status_cap]. Результат по модулю:
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
Общий вызов (широковещание по адресу 0x00) (initialization) · 4.4 Конфигурация флота (0x27..0x2F) (api-reference)
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
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
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);
Читает GC_TICK (0x59) — последнее значение тика, полученное из кадра GC. Используется для обнаружения пропущенных кадров (если у двух модулей разный тик, кто-то пропустил кадр).
rbamp_read_label / rbamp_write_label
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
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
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);
Сбрасывает диагностические счётчики модуля (количество ошибок i2c, количество переинициализаций периферии). На пользовательскую конфигурацию и калибровку не влияет. Используется для стендовых тестов и периодического сброса счётчиков в длительных производственных испытаниях.
Настройка датчика
Двухшаговая последовательность: сначала класс датчика, затем модель. Оба шага обязательны для модуля с датчиком, установленным пользователем (класс 1). Модули, которые поставляются с датчиком (класс 2 / 3), приходят уже настроенными и защищены от случайной перезаписи — см. примечания о защите «сначала чтение, потом запись» ниже.
Подробное руководство по выбору модели — см. 03 · Выбор датчика тока.
rbamp_set_sensor_class
Настройка класса датчика и модели ТТ (initialization) · 4.3 Система (0x20..0x25) (api-reference) · 6.2 Привязка модели ТТ — чистая подготовка + поканальная команда CMD (api-reference)
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
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}.)
Сначала должен быть вызван rbamp_set_sensor_class() (иначе ESP_ERR_INVALID_STATE, запись не выполняется). Действует и защита «сначала чтение, потом запись» у rbamp_set_ct_model_ch().
Для многоканальных модулей используйте поканальную форму ниже.
rbamp_set_ct_model_ch
Настройка класса датчика и модели CT (initialization) · 6.2 Привязка модели CT — чистый staging + CMD по каналам (api-reference)
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 — чистая подготовка: каждое поканальное применение привязывает только свой канал, поэтому каналы можно настраивать в любом порядке — по возрастанию, по убыванию или вперемежку — без взаимного затирания:
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
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
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);
Текущий класс датчика модуля как значение rbamp_sensor_class_t (BASIC: регистр класса; STD: поле конфигурации класса).
Пределы моделей датчиков
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 (по умолчанию включено) отключает механизм, и тогда возвращаются сырые значения модуля.
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
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
Смена адреса (initialization) · 4.5 Адрес (0x30..0x31) (api-reference) · 6.1 Смена адреса — двухфазная фиксация (допустимо в production) (api-reference)
Смена I²C-адреса модуля выполняется через двухфазную фиксацию в производственном режиме. Прошивка намеренно исключает адрес из общего потока CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS — для изменения нужна отдельная последовательность с взводом магическим кодом.
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);
Проводной протокол под капотом:
-
prepare: проверьте диапазонnew_addr(0x08..0x77, ≠ текущий) → запишитеnew_addrвREG_I2C_ADDRESS(0x30) — значение попадает в RAM. -
prepare: запишите0xA5вREG_ADDR_COMMIT_MAGIC(0x31) — это «взводит» фиксацию. Окно взведённого состояния — 5 секунд. -
commit: проверить свежесть взвода → отправитьCMD_COMMIT_ADDR(код операции 0x30) → записать во flash →CMD_RESET -
~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
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
esp_err_t rbamp_reset(rbamp_handle_t dev);
Команда CMD_RESET (0x01) + ожидание 100 мс. Мягкий перезапуск устройства без потери параметров из flash.
Шина с несколькими модулями
rbamp_broadcast_latch
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/.
Идентификация и обнаружение
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 отдаёт энергию за период
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.
Блоки реального времени
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 из банка снимков.
Состояние
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 сопровождает большинство внутренних сбросов, поэтому судите по другим битам.
Конфигурация
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).
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, измеренным мастером с предыдущего снимка.
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 (самая новая) до меток времени, которые у вас уже есть.
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_* (сброс / принятие счётчика срока службы, сохранение калибровки, фиксация прошивки, очистка истории и т. д.). |
Подлинность
Провизионированный модуль несёт сертификат устройства, подписанный производительским ключом, и отвечает на запрос подписью ключом устройства, названным в этом сертификате. Библиотека получает оба; проверка их — задача приложения (с библиотекой подписи на ваш выбор).
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
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).
Типичное использование:
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
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). Предназначено для тестовых сценариев, которым нужна чистая база. Для промышленного мониторинга предпочтителен канонический шаблон «скорость за интервал» — снимок + разность, устойчивая к пропущенным окнам сброса:
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", ...) работает, но сверху ограничен уровнем, заданным при сборке.
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 для типичного производственного сценария:
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)
Для стендового теста под сильной нагрузкой:
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 подряд идущих байт, начиная с addr. Пример: одна транзакция i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) читает 16 байт, начиная с 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK на UI1).
Запись регистров — побайтно (БЕЗ автоинкремента)
приземляетсятолько первый байт— байты 1..N отбрасываются.
Многобайтовый регистр записывается байт за байтом — отдельная однобайтовая I²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):
/* 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:
addr=0x00 | A5 27
A5— магическое значение.27— опкодCMD_LATCH_PERIOD.—0x00= всем (all-call), иначе должен совпадать сREG_GROUP_ID(0x28).— 16-битный счётчик периода (синхронизация мастера).
Кадр только запускает снимок периода; он никогда не несёт деструктивных кодов операций.
Обнаружение режима отказа (двухуровневое, аппаратно подтверждено C.10):
- NACK по общему адресу (немедленно, на уровне шины): если GC отключён на всём парке —
i2c_master_transmitна0x00возвращаетESP_FAIL/ESP_ERR_INVALID_STATE. Это жёсткая ошибка, а не тихий сброс. Библиотека трактует NACK как «GC не включён» (требуются предусловия включения и сброса). - Контрольная проверка по модулю (после выдержки): если NACK не было — мастер читает
REG_V03_PERIOD_VALID (0x07)на каждом ожидаемом подчинённом:1= снимок успешен,0= GC выключен на этом модуле или период пуст.
Ссылки
- 05 · Быстрый старт — ваш первый рабочий проект
- 06 · Примеры — рабочие сценарии
-
10 · Устранение неполадок — расшифровка ошибок и решение типичных проблем
-
Исходный заголовочный файл с комментариями Doxygen:
include/rbamp.h
Приложение — Под капотом
Перенесено из главы «Обзор»: сравнение на уровне регистров, архитектура и схемы взаимодействия.
Без компонента (прямой доступ через i2c_master_transmit_receive)
// 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));
С компонентом
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));
Чтение периода — без компонента
// 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;
Чтение периода — с компонентом
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_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)