rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub (Edit on GitHub)

06 · Esempi

Questo capitolo si apre con gli scenari di riferimento — i reali schemi di distribuzione per cui la libreria è stata progettata (rete principale + N sotto-carichi su un unico bus, snapshot sincronizzati GC). Seguono gli scenari a modulo singolo — dal minimo «hello world» al registratore a batteria in deep-sleep.

La maggior parte degli scenari è fornita come progetto IDF pronto da compilare in examples/, compilabile con idf.py -C examples/ build flash monitor. Il codice di questo capitolo è una sintesi della logica chiave, non il progetto completo (bus_cfg / avvio WiFi / Kconfig sono omessi per brevità).

# Scenario Difficoltà Fonte
1 Rete + N sotto-carichi: il canone dell'80% medio examples/fleet_sync/
2 Flusso di provisioning (vergine → flotta) basso (composition)
3 CT misti multi-canale (I3, modelli diversi) medio (composition)
4 Sincronizzazione GC della flotta — sincronia dei periodi tariffari medio examples/fleet_sync/
5 Lettura rapida (modulo singolo) minimo examples/quick_read/
6 Contatore Wh su LCD 16×2 basso examples/lcd_period/
7 Monitoraggio di 3 moduli (sequenziale, legacy) basso examples/multi_module/
8 MQTT per canale medio examples/mqtt_publisher/
9 Misura bidirezionale lato master medio (composition)
10 Bilancio energetico domestico completo (3 moduli) alta (composition)
11 Registrazione a eventi (EMA) medio (composition)
12 Registratore CSV locale su SPIFFS medio examples/spiffs_logger/
13 Logger a batteria con deep-sleep medio examples/deep_sleep_logger/
14 I3 con CT diverso per canale (approfondimento sui carichi misti) medio (composition)
15 Sotto-misurazione: 5×UI1 su un bus condiviso alta (composition)
16 Snapshot broadcast GC per più di 8 moduli alta (composition)
17 Filtraggio per gruppo GC (misurazione multi-tenant) alta (composition)
18 Modulo STD: potenza reattiva / apparente, THD, energia con tempo del master medio examples/std_meter/
Nota

Lo scenario 18 mostra la linea di moduli STD. Gli scenari 1–4 sono quelli principali, costruiti attorno alla distribuzione canonica della libreria. Il loro codice usa l'API della flotta ed è validato su banco di prova hardware (una flotta eterogenea UI1+I2+I3). Gli scenari 5–13 sono a singolo modulo e pattern compositivi; 14–17 sono scenari di flotta estesi (un approfondimento sulle funzionalità introdotte in 1–4). Lo scenario 7 è la vecchia istantanea sequenziale per modulo senza API della flotta, mantenuta per confronto e come percorso di migrazione.

Tutti gli scenari presuppongono che la classe del sensore e il modello di CT siano già stati configurati con rbamp_set_sensor_class() + rbamp_set_ct_model() (vedi 05 · Guida rapida, Passo 3). Si fa una volta sola in fase di installazione — le impostazioni sono memorizzate nella flash del modulo e sopravvivono a un reset.

REQUIRES aggiuntivi per main/CMakeLists.txt

Il componente base richiama esp_driver_i2c, esp_timer, log. Alcuni scenari usano componenti ESP-IDF aggiuntivi — li aggiunga al REQUIRES della sua main/:

Scenario REQUIRES aggiuntivi
1 — Rete + N carichi secondari (flotta) — (solo rbamp)
2 — Flusso di provisioning —
3 — I3 multicanale con CT misti —
4 — Sincronizzazione GC della flotta —
5 — Lettura rapida —
6 — contatore Wh su LCD rbamp (il driver LCD è un componente separato a sua scelta)
7 — Multimodulo (sequenziale, legacy) —
8 — MQTT per canale rbamp mqtt esp_wifi esp_event esp_netif nvs_flash
9 — Misura bidirezionale —
10 — Bilancio energetico —
11 — Registrazione a eventi —
12 — Registratore SPIFFS rbamp spiffs
13 — Logger in deep-sleep rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (se pubblica)
18 — misuratore STD — (solo rbamp)

