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/. 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/ |
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 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:
-
Scopra —
rbamp_fleet_scantrova tutti i moduli, verifica la loro identità ed esclude gli indirizzi in conflitto. -
Configuri —
rbamp_configure_channelsimposta la classe del sensore + i modelli CT per canale + un unicoSAVE_USER_CONFIGfinale in una sola chiamata per modulo multi-canale. -
Armatura GC —
rbamp_fleet_enable_gc_allabilita la ricezione dello snapshot General-Call su ogni modulo della flotta. -
Ciclo — a ogni tick il master esegue un
_gclatchatomico (uno snapshot sincrono sull'intera flotta), verifica con_check_sync, legge con_poll_all, integra l'energia permaster_dte 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
#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)
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)
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) → unpoll_alllegge l'intera flotta → aggregazione. Nessuna deriva tra moduli da una catena di andate e ritorni sequenziali. -
Comportamento di
total_powerin una flotta eterogenea. La UI1 fornisce la potenza attiva (ha la tensione → haP); le I2/I3 misurano solo corrente, quindi il loro contributo atotal_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_totalcresce in modo monotono (da 2.55 a 6.94 Wh nella finestra di cattura su banco); il componente integra ogni periodo conmaster_dt_ms(esp_timer), non conlatch_mslato chip (un timer diagnostico del modulo che può risultare corto). Un tick spurio aggiunge0 Whse 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_alllo segnala constatus[i] != ESP_OKe 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 an_ok=2/3senza stallo. Lo stesso vale percheck_sync—missed_idxpunta 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 conhas_voltage = true) dagli handle secondari (tutti gli altri). -
Correnti per canale → disaggregazione dei carichi. Tramite
fleet_poll_allil 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 — media112.1 ms(min 112.1 / max 112.3). Cioè ≈ 22-23 ms per modulo aggiuntivo, lineare e con jitter molto basso (min ≈ max). Unfleet_poll_allbatch 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.
#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):
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.
#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):
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.
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).
#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Ω):
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 = 0per 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.
#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.
#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).
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.
#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.
#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.
#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.
#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.
#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.
Richiede una tabella delle partizioni personalizzata con la voce storage,data,spiffs,,128K, in partitions.csv. Un esempio è in examples/spiffs_logger/partitions.csv.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_spiffs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define LOG_PATH "/storage/log.csv"
#define ROTATE_BYTES (64 * 1024)
static const char *TAG = "spiffs_logger";
static void rotate_if_full(void) {
struct stat st;
if (stat(LOG_PATH, &st) == 0 && st.st_size >= ROTATE_BYTES) {
rename(LOG_PATH, "/storage/log_prev.csv");
}
}
void app_main(void) {
esp_vfs_spiffs_conf_t spiffs_cfg = {
.base_path = "/storage",
.partition_label = "storage",
.max_files = 4,
.format_if_mount_failed = true,
};
ESP_ERROR_CHECK(esp_vfs_spiffs_register(&spiffs_cfg));
/* ...bus_cfg + rbamp_new + rbamp_begin... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
rotate_if_full();
FILE *f = fopen(LOG_PATH, "a");
if (!f) {
ESP_LOGE(TAG, "fopen failed");
continue;
}
fprintf(f, "%lld,%.3f,%.4f,%u\n",
(long long)(esp_timer_get_time() / 1000),
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
fclose(f);
}
}
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.
⚠ 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).
#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/.
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.
#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.
#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):
/* 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:
#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):
/* 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:
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/
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_restartedsegnala 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 restituisceESP_ERR_INVALID_STATEper 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
-
07 · Integrazioni fai-da-te — Home Assistant / Node-RED / OpenHAB basati su questi scenari (incluso
examples/ha_discovery/) -
08 · Integrazioni cloud — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Riferimento API — ogni funzione pubblica documentata
-
10 · Risoluzione dei problemi — quando gli scenari si comportano in modo diverso sul suo banco di prova
Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/06_examples.md (v1.7.3)