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

05 · Avvio rapido

Un hello-world di cinque minuti: installi la libreria, colleghi il modulo, scelga un sensore, faccia la sua prima lettura RT e il primo snapshot per periodo (Wh).

I dettagli (piedinatura per un host specifico, bus multimodulo, scelta di un SCT-013 per intervallo) si trovano nei capitoli vicini:

Prima lettura in otto passi: collegamento, accensione, scansione di 0x50, begin(), configurazione facoltativa del sensore, lettura di U, I, P, PF, controllo di sanità, poi energia.

Cosa serve

  • Un modulo rbAmp (qualsiasi livello, UI1 per semplicità)
  • Un host compatibile con Arduino — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • Una pinza SCT-013 di portata superiore alla sua corrente massima attesa (5A / 10A / 30A / 50A / 100A) — oppure il TA che è arrivato collegato al suo modulo
  • Un'alimentazione a 5 V per il modulo (dal USB-5V dell'host o da alimentazione esterna)
  • Un circuito CA da misurare (una lampada, un bollitore, un elettrodomestico)

Passo 1 — Installi la libreria

Arduino IDE — Gestore librerie

Sketch → Include Library → Manage Libraries… → cercare RbAmp → Install. Non ci sono dipendenze. Dopo l'installazione gli esempi compaiono in File → Examples → RbAmp. (Gestore librerie: Library Manager; Installa: Install)

Arduino CLI

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

Passo 2 — Cablaggio

Sicurezza

⚠ La tensione di rete può essere letale. Scollegare e bloccare il circuito prima di collegare i morsetti L/N o montare la pinza; affidare il cablaggio di rete e qualsiasi lavoro dentro un quadro a una persona qualificata. Stringere UN solo conduttore (L) — mai l'intero cavo (L+N si annullano a ~0). Proteggere la derivazione L secondo le norme locali.

Quattro fili a bassa tensione più un DRDY opzionale, poi i morsetti di rete:

Pin rbAmp Host
VCC +5 V (intervallo 4.5..5.5 V)
GND GND
SDA SDA I²C (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (facoltativo) saltarlo per il primo sketch; vedi 04_hardware.md
Morsetti L, N lo stesso circuito che alimenta il carico da misurare (lato rete — vedi l'avvertenza sopra)
Connettore CT Spina SCT-013 inserita fino in fondo

L'alimentazione deve essere 5 V. Le linee I²C lavorano a logica 3.3 V ma sono tolleranti a 5 V — le colleghi direttamente a un Arduino UNO senza convertitore di livello. La scheda del modulo ha già resistenze di pull-up integrate da 4.7 kΩ — per un singolo modulo non servono quelle esterne.

La tabella completa dei pinout per ciascuna scheda Arduino è in 04 · Cablaggio.

La pinza SCT-013 si inserisce attorno al solo conduttore di linea (L), con la freccia sul corpo della pinza che punta nella direzione della corrente verso il carico. Per maggiori dettagli (sezione "Sensore di corrente") vedere il capitolo 04 · Cablaggio.

Collegamento lato rete: la pinza TA sul solo filo L con la freccia verso il carico, e la derivazione di riferimento di tensione L/N.

Passo 3 — Primo sketch (lettura RT)

Uno sketch minimo — verifica la comunicazione senza configurare il sensore:

C++
#include 
#include 

RbAmp dev(Wire, 0x50);  // default address 0x50

void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }

    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz — required for retry discipline
#endif

    while (!dev.begin()) {
        Serial.print(F("rbAmp begin failed: "));
        Serial.println(dev.errorString());
        delay(1000);
    }

    // v1.3: auto-detect the variant via REG_HW_VARIANT — more accurate than
    // the constructor topology hint (which is now a fallback for legacy fw).
    uint8_t variant = static_cast(dev.readVariant());
    Serial.print(F("Module ready, variant="));
    Serial.println(variant);   // 1=UI1, 4=I1, 5=I2, 6=I3
}

void loop() {
    Serial.print(F("U=")); Serial.print(dev.readVoltage(), 1);
    Serial.print(F("V  I=")); Serial.print(dev.readCurrent(0), 3);
    Serial.print(F("A  P=")); Serial.print(dev.readPower(0), 1);
    Serial.print(F("W  PF=")); Serial.println(dev.readPowerFactor(0), 3);
    delay(1000);
}

Caricare lo sketch e aprire il Monitor seriale (Serial Monitor) a 115200 baud.

Output atteso (senza calibrazione del sensore):

Text
Module ready, variant=1
U=230.4V  I=0.000A  P=0.0W  PF=nan
U=230.4V  I=0.000A  P=0.0W  PF=nan

PF può stampare nan, 0.000 o un altro segnaposto mentre la corrente è zero.

Sicurezza

U mostra più o meno la tensione di rete (220-240 V su reti a 230 V) — il che significa che il modulo è collegato correttamente. I=0.000 A anche con il carico acceso è normale in questa fase: il modulo non sa ancora quale pinza TA è in uso. Con I=0, PF è matematicamente indefinito (dipende dal firmware — può essere NaN, 0 o un segnaposto) — la forma esatta del valore non conta finché la corrente è zero. Il passo successivo lo risolve.

Passo 4 — Configurazione del sensore di corrente

Se ha montato una pinza TA SCT-013 separata, deve indicare al modulo la classe e il modello del sensore. Senza questo i coefficienti di calibrazione non vengono caricati e le letture di corrente restano a zero. Se il modulo è arrivato con il suo TA già collegato, salti questo passo.