I componenti di rete richiedono anche nvs_flash_init() in app_main e l'avvio del WiFi. Per brevità tutto questo è omesso negli snippet sotto; il progetto completo è sempre in examples//.

Nota

Nota importante sugli snippet qui sotto. Ogni snippet è una distillazione della logica chiave, non un app_main completo. Nel codice funzionante la riga rbamp_handle_t dev è sempre preceduta da i2c_master_bus_config_t bus_cfg = {...}; i2c_new_master_bus(&bus_cfg, &bus); rbamp_new(bus, 0x50, &dev); rbamp_begin(dev); (per un singolo modulo) oppure rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (per la flotta). Quando il lavoro è finito — rbamp_del(dev) / rbamp_fleet_destroy(fleet) (omessi dove app_main entra in un ciclo infinito — l'handle vive fino al riavvio del chip).


Scenario 1 — Rete principale + N sotto-carichi (il canone 80%): sistema di misura integrato

Obiettivo: la distribuzione canonica della libreria — un sistema di misura coerente su una flotta eterogenea, chiuso in un unico ciclo:

  1. Scopra — rbamp_fleet_scan trova tutti i moduli, verifica la loro identità ed esclude gli indirizzi in conflitto.

  2. Configuri — rbamp_configure_channels imposta la classe del sensore + i modelli CT per canale + un unico SAVE_USER_CONFIG finale in una sola chiamata per modulo multi-canale.

  3. Armatura GC — rbamp_fleet_enable_gc_all abilita la ricezione dello snapshot General-Call su ogni modulo della flotta.

  4. Ciclo — a ogni tick il master esegue un _gclatch atomico (uno snapshot sincrono sull'intera flotta), verifica con _check_sync, legge con _poll_all, integra l'energia per master_dt e calcola _total_power + _total_energy_wh.

Questo è l'esempio principale del capitolo — mostra l'intera libreria in azione nella configurazione canonica. Ogni altro scenario (2–17) scompone questo flusso in singoli blocchi o lo integra con integrazioni di terze parti (LCD, MQTT, SD).

Hardware (validato su HW): una flotta eterogenea di 3 moduli su un unico bus, con una resistenza di pull-up esterna da 4.7 kΩ su SDA/SCL (vedi 04 · Cablaggio, sezione «Bus multimodulo — la topologia principale»):

  • @0x50 — UI1, contatore di rete all'ingresso di servizio (un canale di corrente + tensione).
  • @0x51 — I2, un sotto-contatore di corrente a due canali (senza tensione).
  • @0x52 — I3, un sotto-contatore di corrente a tre canali (senza tensione).

Il carico di riferimento sulla linea è ~0.57 A.

Codice — loop integrato

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

Output da banco (validato su hardware sull'intera flotta)

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)
Nota

Le cifre di banco illustrano la forma dei dati e il loro flusso nel sistema — non la precisione di misura.

Note per la distribuzione

  • Un unico ciclo sincronizzato è l'intero sistema. A ogni tick: un gclatch (una sola transazione I²C General-Call) → tutti i moduli avviano atomicamente il proprio snapshot di periodo (check_sync = 3/3, sfasamento = 0) → un poll_all legge l'intera flotta → aggregazione. Nessuna deriva tra moduli da una catena di andate e ritorni sequenziali.

  • Comportamento di total_power in una flotta eterogenea. La UI1 fornisce la potenza attiva (ha la tensione → ha P); le I2/I3 misurano solo corrente, quindi il loro contributo a total_power è zero. Pertanto, nel canone, total_power ≈ la potenza del modulo di rete. Per la potenza per carico su un sotto-contatore, la calcoli sul lato master: P_subload[k] ≈ V_mains × I_sub[k] (un'approssimazione, corretta quando i PF sono vicini; un sotto-contatore solo di corrente non può riportare la P esatta per carico).

  • Energia (Wh) — orologio master. E_total cresce in modo monotono (da 2.55 a 6.94 Wh nella finestra di cattura su banco); il componente integra ogni periodo con master_dt_ms (esp_timer), non con latch_ms lato chip (un timer diagnostico del modulo che può risultare corto). Un tick spurio aggiunge 0 Wh se tra due interrogazioni non è trascorso alcun nuovo periodo — questo è normale (snap.valid = 0 in quel ciclo).

  • Polling resiliente ai MISS. Se uno dei moduli cade dal bus (disconnessione, riavvio), poll_all lo segnala con status[i] != ESP_OK e continua a interrogare gli altri — il master non si blocca. Verificato su banco: un modulo disconnesso a metà esecuzione ha lasciato la flotta in polling a n_ok=2/3 senza stallo. Lo stesso vale per check_sync — missed_idx punta al primo modulo fuori sincronia mentre gli altri continuano a prendere snapshot.

  • Analisi del bilancio. Nel canone 80%: balance = P_mains − Σ(V_mains × I_sub[k]) — una stima del «resto» (consumo di fondo, carichi non contabilizzati). Il codice mirato scorre la flotta separando l'handle della rete (quello con has_voltage = true) dagli handle secondari (tutti gli altri).

  • Correnti per canale → disaggregazione dei carichi. Tramite fleet_poll_all il master vede tutti i canali di corrente insieme (1+2+3 = 6 sulla nostra flotta di prova), senza lettori separati per modulo.

  • CT misti su un modulo a 3 canali. Usi l'ultima release della libreria; gli specchi [1 2 3] su I3 si assestano come configurati. L'ordine con cui vengono associati i canali non conta.

  • Latenza di poll per il dimensionamento in produzione (misurata su HW). Su banco @50 kHz I²C: 2 moduli — media 89.4 ms (min 89.4 / max 89.6); 3 moduli — media 112.1 ms (min 112.1 / max 112.3). Cioè ≈ 22-23 ms per modulo aggiuntivo, lineare e con jitter molto basso (min ≈ max). Un fleet_poll_all batch singolo è deterministico su un bus pulito. Una flotta di 3 moduli (~112 ms) sta entro un intervallo di polling di 200 ms — quindi una frequenza di polling di 5 Hz è raggiungibile (ogni secondo finestra di 100 ms del modulo) senza saturare il bus. Il budget completo del bus (quando la flotta supera l'intervallo di polling) è nella tabella in 04 · Cablaggio, sezione "Budget energetico del bus".


Scenario 2 — Flusso di messa in servizio (da vergine a flotta)

Obiettivo: spostare un nuovo modulo dal suo indirizzo di fabbrica 0x50 a un indirizzo di lavoro e aggiungerlo a una flotta esistente, rendendo persistente la sua configurazione (modelli CT, etichetta) in flash.

Hardware (validato su HW): un modulo vergine con indirizzo di fabbrica 0x50 (HW_VARIANT a 3 canali). La messa in servizio lo sposta all'indirizzo 0x52 e salva la configurazione in 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);
}

Output su banco (percorso di successo validato su hardware):

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 restituisce true dopo una chiamata riuscita. Su un modulo appena uscito di fabbrica (uno che nulla ha ancora toccato) il valore precedente di is_provisioned sarà false — è il normale stato 0xFB (ERR_FLASH_PARAMS_BAD) descritto in 10 · Risoluzione dei problemi, e non è fatale.

Percorsi di errore

Errore Condizione Ripristino
ESP_ERR_NOT_FOUND Nessuno risponde a 0x50 Verifichi che il modulo vergine sia fisicamente collegato e alimentato (VCC); controllo del bus (10 · Risoluzione dei problemi).
ESP_ERR_INVALID_STATE Rilevato un conflitto a 0x50 o desired_addr; moduli diversi rispondono in modo identico Violazione della disciplina — più di un modulo vergine sul bus. Spegnere e riaccendere + scollegare fisicamente tutti tranne uno + riprovare (vedi il percorso di ripristino in 10 · Risoluzione dei problemi).
ESP_ERR_TIMEOUT Il commit in due fasi è andato a buon fine, ma il modulo non è comparso al nuovo indirizzo entro la finestra di avvio Spenga e riaccenda il modulo, riprovi. Se persiste — problema del ciclo di flash.
ESP_ERR_INVALID_ARG desired_addr fuori da 0x08..0x77 Usi un indirizzo valido a 7 bit.

Un percorso dettagliato delle modalità di guasto: 10 · Risoluzione dei problemi, sezione «Flotta: rbamp_provision ha restituito un errore».


Scenario 3 — I multicanale con CT misti (I3, modelli diversi per canale)

Obiettivo: dimostrare rbamp_configure_channels su un I3 — tre canali con modelli CT diversi (per esempio ch0=SCT-013-005 per un carico piccolo, ch1=SCT-013-030 per uno medio, ch2=SCT-013-020 per uno grande) con un unico ciclo di flash terminale (rispettoso della flash), e confermare la persistenza dopo un riavvio.

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

Output da banco (validato su hardware su un I3 riflashato in pulito):

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)

La proprietà del "singolo SAVE" — perché conta

configure_channels esegue un solo CMD_SAVE_USER_CONFIG terminale alla fine. L'alternativa — chiamate set_ct_model_ch separate per ogni canale, ciascuna con il proprio save_user_config successivo — comporta tre cicli di cancellazione e scrittura della flash.

Confronto della latenza di banco (sulla stessa I3):

Approccio Latenza Cicli di flash
configure_channels(...) — 1 SALVATAGGIO nel terminale ~1403 ms 1
3× (set_ct_model_ch + save_user_config) ~3492 ms 3

3× più lento — cioè (~2.5×) × ~700 ms. Il punto chiave è la differenza di 3× nei cicli di usura sulla stessa pagina di flash: con la tipica riconfigurazione dei moduli sul campo, questo si traduce in un costo di usura significativo. Usi sempre configure_channels quando deve impostare la classe del sensore + i modelli CT per canale.

Codici validi dei modelli CT.

Per la famiglia 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. Un codice fuori da {1, 2, 3, 4, 5, 6, 7} dà ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).


Scenario 4 — Sincronizzazione GC della flotta (sincronia dei periodi tariffari)

Obiettivo: dimostrare uno snapshot atomico sull'intera flotta con un unico frame I²C General-Call. A differenza del singolo CMD_LATCH_PERIOD sequenziale per modulo (dove lo sfasamento si accumula a ogni andata e ritorno), il GC sincronizza tutti i moduli in una sola transazione sul bus.

Hardware: la stessa flotta eterogenea 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));
    }
}

