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:
-
04 · Cablaggio — dettagli hardware e sezioni per MCU ospite
-
03 · Selezione del sensore di corrente — quale modello SCT-013 scegliere e perché
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
arduino-cli lib install RbAmp
PlatformIO
[env:esp32dev]
platform = espressif32
framework = arduino
lib_deps = rbamp/RbAmp@^1.6.1
Passo 2 — Cablaggio
⚠ 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.
Passo 3 — Primo sketch (lettura RT)
Uno sketch minimo — verifica la comunicazione senza configurare il sensore:
#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):
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.
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():
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.
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:
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:
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):
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
}
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:
- Invia al modulo un comando di snapshot di periodo.
- Attende 50 ms mentre il modulo prepara lo snapshot.
- Verifica il flag di pronto; legge la potenza media/di picco.
- 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:
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
- 01 · Panoramica — che cos'è rbAmp e che cosa fa la libreria
- 02 · Livelli del modulo — quale livello si adatta a quale compito
-
06 · Esempi — scenari di lavoro: rete + N carichi secondari (il canone 80%), flusso di provisioning, canali misti multi-canale con CT, sincronizzazione GC della flotta, MQTT, deep sleep
-
07 · Integrazioni fai-da-te — Home Assistant / Node-RED / OpenHAB
-
08 · Integrazioni cloud — AWS IoT / Azure / GCP / InfluxDB
-
09 · Riferimento API — l'API pubblica completa (incluso
RbAmpFleet+ multicanale + modello di errore v1.3 + identità e provisioning) -
10 · Risoluzione dei problemi — quando qualcosa non funziona (mitigazione a tre livelli per il blocco i2c, modalità di guasto di conflitto / blocco / provisioning della flotta)
Sorgente e segnalazioni: rb-amp/rbamp-arduino · questa pagina nel repository: docs/05_quickstart.md (v1.6.2)