Leggere il modello dall'etichetta stampata sulla pinza (ad esempio SCT-013-030 → codice 3, vedi la tabella sotto). Scegliere la pinza di portata minima più grande della corrente massima prevista. Una pinza di portata troppo piccola dà letture tosate e troppo basse ai picchi; una di portata molto superiore dà letture rumorose e imprecise a piccole correnti.

Aggiungere questo a setup() dopo dev.begin(). La funzione loop() resta la stessa del Passo 3 — cambia solo setup():

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif

    while (!dev.begin()) { delay(500); }

    // Step 1: sensor class. SCT-013 = the clip-on clamp you fitted.
    if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
        Serial.print(F("setSensorClass failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    // Step 2: model. For example, SCT-013-030 for a household feed up to ~7 kW.
    if (!dev.setCTModel(RbAmpCTModel::Sct013_030)) {
        Serial.print(F("setCTModel failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    Serial.println(F("Ready."));
}

Codici modello — l'insieme accettato è {1, 2, 3, 4, 5, 6, 7}:

code Modello Intervallo Stato Uso tipico
1 SCT-013-005 0..5 A ✅ selezionabile Piccoli carichi, una sola presa
2 SCT-013-010 0..10 A ✅ selezionabile Frigorifero, lavatrice
3 SCT-013-030 0..30 A ✅ selezionabile Alimentazione domestica fino a ~7 kW
4 SCT-013-050 0..50 A ✅ selezionabile Caricatore EV, riscaldamento elettrico
5 SCT-013-100 0..100 A ✅ selezionabile Ingresso principale del servizio, dorsali grandi
6 SCT-013-020 0..20 A ✅ selezionabile Alimentazione media — elettrodomestici da 3-4 kW
7 SCT-013-060 0..60 A ✅ selezionabile Sotto-contatore industriale

Per approfondire la selezione vedi 03 · Selezione del sensore di corrente.

Nota

Queste due chiamate si eseguono una sola volta alla prima installazione — la scelta viene salvata nella flash del modulo e sopravvive a un reset. Il tempo totale è di circa 1.4 secondi (due scritture in flash × ~700 ms ciascuna). La libreria serializza internamente entrambe le chiamate — ciascuna si blocca fino al completamento della scrittura in flash, quindi non serve aggiungere un delay() tra le due: la seconda attende da sola che la prima rilasci.

Nelle esecuzioni successive dello sketch si possono saltare setSensorClass() e setCTModel() (il modulo ricorda). Ma non c'è danno nel richiamarli — una chiamata ripetuta con lo stesso valore riscrive lo stesso byte.

Dopo il riavvio dello sketch deve comparire il valore di corrente corretto:

Text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

Passo 5 — Contabilizzazione dell'energia (Wh)

Il modulo restituisce solo grandezze istantanee più la potenza media su un periodo. La libreria stessa calcola i Wh dall'orologio del master:

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]     [seconds]     →  [Wh]

dove master_dt_s è il numero di secondi tra due chiamate di readPeriodSnapshot() riuscite.

Un modello minimo di contabilizzazione periodica (una volta al minuto):

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif
    while (!dev.begin()) { delay(500); }
    dev.setSensorClass(RbAmpSensorClass::Sct013);
    dev.setCTModel(RbAmpCTModel::Sct013_030);
    Serial.println(F("Period meter started; the first line covers only the time since begin() — ignore it..."));
}

void loop() {
    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) {
        Serial.print(F("snapshot error: "));
        Serial.println(dev.errorString());
        delay(60000);
        return;
    }

    Serial.print(F("avg P for period: ")); Serial.print(snap.avg_p[0], 2);
    Serial.print(F(" W   accumulated: ")); Serial.print(dev.energy().wh(0), 4);
    Serial.print(F(" Wh   dt=")); Serial.print(snap.master_dt_ms);
    Serial.println(F(" ms"));

    delay(60000);  // the 60-second period sits at the END of loop — the first
                   // snapshot is taken right after setup() and covers only the
                   // seconds since begin(); full periods follow
}
Nota

Dopo il passo 4, setSensorClass() e setCTModel() sono già stati eseguiti una volta e salvati nella flash del modulo; nel modello sopra sono presenti per le riesecuzioni dello sketch — il modulo ignora una chiamata ripetuta con lo stesso valore. La gestione degli errori è omessa per brevità — aggiungere guardie if (!...) se si vogliono intercettare i rari disturbi di comunicazione all'avvio.

Cosa fa readPeriodSnapshot() sotto il cofano:

  1. Invia al modulo un comando di snapshot di periodo.
  2. Attende 50 ms mentre il modulo prepara lo snapshot.
  3. Verifica il flag di pronto; legge la potenza media/di picco.
  4. Aggiorna il contatore Wh interno: += avg_p × master_dt_s / 3600.

begin() esegue già un primo snapshot che la libreria scarta. Il primo readPeriodSnapshot() nello sketch copre quindi solo il tempo trascorso da begin() (pochi secondi, vedi dt= nell'output): ignorare quella prima riga e attendere un periodo completo. Dalla seconda chiamata in poi, ogni riga copre un periodo completo.

Output atteso:

Text
avg P for period: 119.90 W   accumulated: 0.1332 Wh   dt=4000 ms    <- short first period, ignore
avg P for period: 120.18 W   accumulated: 2.1368 Wh   dt=60012 ms
avg P for period: 120.21 W   accumulated: 4.1405 Wh   dt=60005 ms
...

Più moduli

Per più moduli su un bus (alimentazione principale + carichi secondari) usi RbAmpFleet. L'esempio completo è in 06 · Esempi, scenario 1; le regole di cablaggio per un bus multimodulo sono in 04 · Cablaggio.

Cosa segue


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