Output da banco (10 cicli sulla flotta UI1+I2+I3, pull-up da 4.7 kΩ):

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

Quando usare la sincronizzazione GC:

  • Sincronia stretta. Se la differenza di snapshot per minuto/secondo tra moduli conta per il reporting (per esempio un calcolo di bilancio rete − Σ(sub) integrato nel tempo — lo sfasamento tra moduli introduce un errore sistematico), GC dà skew = 0 per misura di banco. Uno snapshot sequenziale per modulo sugli stessi 3 moduli accumula 100-300 µs per modulo × N, che diventa rilevante su una finestra di 60 minuti nelle analisi di precisione.

  • Flotta numerosa. Con l'aumento dei moduli, la differenza tra «N × round_trip sequenziali» e «un unico frame GC» cresce linearmente.

  • Allineamento tra installazioni. Se ha diversi ESP32 su bus diversi che condividono un clock master, il tick GC può essere sincronizzato tramite l'orologio di parete lato master — e gli snapshot di bus diversi risultano allineati entro una singola finestra di andata e ritorno di rete.

Verifica tramite check_sync: un controllo che tutti i moduli abbiano effettivamente ricevuto il frame GC. Può mancare un modulo se era occupato in avvio o in un ciclo di SAVE nel momento del frame — missed_idx punta al primo fuori sincronia. Nella validazione su banco, 10 round di fila — 0 mancate.

