04 · Cablaggio
Questo capitolo descrive il cablaggio fisico di rbAmp a un ESP32: selezione dei GPIO, regole di pull-up, bus multi-modulo, alimentazione, linea DRDY opzionale e provisioning degli indirizzi.
Installazione canonica — una flotta multi-modulo su un unico bus. L'80% delle installazioni sul campo consiste in 1× UI1 (rete) + N× I2/I3 (sotto-contatori) su un unico bus I²C dell'ESP32, con i pull-up impostati come da tabella sotto. Vedi 01_overview.md per il quadro della flotta. Un singolo modulo è il caso minimo, non il canone. Questo capitolo copre entrambe le topologie, ma il multi-modulo è indicato come «topologia primaria» nelle sezioni pertinenti.
Moduli STANDARD (STD). Cablaggio, regole di pull-up, alimentazione e la linea DRDY opzionale sono uguali per moduli BASIC e STANDARD, e lo stesso YAML funziona per entrambi — il componente riconosce il modulo collegato all'avvio. new_address: funziona su entrambe le linee di moduli. La sincronizzazione della flotta via general call (fleet_gc_enable: / group_id:) si applica solo ai moduli BASIC; su un modulo STANDARD tali chiavi vengono ignorate con una riga di log.
PERICOLO: i morsetti L/N portano la tensione di rete. Togli tensione e blocca il circuito prima di collegare, fai eseguire i cablaggi di rete e qualsiasi lavoro dentro un quadro da una persona qualificata, stringi UN SOLO conduttore (L) con la pinza, e non lasciare mai la pinza TA su un conduttore con il jack TA scollegato.
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.
Lato rete in sintesi. L e N della rete vanno ai due morsetti del modulo (forniscono la lettura della tensione); la pinza TA si inserisce nel jack TA e si avvolge solo attorno al conduttore L, con la freccia verso il carico. Tutto il resto di questo capitolo riguarda il lato a bassa tensione.
Pinout lato LV
Il lato a bassa tensione del modulo espone cinque segnali. Sono tutti isolati galvanicamente dalla rete — il pin GND è il GND dell'ESP32, non il neutro di rete.
| Pin | Segnale | Descrizione |
|---|---|---|
VCC |
da +4.5 a +5.5 V CC | Alimentazione del modulo. 5 V nominali; sotto 4.5 V le letture possono diventare inaffidabili. |
GND |
Comune | Comune con il master. Obbligatorio. |
SDA |
Dati I²C | Logica a 3.3 V; tollerante a 5 V. |
SCL |
Clock I²C | Logica a 3.3 V; tollerante a 5 V. |
DRDY |
Dati pronti (facoltativo) | Uscita open-drain. Impulso LOW di ~10 µs ogni ~100 ms dopo l'aggiornamento dei registri istantanei. |
Selezione dei GPIO sull'ESP32
Qualsiasi coppia di GPIO che supporti I²C funzionerà. La matrice periferica dell'ESP32 consente di instradare I²C su quasi qualsiasi pin. Vincoli pratici:
- GPIO0 e GPIO2 sono pin di bootstrap. Un livello basso su di essi all'accensione blocca l'avvio. Non usarli.
- I GPIO 6..11 sono collegati alla flash o alla PSRAM integrate sulla maggior parte dei moduli ESP32-WROOM. Non disponibili.
- GPIO 34..39 sono solo in ingresso. Non adatti a I²C (che richiede pilotaggio bidirezionale).
- Non collegare alcun GPIO dell'ESP32 a una linea di reset del modulo — il modulo viene resettato con un comando I²C, e dal lato master non servono pin di reset hardware.
Assegnazioni predefinite consigliate, che funzionano sulla maggior parte delle schede ESP32-DevKitC:
| Segnale | GPIO | Nota |
|---|---|---|
| SDA | GPIO21 | Predefinito in tutti gli esempi YAML |
| SCL | GPIO22 | Predefinito in tutti gli esempi YAML |
| DRDY | GPIO15 | Facoltativo; va bene qualsiasi pin in grado di ricevere input |
Se GPIO21/22 sono occupati, scegliere un'altra coppia valida e aggiornare il blocco i2c: nel YAML.
Cablaggio di un singolo modulo
Il cablaggio completo dell'ESP32 è mostrato nello schema di riferimento qui sotto.
I resistori di pull-up esterni non servono per un singolo modulo — la scheda rbAmp ha già pull-up integrati da 4.7 kΩ su SDA e SCL verso 3.3 V.
Bus multi-modulo (topologia principale)
La maggior parte dei deployment rbAmp è una flotta di più moduli su un unico bus I²C dell'ESP32: un UI1 sulla rete più diversi I2/I3 sulle derivazioni. Questa è la topologia principale per cui il componente è stato progettato, e la configurazione dei pull-up sotto è ottimizzata per essa.
Quando due o più moduli (o altri dispositivi I²C con i propri pull-up) condividono un bus, i loro pull-up si sommano in parallelo. La resistenza combinata scende sotto il minimo effettivo — il che porta a:
- Consumo eccessivo del bus.
- Possibile sovraccarico delle uscite open-drain dell'ESP32 (tipicamente ≤ 3 mA a 3.3 V).
- Carico capacitivo più alto su un bus lungo.
Sul lato inferiore di ogni PCB rbAmp ci sono ponticelli di saldatura etichettati Pull-Up. Tagliare la pista con una lama affilata disconnette la coppia di pull-up integrata da 4.7 kΩ di quel modulo.
| Moduli sul bus | Configurazione dei pull-up | R effettiva |
|---|---|---|
| 1 | Lasciare la coppia integrata. Non serve alcuna coppia esterna. | ~4.7 kΩ |
| 2 | Lasciarne attivo solo uno; tagliare il secondo. | ~4.7 kΩ |
| 3 | Taglia tutti. Una coppia esterna da 2.7..3.3 kΩ sull'ESP32. | 2.7..3.3 kΩ |
| 4..6 | Taglia tutti. Una coppia esterna da 2.2..2.7 kΩ sull'ESP32. | 2.2..2.7 kΩ |
| 7..16 | Tagliare su tutti. Una coppia esterna di da 1.5 a 2.2 kΩ sull'ESP32 + un controllo della capacità del bus (vedere sotto). | 1.5..2.2 kΩ |
| ESP32 fornisce già i pull-up | Tagliare su tutti i moduli. I pull-up interni dell'ESP32 (≥50 kΩ) sono deboli — un bus lungo richiede comunque 2.2..4.7 kΩ esterni. | come sopra |
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.
Logica di selezione: la R_pullup effettiva è la combinazione in parallelo di tutti i pull-up attivi. L'intervallo di riferimento è 1.5..4.7 kΩ (il minimo è limitato dalla corrente di assorbimento dell'ESP32 ≤ 3 mA a 3.3 V; il massimo dalla costante di tempo RC del bus). Formula: 1/R_eff = N/R_unit. Per la coppia integrata da 4.7 kΩ: 2 moduli = 2.35 kΩ, 3 = 1.57 kΩ, 4 = 1.18 kΩ — con 3 moduli il valore in parallelo è 1.57 kΩ, ancora dentro l'intervallo, e un bus a 3 moduli fino a 15 cm risulta affidabile (cavi da 15 cm, 50 kHz), quindi la tabella mantiene i ponticelli integrati per 2 e 3 moduli. Da 4 moduli in poi, o prima su un bus più lungo, li azzera e passa a un'unica coppia esterna.
Verifica diagnostica: misurare la resistenza tra SDA e VCC a alimentazione spenta. Il risultato dovrebbe essere nell'intervallo da 1.5 a 4.7 kΩ. Sotto 1.0 kΩ significa troppi pull-up attivi in parallelo; sopra 10 kΩ significa nessun pull-up attivo (controllare i ponticelli).
Capacità del bus (per ≥7 moduli o lunghezza totale del cablaggio > 50 cm): la specifica I²C limita la capacità totale C_b a ≤ 400 pF. Un bus corto con 2–3 moduli è di solito 50..100 pF; un bus da 1 m con 10 moduli può salire a 300..400 pF. Quando sei vicino al limite, passa a frequency: 50kHz (se sei ancora a 100 kHz) oppure usa un IC di pull-up attivo (per esempio il PCA9517).
Velocità del bus
Impostare frequency: 50kHz nel blocco i2c: di ESPHome. Sul firmware attuale è obbligatorio per un funzionamento affidabile con ESP-IDF v5:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32 — ESP-IDF i2c_master driver interaction, see below
Il modulo invia periodicamente NACK alle letture da un ESP32 a 100 kHz (una quota sensibile delle transazioni) a causa dell'interazione tra la temporizzazione del driver ESP-IDF v5 i2c_master e la finestra di recupero dopo lo STOP della periferica I²C del modulo. A 50 kHz i NACK sono molto più rari, e il ritentativo per byte nel componente recupera > 99% delle letture valide.
Il firmware ha irrobustito la finestra di recupero I²C del modulo (rilasciata in v1.1 e v1.3), il che ha ridotto il contributo lato modulo — ma 50 kHz resta l'impostazione consigliata sui master basati su ESP-IDF, perché l'interazione di temporizzazione del driver persiste a 100 kHz. Va considerata la raccomandazione permanente per l'ESP32, non una soluzione provvisoria in attesa di una correzione.
Altri master I²C fanno girare questo modulo a 100 kHz senza problemi: STM32 HAL, RP2040 SDK, Raspberry Pi smbus2 (I²C del kernel Linux) e Arduino non ESP32 (AVR / STM32duino). Nota che l'asse è il driver, non la scheda: Arduino su ESP32 usa lo stesso driver ESP-IDF i2c_master, quindi vuole 50 kHz anche lui — solo Arduino non ESP32 funziona a 100 kHz.
Schema di riferimento — un ESP32 + un rbAmp
Notes:
- La resistenza da 10 kΩ su DRDY si trova sul lato master (vicino al GPIO), non sul lato modulo. DRDY è open-drain, senza pull-up interno.
- Il jack TA deve essere inserito a fondo; la pinza deve racchiudere completamente un solo conduttore con la freccia rivolta verso il carico.
- La polarità L/N ai morsetti influisce sul segno di P (vedi 03_sensor_selection.md).
Potenza
Alimentazione del modulo (VCC)
Il modulo richiede da +4.5 a +5.5 V CC. Assorbimento di corrente:
| Modalità | Tipico |
|---|---|
| Misura a regime | ~15 mA |
Scrittura flash (durante il provisioning di ct_model: / indirizzo) |
~25 mA di picco, ~700 ms |
| Riscaldamento all'avvio (~250 ms) | ~15 mA |
Il pin 5V di un ESP32-DevKitC (di solito collegato al VBUS USB) può alimentare direttamente il modulo — l'host USB deve fornire la corrente combinata dell'ESP32 (~200 mA) + rbAmp (~15 mA di picco) = ~215 mA. Per le installazioni in cui l'ESP32 è alimentato da un SMPS esterno a 5 V, collega VCC alla stessa linea a 5 V.
Brownout dell'ESP32
Il rilevatore di brownout dell'ESP32 scatta a ~2.43 V su VDD. Quando scatta, il bus I²C resta inattivo mentre il modulo continua a misurare autonomamente (ha la propria alimentazione a 5 V). Quando l'ESP32 si riprende, setup() ripristina l'energia accumulata dalla NVS prima del primo update(). Home Assistant non vede né un vuoto né un azzeramento nel grafico dell'energia.
DRDY facoltativo
Il pin DRDY del modulo è open-drain. Va a LOW per circa 10 µs ogni circa 100 ms, subito dopo l'aggiornamento del blocco dei registri istantanei. Non scatta sullo snapshot del periodo.
Con update_interval: 60s si può omettere il DRDY — il componente controlla il registro di stato all'inizio di ogni update() e salta la lettura se il modulo non è pronto. Il componente registra il pin DRDY; le letture sono guidate dal timer (update_interval).
Cablaggio DRDY
DRDY è open-drain: porta a LOW ma non può pilotare HIGH. Richiede un pull-up esterno:
rbAmp DRDY ──────────────────┬── ESP32 GPIO (input)
|
[10K]
|
3.3V
10 kΩ verso 3.3 V. Non collegare DRDY a 5 V, anche se SDA/SCL tollerano 5 V — DRDY è un segnale separato e il massimo assoluto su un GPIO di ingresso dell'ESP32 è 3.6 V.
Dichiara il pin nel YAML:
rbamp:
id: meter1
drdy_pin: GPIO15
DRDY multi-modulo
I segnali DRDY di più moduli possono essere collegati in OR su un singolo GPIO dell'ESP32 (le uscite open-drain si combinano naturalmente). Il segnale condiviso va LOW quando un qualsiasi modulo ha aggiornato i propri registri istantanei. Il componente registra solo il pin; non dice quale modulo è scattato.
Se servono segnali separati, instradare il DRDY di ciascun modulo al proprio GPIO e dichiarare drdy_pin: in ciascun blocco rbamp: singolarmente.
Assegnazione degli indirizzi su un bus multi-modulo
Tutti i moduli rbAmp escono di fabbrica all'indirizzo 0x50. Prima di collegare più moduli a un bus, ciascuno necessita di un indirizzo unico. Sul firmware v1.3 può essere fatto in produzione senza la modalità di provisioning di fabbrica — grazie al protocollo di commit in due fasi.
Commit dell'indirizzo in due fasi (v1.3+, produzione-OK)
Con new_address: il componente esegue la seguente sequenza:
-
Verifica se il firmware supporta il commit in due fasi. Se sì, segue il percorso in modalità produzione. Se no, ricade sul vecchio percorso monofase con vincolo di provisioning di fabbrica (firmware v1.0-v1.2).
-
Scrive il nuovo indirizzo in
REG_I2C_ADDRESS(in staging, non ancora attivo). -
Scrive la "parola magica"
0xA5inREG_ADDR_COMMIT_MAGIC— una conferma esplicita dell'intenzione che impedisce una scrittura accidentale suREG_I2C_ADDRESS. -
Invia l'opcode
CMD_COMMIT_ADDR— il modulo applica in modo atomico l'indirizzo in staging, lo salva in flash ed esegue un soft reset. -
Dopo ~700 ms il componente riassegna il proprio handle i2c_address al nuovo indirizzo e verifica la rienumerazione con una lettura di prova.
Se un passo fallisce, il modulo torna all'indirizzo precedente, senza lasciare uno stato "a metà". Un round-trip 0x50 → 0x60 → 0x50 si rienumera in meno di un secondo.
Provisioning sequenziale (flusso consigliato)
Più moduli insieme sul bus prima del provisioning costituiscono una collisione di indirizzi (tutti su 0x50). Quindi il provisioning avviene in sequenza, un modulo alla volta:
- Collega al bus ESP32 solo il modulo 1 (da solo sul bus).
-
Flashare la configurazione da
example/address_change.yamlconaddress: 0x50enew_address: 0x51. All'avvio il componente rileva la discrepanza → esegue il commit in due fasi (vedere sopra). -
Confermare il successo nei log di ESPHome (rienumerazione al nuovo indirizzo). Aggiornare il YAML:
address: 0x51, rimuoverenew_address:. -
Scollegare il modulo 1. Collegare il modulo 2 (ancora all'indirizzo di fabbrica
0x50). -
Ripeti per
0x52,0x53, e così via. OBBLIGATORIO: un solo modulo vergine sul bus alla volta — altrimenti entrambi rispondono su 0x50, causando contesa sul bus. -
Quando tutti i moduli hanno indirizzi unici, collegali tutti al bus e imposta i pull-up come da tabella in Bus multi-modulo (2 moduli: tieni una coppia; 3 o più: taglia tutte e aggiungi una coppia esterna).
Pericolo di provisioning concorrente: se due moduli vergini sono entrambi a 0x50, entrambi fanno ACK sul byte di indirizzo e pilotano SDA l'uno contro l'altro nella fase dati → contesa sul bus + dati indeterminati. Sempre un solo vergine alla volta.
Esempio di YAML per multi-modulo
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
- id: meter_solar
address: 0x51
update_interval: 60s
bidirectional: true
- id: meter_evcharger
address: 0x52
update_interval: 60s
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage: { name: "House Voltage" }
current: { name: "House Current" }
power: { name: "House Power" }
energy: { name: "House Energy" }
- platform: rbamp
rbamp_id: meter_solar
voltage: { name: "Solar Voltage", internal: true }
current: { name: "Solar Current" }
power: { name: "Solar Power" }
energy: { name: "Solar Energy" }
energy_exported: { name: "Solar Energy Exported" }
- platform: rbamp
rbamp_id: meter_evcharger
voltage: { name: "EV Charger Voltage", internal: true }
current: { name: "EV Charger Current" }
power: { name: "EV Charger Power" }
energy: { name: "EV Charger Energy" }
La versione completa con annotazioni è in example/multi_module.yaml.
Lunghezza del bus
I²C è un protocollo a corto raggio (~15 cm di default). Molti utenti collegano i moduli con cavetti a ponticello di bassa qualità, che captano molto rumore e perdono molti trasferimenti — da qui il limite breve. Lunghezze consigliate per rbAmp:
| Tipo di cavo | Lunghezza massima | Velocità |
|---|---|---|
| JST standard / 4 fili piatto | 0.15 m | 50 kHz |
| Doppino ritorto (SDA+GND e SCL+GND in coppie separate) | 1 m | 50 kHz |
| Coppia intrecciata + buffer I²C (PCA9515 / TCA9617) | 3 m | 50 kHz |
| Bus differenziale (PCA9615 / LTC4332) | 100 m | 50 kHz |
Per più di 0.15 m usa una coppia intrecciata, e SDA e SCL devono stare in coppie separate (per esempio blu + bianco-blu per SDA, verde + bianco-verde per SCL). Se SDA e SCL condividono una coppia, l'accoppiamento incrociato distorce i fronti anche a 50 kHz.
⚠ 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.
Modalità di provisioning di fabbrica (firmware legacy v1.0-v1.2)
Sulla v1.3 un cambio di indirizzo non richiede la modalità di provisioning di fabbrica — viene eseguito in produzione tramite il commit in due fasi (vedere sopra). Questa sezione si applica solo al firmware legacy (v1.0-v1.2), dove il cambio di indirizzo monofase richiedeva una modalità speciale.
Sul firmware legacy alcune operazioni sul modulo (cambio dell'indirizzo I²C, ripristino di fabbrica) richiedevano che il modulo fosse in modalità di provisioning di fabbrica — una modalità speciale per azioni di provisioning una tantum. I moduli di produzione standard venivano consegnati con la modalità di provisioning disabilitata: un tentativo di cambiare l'indirizzo restituiva un errore, visibile nei log di ESPHome come WARNING all'avvio.
Comportamento di compatibilità del componente v1.3:
-
Con
new_address:il componente verifica per prima cosa se il firmware supporta il commit in due fasi. Sì → percorso di produzione (due fasi, senza blocco del provisioning di fabbrica). -
Se non lo fa (firmware legacy v1.0-v1.2) → ripiego sulla scrittura monofase, che ha effetto solo in modalità di provisioning di fabbrica. Il componente registra questo come
WARN_FACTORY_MODE_REQUIREDnel log di avvio.
Se hai un modulo con firmware legacy (il DUT viene aggiornato tramite il banco di fabbrica, non via OTA sul campo), contatta il fornitore per la procedura per abilitare temporaneamente la modalità di provisioning. Con firmware v1.3 questo problema non esiste.
La configurazione del sensore di corrente (ct_model: / ct_models:) non ha mai richiesto la modalità di provisioning di fabbrica — un modulo su qualsiasi firmware accetta direttamente la scrittura del modello TA (vedi 03_sensor_selection.md).
Cosa c'è dopo
- 05_quickstart.md — primo avvio
- 06_examples.md — scenari completi: UI1 / UI3 / multi-modulo / provisioning degli indirizzi
- 10_troubleshooting.md — diagnostica orientata ai sintomi
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/04_hardware.md (v1.9.1)