rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub [Edit on GitHub]

02 · Livelli dei moduli

Le linee di moduli BASIC e STANDARD (STD) affiancate: energia sul master per il BASIC, sul modulo per lo STD.

Che cosa è una linea di moduli

Controlli l'etichetta del suo modulo; dev.line() stampa la linea dopo begin().

rbAmp è disponibile in linee di moduli: BASIC e STANDARD (STD). Una linea di moduli è un accoppiamento completo di revisione hardware e firmware, non un flag software. Passare da una linea all'altra richiede un cambio fisico di SKU, non un aggiornamento del firmware.

Dal punto di vista della libreria e del suo codice: una sola classe RbAmp serve entrambe le linee di produzione. begin() rileva se un modulo è BASIC o STANDARD (STD) e instrada internamente ogni chiamata; i metodi comuni (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) funzionano su entrambi. La linea STD aggiunge chiamate proprie — potenza reattiva e apparente, letture di blocco per canale, contatori di energia vita cumulativa con segno — vedere 09 · Riferimento API.

Stato attuale

Il livello BASIC e la linea STANDARD (STD) sono linee di moduli in commercio; questa libreria supporta entrambe (STANDARD (STD) dalla libreria 1.6.0, vedere il README).

Livello Spedizione
BASIC ✅ sì
STANDARD (STD) ✅ sì (libreria 1.6.0+)

BASIC — livello di ingresso per la misura domestica

Hardware

Un percorso analogico a basso costo adatto ai carichi domestici tipici. Il modulo include un front-end analogico isolato, un regolatore di alimentazione a bordo e una calibrazione di fabbrica memorizzata in flash.

Comportamento del firmware

La logica di un classico contatore meccanico a disco — il conteggio va solo in avanti; l'esportazione verso la rete non viene sottratta.

I tre "livelli" dei valori di potenza attiva si comportano in modo diverso:

Segnale Significato Comportamento su BASIC
dev.readPower(ch) potenza RT istantanea, aggiornata ogni ~100 ms con segno — un valore negativo è visibile in tempo reale (esportazione)
PERIOD_AVG_P_W (dentro readPeriodSnapshot) potenza media sul periodo la media P di ogni finestra da 100 ms è limitata a max(P, 0) prima di essere sommata all'accumulatore del periodo
dev.energy().wh(ch) Wh accumulati dalla libreria monotono — solo consumo; l'esportazione non viene conteggiata

In altre parole: l'utente vede l'esportazione nella lettura RT, ma essa manca dal contatore Wh della libreria sul BASIC.

Casi d'uso tipici

  • Abitazioni senza generazione in loco (senza pannelli solari, turbine eoliche o sistemi a batteria)

  • Contatori secondari per carichi puramente consumatori (scaldabagni, motori, elettrodomestici)

  • Monitoraggio dei consumi di un edificio dove la misura bidirezionale non è richiesta

Misura bidirezionale sul BASIC (lato master)

Contabilità dell'energia sul BASIC (consumo sul modulo, esportazione integrata sul master) e sullo STANDARD (STD) (contatori di importazione, esportazione e netto sul modulo).

Se deve tenere traccia separatamente dell'esportazione verso la rete su un modulo BASIC, lo faccia lato master. La potenza RT dev.readPower(0) è con segno, quindi:

C++
double consume_wh = 0.0;
double export_wh  = 0.0;
uint32_t t_prev_ms = millis();

void loop() {
    // Sample RT power at 10 Hz — matches the firmware-commit cadence
    // (100 ms per channel). Faster gives empty repeat reads; slower
    // loses resolution on abrupt load transitions.
    //
    // delay() blocks the loop — incompatible with concurrent work
    // (LCD refresh, MQTT, networking). For sketches with other tasks,
    // replace it with a non-blocking millis() / scheduler pattern.
    delay(100);
    uint32_t t_now_ms = millis();
    float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    float p = dev.readPower(0);
    if (isnan(p)) return;

    double dwh = (double)p * dt_s / 3600.0;
    if (p >= 0) consume_wh += dwh;
    else        export_wh  += -dwh;
}