Precondizione. GC deve essere abilitato su ogni modulo (rbamp_fleet_enable_gc_all oppure per dispositivo rbamp_enable_gc + SAVE_USER_CONFIG + reset). Un modulo nuovo con i valori di fabbrica non accetta GC — è una scelta di progetto, una protezione contro i broadcast accidentali su un bus in fase di avvio.


Scenario 5 — Lettura rapida (modulo singolo)

Obiettivo: stampare U / I / P / PF / frequenza nel log ESP-IDF una volta al secondo. Il medesimo «hello world» scritto nella 05 · Guida rapida, ma tramite rbamp_read_all() — una lettura istantanea dell'intero blocco RT in una sola struct.

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

Cosa succede sul bus: rbamp_read_all() su un UI3 esegue circa 53 transazioni da un byte (13 valori float × 4 byte + 1 byte di frequenza). A 50 kHz con margine di retry — dell'ordine di 25-30 ms. Se non servono tutti i valori, chiami le funzioni per proprietà (rbamp_read_voltage(), rbamp_read_current(ch)) — meno byte sul bus.


Scenario 6 — Contatore Wh su LCD 16×2

Obiettivo: un contatore Wh, aggiornato una volta al minuto, su un display LCD alfanumerico 16×2 con espansore I²C PCF8574 (compatibile HD44780). L'LCD sta sullo stesso bus I²C del rbAmp. Il meccanismo chiave del componente è rbamp_read_period_snapshot(), che racchiude snapshot + assestamento + verifica di validità + lettura + avanzamento Wh in un'unica chiamata.

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

