04 · Cablaggio
Questo capitolo tratta il collegamento fisico del modulo rbAmp a un host compatibile Arduino: piedinatura lato bassa tensione, requisiti di alimentazione, compatibilità dei livelli I²C, lunghezza del bus e schemi di cablaggio per schede Arduino specifiche (UNO, Mega, ESP32, ESP8266, STM32duino, RP2040).
Il lato bassa tensione (alimentazione + I²C + DRDY facoltativo) è isolato dai morsetti di rete. I morsetti di rete e il cablaggio lato TA sono collegati alla rete — veda l'avvertenza in "Cablaggio lato rete" più sotto.
Pinout lato LV
Il modulo funziona con logica I²C a 3.3 V ed è tollerante a 5 V sulle linee di segnale. Tutti i pin LV sono completamente isolati galvanicamente dalla rete.
| Pin | Segnale | Funzione |
|---|---|---|
VCC |
+5 V (4.5..5.5 V) | Alimentazione del modulo; minimo 4.5 V per il corretto funzionamento |
GND |
Terra | Condiviso con il master — obbligatorio |
SDA |
I²C SDA | Dati I²C |
SCL |
I²C SCL | Clock I²C |
DRDY |
Dati pronti (opzionale) | Drain aperto, impulso LOW di ~10 µs ogni ~100 ms |
Potenza
Parametri VCC
- Tensione nominale: 5 V DC
- Intervallo ammesso: 4.5..5.5 V
- Corrente di alimentazione: ~15 mA tipici, ~25 mA di picco durante le scritture in flash
- Ripple: < 50 mV picco-picco (per la precisione di misura)
Il modulo integra un regolatore di bordo, un filtro RC, condensatori ceramici e una perlina di ferrite — non serve alcun filtraggio aggiuntivo da parte dell'utente. Il modulo può essere alimentato dalla linea +5V di qualsiasi scheda Arduino (UNO, ESP32 DevKitC, ecc.).
Compatibilità dei livelli I²C
-
SDA/SCLoperano a logica 3.3 V (i pull-up integrati portano le linee a 3.3 V). -
Le linee sono tolleranti a 5 V: un master a 5 V (Arduino UNO / Nano) legge correttamente HIGH (~3.3 V) e può pilotare il bus senza un traduttore di livello.
-
Per un bus che funziona interamente a livelli 5 V — disabiliti i pull-up integrati (vedere sotto) e aggiunga pull-up esterne verso +5 V dal lato master.
Comportamento all'accensione
- Avvio a freddo: ~250 ms fino al primo risultato valido.
- Dopo un reset (software o brown-out): ~250 ms per riprendersi.
- Fino al primo risultato valido, i registri leggono
0eDATA_VALID= 0.
La libreria attende che il modulo sia pronto all'interno di dev.begin() — il suo codice chiama semplicemente begin() e prosegue.
Isolamento
Il lato bassa tensione (I²C, alimentazione, DRDY) è isolato dai morsetti di rete. Consideri i morsetti di rete e il cablaggio lato TA come sotto tensione.
- Il
GNDdel modulo non è collegato alla linea di rete né al neutro. - Non toccare i morsetti L/N né il conduttore della pinza mentre il circuito è sotto tensione.
⚠ Non aprire l'involucro del modulo — questo invalida la calibrazione di fabbrica.
Resistori di pull-up a bordo
Importante: ogni modulo rbAmp è fornito con resistenze di pull-up integrate da 4.7 kΩ su SDA e SCL verso 3.3 V. Per un singolo modulo sul bus non servono pull-up esterne — colleghi il master direttamente.
Quando disattivare i pull-up integrati
Se il bus ha più moduli rbAmp (o altri dispositivi I²C con i propri pull-up), collegarli in parallelo dà una resistenza effettiva troppo bassa, che:
- Aumenta il consumo del bus
-
Può superare la corrente massima di assorbimento dello stadio di uscita del master I²C (tipicamente ≤ 3 mA a logica 3.3 V)
-
Aggiunge capacità capacitiva su un bus lungo, con scarso beneficio per l'immunità al rumore
Soluzione: sul lato inferiore della scheda, vicino alle resistenze di pull-up, ci sono ponticelli a saldare (serigrafia Pull-Up). Li tagli con una lama affilata per disattivare una pull-up:
-
Lasciare i pull-up abilitati su un solo modulo (oppure spostarli in un unico punto vicino al master).
-
Tagliare i ponticelli sugli altri moduli rimanenti.
- Se sulla scheda master sono già presenti pull-up — tagli i ponticelli su tutti i moduli rbAmp.
Regola pratica
| moduli rbAmp sul bus | Pull-up |
|---|---|
| 1 | Lasci così (la pull-up integrata da 4.7 kΩ funziona) |
| 2 | Lasci inserito uno, stacchi l'altro |
| 3 | Tagli su tutti i moduli, monti una coppia esterna da 2.7…3.3 kΩ vicino al master |
| 4…6 | Tagli su tutti i moduli, una coppia esterna da 2.2…2.7 kΩ vicino al master |
| 7…16 | Tagli su tutti i moduli, una coppia esterna da 1.5…2.2 kΩ vicino al master; controlli la capacità del bus (≤ 400 pF), abbassi la velocità del bus se serve |
I valori esterni sono valori consigliati (calcolati dalla specifica I²C: corrente di assorbimento ≤ 3 mA a 3.3 V, capacità del bus ≤ 400 pF). Collegare i pull-up esterni a 3.3 V (il livello logico del bus), non all'alimentazione VCC a 5 V.
: misuri la resistenza tra SDA e VCC con i dispositivi non alimentati. Dovrebbe essere nell'intervallo 1.5..4.7 kΩ. Un valore inferiore significa troppe pull-up attive in parallelo.
Parametri del bus I²C
- Indirizzo predefinito:
0x50(7 bit) - Intervallo di indirizzi:
0x08..0x77(riassegnato tramite commit dell'indirizzo in due fasi, OK per la produzione) - Velocità: UNO / Mega / STM32 / RP2040 100 kHz; ESP32 / ESP8266 50 kHz. Non usi 400 kHz.
- Auto-incremento del puntatore: solo in lettura. Una lettura a raffica di
restituisce N byte consecutivi a partire da+ N byte addr. Le scritture NON sono ad auto-incremento: una scrittura a raffica scarta i byte 1..N e solo il primo viene scritto. I registri multi-byte si scrivono byte per byte in transazioni separate da un byte. Vedi 09 · Riferimento API — "Scritture multi-byte".
Lunghezza del bus
L'I²C è un bus corto (~15 cm di default). Molti utenti collegano i moduli con cavetti di bassa qualità, che captano molto rumore e perdono molti trasferimenti — da qui il limite breve. Topologie consigliate per rbAmp:
| Cavo | Lunghezza massima | Velocità |
|---|---|---|
| JST standard / piatto a 4 conduttori | fino a 0.15 m | 100 kHz |
| Doppino intrecciato UTP (cat-5/5e/6) — SDA+GND e SCL+GND in coppie separate | fino a 1 m | 100 kHz |
| Coppia intrecciata + buffer I²C (PCA9515 / TCA9617) | fino a 3 m | 100 kHz |
| Bus differenziale (PCA9615 / LTC4332) | fino a 100 m | 100 kHz |
Per lunghezze oltre 0.15 m, il doppino ritorto è obbligatorio: SDA e SCL devono stare in coppie diverse, ciascuna con la propria massa (ad esempio blu + blu-bianco per SDA, verde + verde-bianco per SCL). SDA e SCL in un'unica coppia creano una capacità accoppiata che distorce i fronti.
⚠ All'interno di un quadro elettrico, schermi il cavo I2C. Campi magnetici intensi vicino ai conduttori di rete, ai contattori e ai trasformatori inducono rumore in un cavo non schermato. Tenga il cavo il più corto possibile e lontano dai cablaggi di rete.
Cablaggio lato rete (sensori)
⚠ 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.
Sensore di tensione (varianti UI*)
La scheda espone i morsetti L (linea) e N (neutro). La polarità conta per il segno della potenza attiva:
-
Corretto (L → L, N → N):
P > 0significa consumo (corrente dalla rete verso il carico),P < 0significa esportazione verso la rete (generazione). -
Scambiati (L e N invertiti): il segno di P si inverte — il consumo viene conteggiato come potenza negativa.
Filo e fusibile. Non serve un filo spesso per il collegamento di tensione: AWG26–22 è sufficiente, perché il sensore di tensione assorbe pochissima corrente. Un fusibile sulla linea L è obbligatorio, con portata fino a 0.1 A.
La corretta polarità è fondamentale per:
-
Contabilità corretta sul livello BASIC (il BASIC conta solo
max(P, 0); con polarità scambiata il contatore di energia resta a zero). -
Separazione corretta di consumo e generazione sulla linea STANDARD (STD).
: su un carico puramente resistivo (bollitore elettrico, scaldabagno, lampada a incandescenza) P > 0 e PF ≈ 1.0. Se P è negativo con un carico in consumo — scambi L e N sulla scheda.
Sensore di corrente — pinza TA SCT-013
Le pinze CT esterne si collegano al modulo tramite un connettore jack da 3.5 mm. Il connettore è polarizzato — non occorre prendere decisioni di cablaggio.
Una freccia sul corpo della pinza indica la direzione della corrente per l'orientamento "normale". Regole:
- Stringa la pinza TA attorno al solo conduttore di linea (L) diretto al carico.
-
La freccia sulla pinza deve puntare nella direzione della corrente verso il carico (dall'interruttore al carico).
-
La pinza deve chiudersi completamente — senza spazi tra le due metà del nucleo magnetico. Se le metà non scattano del tutto in chiusura, la precisione si perde.
⚠ Non far passare L e N entrambi attraverso una sola pinza contemporaneamente. I loro flussi magnetici sono uguali e opposti, quindi si annullano — il sensore leggerà circa zero anche sotto carico.
Per la scelta del modello SCT-013 (5A / 10A / 30A / 50A / 100A) e per comunicarla al modulo tramite dev.setCTModel(code) — vedi 03_sensor_selection.md.
⚠ La polarità della pinza CT conta su BASIC: se la freccia della pinza punta lontano dal carico (oppure L/N sui morsetti sono scambiati), P_real risulta negativo sotto consumo — e il livello BASIC porta a max(P, 0), quindi il contatore Wh resta a zero. Girare la pinza fisicamente sul conduttore; non invertirla via software.
DATA_READY (DRDY)
Un pin opzionale per l'ottimizzazione del polling. Se l'applicazione interroga il modulo non più di una volta ogni 100 ms, DRDY può restare non collegato.
Parametri elettrici
- Tipo di uscita: drain aperto (nessuna pull-up attiva verso VCC)
-
Livello di riposo: ALTO (richiede un pull-up sul lato master — il pull-up integrato dell'MCU o una resistenza esterna)
-
Impulso di prontezza: LOW per ~10 µs dopo l'aggiornamento dei registri RT (
0x86..0xCF) con dati freschi -
Frequenza degli impulsi: ~10 Hz (un impulso per finestra RT di ~100 ms)
La libreria può usare la linea per lei: dev.setDrdyPin(pin) la collega (pull-up interna, interrupt sul fronte di discesa) e dev.waitDataReady() / dev.readAllReady() attendono il prossimo snapshot del modulo — vedere 09 · Riferimento API. Più moduli possono condividere una linea DRDY (wired-OR); una linea tenuta fissa a LOW significa che un modulo ha un evento mascherato in attesa (allarme). Senza una linea, le stesse chiamate interrogano.
Semantica
Un fronte di discesa su DRDY garantisce che tutti i registri RT siano sincronizzati e pubblicati (il firmware li aggiorna in modo atomico in un ISR prima di portare a massa il pin). Dopo il fronte di discesa il master può leggere 0x86..0xCD senza rischio di ottenere un campione spezzato.
Uso su Arduino
-
Interruzione esterna (
attachInterruptsul fronte di discesa) — risveglia il master e avvia una lettura. -
Pull-up: o
INPUT_PULLUPsul MCU, o un 10 kΩ esterno verso 3.3 V. Su UNO / Nano (AVR) usare un 10 kΩ esterno verso 3.3 V — il pull-up integrato (~40 kΩ) è troppo debole per linee DRDY lunghe.
const int PIN_DRDY = 15;
volatile bool data_ready = false;
#if defined(ESP32) || defined(ESP_PLATFORM)
void IRAM_ATTR on_drdy() { data_ready = true; } // ESP32 — ISR in IRAM
#else
void on_drdy() { data_ready = true; } // AVR / STM32duino / RP2040 / SAMD
#endif
void setup() {
Wire.begin();
while (!dev.begin()) { delay(500); }
// Raise the pull-up + attach the ISR AFTER dev.begin() — this
// guarantees the module is already ready and the pull-up edge will not
// cause a spurious interrupt before the first RT window is captured.
// INPUT_PULLUP is fine for most cases; for long
// lines or AVR hosts add an external 10 kΩ to 3.3 V.
pinMode(PIN_DRDY, INPUT_PULLUP);
attachInterrupt(digitalPinToInterrupt(PIN_DRDY), on_drdy, FALLING);
}
void loop() {
if (!data_ready) return; // sleep until the next RT window
data_ready = false;
float p = dev.readPower(0);
// ...integration / transmit...
}
DRDY è opzionale — il polling a qualsiasi frequenza ≤ 10 Hz funziona senza. La libreria non dipende da DRDY; setDrdyPin() / waitDataReady() sono funzioni di supporto facoltative.
Collegamento a diversi host Arduino
Il modulo funziona con qualsiasi scheda compatibile Arduino tramite il Wire standard. Di seguito i pin predefiniti per le varianti più diffuse.
Arduino UNO / Nano (logica a 5 V)
| rbAmp | Pin Arduino |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
A4 |
SCL |
A5 |
DRDY (opz.) |
qualsiasi digitale, ad esempio D2 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(); // SDA=A4, SCL=A5 by default
Wire.setClock(100000); // 100 kHz — no 50 kHz clamp needed on AVR
while (!dev.begin()) { delay(500); }
}
L'UNO è un host a 5 V, non serve alcun traduttore di livello (le linee SDA/SCL del modulo tollerano 5 V). I pull-up integrati del modulo portano le linee a 3.3 V, che un master a 5 V legge correttamente come ALTO.
Arduino Mega 2560 (logica 5 V)
| rbAmp | Pin Mega |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
D20 |
SCL |
D21 |
DRDY (opz.) |
qualsiasi digitale, ad es. D18 (supporta interrupt) |
Identico all'UNO nel codice, cambiano solo i pin fisici. Nessun traduttore di livello necessario.
ESP32 / ESP32-S3 / ESP32-C3 (logica 3.3 V)
| rbAmp | Pin ESP32 DevKitC |
|---|---|
VCC |
+5V (alimentato da USB-5V sul DevKitC) |
GND |
GND |
SDA |
GPIO21 |
SCL |
GPIO22 |
DRDY (opz.) |
qualsiasi GPIO libero, ad es. GPIO4 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(21, 22); // SDA=21, SCL=22 (or Wire.begin() with board defaults)
Wire.setClock(50000); // ESP32: 50 kHz
while (!dev.begin()) { delay(500); }
}
L'ESP32 è un host a 3.3 V, collegamento diretto al modulo. L'alimentazione VCC viene presa dal pin +5V della DevKitC (collegato direttamente al 5 V USB).
Pinza a 50 kHz su ESP32 — lo schema raccomandato. Invece di una chiamata esplicita Wire.setClock(50000), definisca la macro facoltativa prima dell'include — begin() applicherà la pinza internamente:
#define RBAMP_ESP32_CLAMP_HZ 50000
#include
La macro è facoltativa (non attiva di default) — così le chiamate esplicite dell'utente a Wire.setClock() (ad esempio quando un OLED condivide il bus) vengono preservate. Entrambe le forme funzionano — scelga quella più leggibile nel suo sketch.
Se la sua scheda ESP32 non porta fuori un pin a 5 V (alcuni moduli compatti ESP32-S3 / C3 si accontentano solo di Vin o non hanno affatto 5 V) — alimenti rbAmp da una sorgente esterna a 5 V (ad esempio un caricatore USB + breakout), con GND condiviso con l'ESP32.
Una nota a parte sul reset del modulo:
Per un reset software del modulo usare dev.reset() — la libreria invia il comando e il modulo si riavvia in ~100 ms. Se serve un reset hardware (ad esempio per uscire da uno stato di blocco) — togliere e ridare alimentazione a VCC (scollegare per 1+ secondo).
ESP8266 (Wemos D1 mini / NodeMCU, logica 3.3 V)
| rbAmp | Pin ESP8266 (NodeMCU) |
|---|---|
VCC |
Vin oppure +5V |
GND |
GND |
SDA |
D2 (GPIO4) |
SCL |
D1 (GPIO5) |
DRDY (opz.) |
D5 (GPIO14) |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(D2, D1); // SDA=GPIO4, SCL=GPIO5
Wire.setClock(50000); // ESP8266 software I²C: 50 kHz for consistency with ESP32
while (!dev.begin()) { delay(500); }
}
L'ESP8266 è un host a 3.3 V, collegamento diretto.
STM32duino (scheda di sviluppo STM32F1 F103 / Black Pill F411, logica 3.3 V)
| rbAmp | Pin STM32 (scheda di sviluppo STM32F1) |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
PB7 (I²C1_SDA) |
SCL |
PB6 (I²C1_SCL) |
DRDY (opz.) |
qualsiasi GPIO con EXTI, ad esempio PA0 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(); // SDA=PB7, SCL=PB6 by default for I²C1
Wire.setClock(100000); // the STM32 HAL I²C needs no 50 kHz clamp
while (!dev.begin()) { delay(500); }
}
STM32duino supporta più istanze Wire (Wire1, Wire2 per un secondo I²C). Se il bus primario è occupato — usi la seconda periferica I²C.
RP2040 / SAMD (Raspberry Pi Pico, arduino-pico)
| rbAmp | Pin RP2040 (Pico) |
|---|---|
VCC |
VBUS (5 V da USB) oppure +5V |
GND |
GND |
SDA |
GP4 |
SCL |
GP5 |
DRDY (opz.) |
qualsiasi GP |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.setSDA(4);
Wire.setSCL(5);
Wire.begin();
Wire.setClock(100000); // the RP2040 hardware I²C needs no 50 kHz clamp
while (!dev.begin()) { delay(500); }
}
L'RP2040 è un host a 3.3 V, collegamento diretto. Sulle schede SAMD (Arduino Zero, MKR) Wire.begin() con i valori predefiniti funziona allo stesso modo — i pin specifici dipendono dalla scheda.
Pico tramite VSYS (batteria / alimentazione esterna): il pin VBUS è presente solo quando alimentato via USB. Se il Pico funziona a batteria o con una sorgente esterna tramite VSYS — VBUS non trasporta nulla. Alimentare i 5 V da una sorgente esterna direttamente al VCC del modulo, con GND in comune con il Pico.
Schema di cablaggio di riferimento (ESP32 + singolo modulo)
In questa configurazione:
- Pull-up esterne su I²C NON necessarie (integrate nel modulo).
- DRDY è opzionale; come nell'immagine, usare un pull-up esterno da 10 kΩ verso 3.3 V (anche INPUT_PULLUP sul pin ESP32 funziona con cavi corti).
- Il connettore della pinza SCT-013 è inserito a fondo.
- La pinza è completamente chiusa sul filo L, con la freccia verso il carico.
Schema di cablaggio di riferimento (Arduino UNO + singolo modulo)
In questa configurazione:
- Le pull-up esterne su I²C NON sono necessarie.
- L'UNO è a logica 5 V; SDA/SCL del modulo tollerano 5 V, non serve alcun traduttore di livello.
- DRDY ha un livello di 3.3 V — sulla UNO un ingresso TTL lo legge come HIGH (VIH_TTL ≥ 2.0 V, 3.3 V > 2.0 V). Una pull-up di DRDY è consigliata specificamente verso 3.3 V per sicurezza: se i circuiti di protezione interni del pin DRDY non sono tolleranti a 5 V (separatamente dalle linee I²C, la cui tolleranza a 5 V è confermata), una pull-up verso 5 V creerebbe una piccola corrente di dispersione attraverso i diodi ESD nel rail 3.3 V del modulo. Verso 3.3 V — non è mai un problema.
Modelli multifase e linea STANDARD (STD)
Le SKU multicanale e multifase mantengono la stessa piedinatura LV (VCC / GND / SDA / SCL / DRDY). Cambia solo il lato di rete — più morsetti L e più connettori jack TA.
I moduli STANDARD (STD) usano lo stesso cablaggio I²C dei moduli BASIC — stesse quattro linee di segnale, stesse regole di pull-up e di bus di cui sopra. Nulla cambia nella connessione; dev.begin() rileva quale linea è collegata (dev.line()), e lo stesso sketch serve entrambi. Note:
-
Le chiamate esclusive della linea STD (la famiglia
std*, potenza reattiva e apparente) restituisconoRB_ERR_NOT_IMPLEMENTEDsu un modulo BASIC (sul BASIC la potenza reattiva non è esposta da questa libreria). -
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 un'immagine di almeno
0x0001007B(dev.stdReadImageVersion()). Su un'immagine più vecchia sono segnalate come "non disponibili". -
Il numero di canali di tensione e di corrente viene dal modulo (
dev.stdInfo()); la libreria espone fino aRBAMP_MAX_CHANNELS(7) canali di corrente.
Bus multimodulo — la topologia principale
Il caso d'uso canonico della libreria è più moduli rbAmp su un unico bus I²C, gestiti da un singolo Arduino / ESP32 tramite RbAmpFleet. Tutte le regole e le ottimizzazioni che seguono sono pensate proprio per questa topologia; un singolo modulo è un caso particolare (lo stesso handle, ma le chiamate alla flotta si riducono a quelle banali).
Installazioni tipiche
| Scenario | Configurazione | Numero di moduli |
|---|---|---|
| Canone dell'80%: alimentazione domestica + sotto-contatori | 1× UI1 (alimentazione, energia di rete) + 3-6× UI1/I1 (carichi) | 4-7 |
| Sottoquadro con ripartizione della corrente | 1× UI1 (alimentazione) + 1-2× I2/I3 (corrente per circuito) | 3-5 |
| Sotto-misura industriale | 1× UI1 (alimentazione) + N× I2/I3 (per macchina, ripartizione della corrente) | fino a ~16 |
Limiti elettrici
- Numero di moduli: fino a ~16 (capacità totale del bus ≤ 400 pF a 100 kHz; a 50 kHz c'è più margine).
- Pull-up per il bus della flotta (importante): ogni modulo viene fornito con 4.7 kΩ integrati. Su un bus multi-modulo N pull-up lavorano in parallelo → il drain è sovraccarico e il bus non riesce a tirare BASSO. Da 4 moduli in su (o già con un bus più lungo di 15 cm) tagliare i pull-up integrati su tutti i moduli tranne uno — con 2–3 moduli su un bus fino a 15 cm lasciarli stare, questo caso è misurato (oppure tagliarli su tutti e tenere solo pull-up esterni (2.7…3.3 kΩ per 3 moduli, valori inferiori per bus più grandi — vedi la tabella sopra) verso 3.3 V in un unico punto del bus — consigliato per tratte lunghe / rumore / ESP32 come master).
- I pull-up interni dell'ESP32 (~45 kΩ) sono troppo deboli per un bus multi-modulo con lunghezze reali — servono pull-up esterni (valori: vedi la tabella sopra). Fa parte della mitigazione a tre livelli contro il blocco del bus su un bus marginale — vedi 10 · Risoluzione dei problemi, la sezione "ESP32 project hangs" (il progetto si blocca).
Indirizzamento — provisioning e sostituzione sul campo (adatto alla produzione)
L'indirizzo di fabbrica predefinito è 0x50. Ogni modulo nuovo o di sostituzione passa per il provisioning (una volta): riassegnazione da 0x50 a un indirizzo operativo + salvataggio facoltativo della configurazione (modelli TA, group_id, etichetta) in flash. La modalità di fabbrica non è richiesta — il cambio di indirizzo funziona direttamente in produzione tramite commit dell'indirizzo in due fasi.
Metodo 1 — RbAmpFleet::provision() (consigliato)
RbAmp* dev = nullptr;
if (RbAmpFleet::provision(Wire, /*desired=*/0x52, /*save=*/true, dev)) {
fleet.add(dev); // ready handle, now in the fleet
}
Una sola chiamata esegue la scansione di 0x50, effettua il commit dell'indirizzo in due fasi, esegue un reset, cerca il modulo al nuovo indirizzo nella finestra di avvio e (facoltativamente) emette SAVE_USER_CONFIG per la persistenza. Restituisce false in caso di violazione della disciplina (vedi sotto) o di errore di trasporto.
Metodo 2 — prepare/commitAddressChange di basso livello (forma manuale)
dev.prepareAddressChange(0x52); // candidate in RAM
dev.commitAddressChange(); // arms 0xA5 + COMMIT_ADDR + reset
delay(300); // boot window
Lo stesso meccanismo a due fasi di provision(), senza il wrapper della flotta. Si usa quando RbAmpFleet non è stato creato.
Protocollo sul filo in dettaglio (per riferimento)
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. wait ~700 ms (flash erase + write)
5. issue CMD_RESET (opcode 0x01) — CMD_COMMIT_ADDR does not auto-reset
6. wait ~300 ms; the module responds at the new address
✅ REG_I2C_ADDRESS (0x30) legge l'indirizzo attivo all'avvio (v1.3 addr-boot-sync). Dopo il riavvio successivo al commit, la lettura di 0x30 mostra il nuovo indirizzo attivo. Il comportamento di eco della predisposizione persiste fino a CMD_COMMIT_ADDR + reset.
⚠ Disciplina di provisioning — DEVE essercene uno alla volta.
La causa più comune dei fallimenti di provisioning è avere più di un modulo con l'indirizzo di fabbrica 0x50 sul bus. È fisicamente impossibile distinguerli via I²C (bus a drain aperto: entrambi i moduli rispondono con ACK in modo identico, e i dati letti risultano "incollati insieme").
Quindi la regola è rigorosa (un MUST normativo, non una raccomandazione): nel momento in cui si chiama RbAmpFleet::provision() (o prepareAddressChange()), deve esserci esattamente un modulo a 0x50 (uno nuovo o uno riportato alle impostazioni di fabbrica con uno strumento da banco separato). Nessun "sono sicuro che questi due moduli siano diversi — li separo adesso" — non funzionerà: la collisione si manifesta più tardi, quando si pensa già che la flotta sia pulita.
Percorso di recupero se sospetta una violazione della disciplina: 1. Spenga e riaccenda tutti i moduli. 2. Scolleghi fisicamente tutti i moduli tranne uno "vergine". 3. Chiami RbAmpFleet::provision() sul bus con il solo modulo. 4. Aggiunga i moduli restanti uno alla volta, facendo il provisioning di ciascuno separatamente.
Budget di potenza del bus
A 50 kHz, una transazione di lettura ≈ 200-400 µs. Un intero blocco RT di un canale (U + I + P + PF) ≈ 5-8 ms per canale.
| Configurazione | Bus per ciclo | A 50 kHz | Frequenza massima di polling |
|---|---|---|---|
| 1× UI1, blocco RT | ~5 ms | < 5 ms | 100+ Hz (ma il modulo aggiorna a 10 Hz) |
| 1× UI3, blocco RT + periodo | ~25 ms | ~25 ms | fino a 10 Hz |
| 5× UI1, blocco RT | ~25 ms | ~25 ms | fino a 10 Hz |
| 16× UI3, RT + periodo | ~400 ms | 400 ms > 100 ms | non riesce a stare al passo con il modulo (10 Hz); ~2 Hz al massimo |
I numeri sono stime (200-400 µs per transazione a seconda dell'MCU). I numeri sono stime e dipendono dall'MCU ospite.
Regola: a 50 kHz i limiti comodi sono 8-10× UI3 o 15-16× UI1 con interrogazione a 5 Hz (ogni secondo finestra del modulo), e circa la metà a 10 Hz pieni.
Sincronizzazione dei periodi
Per la misura tariffaria, tutti i moduli devono prendere lo snapshot sullo stesso intervallo. Due strategie:
Strategia 1 — snapshot sequenziale + assestamento comune (qualsiasi firmware):
RbAmp meters[N]; // array of initialized modules
void period_cycle() {
// Phase 1: sequential snapshot
for (auto& m : meters) m.latchPeriod();
// Phase 2: common settle (≥ 50 ms)
delay(50);
// Phase 3: read the snapshots with skip_latch=true
for (auto& m : meters) {
RbAmpSnapshot snap;
m.readPeriodSnapshot(snap, /*skip_latch=*/true);
}
}
Skew tra i moduli: 16 moduli × ~1 ms/snapshot = ~16 ms su un periodo di 60 s. Trascurabile per i totali di energia.
Strategia 2 — snapshot broadcast General-Call (richiede l'abilitazione):
Tutti i moduli prendono il loro snapshot con un unico frame I²C sull'indirizzo 0x00:
addr=0x00 | A5 27 (5 bytes)
Skew = 0 (atomico). Preconfigurazione (una volta su ciascun modulo della flotta):
- Impostare
REG_FLEET_CONFIG.bit0 = 1tramiteCMD_SAVE_USER_CONFIG. CMD_RESET— la ricezione GC viene attivata all'avvio.- Dopo il reset, il master invia il frame di 5 byte su
0x00. - Testimone: per ogni modulo atteso, leggere
REG_V03_PERIOD_VALID (0x07).!=1→ ripiegare sulla strategia 1.
Quale usare:
- < 8 moduli: strategia 1 (più semplice, nessuna abilitazione richiesta).
- ≥ 8 moduli o sincronizzazione stretta: strategia 2.
Filtro per gruppo GC (bus multi-tenant)
REG_GROUP_ID (0x28) permette di avere più domini GC su un bus:
group = 0x00→ all-call (tutti i moduli con GC abilitato eseguono uno snapshot).group = N→ solo i moduli conREG_GROUP_ID = Neseguono uno snapshot.
Caso d'uso — separare i gruppi tariffari (giorno e notte) su un bus condiviso.
Modalità di guasto
| Sintomo | Causa | Che cosa fare |
|---|---|---|
scansione del bus i2c mostra più moduli allo stesso indirizzo dopo un'aggiunta sul campo |
Un nuovo modulo a 0x50 entra in conflitto con uno già indirizzato |
Riassegni il nuovo modulo separatamente prima di aggiungerlo |
| Un modulo risponde con NACK più spesso degli altri | Guasto del cavo / calo della VCC | Verifichi la VCC sotto carico |
| Il Wh di un modulo diverge in modo costante | L'orologio proprio del modulo differisce da quello del master | L'energia viene integrata sull'orologio del master; confronti con master_dt_ms, non con latch_ms |
| Dopo un frame GC, un modulo non esegue lo snapshot | FLEET_CONFIG.bit0 = 0 o gruppo non corrispondente |
Controlli REG_FLEET_CONFIG e REG_GROUP_ID |
Note di progettazione del bus
- Clock stretching: lo snapshot del modulo lo mette in pausa solo per microsecondi; SCL non viene allungato in modo significativo. Per il Raspberry Pi BCM283x (bug hardware noto nello stretching): la precauzione standard è 50 kHz + ripetizione.
- Lunghezza con più di 4 moduli: valutare un buffer I²C (PCA9515) con ≥ 8 moduli + lunghezza > 1 m.
Scenari multimodulo dettagliati — in 06 · Esempi.
Cosa c'è dopo
- 02 · Livelli del modulo — comportamento del firmware per livello
-
03 · Scelta del sensore di corrente — quale modello SCT-013 e come indicarlo al modulo
-
05 · Avvio rapido — il primo sketch funzionante
- 10 · Risoluzione dei problemi — cosa fare se il bus non funziona / I_rms è instabile / il segno di P è sbagliato
Sorgente e problemi: rb-amp/rbamp-arduino · questa pagina nel repo: docs/04_hardware.md (v1.6.2)