06 · Примеры
Эта глава открывается флагманскими сценариями — реальными шаблонами развёртывания, для которых создавалась библиотека (сеть + N поднагрузок на одной шине, снимки с синхронизацией GC). За ними идут сценарии с одним модулем — от минимального «hello world» до журнала на батарее с глубоким сном.
Большинство сценариев поставляются как готовый к сборке проект IDF в examples/, который можно собрать командой idf.py -C examples/. Код в этой главе — выжимка ключевой логики, а не полный проект (bus_cfg / запуск WiFi / Kconfig опущены для краткости).
| # | Сценарий | Сложность | Источник |
|---|---|---|---|
| 1 | Сеть + N подгрузок — канон 80 % | средний | examples/fleet_sync/ |
| 2 | Процесс развёртывания (новый → парк) | низкий | (composition) |
| 3 | Смешанный CT на нескольких каналах (I3, разные модели) | средний | (composition) |
| 4 | Синхронизация GC парка — синхронность тарифных периодов | средний | examples/fleet_sync/ |
| 5 | Быстрое чтение (один модуль) | минимальный | examples/quick_read/ |
| 6 | Счётчик Wh на LCD 16×2 | низкий | examples/lcd_period/ |
| 7 | Контроль 3 модулей (устаревшая последовательная схема) | низкий | examples/multi_module/ |
| 8 | MQTT для каждого канала | средний | examples/mqtt_publisher/ |
| 9 | Двунаправленный учёт на стороне мастера | средний | (composition) |
| 10 | Баланс энергии всего дома (3 модуля) | высокий | (composition) |
| 11 | Журналирование по событиям (EMA) | средний | (composition) |
| 12 | Локальный CSV-журнал на SPIFFS | средний | examples/spiffs_logger/ |
| 13 | Батарейный регистратор с глубоким сном | средний | examples/deep_sleep_logger/ |
| 14 | I3 с разными CT на каждом канале (разбор смешанной нагрузки) | средний | (composition) |
| 15 | Субучёт: 5×UI1 на общей шине | высокий | (composition) |
| 16 | Широковещательный снимок GC для более чем 8 модулей | высокий | (composition) |
| 17 | Фильтрация по группам GC (учёт для нескольких арендаторов) | высокий | (composition) |
| 18 | Модуль STD: реактивная / полная мощность, THD, энергия по времени мастера | средний | examples/std_meter/ |
Сценарий 18 показывает линейку модулей STD. Сценарии 1–4 — флагманские, построены вокруг канонического развёртывания библиотеки. Их код использует fleet API и проверен на стенде (разнородный парк UI1+I2+I3). Сценарии 5–13 — одномодульные и компонующие шаблоны; 14–17 — расширенные сценарии для парка (углублённое рассмотрение возможностей из 1–4). Сценарий 7 — устаревший последовательный снимок по каждому модулю без fleet API, оставлен для сравнения и как путь миграции.
Все сценарии предполагают, что класс датчика и модель CT уже заданы через rbamp_set_sensor_class() + rbamp_set_ct_model() (см. 05 · Быстрый старт, шаг 3). Это делается один раз при установке — настройки хранятся во flash модуля и переживают сброс.
Дополнительный REQUIRES для main/CMakeLists.txt
Базовый компонент подтягивает esp_driver_i2c, esp_timer, log. Некоторым сценариям нужны дополнительные компоненты ESP-IDF — добавьте их в REQUIRES вашего main/:
| Сценарий | Дополнительные REQUIRES |
|---|---|
| 1 — Ввод + N субнагрузок (парк) | — (только rbamp) |
| 2 — Процесс ввода в эксплуатацию | — |
| 3 — многоканальный смешанный CT (I3) | — |
| 4 — синхронизация флота GC | — |
| 5 — Быстрое чтение | — |
| 6 — счётчик Wh на LCD | rbamp (драйвер LCD — отдельный компонент на ваш выбор) |
| 7 — несколько модулей (устаревшая последовательная схема) | — |
| 8 — MQTT по каждому каналу | rbamp mqtt esp_wifi esp_event esp_netif nvs_flash |
| 9 — Двунаправленный учёт | — |
| 10 — Баланс энергии | — |
| 11 — Журналирование по событиям | — |
| 12 — журнал на SPIFFS | rbamp spiffs |
| 13 — Регистратор в глубоком сне | rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (если публикуете) |
| 18 — счётчик STD | — (только rbamp) |
Сетевым компонентам также нужен nvs_flash_init() в app_main и подъём Wi-Fi. Для краткости всё это опущено во фрагментах ниже; полный проект всегда находится в examples/.
Важное примечание о фрагментах ниже. Каждый фрагмент — выжимка ключевой логики, а не полноценный app_main. В рабочем коде строке rbamp_handle_t dev всегда предшествует i2c_master_bus_config_t bus_cfg = {...}; i2c_new_master_bus(&bus_cfg, &bus); rbamp_new(bus, 0x50, &dev); rbamp_begin(dev); (для одного модуля) или rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (для парка). По окончании работы — rbamp_del(dev) / rbamp_fleet_destroy(fleet) (опущено там, где app_main входит в бесконечный цикл — дескриптор живёт, пока чип не перезагрузится).
Сценарий 1 — сеть + N поднагрузок (канон 80%): интегрированная система учёта
Цель: каноническое развёртывание библиотеки — согласованная система учёта на разнородном флоте, замкнутая в одном цикле:
-
Обнаружение —
rbamp_fleet_scanнаходит все модули, проверяет их идентичность и отсеивает конфликтующие адреса. -
Настройка —
rbamp_configure_channelsзадаёт класс датчика + модели CT по каналам + один завершающийSAVE_USER_CONFIGодним вызовом на модуль с несколькими каналами. -
Взвод GC —
rbamp_fleet_enable_gc_allвключает приём снимков General-Call на каждом модуле флота. -
Цикл — на каждом тике мастер выполняет атомарный
_gclatch(синхронный снимок по всему флоту), сверяет_check_sync, читает_poll_all, интегрирует энергию поmaster_dtи вычисляет_total_power+_total_energy_wh.
Это главный пример главы — он показывает всю библиотеку в работе в каноничной конфигурации. Каждый другой сценарий (2–17) разбивает этот ход на отдельные блоки или дополняет его сторонними интеграциями (LCD, MQTT, SD).
Аппаратная часть (проверено на оборудовании): разнородный флот из 3 модулей на одной шине с внешней подтяжкой 4.7 кОм на SDA/SCL (см. 04 · Подключение, раздел «Шина нескольких модулей — основная топология»):
@0x50— UI1, счётчик сети на вводе (один токовый канал + напряжение).@0x51— I2, двухканальный токовый субсчётчик (без напряжения).@0x52— I3, трёхканальный токовый субсчётчик (без напряжения).
Опорная нагрузка на линии — ~0.57 А.
Код — интегрирующий цикл
#include "rbamp.h"
#include "rbamp_fleet.h"
#include "esp_timer.h"
static const char *TAG = "metering";
/* The per-module Wh accumulator lives in the handle (the component
* already integrates by master_dt in rbamp_read_period_snapshot —
* here we only read it). */
static void configure_one(rbamp_handle_t dev) {
if (!dev) return;
uint8_t n = rbamp_channels(dev);
if (n == 1) { /* UI1 mains */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
} else if (n == 2) { /* I2 sub-meter */
const uint8_t models[2] = { 1, 3 }; /* 5A, 30A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 2);
} else if (n == 3) { /* I3 sub-meter */
const uint8_t models[3] = { 1, 3, 6 }; /* 5A, 30A, 20A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 3);
}
}
void app_main(void) {
/* 1) bus + fleet_create — omitted for brevity */
rbamp_fleet_t fleet;
ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));
/* 2) discover */
size_t n_added = 0;
if (rbamp_fleet_scan(fleet, true, &n_added) == ESP_ERR_INVALID_STATE) {
ESP_LOGE(TAG, "bus wedged — see ch.10");
return;
}
ESP_LOGI(TAG, "fleet_scan: %u module(s), %u excluded",
(unsigned)n_added,
(unsigned)rbamp_fleet_excluded_count(fleet));
/* 3) configure per-module (mixed-CT on the sub-meters) */
for (size_t i = 0; i < rbamp_fleet_count(fleet); ++i) {
configure_one(rbamp_fleet_get(fleet, i));
}
/* 4) arm GC across the whole fleet */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "enable_gc_all → %u/%u modules armed",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
/* 5) loop: gclatch → check_sync → poll_all → energy + totals */
rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
while (1) {
rbamp_fleet_gclatch(fleet, /*group=*/0, tick, /*settle_ms=*/50);
size_t n_missed = SIZE_MAX;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_ok = 0;
rbamp_fleet_poll_all(fleet, snaps, status,
RBAMP_FLEET_MAX_MODULES, &n_ok);
/* Energy is accumulated per-handle by the component on each
* period-snapshot read. Here we read the fleet-wide aggregates. */
float p_total = 0.0f;
double e_total = 0.0;
rbamp_fleet_total_power(fleet, &p_total);
rbamp_fleet_total_energy_wh(fleet, &e_total);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "ITER %3u: GC %u/%u in_sync | poll n_ok=%u/%u | "
"P_total=%.1f W E_total=%.3f Wh",
(unsigned)tick,
(unsigned)(n_total - n_missed), (unsigned)n_total,
(unsigned)n_ok, (unsigned)n_total,
p_total, e_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(1000)); /* 1 Hz for a compact summary */
}
}
Вывод на стенде (проверено на оборудовании на всём флоте)
INTEGRATED METERING SYSTEM — fleet_scan: 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (mains meter: voltage + 1 current)
module[1] @0x51 channels=2 voltage=no (2-channel current sub-meter)
module[2] @0x52 channels=3 voltage=no (3-channel current sub-meter)
configure_channels(2ch) → mirrors [1 2 -]
configure_channels(3ch) → mirrors [1 2 3]
enable_gc_all → 3/3 modules armed
ITER 1..N: GC in_sync=3/3 skew=0 | poll n_ok=3/3 | P_total≈1260 W | E_total: 2.49 → 4.38 Wh (accumulating)
@0x50 V=226 I=[5.58] P=[1256] (mains)
@0x51 V= — I=[11.30, 3.75] P=[—] (current sub-meter)
@0x52 V= — I=[ 3.73, 1.87, 7.50] P=[—] (current sub-meter; the 3rd input
is unused on this rig,
pickup ≈ zero)
Стендовые цифры иллюстрируют форму данных и их путь по системе — не точность измерений.
Заметки по развёртыванию
-
Один синхронизированный цикл — это вся система. На каждом тике: один
gclatch(одна транзакция I²C General-Call) → все модули атомарно начинают снимок периода (check_sync= 3/3, перекос = 0) → одинpoll_allчитает весь флот → агрегация. Дрейфа между модулями из цепочки последовательных обменов нет. -
Поведение
total_powerво разнородном флоте. UI1 даёт активную мощность (у него есть напряжение → естьP); I2/I3 — только ток, поэтому их вклад вtotal_powerравен нулю. Поэтому в канонеtotal_power≈ мощность модуля сети. Для мощности по каждой нагрузке на субсчётчике вычисляйте её на стороне мастера:P_subload[k] ≈ V_mains × I_sub[k](приближение, верное при близких PF; токовый субсчётчик не может дать точную мощность по каждой нагрузке). -
Энергия (Wh) — мастер-часы реального времени.
E_totalмонотонно растёт (от 2.55 до 6.94 Wh за окно записи на стенде); компонент интегрирует каждый период поmaster_dt_ms(esp_timer), а не поlatch_msсо стороны чипа (диагностический таймер модуля, который может показывать меньше). Ложный тик добавляет0 Wh, если между опросами не прошёл новый период, — это нормально (snap.valid = 0 в этом цикле). -
Опрос, устойчивый к пропускам. Если один из модулей выпадает с шины (отключение, перезагрузка),
poll_allпомечает егоstatus[i] != ESP_OKи продолжает опрашивать остальные — мастер не зависает. Проверено на стенде: модуль, отключившийся в середине работы, оставил парк опрашивающимся сn_ok=2/3без остановки. То же относится кcheck_sync—missed_idxуказывает на первый рассинхронизированный модуль, а остальные продолжают снимать снимки. -
Аналитика баланса. В каноне 80%:
balance = P_mains − Σ(V_mains × I_sub[k])— оценка «остального» (фоновое потребление, неучтённые нагрузки). Целевой код перебирает флот, отделяя дескриптор сети (тот, у которогоhas_voltage = true) от поддескрипторов (все остальные). -
Токи по каналам → разложение нагрузки. Через
fleet_poll_allмастер видит сразу все токовые каналы (1+2+3 = 6 на нашем стенде), без отдельных считывателей для каждого модуля. -
Смешанный CT на 3-канальном модуле. Используйте текущий релиз библиотеки; зеркала [1 2 3] на I3 устанавливаются так, как настроено. Порядок привязки каналов не имеет значения.
-
Задержка опроса для расчёта парка (измерено на аппаратуре). На стенде при I²C 50 кГц: 2 модуля — в среднем
89.4 мс(мин. 89.4 / макс. 89.6); 3 модуля — в среднем112.1 мс(мин. 112.1 / макс. 112.3). Это ≈ 22–23 мс на каждый дополнительный модуль, линейно и с очень малым джиттером (мин ≈ макс). Один пакетныйfleet_poll_allдетерминирован на чистой шине. Парк из 3 модулей (~112 мс) укладывается в интервал опроса 200 мс — то есть частота опроса 5 Гц достижима (каждое второе окно модуля по 100 мс) без насыщения шины. Полный бюджет шины (когда парк превышает интервал опроса) — в таблице в 04 · Проводка, раздел «Бюджет энергии шины».
Сценарий 2 — процесс провизионинга (чистый модуль → флот)
Цель: перевести новый модуль с заводского адреса 0x50 на рабочий адрес и добавить его в существующий флот с сохранением конфигурации (модели CT, метка) во flash.
Аппаратная часть (проверено на оборудовании): чистый модуль на заводском 0x50 (HW_VARIANT 3-канальный). Провизионинг переводит его на адрес 0x52 и сохраняет конфигурацию во flash.
#include "rbamp_fleet.h"
#include "rbamp.h"
void provision_new_module(i2c_master_bus_handle_t bus,
rbamp_fleet_t fleet,
uint8_t desired_addr,
const char *label /* nullable */) {
/* PRECONDITION: exactly one virgin at 0x50 on the bus.
* MUST one-virgin-at-a-time — see ch.04 + ch.10. */
rbamp_handle_t dev = NULL;
esp_err_t err = rbamp_provision(bus, desired_addr,
/*save_config=*/true, &dev);
if (err == ESP_ERR_NOT_FOUND) {
ESP_LOGE("prov", "nobody answers at 0x50 — check VCC/I2C");
return;
}
if (err == ESP_ERR_INVALID_STATE) {
ESP_LOGE("prov", "0x50 or 0x%02X is already taken — "
"discipline violation? see ch.10",
desired_addr);
return;
}
if (err != ESP_OK) {
ESP_LOGE("prov", "provision fail: %s", esp_err_to_name(err));
return;
}
ESP_LOGI("prov", "provisioned virgin → 0x%02X (+saved)", desired_addr);
/* Label for fleet iterations (optional). */
if (label) rbamp_write_label(dev, label);
/* Bind the sensor class + CT model + one more SAVE_USER_CONFIG. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
/* Add to the fleet — from here the module is polled the usual way. */
rbamp_fleet_add(fleet, dev);
ESP_LOGI("prov", "module @0x%02X added to the fleet", desired_addr);
}
Вывод стенда (проверенный на оборудовании путь успеха):
before: present(0x50)=yes present(0x52)=no
virgin @0x50: variant=3-channel, channels=3
rbamp_provision(→0x52, save_config=true) = ESP_OK
(lib log: "provisioned virgin → 0x52 (+saved)")
post: handle now answers @0x52, is_provisioned=true
after: present(0x50)=no present(0x52)=yes
is_provisioned возвращает true после успешного вызова. У модуля, только что с завода (к которому ещё ничего не прикасались), предыдущий is_provisioned будет false — это обычное состояние 0xFB (ERR_FLASH_PARAMS_BAD), описанное в 10 · Устранение неполадок, и оно не фатально.
Пути отказа
| Ошибка | Условие | Восстановление |
|---|---|---|
ESP_ERR_NOT_FOUND |
По адресу 0x50 никто не отвечает |
Проверьте, что новый модуль физически подключён и запитан (VCC); сканирование шины (10 · Устранение неполадок). |
ESP_ERR_INVALID_STATE |
Обнаружен конфликт по 0x50 или desired_addr; разные модули отвечают одинаково |
Нарушение дисциплины — на шине больше одного чистого модуля. Выключите питание + физически отключите все, кроме одного, и повторите (см. путь восстановления в 10 · Устранение неполадок). |
ESP_ERR_TIMEOUT |
Двухфазная фиксация прошла, но модуль не появился по новому адресу в пределах окна загрузки | Выключите и включите питание модуля и повторите. Если сохраняется — проблема циклов записи flash. |
ESP_ERR_INVALID_ARG |
desired_addr вне 0x08..0x77 |
Используйте допустимый 7-битный адрес. |
Подробный обзор режимов отказа: 10 · Устранение неполадок, раздел «Флот: rbamp_provision вернул ошибку».
Сценарий 3 — многоканальный смешанный CT (I3, разные модели по каналам)
Цель: показать rbamp_configure_channels на I3 — три канала с разными моделями CT (например, ch0=SCT-013-005 для малой нагрузки, ch1=SCT-013-030 для средней, ch2=SCT-013-020 для большой) одним терминальным циклом flash (щадящим для flash) и подтвердить сохранность после перезагрузки.
#include "rbamp.h"
#include "esp_timer.h"
void configure_mixed_ct(rbamp_handle_t dev_i3) {
/* (a) Configure — three CT models in a single call. */
const uint8_t models[3] = { 1, 3, 6 };
/* 1=SCT-013-005 (5A), 3=SCT-013-030 (30A), 6=SCT-013-020 (20A) */
int64_t t0 = esp_timer_get_time();
esp_err_t err = rbamp_configure_channels(
dev_i3, RBAMP_SENSOR_SCT013, models, 3);
int64_t t1 = esp_timer_get_time();
if (err != ESP_OK) {
uint8_t reg_err;
rbamp_read_last_error(dev_i3, ®_err);
ESP_LOGE("3", "configure rejected: %s, REG_ERROR=0x%02X",
esp_err_to_name(err), reg_err);
return;
}
ESP_LOGI("3", "configure_channels latency = %lld ms",
(long long)((t1 - t0) / 1000));
/* (b) Verify the mirror via registers 0x51 / 0x52 / 0x53 (RAM). */
uint8_t m0, m1, m2;
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "applied: [%u %u %u] (expected [1 3 6])", m0, m1, m2);
/* (c) Persist verify — reset + re-read the mirror after boot. */
rbamp_reset(dev_i3);
vTaskDelay(pdMS_TO_TICKS(300)); /* boot window */
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "after reboot: [%u %u %u]", m0, m1, m2);
}
Вывод на стенде (проверено на оборудовании, I3 с чистой перепрошивкой):
configure_channels(SCT013, {1, 3, 6}, 3) = ESP_OK
configure_channels latency = 1403 ms
applied: [1 3 6] (raw 0x01 0x03 0x06)
after reboot: [1 3 6] (persisted through CMD_RESET + boot)
Свойство «одного SAVE» — почему это важно
configure_channels выполняет одно терминальное CMD_SAVE_USER_CONFIG в конце. Альтернатива — отдельные вызовы set_ct_model_ch для каждого канала, каждый с собственным save_user_config после — даёт три цикла стирания и записи flash.
Сравнение задержек на стенде (на одном I3):
| Подход | Задержка | Циклы записи во flash |
|---|---|---|
configure_channels(...) — 1 терминальное СОХРАНЕНИЕ |
~1403 мс | 1 |
3× (set_ct_model_ch + save_user_config) |
~3492 мс | 3 |
В 3 раза медленнее — это (~2.5×) × ~700 мс. Ключевое: разница в 3 раза по циклам износа на одной и той же странице флеша: при типичной перенастройке модулей в полевых условиях это превращается в ощутимый износ. Всегда используйте configure_channels, когда нужно задать класс датчика и модели CT по каналам.
Для семейства SCT-013: 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. Код вне {1, 2, 3, 4, 5, 6, 7} даёт ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).
Сценарий 4 — синхронизация флота GC (синхронность тарифных периодов)
Цель: показать атомарный снимок по всему флоту одним кадром I²C General-Call. В отличие от последовательной фиксации CMD_LATCH_PERIOD по модулям (где перекос накапливается на каждом круговом обмене), GC синхронизирует все модули в одной транзакции шины.
Аппаратура: тот же разнородный парк UI1+I2+I3 (@0x50/0x51/0x52).
#include "rbamp_fleet.h"
static const char *TAG = "gc_sync";
void app_main(void) {
/* bus init + fleet_create + fleet_scan ... as in Sc.1 */
/* Step 1: enable GC on all modules in the fleet. */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "GC armed: %u/%u",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
for (int round = 0; round < 10; ++round) {
/* Step 2: a single broadcast snapshot — all modules atomically. */
ESP_ERROR_CHECK(rbamp_fleet_gclatch(fleet, /*group=*/0, tick,
/*settle_ms=*/50));
/* Step 3: in-sync check — all modules caught the same tick. */
size_t n_missed = 0;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "round %d tick=%u in_sync=%u/%u",
round, tick,
(unsigned)(n_total - n_missed), (unsigned)n_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(100));
}
}
Вывод на стенде (10 циклов на флоте UI1+I2+I3, подтяжка 4.7 кОм):
rbamp_fleet_enable_gc_all() → 3/3 modules armed
round 0 tick=0 in_sync=3/3 skew=0
round 1 tick=1 in_sync=3/3 skew=0
round 2 tick=2 in_sync=3/3 skew=0
round 3 tick=3 in_sync=3/3 skew=0
round 4 tick=4 in_sync=3/3 skew=0
round 5 tick=5 in_sync=3/3 skew=0
round 6 tick=6 in_sync=3/3 skew=0
round 7 tick=7 in_sync=3/3 skew=0
round 8 tick=8 in_sync=3/3 skew=0
round 9 tick=9 in_sync=3/3 skew=0
Когда использовать синхронизацию GC:
-
Жёсткая синхронизация. Если разница снимков между модулями за минуту или за секунду важна для отчётности (например, расчёт баланса
сеть − Σ(субнагрузки), интегрированный во времени — рассогласование модулей вносит систематическую ошибку), GC обеспечиваетskew = 0по стендовому измерению. Последовательный снимок по каждому модулю на тех же 3 модулях накапливает 100–300 мкс на модуль × N, что становится заметным на 60-минутном окне в точном аналитическом учёте. -
Большой флот. По мере роста числа модулей разница между «последовательно N × round_trip» и «одним кадром GC» растёт линейно.
-
Согласование между развёртываниями. Если у вас несколько ESP32 на разных шинах с общими часами мастера, тик GC можно синхронизировать по настенным часам мастера — и тогда снимки с разных шин выравниваются в пределах одного окна сетевого обмена.
Свидетель через check_sync: проверка, что все модули действительно получили кадр GC. Он может пропустить модуль, если тот был занят загрузкой / циклом SAVE в момент кадра — missed_idx указывает на первый рассинхронизированный. При проверке на стенде — 10 раундов подряд, 0 пропусков.
Предусловие. GC должен быть включён на каждом модуле (rbamp_fleet_enable_gc_all или для каждого устройства rbamp_enable_gc + SAVE_USER_CONFIG + сброс). Новый модуль с заводскими значениями не принимает GC — так задумано, как защита от случайных широковещательных сообщений на шине при вводе в работу.
Сценарий 5 — Быстрое чтение (один модуль)
Цель: печатать U / I / P / PF / частоту в журнал ESP-IDF раз в секунду. Тот же «hello world», что вы писали в 05 · Быстрый старт, но через rbamp_read_all() — однократное чтение всего блока RT в одну структуру.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "quick_read";
void app_main(void) {
/* ...bus_cfg setup, rbamp_new + rbamp_begin as in the Quickstart... */
rbamp_handle_t dev = NULL;
while (1) {
rbamp_snapshot_t s;
if (rbamp_read_all(dev, &s) != ESP_OK) {
ESP_LOGE(TAG, "read fail");
vTaskDelay(pdMS_TO_TICKS(1000));
continue;
}
ESP_LOGI(TAG, "U=%.1f V f=%.1f Hz channels=%u",
(double)s.voltage, (double)s.frequency, s.channels);
for (uint8_t ch = 0; ch < s.channels; ++ch) {
ESP_LOGI(TAG, " I%u=%.2f A P%u=%.1f W PF%u=%.2f",
ch, (double)s.current[ch],
ch, (double)s.power[ch],
ch, (double)s.power_factor[ch]);
}
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Что происходит на шине: rbamp_read_all() на UI3 выполняет ~53 однобайтовые транзакции (13 значений float × 4 байта + 1 байт частоты). При 50 кГц с запасом на повторы — порядка 25–30 мс. Если вам нужны не все значения, вызывайте функции по свойствам (rbamp_read_voltage(), rbamp_read_current(ch)) — меньше байтов на шине.
Сценарий 6 — счётчик Wh на 16×2 LCD
Цель: счётчик Wh, обновляемый раз в минуту, на символьном LCD 16×2 с расширителем I²C PCF8574 (совместим с HD44780). LCD стоит на той же шине I²C, что и rbAmp. Ключевой механизм компонента — rbamp_read_period_snapshot(), который инкапсулирует снимок + выдержку + проверку валидности + чтение + такт Wh в одном вызове.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
/* Minimal LCD shim — inline in the example, no third-party drivers.
* The full lcd_print/lcd_clear functions are in examples/lcd_period/main/main.c. */
void app_main(void) {
/* ...bus_cfg + rbamp + lcd init... */
rbamp_handle_t dev = NULL;
uint32_t ok_count = 0, bad_count = 0;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK
|| !snap.valid) {
bad_count++;
continue;
}
ok_count++;
char line1[17], line2[17];
snprintf(line1, sizeof(line1), "P=%6.1f W ", (double)snap.avg_p[0]);
snprintf(line2, sizeof(line2), "%8.4f Wh ok%lu", rbamp_energy_wh(dev, 0),
(unsigned long)ok_count);
lcd_clear();
lcd_print(0, 0, line1);
lcd_print(0, 1, line2);
}
}
Полный проект IDF — examples/lcd_period/.
Обработка устаревших снимков. rbamp_read_period_snapshot() возвращает ESP_ERR_INVALID_RESPONSE, если модуль не успел подготовить новый снимок к моменту чтения. Компонент всё равно записывает свою временную метку (esp_timer_get_time()) внутренне — поэтому следующий успешный снимок не удваивается в интервале.
Сценарий 7 — Мониторинг 3 модулей (устаревший последовательный режим) на одной шине
Цель: опросить 3 модуля по адресам 0x50 / 0x51 / 0x52 с одного мастера. Каждый модуль должен иметь уникальный адрес (адреса назначаются при заводской установке или монтаже — см. 09 · Справочник API о методах смены адреса с примечаниями ПРЕДУПРЕЖДЕНИЕ).
Канонический шаблон для прошивки v1 — последовательный rbamp_latch_period() на каждом устройстве + один общий 50-мс отстой + rbamp_read_period_snapshot(skip_latch=true) по каждому устройству. Расхождение между устройствами при 100 кГц: ~1 мс на устройство — пренебрежимо мало на фоне 60-секундного периода.
На прошивке v1.3 (REG_VERSION = 0x04) rbamp_broadcast_latch() полностью поддерживается, как только GC включён на всём флоте через rbamp_fleet_enable_gc_all() — это канонический путь синхронизации флота для жёсткой синхронности между субсчётчиками (см. раздел флота GC Strategy 2 ранее в этой главе). На устаревшей прошивке v1.0–v1.2 (без поддержки снимков General-Call) вызов возвращает ESP_ERR_NOT_SUPPORTED, и библиотека переходит к снимку по устройствам, показанному выше. См. 09 · Справочник API.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
#define N_MODULES 3
static const char *TAG = "multi_module";
static const uint8_t ADDRS[N_MODULES] = { 0x50, 0x51, 0x52 };
void app_main(void) {
/* ...bus_cfg setup as in the Quickstart... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t modules[N_MODULES] = { NULL };
/* Create a handle for each module */
for (int i = 0; i < N_MODULES; ++i) {
if (rbamp_new(bus, ADDRS[i], &modules[i]) != ESP_OK ||
rbamp_begin(modules[i]) != ESP_OK) {
ESP_LOGE(TAG, "module 0x%02X init failed", ADDRS[i]);
modules[i] = NULL;
}
}
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Phase 1: sequential snapshot on each device, measure the skew */
const int64_t sync_start_us = esp_timer_get_time();
for (int i = 0; i < N_MODULES; ++i) {
if (modules[i]) rbamp_latch_period(modules[i]);
}
const uint32_t sync_us = (uint32_t)(esp_timer_get_time() - sync_start_us);
/* Phase 2: a single shared settle for all 3 modules */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read the snapshots with skip_latch=true */
ESP_LOGI(TAG, "sync_us=%u", (unsigned)sync_us);
for (int i = 0; i < N_MODULES; ++i) {
if (!modules[i]) continue;
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(modules[i], &snap, 0,
/*skip_latch=*/true) != ESP_OK) {
continue;
}
ESP_LOGI(TAG, "mod%d 0x%02X P=%.0f W Wh=%.3f",
i, ADDRS[i],
(double)snap.avg_p[0],
rbamp_energy_wh(modules[i], 0));
}
}
}
Полный проект (с зондированием шины и отчётом об ошибках) — examples/multi_module/.
Сценарий 8 — MQTT по каналам
Цель: модуль UI3 с 3 клещами CT на трёх независимых линиях. Счётчики Wh по каждому каналу, публикуются в MQTT раз в минуту. Показывает, что rbamp_energy_wh(dev, ch) работает по каждому каналу независимо — не нужен ручной массив total_wh[3] на стороне мастера.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static const char *TAG = "ui3_mqtt";
static const char *CH_NAMES[3] = { "main", "heatpump", "lights" };
static esp_mqtt_client_handle_t mqtt;
static void publish_channel(const char *name, float avg_p, double e_wh) {
char topic[64], payload[96];
snprintf(topic, sizeof(topic), "rbamp/%s/state", name);
snprintf(payload, sizeof(payload),
"{\"power\":%.1f,\"energy\":%.4f}", (double)avg_p, e_wh);
esp_mqtt_client_publish(mqtt, topic, payload, 0, /*qos*/1, /*retain*/1);
}
void app_main(void) {
/* ...wifi STA + mqtt_client init... */
/* ...bus_cfg + rbamp_new + rbamp_begin (50 kHz via Kconfig)... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) {
continue;
}
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
publish_channel(CH_NAMES[ch], snap.avg_p[ch],
rbamp_energy_wh(dev, ch));
}
}
}
Полный проект — examples/mqtt_publisher/. Об автообнаружении MQTT в HA на основе этого шаблона — см. 07 · Самостоятельные интеграции + examples/ha_discovery/.
Сценарий 9 — Двунаправленный учёт на стороне мастера
Цель: разделить знаковую мгновенную мощность на валовое потребление и валовый экспорт. Используйте этот шаблон на линейке BASIC, где прошивка обрезает отрицательные значения в snap.avg_p[ch] (средняя за период мощность) — опрашивайте rbamp_read_power(dev, 0, &p) (мгновенная мощность, знаковая на всех линейках) с частотой 10 Гц на стороне мастера и раскладывайте по корзинам самостоятельно.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "bidir";
void bidir_task(void *arg) {
rbamp_handle_t dev = arg;
double consume_wh = 0.0, export_wh = 0.0;
int64_t t_prev_us = esp_timer_get_time();
while (1) {
vTaskDelay(pdMS_TO_TICKS(100)); /* 10 Hz, matches the RT cadence */
const int64_t t_now_us = esp_timer_get_time();
const double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
const double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
/* Print once a second */
static int n = 0;
if (++n % 5 == 0) {
ESP_LOGI(TAG, "P=%.1f W cons=%.4f Wh exp=%.4f Wh net=%.4f Wh",
(double)p, consume_wh, export_wh,
consume_wh - export_wh);
}
}
}
Это составной сценарий без отдельного проекта IDF. На модуле STD счётчики энергии знаковые, и rbamp_energy_wh(dev, 0) возвращает чистый баланс (импорт и экспорт хранятся раздельно в rbamp_std_read_energy()) — такое разделение на стороне мастера нужно только на модулях BASIC либо для раздельной отчётности валового потребления и валового экспорта по мгновенной мощности.
Сценарий 10 — Баланс энергии всего дома
Цель: 3 модуля — сеть (двунаправленный), солнечная генерация (только выработка), нагрузки (UI3 для учёта по приборам). Сводная панель публикуется раз в минуту.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static rbamp_handle_t mains_dev, solar_dev, loads_dev;
static esp_mqtt_client_handle_t mqtt;
void app_main(void) {
/* ...wifi STA + mqtt init... */
/* ...bus_cfg + per-module rbamp_new(bus, 0x50/0x51/0x52, ...) +
* rbamp_begin() on each... */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Sequential snapshot + shared settle (the pattern from Scenario 3) */
rbamp_latch_period(mains_dev);
rbamp_latch_period(solar_dev);
rbamp_latch_period(loads_dev);
vTaskDelay(pdMS_TO_TICKS(50));
rbamp_period_snapshot_t sm, ss, sl;
if (rbamp_read_period_snapshot(mains_dev, &sm, 0, true) != ESP_OK || !sm.valid ||
rbamp_read_period_snapshot(solar_dev, &ss, 0, true) != ESP_OK || !ss.valid ||
rbamp_read_period_snapshot(loads_dev, &sl, 0, true) != ESP_OK || !sl.valid) {
continue;
}
char payload[256];
snprintf(payload, sizeof(payload),
"{\"mains\":%.3f,\"solar\":%.3f,"
"\"hp\":%.3f,\"ac\":%.3f,\"ev\":%.3f}",
rbamp_energy_wh(mains_dev, 0),
rbamp_energy_wh(solar_dev, 0),
rbamp_energy_wh(loads_dev, 0),
rbamp_energy_wh(loads_dev, 1),
rbamp_energy_wh(loads_dev, 2));
esp_mqtt_client_publish(mqtt, "home/energy/balance",
payload, 0, 1, 1);
}
}
Для явного разделения валового потребления и валового экспорта на вводе — объедините с шаблоном из Сценария 5 (отдельная задача 10 Гц на rbamp_read_power(mains_dev, 0, ...)).
Это составной сценарий без отдельного проекта IDF — соберите его из examples/mqtt_publisher/ + examples/multi_module/.
Сценарий 11 — Журналирование по событиям (EMA)
Цель: на каждом окне RT 100 мс сравнивать мгновенную мощность со скользящим средним по экспоненте. Записывать значимые отклонения — нагрузки вроде микроволновки, чайника или фена «появляются» в журнале как событие включения / выключения.
#include /* fabsf */
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define EMA_ALPHA 0.05f
#define EVENT_THRESHOLD_W 200.0f
static const char *TAG = "event";
void event_task(void *arg) {
rbamp_handle_t dev = arg;
float p_ema = 0.0f;
/* seed the EMA so the first reading is not a false event */
if (rbamp_read_power(dev, 0, &p_ema) != ESP_OK) p_ema = 0.0f;
while (1) {
vTaskDelay(pdMS_TO_TICKS(200));
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
const float delta = p - p_ema;
p_ema = (1.0f - EMA_ALPHA) * p_ema + EMA_ALPHA * p;
if (fabsf(delta) > EVENT_THRESHOLD_W) {
ESP_LOGI(TAG, "%s delta=%.0f W P=%.0f W EMA=%.0f W",
(delta > 0) ? "TURN_ON" : "TURN_OFF",
(double)delta, (double)p, (double)p_ema);
}
}
}
Составной сценарий — отдельного проекта IDF нет. Объедините его с публикацией MQTT из сценария 4 для автоматизаций на стороне HA или запишите события в SPIFFS по шаблону сценария 8 для автономного журнала.
Сценарий 12 — Локальный CSV-регистратор на SPIFFS
Цель: раз в минуту записывать снимок периода в CSV-файл на SPIFFS. Полезно для автономных развёртываний без Wi-Fi / MQTT или как буфер для отложенной синхронизации с облаком.
Нужна собственная таблица разделов с записью storage,data,spiffs,,128K, в partitions.csv. Пример — в examples/spiffs_logger/partitions.csv.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_spiffs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define LOG_PATH "/storage/log.csv"
#define ROTATE_BYTES (64 * 1024)
static const char *TAG = "spiffs_logger";
static void rotate_if_full(void) {
struct stat st;
if (stat(LOG_PATH, &st) == 0 && st.st_size >= ROTATE_BYTES) {
rename(LOG_PATH, "/storage/log_prev.csv");
}
}
void app_main(void) {
esp_vfs_spiffs_conf_t spiffs_cfg = {
.base_path = "/storage",
.partition_label = "storage",
.max_files = 4,
.format_if_mount_failed = true,
};
ESP_ERROR_CHECK(esp_vfs_spiffs_register(&spiffs_cfg));
/* ...bus_cfg + rbamp_new + rbamp_begin... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
rotate_if_full();
FILE *f = fopen(LOG_PATH, "a");
if (!f) {
ESP_LOGE(TAG, "fopen failed");
continue;
}
fprintf(f, "%lld,%.3f,%.4f,%u\n",
(long long)(esp_timer_get_time() / 1000),
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
fclose(f);
}
}
Полный проект — examples/spiffs_logger/. Приведённый выше фрагмент — учебное упрощение со строкой CSV из 4 столбцов. Сам пример пишет строку CSV из 9 столбцов с avg_p по каждому каналу и Wh по всем 3 каналам — полезнее для промышленных сценариев на модулях UI3.
Для отложенной синхронизации с облаком (локальная запись, отправка раз в час) — см. раздел «Гибрид: локальное хранение + синхронизация» в 08 · Облачные интеграции.
Сценарий 13 — Батарейный регистратор с глубоким сном
Цель: ESP32 просыпается раз в 10 минут, делает один снимок периода, публикует через WiFi+MQTT и возвращается в глубокий сон. Энергия сохраняется между циклами сна через память RTC. Накопитель компонента отключён — сохранность Wh обеспечивает сам мастер.
⚠ Важное замечание о глубоком сне. В текущей прошивке rbamp_begin() всегда выдаёт праймер CMD_LATCH_PERIOD, который сбрасывает накопитель периода прошивки. Поэтому после пробуждения из глубокого сна нельзя просто вызвать rbamp_read_period_snapshot() по умолчанию — этот вызов снимет ещё один снимок и вернёт почти нулевые данные примерно через 50 мс после праймера. Правильный шаблон ниже использует skip_latch=true, чтобы прочитать данные, накопленные за время сна, и собственный таймер RTC мастера для интервала между пробуждениями (поле snap.master_dt_ms отражает только время внутри текущего цикла пробуждения, а не между пробуждениями).
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "esp_sleep.h"
#include "esp_timer.h"
#include "rbamp.h"
#define WAKE_INTERVAL_US (10ULL * 60ULL * 1000000ULL)
#define RTC_MAGIC 0xCAFEFEEDu
RTC_DATA_ATTR static uint32_t rtc_magic = 0;
RTC_DATA_ATTR static double rtc_total_wh = 0.0;
RTC_DATA_ATTR static bool rtc_primer_done = false;
RTC_DATA_ATTR static uint64_t rtc_last_wake_us = 0;
static const char *TAG = "deep_sleep";
void app_main(void) {
/* ...bus_cfg setup... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t dev = NULL;
if (rtc_magic != RTC_MAGIC) {
/* Cold start — initialize RTC-RAM */
rtc_magic = RTC_MAGIC;
rtc_total_wh = 0.0;
rtc_primer_done = false;
rtc_last_wake_us = 0;
}
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev));
ESP_ERROR_CHECK(rbamp_begin(dev)); /* issues the primer snapshot */
rbamp_energy_disable(dev); /* the master owns Wh itself */
if (!rtc_primer_done) {
/* First wake: the primer snapshot just captured the "dirty" data from
* before wake. Record the time and go straight back to sleep —
* the next wake in 10 min gets a full accumulator for the interval. */
rtc_last_wake_us = esp_timer_get_time();
rtc_primer_done = true;
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* skip_latch=true reads what the rbamp_begin() primer latched —
* that is, the accumulator for the elapsed 10-minute sleep interval. */
rbamp_period_snapshot_t snap;
esp_err_t snap_err = rbamp_read_period_snapshot(dev, &snap, /*settle_ms=*/0,
/*skip_latch=*/true);
if (snap_err != ESP_OK || !snap.valid) {
ESP_LOGW(TAG, "snapshot fail: %s (valid=%d)",
rbamp_err_to_str(snap_err), snap.valid);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* `snap.master_dt_ms` here is the time within the current wake (after
* the primer); for energy integration we use `esp_timer_get_time()`
* against `rtc_last_wake_us`. On ESP-IDF v5.x, the value returned by
* `esp_timer_get_time()` **survives deep sleep** — the timer is
* re-derived from the RTC slow-clock on wake. So the delta gives the
* real wake-to-wake interval in microseconds. */
const uint64_t now_us = esp_timer_get_time();
const double dt_s = (double)(now_us - rtc_last_wake_us) / 1e6;
rtc_last_wake_us = now_us;
rtc_total_wh += (double)snap.avg_p[0] * dt_s / 3600.0;
ESP_LOGI(TAG, "wake: P=%.1f W Wh=%.4f dt_s=%.1f",
(double)snap.avg_p[0], rtc_total_wh, dt_s);
publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
Полный проект (с настройкой WiFi, публикацией MQTT, защитой маркером RTC) — examples/deep_sleep_logger/.
rbamp_begin_resume() (компонент 1.7.0 и новее) — вариант инициализации без праймера CMD_LATCH_PERIOD, поэтому rbamp_read_period_snapshot() работает сразу после пробуждения из глубокого сна. Шаблон выше (skip_latch=true + RTC-таймер мастера) остаётся корректным на более старых версиях компонента.
Бюджет энергии (ESP32-WROOM, интервал пробуждения 10 минут):
- Длительность активного цикла: ~3 с (WiFi + MQTT + I²C)
- Активный ток: ~80 мА в среднем → ~0.07 мАч на одно пробуждение
- Ток покоя: ~10 µA (RTC + сохраняемые домены)
- ~10 мАч в сутки → литий-ионный на 2000 мАч работает ~6 месяцев
Сценарий 14 — I3 с разными CT по каналам (контроль смешанной нагрузки)
Цель: один модуль UI3 контролирует три независимые линии на одной фазе с разными уровнями нагрузки:
- Канал 0 — одна розетка (SCT-013-005, ≤5 А) — ТВ / роутер / дежурный режим.
- Канал 1 — линия кухни (SCT-013-030, ≤30 А) — чайник / микроволновка.
- Канал 2 — бойлер водонагревателя (SCT-013-020, ≤20 А) — пиковая нагрузка.
Все три канала питаются от одной фазы (в фазе с каналом U), поэтому P/PF/Q верны для всех трёх — см. предостережение об одном напряжении в 03 · Выбор токового датчика.
#include "driver/i2c_master.h"
#include "rbamp.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static const char *TAG = "ui3-mixed";
void mixed_load_task(void *arg) {
rbamp_handle_t dev = (rbamp_handle_t)arg;
/* Per-channel configuration — v1.3: order is arbitrary (pure staging) */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model_ch(dev, 2, 6); /* ch2: SCT-013-020 (boiler) */
rbamp_set_ct_model_ch(dev, 1, 3); /* ch1: SCT-013-030 (kitchen) */
rbamp_set_ct_model_ch(dev, 0, 1); /* ch0: SCT-013-005 (outlet) */
while (1) {
float u, i0, i1, i2, p0, p1, p2;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i0);
rbamp_read_current(dev, 1, &i1);
rbamp_read_current(dev, 2, &i2);
rbamp_read_power(dev, 0, &p0);
rbamp_read_power(dev, 1, &p1);
rbamp_read_power(dev, 2, &p2);
ESP_LOGI(TAG, "U=%.1f V", (double)u);
ESP_LOGI(TAG, " outlet: I=%.3f A P=%.1f W", (double)i0, (double)p0);
ESP_LOGI(TAG, " kitchen: I=%.2f A P=%.1f W", (double)i1, (double)p1);
ESP_LOGI(TAG, " boiler: I=%.2f A P=%.1f W", (double)i2, (double)p2);
ESP_LOGI(TAG, " total: P=%.1f W", (double)(p0 + p1 + p2));
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
Когда применять: контроль одной фазы с тремя группами нагрузок разной величины тока. Главное преимущество — разрешение: каждая клипса соответствует своему диапазону (SCT-013-005 даёт точные показания при нагрузке дежурного режима 50 Вт, а SCT-013-020 не насыщается на бойлере водонагревателя ~4 кВт).
Сценарий 15 — Субучёт: 5×UI1 на общей шине
Цель: контролировать 5 независимых линий в однофазной квартире с синхронностью тарифных периодов. По одному UI1 на линию (всего 5 модулей).
Это стратегия 1 синхронизации периодов из 04 · Подключение: последовательный снимок + общая выдержка.
#define N_METERS 5
static rbamp_handle_t meters[N_METERS]; /* initialized in app_main */
void sub_meter_task(void *arg) {
int64_t period_start_us = esp_timer_get_time();
const int64_t PERIOD_S = 60; /* 60-second metering period */
while (1) {
/* Wait until the end of the period */
int64_t now_us = esp_timer_get_time();
int64_t elapsed_s = (now_us - period_start_us) / 1000000;
if (elapsed_s < PERIOD_S) {
vTaskDelay(pdMS_TO_TICKS((PERIOD_S - elapsed_s) * 1000));
continue;
}
/* Phase 1: sequential snapshot (skew ~5 ms between modules at 50 kHz) */
for (int i = 0; i < N_METERS; i++) {
rbamp_latch_period(meters[i]);
}
/* Phase 2: shared settle */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read snapshots with skip_latch=true */
float total_wh_period = 0.0f;
for (int i = 0; i < N_METERS; i++) {
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(meters[i], &snap, 0, /*skip_latch=*/true) == ESP_OK
&& snap.valid) {
float wh_this_period = snap.avg_p[0] * snap.period_ms / 3600000.0f;
ESP_LOGI("meter", "[%d] avg_p=%.1f W Wh_period=%.2f",
i, (double)snap.avg_p[0], (double)wh_this_period);
total_wh_period += wh_this_period;
}
}
ESP_LOGI("meter", "TOTAL for the period: %.2f Wh\n", (double)total_wh_period);
period_start_us = esp_timer_get_time();
}
}
Анализ перекоса: 5 модулей × ~1 мс/снимок = ~5 мс. Относительно периода 60 с — 0.008%. Пренебрежимо мало.
Бюджет шины: 5 модулей × ~5 мс блок RT = 25 мс на полный круг; это укладывается и в частоту опроса 5 Гц (25 мс ≪ 100 мс). Запас шины комфортный примерно до ~15 модулей UI1.
Сценарий 16 — широковещательный снимок GC (жёсткая синхронизация для >8 модулей)
Цель: при ≥ 8 модулях перекос стратегии 1 (последовательной) приближается к ~10 мс. Для синхронности тарифных периодов — стратегия 2, широковещательный General-Call.
Предварительная конфигурация (один раз на модуль):
/* Enable GC reception on each module: the call writes FLEET_CONFIG.bit0,
saves the configuration and restarts the module (~1 s) */
rbamp_enable_gc(dev, true);
Широковещательный снимок во время работы с контрольной проверкой:
#define N_METERS 12
esp_err_t synced_snapshot(i2c_master_bus_handle_t bus,
rbamp_handle_t meters[], int n,
uint16_t tick_counter) {
/* All-call broadcast snapshot (group 0x00): the library builds the
General-Call frame and sends it to address 0x00 on the bus */
esp_err_t err = rbamp_broadcast_latch_group(bus, 0x00, tick_counter, 100);
if (err != ESP_OK) return err;
/* Settle: snapshot + 1 commit-cycle for witness refresh */
vTaskDelay(pdMS_TO_TICKS(50));
/* Witness check: each module echoes the tick of the last GC frame it accepted */
int n_ok = 0;
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) == ESP_OK && tick == tick_counter) {
n_ok++;
} else {
ESP_LOGW("gc-snapshot", "module %d did not take its snapshot (witness mismatch)", i);
}
}
if (n_ok < n) {
ESP_LOGW("gc-snapshot", "fallback to sequential snapshot for %d modules",
n - n_ok);
/* Strategy 1 fallback on the remaining ones */
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) != ESP_OK || tick != tick_counter) {
rbamp_latch_period(meters[i]);
}
}
vTaskDelay(pdMS_TO_TICKS(50));
}
return ESP_OK;
}
Анализ перекоса: кадр GC — ~1 мс при 50 кГц → все 12 модулей делают снимок одновременно на уровне шины. Перекос практически 0.
Когда использовать: ≥ 8 модулей и/или жёсткая синхронизация.
Когда НЕ использовать: на смешанной шине с устройствами не rbAmp (GC может конфликтовать).
Сценарий 17 — фильтрация групп GC (учёт для нескольких арендаторов)
Цель: 10 модулей на одной шине, где нужно независимо снимать снимки с подмножеств. Например, 5 модулей ведут учёт тарифа А (дневной), 5 — тарифа Б (ночного); их взводят и читают по разным расписаниям.
Настройка (один раз):
/* Tariff A — modules 0..4 → group = 1 */
for (int i = 0; i < 5; i++) {
rbamp_set_group_id(meters[i], 1);
rbamp_save_user_config(meters[i]);
}
/* Tariff B — modules 5..9 → group = 2 */
for (int i = 5; i < 10; i++) {
rbamp_set_group_id(meters[i], 2);
rbamp_save_user_config(meters[i]);
}
Во время работы — независимый снимок на каждый тариф:
void daytime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff A only (group 1) */
rbamp_broadcast_latch_group(bus, 1, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff A */
}
void nighttime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff B only (group 2) */
rbamp_broadcast_latch_group(bus, 2, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff B */
}
void all_modules_snapshot(i2c_master_bus_handle_t bus, uint16_t tick) {
/* group = 0x00 — all-call, all 10 take a snapshot */
rbamp_broadcast_latch_group(bus, 0, tick, 100);
}
Выгода: один цикл на тариф = чистое разделение интервалов учёта. Без групп пришлось бы вести параллельные циклы последовательных снимков с разрешением конфликтов.
Сценарий 18 — Модуль STD: реактивная мощность, THD и энергия по времени мастера
Цель: считать величины, которые измеряет только модуль STD — реактивную и полную мощность, THD, коэффициент мощности смещения — и учитывать энергию за период, который вы задаёте сами. Один и тот же API rbamp_* обслуживает обе линейки модулей; rbamp_begin() определяет линейку. На модуле BASIC пример выводит пометку и переходит к поведению quick_read — ничего не падает, вызовы STD просто сообщают «не поддерживается».
Source: examples/std_meter/
rbamp_new(bus, 0x50, &dev);
rbamp_begin(dev); /* detects BASIC / STD */
const bool std = (rbamp_line(dev) == RBAMP_LINE_STD);
if (std) {
rbamp_std_info_t info;
rbamp_std_info(dev, &info);
/* THD and displacement PF are off by default (RAM-only setting;
* reverts at a module reset). */
rbamp_std_set_harmonics(dev, true);
/* Period energy depends on what the module offers. */
if (info.period_source == RBAMP_STD_PERIOD_LATCH) {
/* Snapshot banks: keep bank 0 (the library's) armed, add our own. */
rbamp_std_arm_banks(dev, (1u << 0) | (1u << 1));
rbamp_std_latch(dev, 1); /* primer: the period starts now */
} /* COUNTERS: nothing to arm */
}
while (1) {
rbamp_std_voltage_t v;
rbamp_std_read_voltage(dev, 0, &v); /* U, THD, phase angle */
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
rbamp_std_channel_t c;
rbamp_std_read_channel(dev, ch, &c); /* I, P, Q, S, PF, PF1, THD in one burst */
}
rbamp_std_health_t h; /* the frame counter must keep growing */
rbamp_std_read_health(dev, &h);
/* Every PERIOD_MS: */
/* - LATCH module: rbamp_std_latch(dev, 1); wait >= 300 ms;
* rbamp_std_read_latch(dev, 1, <);
* rbamp_std_latch_wh(<, dt_ms, RBAMP_STD_TOTAL, &wh_in, &wh_out);
* - COUNTERS module: rbamp_read_period_snapshot(dev, &ps, 0, false);
* ps.wh_net / ps.avg_p_total / ps.module_restarted */
vTaskDelay(pdMS_TO_TICKS(1000));
}
Notes:
-
dt_ms— это мастер-время настенных часов между двумя снимками банка; у модуля для периода собственных часов нет. -
На модуле со счётчиками нет банка снимков и нечего взводить: снимок периода библиотеки читает сохранённые счётчики и сообщает разность;
module_restartedотмечает перезагрузку внутри периода (разность всё равно валидна). -
Маска банка снимков — это RAM на модуле. Если сброс модуля её очистит,
rbamp_std_read_latch()заново взведёт банк и вернётESP_ERR_INVALID_STATEза этот один период — отбросьте его и перезапустите якорь dt. -
Полный API: 09 · Справочник API, глава «Линия STD».
Сводная таблица сценариев
| # | LOC | шина I²C | Период? | DRDY? | MQTT? | Сохранение |
|---|---|---|---|---|---|---|
| 1 | ~120 | общие 3 модуля (UI1+I2+I3) | да (синхронизация GC) | нет | да | ОЗУ (принадлежит мастеру) |
| 2 | ~50 | выделенный (один новый) | нет | нет | нет | флеш (save_config=true) |
| 3 | ~60 | выделенный (I3) | нет | нет | нет | флеш (SAVE_USER_CONFIG) |
| 4 | ~50 | общий на 3 модуля | да (GC) | нет | нет | RAM |
| 5 | ~40 | выделенный | нет | нет | нет | нет |
| 6 | ~60 | общий с LCD | да | нет | нет | RAM |
| 7 | ~80 | общий на 3 модуля | да | нет | нет | RAM |
| 8 | ~70 | выделенный | да | нет | да | retained MQTT |
| 9 | ~50 | выделенный | нет (RT) | нет | нет | ОЗУ (принадлежит мастеру) |
| 10 | ~80 | общий на 3 модуля | да | нет | да | retained MQTT |
| 11 | ~80 | выделенный | нет (RT) | да | нет | RAM |
| 12 | ~70 | выделенный | да | нет | нет | SPIFFS |
| 13 | ~80 | выделенный | да | нет | да | Память RTC + MQTT |
| 14 | ~60 | выделенный I3 | нет (RT) | нет | нет | RAM |
| 15 | ~80 | общий 5×UI1 | да | нет | нет | RAM |
| 16 | ~100 | общий 12 модулей | да (синхронизация GC) | нет | нет | RAM |
| 17 | ~60 | общий 10 модулей, несколько арендаторов | да (группы GC) | нет | нет | RAM |
| 18 | ~110 | выделенный (модуль STD) | да (банк снимков или счётчики) | нет | нет | RAM (счётчики за весь срок службы хранятся в модуле) |
Что дальше
-
07 · Интеграции DIY — Home Assistant / Node-RED / OpenHAB на основе этих сценариев (включая
examples/ha_discovery/) -
08 · Облачные интеграции — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Справочник API — задокументирована каждая публичная функция
-
10 · Устранение неполадок — когда сценарии ведут себя на вашем стенде иначе
Исходный код и вопросы: rb-amp/rbamp-esp-idf · эта страница в репозитории: docs/06_examples.md (v1.7.3)