Il progetto IDF completo — examples/lcd_period/.

Gestione degli snapshot stantii. rbamp_read_period_snapshot() restituisce ESP_ERR_INVALID_RESPONSE se il modulo non è riuscito a preparare un nuovo snapshot al momento della lettura. Il componente registra comunque il proprio timestamp (esp_timer_get_time()) internamente — così lo snapshot valido successivo non viene contato due volte nell'intervallo.


Scenario 7 — Monitoraggio di 3 moduli (sequenziale legacy) su un unico bus

Obiettivo: interrogare 3 moduli agli indirizzi 0x50 / 0x51 / 0x52 da un unico master. Ogni modulo deve avere un indirizzo unico (gli indirizzi sono assegnati durante la fase di fabbrica / installazione — vedi 09 · Riferimento API sui metodi di cambio indirizzo con le relative note WARNING).

Nota

Il pattern canonico per il firmware v1 è un rbamp_latch_period() sequenziale su ciascun dispositivo + un unico assestamento condiviso di 50 ms + rbamp_read_period_snapshot(skip_latch=true) per dispositivo. Lo sfasamento tra dispositivi a 100 kHz: ~1 ms per dispositivo — trascurabile rispetto a un periodo di 60 secondi.

Sul firmware v1.3 (REG_VERSION = 0x04) rbamp_broadcast_latch() è pienamente supportato una volta che il GC è abilitato su tutta la flotta tramite rbamp_fleet_enable_gc_all() — il percorso canonico di sincronizzazione della flotta per una sincronia stretta tra i sotto-contatori (vedi la sezione GC di flotta Strategia 2 più in alto in questo capitolo). Sul firmware legacy v1.0-v1.2 (senza supporto allo snapshot General-Call) la chiamata restituisce ESP_ERR_NOT_SUPPORTED e la libreria ricade sullo snapshot per dispositivo mostrato sopra. Vedi 09 · Riferimento API per i dettagli.

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

Il progetto completo (con sonda di scansione del bus + segnalazione degli errori) — examples/multi_module/.


Scenario 8 — MQTT per canale

