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

06 · Примеры

Эта глава открывается флагманскими сценариями — реальными шаблонами развёртывания, для которых создавалась библиотека (сеть + N поднагрузок на одной шине, снимки с синхронизацией GC). За ними идут сценарии с одним модулем — от минимального «hello world» до журнала на батарее с глубоким сном.

Большинство сценариев поставляются как готовый к сборке проект IDF в examples/, который можно собрать командой idf.py -C examples/ build flash monitor. Код в этой главе — выжимка ключевой логики, а не полный проект (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%): интегрированная система учёта

Цель: каноническое развёртывание библиотеки — согласованная система учёта на разнородном флоте, замкнутая в одном цикле:

  1. Обнаружение — rbamp_fleet_scan находит все модули, проверяет их идентичность и отсеивает конфликтующие адреса.

  2. Настройка — rbamp_configure_channels задаёт класс датчика + модели CT по каналам + один завершающий SAVE_USER_CONFIG одним вызовом на модуль с несколькими каналами.

  3. Взвод GC — rbamp_fleet_enable_gc_all включает приём снимков General-Call на каждом модуле флота.

  4. Цикл — на каждом тике мастер выполняет атомарный _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 А.

Код — интегрирующий цикл

C
#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 */
    }
}

Вывод на стенде (проверено на оборудовании на всём флоте)

Text
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.

C
#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);
}

Вывод стенда (проверенный на оборудовании путь успеха):

Text
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) и подтвердить сохранность после перезагрузки.

C
#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 с чистой перепрошивкой):

Text
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 по каналам.

Допустимые коды моделей 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).

C
#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 кОм):

Text
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 в одну структуру.

C
#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 в одном вызове.

C
#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.

C
#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] на стороне мастера.

C
#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 Гц на стороне мастера и раскладывайте по корзинам самостоятельно.

C
#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 для учёта по приборам). Сводная панель публикуется раз в минуту.

C
#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 мс сравнивать мгновенную мощность со скользящим средним по экспоненте. Записывать значимые отклонения — нагрузки вроде микроволновки, чайника или фена «появляются» в журнале как событие включения / выключения.

C
#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.

C
#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 отражает только время внутри текущего цикла пробуждения, а не между пробуждениями).

C
#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 · Выбор токового датчика.

C
#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 · Подключение: последовательный снимок + общая выдержка.

C
#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.

Предварительная конфигурация (один раз на модуль):

C
/* 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);

Широковещательный снимок во время работы с контрольной проверкой:

C
#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 — тарифа Б (ночного); их взводят и читают по разным расписаниям.

Настройка (один раз):

C
/* 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]);
}

Во время работы — независимый снимок на каждый тариф:

C
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/

C
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 (счётчики за весь срок службы хранятся в модуле)

Что дальше


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