04 · Misura per periodo e contabilità tariffaria
Per la contabilità energetica tariffaria (Wh per 1 min / 15 min / 1 ora / giorno / mese / anno) rbAmp fornisce un meccanismo di snapshot atomico del periodo: un solo comando I²C congela la potenza media nel tempo su un periodo, e il master la moltiplica per il proprio dt di parete per ottenere i Wh.
Questo è il modo di livello produzione per estrarre i dati di energia. L'alternativa — integrare la P_real RT lato master a ogni finestra di misura (~100 ms, v1.2 e successive) — dà quasi lo stesso risultato su BASIC (precisione leggermente inferiore per la discretizzazione del campionamento) e tiene il master costantemente attivo.
Periodi BASIC e STD. BASIC mantiene uno snapshot del periodo per canale: su comando del master il modulo congela la potenza media e di picco e la lunghezza del periodo (accanto alla finestra live da 100 ms, che non è un periodo), e l'host integra l'energia. STANDARD (STD) mantiene l'energia sul modulo: contatori cumulativi (importazione/esportazione, attiva e reattiva) che sopravvivono alla perdita di alimentazione, più registrazioni con marca temporale ogni 15 minuti e ogni ora (il master imposta l'orologio). I moduli STD con il bit 8 di CAPABILITIES impostato hanno anche 8 banchi di snapshot indipendenti; senza di esso l'energia di intervallo deriva dalle differenze dei contatori. Il resto di questo capitolo descrive lo snapshot del periodo BASIC; STD è descritto nel riferimento tecnico STD.
Perché serve uno snapshot di periodo
Una base dei tempi unica, gestita dal master
In un sistema multi-modulo la base dei tempi deve stare sul master. Il chip quindi non integra internamente i Wh. Invece:
- Il chip espone una statistica indipendente dal tempo — la P media sul periodo.
- Il master lo moltiplica per il suo proprio dt di tempo di parete.
- Tutti i moduli condividono lo stesso riferimento temporale → nessuna deriva si accumula nel totale energetico del sistema.
La formula
E_Wh = avg_P_W × master_dt_seconds / 3600
Where:
avg_P_W— il valore diPERIOD_AVG_P_W, letto dopoCMD_LATCH_PERIOD.master_dt_seconds— i secondi trascorsi tra due snapshot successivi, misurati dal master.
Periodo atomico — concetto
Cosa fa il comando
Scrivere 0x27 in REG_COMMAND = 0x01 attiva una sequenza atomica nel firmware (eseguita sotto __disable_irq()):
1. snapshot ← live (copy the live accumulator into the I2C-visible snapshot)
2. live ← 0 (reset the accumulator; start the next period)
3. period_start_ms = now
Questi tre passi sono indivisibili — nessun interrupt può inserirsi tra l'uno e l'altro. Questo garantisce:
- Atomicità: ogni campione di P per finestra appartiene a esattamente uno snapshot — o il precedente o il successivo — mai duplicato, mai perso.
- Nessuna lacuna: il nuovo periodo inizia nello stesso istante in cui è terminato il precedente — non c'è alcun intervallo cieco.
Dove risiede lo snapshot
Dopo uno snapshot, i registri di snapshot del periodo (0xBE..0xCD, più 0xDC..0xDF per ch0 avg_p, più 0xE0..0xE3 per MAX_P, più 0xEC..0xEF per il diagnostico PERIOD_LATCH_MS) restituiscono il periodo appena chiuso. Noti che questo intervallo non è contiguo — 0xD0..0xDB contiene il blocco Q (RT live, non snapshot di periodo) e 0xE4..0xEB è riservato/di fabbrica. Per il layout esatto veda il capitolo 11 §4.11–4.13. L'accumulatore live inizia già a contare il periodo successivo; questi registri di snapshot si aggiornano solo al successivo snapshot.
Una scrittura — chiude e apre
Questa è la proprietà che definisce lo snapshot rbAmp. Un singolo comando di snapshot fa contemporaneamente:
- Chiude il periodo appena terminato (i suoi dati → snapshot)
- Apre il periodo successivo (live ← 0)
Il master ha bisogno di una sola scrittura per misura, non due (come in una semplice implementazione « avvio → arresto → lettura »).
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::latchPeriod() / RbAmp::isPeriodValid() |
invii il comando di snapshot; controlli il flag di validità |
| ESP-IDF | rbamp_latch_period() / rbamp_is_period_valid() |
invii il comando di snapshot; controlli il flag di validità |
| Python | dev.latch_period() / dev.is_period_valid() |
invii il comando di snapshot; controlli il flag di validità |
| ESPHome | update_interval: |
ogni aggiornamento chiude il periodo; il comando di snapshot e l'assestamento sono gestiti dal componente |
Ciclo di polling continuo (consigliato)
master chip
------ ----
accumulator running since boot...
write CMD_LATCH (0x27) ────► snapshot ← live (since-boot — DISCARD)
live ← 0, period_start = T0
t0 = master.clock() ◄──── first snapshot — primer (discard)
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T0..T1] — KEEP)
live ← 0, period_start = T1
t1 = master.clock()
read avg_p_W @ 0xDC ────► float32 LE
E1_Wh = avg_p × (t1 − t0) / 3600
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T1..T2] — KEEP)
live ← 0, period_start = T2
t2 = master.clock()
read avg_p_W
E2_Wh = avg_p × (t2 − t1) / 3600
...and so on. t1 is both the end of period 1 and the start of period 2.
Il primo snapshot è un innesco (da scartare)
Il primo snapshot dopo l'avvio cattura tutto ciò che l'accumulatore ha raccolto dall'accensione fino alla prima chiamata del master — una finestra di lunghezza indefinita, non adatta alla misura. Scarti il suo risultato. Dal secondo snapshot in poi i dati sono puliti e utilizzabili.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() |
snapshot, assestamento, verifica di validità e lettura in un'unica chiamata; begin() scarta il primo snapshot |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_begin() |
snapshot, assestamento, verifica di validità e lettura in una sola chiamata; begin scarta il primo snapshot |
| Python | dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() |
snapshot, assestamento, verifica di validità e lettura in un'unica chiamata; begin() scarta il primo snapshot |
| ESPHome | update_interval: / latch_interval: |
cadenza di aggiornamento del ciclo di snapshot; cadenza di snapshot separata facoltativa |
Registri dello snapshot del periodo
| Indirizzo | Nome | Tipo | Quando leggere | Descrizione |
|---|---|---|---|---|
0x07 |
PERIOD_VALID |
u8 | legga prima | bit0 = 1 se lo snapshot è recente e valido, 0 se obsoleto (race o snapshot prematuro) |
0xDC..0xDF |
PERIOD_AVG_P_W[0] |
float32 LE | primario | PRODUZIONE — P_real medio del canale I0 sul periodo (W) |
0xC2..0xC5 |
PERIOD_AVG_P_W[1] |
float32 LE | UI2/UI3 | P_real medio del canale I1 |
0xC6..0xC9 |
PERIOD_AVG_P_W[2] |
float32 LE | UI3 | P_real media del canale I2 |
: lo stesso snapshot congela anche le medie per canale — legga 0xC2 (ch1) / 0xC6 (ch2) nello stesso passaggio e moltiplichi per lo stesso dt: e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | opzionale | P_real di picco durante il periodo (per le tariffe a potenza impegnata) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | solo diagnostica | Visione del chip del dt tra gli snapshot — può risultare bassa sotto carico; usi PERIOD_COMMIT_COUNT × la lunghezza del commit per la lunghezza della finestra lato modulo | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | misura della finestra | Numero di commit RT nel periodo chiuso. Un commit = 0.1 s dalla v1.2; 0.2 s sulle immagini più vecchie — count × 0.1 s (oppure × 0.2 s) è la misura propria del modulo della lunghezza della finestra. Vedi la sezione sulla deriva del clock per capire quale si applica
Accumulatori di esportazione
| Indirizzo | Nome | Tipo | Descrizione |
|---|---|---|---|
| — | — | La mappa BASIC non ha accumulatori di esportazione (direzione negativa); su STD l'energia è gestita diversamente — vedi la documentazione STD |
Sui moduli BASIC non ci sono registri di esportazione; le letture da un indirizzo non mappato restituiscono 0x00 (il firmware non risponde mai con NACK alle letture — vedi capitolo 11 §5.2). Un master che ha bisogno del tracciamento dell'esportazione su BASIC ricorre alla contabilità basata su RT (vedi arduino-examples.md → Esempio 5).
Nelle librerie client — la stessa operazione senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
potenza media e di picco del periodo chiuso |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
potenza media e di picco del periodo chiuso |
| Python | dev.read_period_avg_power(ch=0) / dev.read_period_max_power() |
potenza media e di picco del periodo chiuso |
| ESPHome | update_interval: |
il componente legge le medie di periodo a ogni aggiornamento |
Algoritmo lato master
Ciclo base (un modulo, periodo di 60 secondi)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
// 1. Primer snapshot (discard result)
rb_write_u8(RB_ADDR, 0x01, 0x27);
}
void loop() {
static uint32_t t_prev = millis();
delay(60000); // wait 60 seconds
// 2. Final snapshot — closes [t_prev, now]
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50); // firmware finishes in ~5 ms; allow margin
// 3. Check PERIOD_VALID
uint8_t valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
// Race or premature snapshot — retry
delay(250);
rb_write_u8(RB_ADDR, 0x01, 0x27);
t_now = millis();
delay(50);
valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
Serial.println("WARN: two stale snapshots in a row");
t_prev = millis();
return;
}
}
// 4. Read the snapshot
float avg_p = rb_read_float_le(RB_ADDR, 0xDC);
float max_p = rb_read_float_le(RB_ADDR, 0xE0);
// 5. Compute energy on master clock
float dt_s = (t_now - t_prev) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[+%5.1fs] E=%.3f Wh avg_P=%.1f W max_P=%.1f W\n",
dt_s, e_wh, avg_p, max_p);
t_prev = t_now;
}
Cosa è essenziale in questo codice
- Il primo snapshot è un innesco — il suo risultato viene scartato.
PERIOD_VALIDva letto PRIMA di usare lo snapshot — altrimenti dati obsoleti possono passare in caso di race.- dt è misurato sul master, non ricavato da
PERIOD_LATCH_MS— il registro del chip serve solo per la diagnostica della deriva. t_prevsi aggiorna al t_now di uno snapshot riuscito, non all'inizio originale del periodo — così la catena resta continua senza lacune.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) |
totale Wh in corso mantenuto sull'host; azzera l'accumulatore |
| ESP-IDF | rbamp_energy_wh() / rbamp_energy_reset() |
totale Wh in corso mantenuto sull'host; azzera l'accumulatore |
| Python | dev.energy.wh(ch) / dev.energy.reset(ch) |
totale Wh in corso mantenuto sull'host; azzera l'accumulatore |
| ESPHome | energy |
sensore di energia integrato dal componente |
Contabilità bidirezionale
Su un modulo BASIC i registri PERIOD_AVG_P_NEG_W non sono allocati (le letture restituiscono 0x00), e PERIOD_AVG_P_W è sempre ≥ 0 (i campioni negativi vengono esclusi dall'accumulatore).
Cosa significa la contabilità bidirezionale
Il chip integra due accumulatori separati per periodo:
- Consumo: integrale di
max(P, 0) × dt— solo potenza positiva. - Esportazione: integrale di
max(−P, 0) × dt— solo potenza negativa, in valore assoluto.
La somma di entrambi dà l'energia totale che è passata dal contatore in valore assoluto; la differenza è il consumo netto (ciò che mostrerebbe un contatore meccanico a disco).
Applicazioni
- Abitazioni con pannelli solari: consumo ed esportazione sono fatturati con tariffe diverse (tariffa di immissione)
- Impianti con accumulo a batteria: monitoraggio dei cicli di carica/scarica
- Turbine eoliche, carichi rigenerativi, caricatori EV V2G
Dove vive la misura bidirezionale
I prodotti bidirezionali (consumo + esportazione) appartengono alla linea rbAmp STD, che usa una mappa di registri diversa, a 16 bit, con contatori di energia con segno sul dispositivo — vedi la documentazione di riferimento STD. Nella mappa BASIC a 8 bit descritta in questo capitolo non ci sono registri di esportazione.
// BASIC-map period accounting, 60-second period (consumption only)
void loop() {
static uint32_t t_prev = millis();
delay(60000);
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if ((rb_read_u8(RB_ADDR, 0x07) & 0x01) == 0) {
t_prev = millis();
return;
}
float avg_p_consume = rb_read_float_le(RB_ADDR, 0xDC); // ≥ 0
float dt_s = (t_now - t_prev) / 1000.0f;
float e_consume_wh = avg_p_consume * dt_s / 3600.0f;
Serial.printf("[%.1fs] consume=%.3f Wh\n", dt_s, e_consume_wh);
t_prev = t_now;
}
Ciò che non è disponibile su BASIC
Se possiede un modulo di livello BASIC e le serve la contabilità bidirezionale, ha due opzioni:
- Integrazione lato master — legga RT
P_real(0xA6) a ogni finestra di misura (~100 ms dalla v1.2; 200 ms prima) e integri separatamente i campioni positivi e negativi lato master. Vedi l'Esempio 5 in arduino-examples.md. La precisione è leggermente inferiore (per la discretizzazione del campionamento), ma funziona su qualsiasi firmware.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) |
STD: contatori di importazione/esportazione sul dispositivo; BASIC: potenza con segno, suddivisa sull'host |
| ESP-IDF | rbamp_std_read_energy() / rbamp_read_power() (con segno) |
STD: contatori di importazione/esportazione sul dispositivo; BASIC: potenza con segno, suddivisa sull'host |
| Python | dev.read_std_energy() / dev.read_power(ch) |
STD: contatori di importazione/esportazione sul dispositivo; BASIC: potenza con segno, suddivisa sull'host |
| ESPHome | bidirectional: / energy_exported |
abiliti l'energia in esportazione; sensori di esportazione (BASIC pubblica 0) |
Varianti solo-I — la misura del periodo restituisce zero
Su I1/I2/I3 (e varianti solo-I superiori) senza sensore di tensione:
PERIOD_AVG_P_W[*]è sempre 0.0f — non c'è U, quindi non c'è nulla da integrare.PERIOD_VALIDcontinua a segnalare 1 (lo snapshot è valido, solo a zero).PERIOD_MAX_P_Wè anch'esso 0.
Per le varianti solo corrente la misura di periodo a bordo non fornisce una lettura di energia. Il master deve:
- Usi un proprio sensore di tensione e integri
I_rms × U_master × cos(φ)_master(più complesso; richiede la sincronizzazione di fase), oppure - Usi il modulo solo corrente esclusivamente per il monitoraggio della presenza di corrente, e lo abbini a un modulo UI* o a un misuratore esterno per l'energia.
Polling guidato dagli eventi o periodico
Periodico (stile cron)
Il master legge ogni N secondi con un timer:
// Once per hour
setInterval(60 * 60 * 1000, [](){
rb_write_u8(0x50, 0x01, 0x27);
// ... read snapshot, accumulate Wh
});
Adatto alla misura tariffaria classica (1 minuto, 15 minuti, 1 ora).
Guidato dagli eventi
Il master emette uno snapshot quando si verifica un evento esterno:
- Un impulso dal contatore elettronico del gestore (controllo incrociato)
- Un cambio di tariffa (punta / fuori punta)
- Una domanda dell'utente (« quanto ho consumato finora? »)
void on_tariff_change() {
rb_write_u8(0x50, 0x01, 0x27); // close the period under the old tariff
delay(50);
if (rb_read_u8(0x50, 0x07) & 0x01) {
float avg_p = rb_read_float_le(0x50, 0xDC);
save_period_to_tariff_a_bucket(avg_p, current_dt_s);
}
// the next period accumulates into bucket B
}
Riavvio del periodo
Per scartare l'accumulatore live e ripartire da zero, esegua uno snapshot in più e ne ignori il risultato:
void restart_period() {
rb_write_u8(0x50, 0x01, 0x27); // close current + start new
// do not read the snapshot — discard
}
Dopodiché riprenda da zero il normale ciclo di snapshot.
Rilevamento del riavvio di un modulo
Un riavvio del modulo (calo di alimentazione, watchdog) azzera in silenzio l'accumulatore attivo, quindi il successivo snapshot copre una finestra indefinita — proprio come il primo snapshot dopo l'avvio. Il modulo espone:
| Indirizzo | Nome | Tipo | Descrizione |
|---|---|---|---|
0x46..0x49 |
UPTIME_S |
u32 LE | Contatore di uptime proprio del modulo (in secondi dall'avvio, nominalmente). Solo rilevatore di riavvio — sul firmware fino alla 1.4.21 va più lento del tempo reale (misurato 0.58–0.80×); non lo usi mai come orologio o per calcoli temporali |
0x4A |
RESET_CAUSE |
u8 | Flag della causa di reset: bit0 pin esterno, bit1 accensione/brown-out, bit2 software, bit3/bit4 watchdog. Solo per il logging |
Verifichi a ogni snapshot — il modulo si è riavviato all'interno del periodo se:
UPTIME_Sè diminuito dal suo snapshot precedente, oppureUPTIME_Sè inferiore al tempo trascorso dal precedente snapshot (sul clock del master).
Poiché il contatore può andare lento, il secondo controllo può occasionalmente segnalare un riavvio che non c'è stato (poco dopo un vero avvio) — è innocuo: scarta un periodo in più come innesco. Consideri UPTIME_S rigorosamente come questo discriminatore di riavvio, non come fonte di tempo.
Al rilevamento di un riavvio, scarti lo snapshot di quel periodo (lo tratti come un nuovo innesco), riconfermi il modello CT se usa un modello non di fabbrica sul firmware precedente alla 1.4.20 (bit 12 di CAPABILITY a zero) (initialization.md → Cosa persiste dopo un riavvio), e reinizializzi qualsiasi configurazione solo-RAM — vedi capitolo 11 (bit di evento RESET_OCCURRED). RESET_CAUSE non cambia la gestione; lo registri e vada avanti.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpPeriodSnapshot::module_restarted |
flag di riavvio nel risultato del periodo (percorso del contatore STD) |
| ESP-IDF | rbamp_read_uptime_s() / module_restarted |
legga l'uptime del modulo; flag di riavvio nel risultato del periodo |
| Python | — | non esposto — nessuna chiamata dedicata per il rilevamento dei riavvii su BASIC |
| ESPHome | — | non esposto — nessuna opzione di rilevamento riavvio nel YAML |
Multi-modulo — snapshot simultaneo
Se il master vuole snapshot sincroni da tutti i moduli (per un bilancio energetico istantaneo della casa), ci sono due approcci.
Approccio 1 — snapshot sequenziale (semplice)
Il master fa lo snapshot di ciascun modulo a turno:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev[] = {0, 0, 0};
void setup() {
Wire.begin();
// Primer
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
t_prev[i] = millis();
}
}
void loop() {
delay(60000);
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float dt_s = (t_now - t_prev[i]) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh\n", modules[i], e_wh);
t_prev[i] = t_now;
}
}
}
Svantaggio: gli istanti degli snapshot differiscono di alcuni millisecondi. Per un periodo di 60 secondi l'errore è < 0.1 % — trascurabile.
Approccio 2 — snapshot broadcast via general call (preciso, su attivazione)
L'indirizzo general-call I²C 0x00 è un pacchetto che tutti gli slave ricevono simultaneamente. rbAmp accetta un frame canonico di 5 byte sull'indirizzo general-call che attiva CMD_LATCH_PERIOD su ogni modulo con la ricezione GC abilitata. GC è da attivare per modulo tramite FLEET_CONFIG.bit0 (predefinito OFF) — vedi initialization.md per la sequenza di abilitazione e il formato dei frame.
// Canonical 5-byte GC frame: A5 27 group tick_lo tick_hi.
// Returns true on ACK, false on bus-level NACK (no module has GC enabled).
bool broadcast_latch(uint16_t tick16, uint8_t group = 0) {
Wire.beginTransmission(0x00); // general call
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(group); // group_id (0 = all-call)
Wire.write((uint8_t)(tick16 & 0xFF)); // tick_lo
Wire.write((uint8_t)((tick16 >> 8) & 0xFF)); // tick_hi
return Wire.endTransmission() == 0;
}
Il master mantiene un contatore tick a 16 bit che si incrementa a ogni broadcast. Ogni modulo riporta l'ultimo tick accettato in GC_TICK (0x59), così il master può rilevare un broadcast perso su un modulo specifico.
Dopo lo snapshot in broadcast il master legge lo snapshot di ciascun modulo al suo indirizzo individuale. Controlli sempre il valore di ritorno — in caso di NACK il frame GC non è arrivato (nessun modulo ha la GC attiva), e il master deve ricadere sullo snapshot sequenziale per modulo:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev;
uint16_t gc_tick = 0;
void setup() {
Wire.begin();
if (!broadcast_latch(gc_tick++)) {
// Fall back: per-module sequential snapshot.
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
t_prev = millis();
}
void loop() {
delay(60000);
if (!broadcast_latch(gc_tick++)) {
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
uint32_t t_now = millis();
delay(50);
float dt_s = (t_now - t_prev) / 1000.0f;
for (int i = 0; i < 3; i++) {
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh P_avg=%.1f W\n",
modules[i], e_wh, avg_p);
}
}
t_prev = t_now;
}
Vantaggio: sincronizzazione precisa — gli snapshot vengono presi nello stesso istante su tutti i moduli con GC abilitato, entro pochi microsecondi.
Caso d'uso: critico per il bilanciamento istantaneo (per esempio consumo_casa − esportazione_solare in un dato momento).
per modulo tramite FLEET_CONFIG.bit0 (predefinito OFF su un modulo nuovo). Se OFF, lo slave risponde con NACK al frame general-call e il master ripiega automaticamente sullo snapshot sequenziale per modulo. Vedi initialization.md — General Call (broadcast all'indirizzo 0x00) — per la sequenza di abilitazione e il formato dei frame.
Un accumulatore, due trigger. Lo snapshot indirizzato (0x27 all'indirizzo proprio del modulo) e lo snapshot in broadcast azzerano lo stesso accumulatore di periodo — ce n'è uno solo per modulo. Scelga un metodo per modulo per il ciclo regolare; uno snapshot extra con l'altro metodo interrompe in anticipo il periodo in corso. I modelli di ripiego sopra sono sicuri perché si attivano solo quando il broadcast non è arrivato su quel modulo.
Nelle librerie client — la stessa operazione senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) |
frame di snapshot broadcast a tutta la flotta; legga ogni modulo dopo uno snapshot esterno |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) |
frame di snapshot broadcast a tutta la flotta; legga ogni modulo dopo uno snapshot esterno |
| Python | fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) |
frame di snapshot broadcast a tutta la flotta; legga ogni modulo dopo uno snapshot esterno |
| ESPHome | fleet_gc_enable: / group_id: |
Opzioni YAML per l'attivazione della General Call e l'ID di gruppo |
Scegliere la durata del periodo
| Applicazione | dt consigliato |
|---|---|
| Cruscotto UI in tempo reale | 1 s (oppure legga direttamente la P_real RT) |
| Grafico di tendenza, risoluzione di 1 minuto | 60 s |
| Misura del picco di domanda a 15 minuti | 900 s |
| Misura oraria | 3600 s |
| Totali giornalieri | Accumuli gli snapshot orari sul master; non lasci che un singolo periodo superi 1 ora |
Periodi più lunghi di 1 ora sono consentiti e nulla va in overflow — l'accumulatore continua a mediare finché non arriva uno snapshot. Ciò che si degrada su una finestra molto lunga è la precisione della media: nel caso peggiore ≈ 0.2 % a 1 ora, 1.3 % a 6 ore, 5 % a 24 ore. Per questo mantenga i singoli periodi ≤ 1 ora e accumuli i totali più lunghi sul master.
PERIOD_MAX_P_W — picco di domanda
Il registro 0xE0 riporta la potenza massima osservata in una qualsiasi finestra RT all'interno del periodo. Usi:
- Tariffe a picco di domanda: i gestori fatturano la domanda più alta di 15 minuti del mese per le quote di capacità.
- Rilevamento dello spunto: l'avvio dei motori produce un picco di 5–10× la nominale —
max_P >> avg_Psegnala l'evento. - Controllo di buon senso: se
max_Psupera di moltoavg_P, il carico è a raffiche — normale per molti scenari domestici, ma è un segnale da verificare se ci si aspetta un carico stabile.
L'atomicità è garantita
CMD_LATCH_PERIOD viene eseguito con gli interrupt disabilitati durante la copia dello snapshot (alcuni microsecondi). Il master non può mai leggere uno snapshot a metà aggiornamento — anche se legge i byte subito dopo la scrittura, il firmware termina l'aggiornamento del blocco prima che si concluda la successiva transazione I²C (passano almeno 10+ µs tra scrittura e lettura).
La stessa atomicità lega il reset dell'accumulatore alla copia dello snapshot — ogni campione P è in esattamente uno snapshot (quello del periodo precedente o del successivo), mai in entrambi, mai in nessuno.
Cosa il master NON deve fare
- ❌ Non calcoli
U_rms × I_rms × dt— è energia apparente (VAh), non Wh. La potenza apparente include il contenuto reattivo e sovraccarica ogni carico induttivo. UsiPERIOD_AVG_P_W. - ❌ Non dedurre la direzione da
I_rms— l'RMS è sempre ≥ 0. La direzione sta nel segno diP_real. - ❌ Non usi
PERIOD_LATCH_MSper i Wh — quel registro è diagnostico e può derivare con il clock del chip.master_dtfa fede. - ❌ Non faccia snapshot più rapidi del ciclo di commit RT. Il chip ha bisogno di almeno un periodo di rete (~20 ms a 50 Hz) di accumulo più l'assestamento — minimo 50 ms tra un
CMD_LATCH_PERIODe il successivo. Snapshot più frequenti producono uno snapshot vuoto (PERIOD_VALID = 0). 200 ms è una soglia pratica sicura per il polling a regime; vedi capitolo 11 §6.0 / §6.4.
Diagnostica della deriva del clock
PERIOD_LATCH_MS è un registro solo diagnostico — la base dei tempi interna del modulo legge valori bassi quando il modulo è occupato. Il controllo incrociato deve usare un intervallo ampio:
uint32_t chip_dt = rb_read_u32(0x50, 0xEC);
uint32_t master_dt = t_now - t_prev;
float ratio = (float)chip_dt / (float)master_dt;
if (ratio < 0.70f || ratio > 1.05f) {
Serial.printf("WARN: chip drift outside ±30%% envelope, ratio=%.3f\n", ratio);
}
Accettazione: fino al 30 % di sottostima sotto carico è normale (rapporto fino a ~0.70). È una scelta di progetto — vedi troubleshooting.md §13. Non usi una soglia stretta del 3 %–5 %; scarterebbe in massa moduli sani.
Questa deriva non influisce sulla precisione dei Wh (i Wh usano il clock del master); PERIOD_LATCH_MS serve solo a segnalare anomalie gravi lato chip.
Quando vuole la misura propria del modulo della lunghezza della finestra chiusa, usi PERIOD_COMMIT_COUNT (registro 0xBE) per la lunghezza del commit: conta i commit RT interi e non risulta bassa sotto carico come può accadere con PERIOD_LATCH_MS. Un commit è 0.1 s dalla v1.2; le immagini precedenti alla v1.2 usavano 0.2 s. Non serve una tabella di versioni per distinguerle: il rapporto PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT risulta vicino a 100 o vicino a 200.
Avanti
- troubleshooting.md — cosa fare quando i valori sembrano errati
- arduino-examples.md — Esempio 5 (bidirezionale lato master su firmware BASIC)