Un esempio completo funzionante è in 06_examples.md (lo scenario BidirectionalEnergy) e in examples/06_BidirectionalEnergy/.

STANDARD (STD) — linea bidirezionale

I moduli STANDARD (STD) sono una linea di moduli in commercio. La libreria li rileva in begin() (dev.line() == RbAmpLine::Std) e usa lo stesso cablaggio e la stessa API comune del BASIC (vedere 04 · Cablaggio).

Cosa aggiunge la linea STD

Su un modulo STD con contatori di energia persistenti, l'API per periodo/snapshot e l'energia provengono dai contatori del modulo stesso (le immagini STD più vecchie usano i banchi di snapshot del modulo); il modello CT su STD è solo un'etichetta e non imposta alcun guadagno.

  • Energia con segno: importazione ed esportazione sono contabilizzate separatamente. Sui moduli che conservano contatori vita persistenti, dev.energy() e readPeriodSnapshot() prendono i valori del modulo stesso (wh_net = importazione − esportazione), e stdReadEnergy() fornisce i contatori grezzi (Wh, mWh e, sulle immagini che li prevedono, µWh / µvarh).

  • Altre grandezze (su BASIC la potenza reattiva non è esposta da questa libreria): readReactivePower(ch), readApparentPower(ch), stdReadChannel(ch) (I / P / Q / S / PF / picco in una sola raffica) e, quando abilitati, valori basati sulle armoniche (THD, fattore di potenza di spostamento).

  • Moduli multi-canale / multi-tensione: il numero di canali proviene dal modulo; stdReadVoltage(v), totali per fase con stdReadTotals(k).

  • Diagnostica e assistenza: stdReadHealth(), orologio del modulo, cronologia e registro eventi, identificazione tramite UID, aggiornamento del firmware via I²C.

Tutto questo è elencato chiamata per chiamata in 09 · Riferimento API § API della linea STD.

Dipendenza dall'immagine.

Alcune funzioni STD dipendono dalla versione dell'immagine del modulo: contatori di energia a micro-risoluzione, corrente di avvio per l'energia, angoli di fase di tensione e sequenza di fase richiedono una versione dell'immagine di almeno 0x0001007B (dev.stdReadImageVersion()); su un'immagine più vecchia sono segnalate come "non disponibili". Le chiamate solo-STD su un modulo BASIC restituiscono RB_ERR_NOT_IMPLEMENTED.

Casi d'uso tipici

  • Abitazioni con generazione solare sul tetto
  • Abitazioni con turbine eoliche
  • Sistemi di accumulo a batteria
  • Carichi rigenerativi
  • Ricarica EV vehicle-to-grid (V2G)

Come rilevare la linea a runtime

Come sapere quale linea di moduli possiede: legga l'etichetta oppure chiami line() dopo begin().

C++
if (!dev.begin()) { /* see dev.errorString() */ }

// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line();          // RbAmpLine::Basic / RbAmpLine::Std

// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();

// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();

// Number of current channels
uint8_t channels = dev.channels();

// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant();   // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
Nota

: line() indica BASIC o STANDARD (STD). Gli altri indicatori (versione del firmware, numero di canali, sensore di tensione, SKU) descrivono l'hardware. L'etichetta SKU sull'involucro del modulo resta la fonte autorevole per il prodotto.

Dove nella documentazione sono segnalate le voci che dipendono dal livello

In tutto il testo della libreria e nella documentazione canonica, le funzioni dipendenti dal livello sono segnalate esplicitamente, ad esempio:

solo STANDARD (STD)

— non disponibile su un modulo BASIC.

Oppure, al contrario, comportamento specifico del BASIC:

BASIC

: il contatore dev.energy().wh(ch) è monotono — l'esportazione verso la rete non viene conteggiata. Per la misura bidirezionale, vedere l'esempio BidirectionalEnergy o usi un modulo STANDARD (STD).

Cosa c'è dopo


Sorgente e segnalazioni: rb-amp/rbamp-arduino · questa pagina nel repository: docs/02_tiers.md (v1.6.2)