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

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

Il connettore a bassa tensione del modulo rbAmp: VCC, GND, SDA, SCL e il pin DRDY facoltativo con ciò che ciascuno richiede.

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 / SCL operano 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 0 e DATA_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 GND del 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.
Sicurezza

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

In caso di dubbio

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

Quanti moduli sono sul bus e quali pull-up I²C restano: tenere le coppie integrate per uno–tre moduli su un bus fino a 15 cm; da quattro moduli in su, o su un bus più lungo, tagliarle tutte e usare una sola coppia esterna.

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 + N byte restituisce N byte consecutivi a partire da 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
Sicurezza

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)

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.

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 > 0 significa consumo (corrente dalla rete verso il carico), P < 0 significa 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).

Controllo rapido

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

Sicurezza

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

Sicurezza

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

Collegamento lato rete in un quadro: pinza TA sul filo L dopo l'interruttore di ingresso, N fuori dalla pinza, derivazione L fusibile e N per il riferimento di tensione.

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 (attachInterrupt sul fronte di discesa) — risveglia il master e avvia una lettura.

  • Pull-up: o INPUT_PULLUP sul 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.

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

Nota

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:

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

Nota

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

Nota

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)

Schema di cablaggio di riferimento di una scheda ESP32 a un singolo modulo rbAmp, con la pinza TA sul filo L.

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)

Schema di cablaggio di riferimento di un Arduino UNO con un singolo modulo rbAmp, con la pinza CT sul filo L.

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) restituiscono RB_ERR_NOT_IMPLEMENTED su 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 a RBAMP_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).

Più moduli rbAmp su un bus I²C con le pull-up integrate tagliate e una coppia di pull-up esterne al master, più le opzioni DRDY.

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.

Il provisioning indirizza un modulo vergine alla volta: collegare un modulo a 0x50, eseguire la chiamata di provisioning, verificare al nuovo indirizzo, poi collegare il successivo.

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

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

Text
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
Sicurezza

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

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

Sincronizzazione dei periodi tra moduli: snapshot sequenziale con un piccolo scarto temporale rispetto a un unico frame General-Call all'indirizzo 0x00.

Per la misura tariffaria, tutti i moduli devono prendere lo snapshot sullo stesso intervallo. Due strategie:

Strategia 1 — snapshot sequenziale + assestamento comune (qualsiasi firmware):

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

Text
addr=0x00 | A5 27      (5 bytes)

Skew = 0 (atomico). Preconfigurazione (una volta su ciascun modulo della flotta):

  1. Impostare REG_FLEET_CONFIG.bit0 = 1 tramite CMD_SAVE_USER_CONFIG.
  2. CMD_RESET — la ricezione GC viene attivata all'avvio.
  3. Dopo il reset, il master invia il frame di 5 byte su 0x00.
  4. 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 con REG_GROUP_ID = N eseguono 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


Sorgente e problemi: rb-amp/rbamp-arduino · questa pagina nel repo: docs/04_hardware.md (v1.6.2)