Obiettivo: un modulo UI3 con 3 pinze CT su tre linee indipendenti. Contatori Wh per canale, pubblicati su MQTT una volta al minuto. Mostra che rbamp_energy_wh(dev, ch) funziona su ciascun canale in modo indipendente — senza bisogno di un array manuale total_wh[3] sul lato master.

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

Il progetto completo — examples/mqtt_publisher/. Per l'auto-discovery MQTT di HA basata su questo schema — vedi 07 · Integrazioni fai-da-te + examples/ha_discovery/.


Scenario 9 — Misura bidirezionale lato master

Obiettivo: separare la potenza istantanea con segno in consumo lordo e immissione lorda. Usi questo schema sulla classe BASIC, dove il firmware azzera i valori negativi in snap.avg_p[ch] (potenza mediata sul periodo) — campioni rbamp_read_power(dev, 0, &p) (potenza istantanea, con segno su tutte le classi) a 10 Hz sul lato master e le raggruppi lei stesso.

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

Questo è uno scenario composito senza un progetto IDF dedicato. Su un modulo STD i contatori di energia sono con segno e rbamp_energy_wh(dev, 0) restituisce un bilancio netto (importazione ed esportazione sono mantenute separatamente in rbamp_std_read_energy()) — questa suddivisione lato master serve solo sui moduli BASE, o per una rendicontazione separata di consumo lordo / esportazione lorda dalla potenza in tempo reale.


Scenario 10 — Bilancio energetico domestico completo

Obiettivo: 3 moduli — rete (bidirezionale), solare (solo produzione), carichi (UI3 per singolo apparecchio). Il cruscotto combinato viene pubblicato una volta al minuto.

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

Per una suddivisione esplicita consumo lordo / esportazione lorda sulla rete — la combini con il pattern dello Scenario 5 (un task separato a 10 Hz su rbamp_read_power(mains_dev, 0, ...)).

È uno scenario composito senza un progetto IDF dedicato — lo assembli da examples/mqtt_publisher/ + examples/multi_module/.


Scenario 11 — Registrazione basata su eventi (EMA)

Obiettivo: su ogni finestra RT di 100 ms, confrontare la potenza istantanea con una media mobile esponenziale. Registrare le deviazioni significative — carichi come un forno a microonde, un bollitore o un asciugacapelli "compaiono" nel log come evento di accensione / spegnimento.

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

Uno scenario composito — nessun progetto IDF dedicato. Lo combini con la pubblicazione MQTT dello Scenario 4 per le automazioni lato HA, oppure scriva gli eventi su SPIFFS con lo schema dello Scenario 8 per un registro offline.


Scenario 12 — Logger CSV locale su SPIFFS

Obiettivo: scrivere uno snapshot di periodo su un file CSV su SPIFFS una volta al minuto. Utile per distribuzioni autonome senza WiFi / MQTT, o come buffer per una sincronizzazione cloud differita.

Nota

Richiede una tabella delle partizioni personalizzata con la voce storage,data,spiffs,,128K, in partitions.csv. Un esempio è in 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);
    }
}

Il progetto completo — examples/spiffs_logger/. Lo snippet sopra è una semplificazione didattica con una riga CSV di 4 colonne. L'esempio stesso scrive una riga CSV di 9 colonne con avg_p per canale e Wh per tutti e 3 i canali — più utile per scenari di produzione su moduli UI3.

Per la sincronizzazione differita verso il cloud (registrare in locale, inviare una volta l'ora) — vedi la sezione «Ibrido: archiviazione locale + sincronizzazione» in 08 · Integrazioni cloud.


Scenario 13 — Logger a batteria con deep-sleep

Obiettivo: un ESP32 si risveglia una volta ogni 10 minuti, esegue un unico snapshot di periodo, pubblica via WiFi+MQTT e torna in deep-sleep. L'energia persiste nella memoria RTC tra un ciclo di sospensione e l'altro. L'accumulatore del componente è disattivato — la persistenza del Wh è gestita dal master stesso.

Sicurezza

⚠ Nota importante sul deep-sleep. Sul firmware attuale rbamp_begin() emette sempre un innesco CMD_LATCH_PERIOD, che azzera l'accumulatore di periodo del firmware. Quindi dopo un risveglio da deep-sleep non può semplicemente chiamare rbamp_read_period_snapshot() per impostazione predefinita — quella chiamata farebbe un altro snapshot e restituirebbe dati quasi nulli ~50 ms dopo l'innesco. Lo schema corretto qui sotto usa skip_latch=true per leggere i dati accumulati durante l'intervallo di sospensione, e il timer RTC proprio del master per l'intervallo tra i risvegli (il campo snap.master_dt_ms riflette solo il tempo nel ciclo di risveglio corrente, non da risveglio a risveglio).

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();
}

