rbAmp
IT
Negozio
Docs
Aggiornato

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

Perché lo snapshot del periodo è usato oltre alla finestra di misura.

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

Text
E_Wh = avg_P_W × master_dt_seconds / 3600

Where:

  • avg_P_W — il valore di PERIOD_AVG_P_W, letto dopo CMD_LATCH_PERIOD.
  • master_dt_seconds — i secondi trascorsi tra due snapshot successivi, misurati dal master.

Periodo atomico — concetto

Come un singolo comando di snapshot congela lo snapshot del periodo e apre il periodo successivo.

Cosa fa il comando

Scrivere 0x27 in REG_COMMAND = 0x01 attiva una sequenza atomica nel firmware (eseguita sotto __disable_irq()):

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

Nelle librerie client

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

Nelle librerie client

— 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
Energia per canale (UI2/UI3)

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

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)

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

  1. Il primo snapshot è un innesco — il suo risultato viene scartato.
  2. PERIOD_VALID va letto PRIMA di usare lo snapshot — altrimenti dati obsoleti possono passare in caso di race.
  3. dt è misurato sul master, non ricavato da PERIOD_LATCH_MS — il registro del chip serve solo per la diagnostica della deriva.
  4. t_prev si aggiorna al t_now di uno snapshot riuscito, non all'inizio originale del periodo — così la catena resta continua senza lacune.
Nelle librerie client

— 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

Nota

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

Come vengono contabilizzate l'energia sui moduli BASIC rispetto a quelli STANDARD (STD).

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.

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

  1. 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.
Nelle librerie client

— 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_VALID continua 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:

C++
// 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? »)
C++
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:

C++
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, oppure
  • UPTIME_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.

Nelle librerie client

— 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:

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

Uno snapshot broadcast che raggiunge tutti i moduli nello stesso momento tramite l'indirizzo general-call.

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

C++
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).

Lo snapshot broadcast è su attivazione

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
Nota

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_P segnala l'evento.
  • Controllo di buon senso: se max_P supera di molto avg_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. Usi PERIOD_AVG_P_W.
  • ❌ Non dedurre la direzione da I_rms — l'RMS è sempre ≥ 0. La direzione sta nel segno di P_real.
  • ❌ Non usi PERIOD_LATCH_MS per i Wh — quel registro è diagnostico e può derivare con il clock del chip. master_dt fa 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_PERIOD e 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:

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