Il progetto completo (con configurazione WiFi, pubblicazione MQTT, protezioni con marcatore magico RTC) — examples/deep_sleep_logger/.

Sicurezza

rbamp_begin_resume() (componente 1.7.0 e successivi) è la variante di inizializzazione senza il latch di innesco CMD_LATCH_PERIOD, quindi rbamp_read_period_snapshot() funziona direttamente dopo un risveglio da deep-sleep. Lo schema sopra (skip_latch=true + il timer RTC del master) resta valido sulle versioni precedenti del componente.

Budget energetico (ESP32-WROOM, intervallo di risveglio di 10 minuti):

  • Durata del ciclo attivo: ~3 s (WiFi + MQTT + I²C)
  • Assorbimento in attivo: ~80 mA medi → ~0.07 mAh per risveglio
  • Corrente di sleep: ~10 µA (RTC + domini conservati)
  • ~10 mAh al giorno → una cella Li-ion da 2000 mAh dura ~6 mesi

Scenario 14 — I3 con CT diverso per canale (monitoraggio di carichi misti)

Obiettivo: un singolo modulo UI3 monitora tre linee indipendenti su una fase con livelli di carico diversi:

  • Canale 0 — una sola presa (SCT-013-005, ≤5 A) — TV / router / standby.
  • Canale 1 — la linea della cucina (SCT-013-030, ≤30 A) — bollitore / forno a microonde.
  • Canale 2 — una caldaia per scaldabagno (SCT-013-020, ≤20 A) — carico di picco.

Tutti e tre i canali sono alimentati da una sola fase (in fase con il canale U), quindi P/PF/Q sono corretti per tutti e tre — vedi l'avvertenza sulla tensione singola in 03 · Scelta del sensore di corrente.

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

Quando usarlo: monitoraggio di una singola fase con tre gruppi di carico di diversa intensità di corrente. Il vantaggio principale è la risoluzione — ogni pinza corrisponde al proprio intervallo (una SCT-013-005 dà letture accurate su un carico in standby da 50 W, mentre una SCT-013-020 non va in saturazione su uno scaldabagno da ~4 kW).


Scenario 15 — Sotto-misurazione: 5×UI1 su un bus condiviso

Obiettivo: monitorare 5 linee indipendenti in un appartamento monofase con sincronia tariffaria dei periodi. Una UI1 per linea (5 moduli in tutto).

Questa è la strategia 1 per la sincronia dei periodi da 04 · Cablaggio: snapshot sequenziale + assestamento condiviso.

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();
    }
}

Analisi dello sfasamento: 5 moduli × ~1 ms/snapshot = ~5 ms. Rispetto al periodo di 60 s = 0.008%. Trascurabile.

Budget del bus: 5 moduli × ~5 ms di blocco RT = 25 ms per un ciclo completo; ciò rientra anche in una frequenza di polling di 5 Hz (25 ms ≪ 100 ms). Il margine del bus è comodo fino a ~15 moduli UI1.


Scenario 16 — Snapshot broadcast GC (sincronia stretta per più di 8 moduli)

Obiettivo: con ≥ 8 moduli lo sfasamento della strategia 1 (sequenziale) si avvicina a ~10 ms. Per la sincronia dei periodi tariffari — strategia 2, broadcast General-Call.

Preconfigurazione (una volta per modulo):

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);

Snapshot broadcast in esecuzione con testimone:

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;
}

Analisi dello sfasamento: un frame GC dura ~1 ms a 50 kHz → tutti i 12 moduli fanno lo snapshot simultaneamente a livello di bus. Lo sfasamento è praticamente 0.

Quando usarlo: ≥ 8 moduli e/o sincronizzazione stretta.

Quando NON usarlo: su un bus misto con dispositivi non rbAmp (GC potrebbe andare in conflitto).


Scenario 17 — Filtraggio per gruppo GC (contabilità multi-inquilino)

Obiettivo: 10 moduli su un unico bus, dove serve prendere snapshot di sottoinsiemi in modo indipendente. Per esempio, 5 moduli misurano la tariffa A (diurna), 5 — la tariffa B (notturna); vengono armati e letti secondo programmi diversi.

Configurazione (una tantum):

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

Runtime — snapshot indipendente per tariffa:

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

Vantaggi: un ciclo per tariffa = separazione netta degli intervalli di misura. Senza gruppi bisognerebbe mantenere cicli di snapshot sequenziali paralleli con risoluzione dei conflitti.


Scenario 18 — Modulo STD: potenza reattiva, THD ed energia con tempo del master

Obiettivo: leggere le grandezze che misura solo un modulo STD — potenza reattiva e apparente, THD, fattore di potenza di spostamento — e contabilizzare l'energia su un periodo proprio. La stessa API rbamp_* serve entrambe le linee di moduli; rbamp_begin() rileva la linea. Su un modulo BASIC l'esempio stampa una nota e ricade sul comportamento di quick_read — nulla fallisce, le chiamate STD semplicemente riportano «non supportato».

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 è il tempo di parete del master tra due snapshot del banco — il modulo non ha un proprio clock per il periodo.

  • Su un modulo a contatori non c'è banco di snapshot e nulla da armare: la chiamata di snapshot di periodo della libreria legge i contatori persistenti e riporta la differenza; module_restarted segnala un riavvio all'interno del periodo (la differenza resta valida).

  • La maschera del banco di snapshot è in RAM sul modulo. Se un reset del modulo la azzera, rbamp_std_read_latch() riarma il banco e restituisce ESP_ERR_INVALID_STATE per quel periodo — lo scarti e riavvii il suo ancoraggio dt.

  • API completa: 09 · Riferimento API, capitolo "Linea STD".


Tabella riassuntiva degli scenari

# LOC bus I²C Periodo? DRDY? MQTT? Persistenza
1 ~120 condivisi 3 moduli (UI1+I2+I3) sì (sincronizzazione GC) no sì RAM (di proprietà del master)
2 ~50 dedicato (uno vergine) no no no flash (save_config=true)
3 ~60 dedicato (I3) no no no flash (SAVE_USER_CONFIG)
4 ~50 condiviso tra 3 moduli sì (GC) no no RAM
5 ~40 dedicato no no no no
6 ~60 condiviso con LCD sì no no RAM
7 ~80 condiviso tra 3 moduli sì no no RAM
8 ~70 dedicato sì no sì MQTT retained
9 ~50 dedicato no (RT) no no RAM (di proprietà del master)
10 ~80 condiviso tra 3 moduli sì no sì MQTT retained
11 ~80 dedicato no (RT) sì no RAM
12 ~70 dedicato sì no no SPIFFS
13 ~80 dedicato sì no sì Memoria RTC + MQTT
14 ~60 I3 dedicato no (RT) no no RAM
15 ~80 condiviso da 5×UI1 sì no no RAM
16 ~100 condiviso da 12 moduli sì (sincronizzazione GC) no no RAM
17 ~60 condiviso da 10 moduli multi-inquilino sì (gruppi GC) no no RAM
18 ~110 dedicato (modulo STD) sì (banco di snapshot o contatori) no no RAM (i contatori di vita risiedono sul modulo)

Cosa c'è dopo


Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/06_examples.md (v1.7.3)