03 · Selezione del sensore di corrente
rbAmp misura la corrente con una pinza TA esterna (trasformatore di corrente) e la tensione con un trasformatore di tensione integrato (sui SKU UI*). Questo capitolo spiega come scegliere la pinza per il tuo carico e come indicare al modulo, tramite YAML, quale modello è installato.
Famiglia del sensore (sensor_class:)
La revisione hardware del modulo determina quale famiglia di sensori di corrente è supportata. Sui SKU attuali ne è disponibile solo una:
| Classe | Valore YAML | Stato |
|---|---|---|
| SCT-013 (TA split-core) | SCT_013 |
Disponibile ora, predefinito |
| WIRED_CT (modulo con TA cablato montato) | WIRED_CT |
Accoppiato in fabbrica: calibrato insieme al proprio sensore |
| BUILTIN_CT (modulo con sensore integrato) | BUILTIN_CT |
Accoppiato in fabbrica: calibrato insieme al proprio sensore |
La classe viene impostata una sola volta e memorizzata nella flash del modulo:
rbamp:
id: meter1
sensor_class: SCT_013 # defaults to SCT_013, can be omitted
Sul firmware v1.2+ questo valore diventa una precondizione per scrivere il modello TA: il modulo rifiuta se la classe non è impostata. Il componente non scrive mai una classe che il modulo ha già.
Controlli di scrittura: lettura-confronto-scrittura (v1.3+) e protezione di fabbrica (v1.8.1+)
All'avvio il componente legge la classe del sensore di corrente del modulo e la confronta con il valore richiesto dal YAML. Se coincidono, la scrittura in flash non avviene (una scrittura della classe sul modulo cancellerebbe anche i modelli di canale, quindi un valore invariato non viene mai riscritto). Questo significa:
-
Il blocco YAML può mantenere
sensor_class: SCT_013per sempre — un riavvio ripetuto non provoca una cancellazione del flash (~0 ms invece di ~700 ms). -
Il vecchio consiglio di "rimuovere
sensor_class:dal YAML dopo il primo avvio" è obsoleto — la configurazione è idempotente.
Lo stesso comportamento vale per ct_model: / ct_models: (vedere sotto).
Moduli accoppiati in fabbrica (WIRED_CT / BUILTIN_CT). Un modulo fornito insieme al proprio sensore montato viene calibrato come coppia con quel sensore. Il componente protegge tale calibrazione: una modifica di sensor_class: o ct_model: dal YAML su tale modulo viene rifiutata con una riga di log esplicita (la scrittura sostituirebbe la calibrazione individuale con un'impostazione generica). Lasciare fuori dal YAML entrambe le chiavi per questi moduli. Per le pinze SCT-013 (SCT_013, il valore predefinito) le chiavi funzionano come descritto sotto.
Scelta del modello SCT-013
Il modulo accetta uno qualsiasi dei sette modelli della serie SCT-013. La loro uscita elettrica differisce, quindi il modulo deve sapere quale è installata — i coefficienti di fabbrica vengono caricati per lo specifico modello.
Quale modello ho? Leggere il valore nominale sull'etichetta del corpo della pinza: SCT-013-030 significa 30 A, quindi si scrive ct_model: SCT_013_030. Usare il modello il cui valore nominale corrisponde all'etichetta, non quello che "sembra più vicino" al proprio carico.
| Codice | Nome nel YAML | Corrente nominale | Carico tipico | Massimo a 230 V | Stato v1.3 |
|---|---|---|---|---|---|
| 1 | SCT_013_005 |
5 A | Illuminazione a LED, singoli apparecchi, portatili | ~1.15 kW | produzione |
| 2 | SCT_013_010 |
10 A | PC desktop, piccolo condizionatore, circuito singolo | ~2.3 kW | produzione |
| 6 | SCT_013_020 |
20 A | Scaldabagni, derivazioni medie, ~3-5 kW | ~4.6 kW | produzione |
| 3 | SCT_013_030 |
30 A | Misura dell'intera casa con consumi tipici | ~6.9 kW | produzione (SKU predefinito) |
| 4 | SCT_013_050 |
50 A | Ricarica di veicoli elettrici, grande climatizzatore a corrente alternata, piano a induzione | ~11.5 kW | produzione |
| 7 | SCT_013_060 |
60 A | Sotto-contatore industriale, grandi derivazioni | ~13.8 kW | produzione |
| 5 | SCT_013_100 |
100 A | Ingresso principale del servizio, dorsali grandi | ~23 kW | produzione |
SCT_013_060 (60 A) e SCT_013_100 (100 A) sono accettati; scegliere la pinza il cui valore nominale copre la corrente massima.
La resistenza di carico è già installata sulla scheda del modulo — non serve aggiungere resistenze esterne tra i terminali di uscita della pinza.
Albero di selezione
Regola generale: scegliere la pinza con il valore nominale più basso il cui valore massimo misurabile copre il carico di picco con un margine di ~30%. Un valore nominale sovradimensionato su un carico piccolo abbassa l'ampiezza del segnale rispetto al rumore — l'accuratezza cala. Una pinza di valore nominale inferiore al picco saturerà il nucleo magnetico e darà letture gravemente errate.
Validazione delle pinze per classe (nuovo nella v1.3)
Il validatore dello schema _validate_ct_model_per_class rifiuta le combinazioni non valide di sensor_class: × ct_model: nella fase esphome config, prima di flash + avvio. Gli insiemi ammessi non sono contigui — questa è una regola esplicita del canone, non un errore:
| sensor_class | Codici ammessi | Nomi YAML | Comportamento in caso di mancata corrispondenza |
|---|---|---|---|
SCT_013 |
{1, 2, 3, 4, 5, 6, 7} | SCT_013_005/010/030/050/100/020/060 |
cv.Invalid con un suggerimento |
WIRED_CT |
{1–10, 12} | WIRED_CT_ |
cv.Invalid |
BUILTIN_CT |
{} (nessuno) | — | cv.Invalid (qualsiasi ct_model viene rifiutato) |
UNSET |
{} | — | cv.Invalid (classe non impostata) |
Specifically:
-
SCT_013non contiguo: i codici ammessi sono{1, 2, 3, 4, 5, 6, 7}(SCT_013_005,_010,_030,_050,_100,_020,_060); l'ordine dei codici non è l'ordine delle portate. -
WIRED_CTè la classe dei moduli forniti con la propria TA cablata montata; lo schema accetta per essa i codici 1/2/3. Il modulo è calibrato di fabbrica con quel sensore, quindi il componente rifiuta di cambiarne classe o modello (vedere la nota sui moduli accoppiati in fabbrica sopra). -
BUILTIN_CTè la classe dei moduli con sensore integrato;ct_model:non è né necessario né accettato dallo schema. DichiarareBUILTIN_CTsenza l'hardware corrispondente non ha senso.
Se il YAML supera il validatore (schema vecchio + firmware nuovo, forzatura manuale), il firmware restituisce REG_ERROR = 0xFE DEV_ERR_PARAM — il modulo non scrive un codice non supportato: restituisce DEV_ERR_PARAM e gli specchi restano al valore precedente.
Come riconoscere il modulo
Ci sono due chiavi nel YAML — se ne sceglie una a seconda che si abbia la stessa pinza su tutti i canali oppure pinze diverse. La transizione sintattica va da un valore scalare a una lista YAML (array):
Passaggio 1 — una sola pinza per tutti i canali (ct_model:, valore singolo)
Se si ha una UI1 (un solo canale di corrente) oppure una UI3 con pinze identiche su tutti e tre i canali — una sola riga:
rbamp:
id: meter1
ct_model: SCT_013_030 # ← scalar value, one model for all channels
Questo è il caso più comune. La maggior parte delle installazioni parte con un unico modello di pinza e non va mai oltre questa linea.
Passaggio 2 — pinze diverse su canali diversi (ct_models:, elenco)
Se hai un UI2 / UI3 e vuoi mettere pinze diverse sui canali (per esempio una piccola su una linea stand-by, una grande sull'alimentazione di rete) — sostituisci ct_model: con ct_models: (con la s finale) e usa un elenco YAML tra parentesi quadre:
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# ↑ ↑ ↑
# channel 0 channel 1 channel 2
#
# This is a standard YAML list (1..16 elements; only as many as the module has channels are applied).
# Order matters: the position in the list = the channel index.
# Mixed codes such as [1, 3, 6] are each kept on their own channel.
È il punto in cui si sbaglia più spesso nel modificare sistemi multi-canale. Ricordare: ct_model: (senza s) è un valore scalare per un singolo modello; ct_models: (con s) è una lista di valori tra parentesi quadre, uno per canale. Vengono applicate solo tante voci quanti sono i canali del modulo (1 per UI1, 2 per UI2, 3 per UI3); le voci in più sono ignorate con un avviso.
I modelli per canale sono memorizzati solo dai moduli che li conservano dopo un ciclo di alimentazione. Se il modulo collegato non lo fa, il componente rifiuta rumorosamente (avviso, chiavi ignorate) invece di scrivere un valore che si annullerebbe in silenzio — usare lì la singola ct_model:.
⚠ Mutuamente esclusive. Dichiarare contemporaneamente sia ct_model: SIA ct_models: è un errore di validazione dello schema (cv.Invalid). Usarne solo una delle due.
Un'installazione UI3 con pinze di dimensioni diverse
Lo scenario canonico per una casa con generazione propria o con tipi misti di carichi:
- Canale 0 — piccoli consumatori (illuminazione LED, modalità stand-by, elettronica). Una pinza SCT_013_005 (5 A) dà la massima risoluzione a bassa corrente.
- Canale 1 — carichi principali (piano cottura, scaldabagno). Una pinza SCT_013_030 (30 A) copre il picco domestico tipico.
- Canale 2 — una derivazione a media potenza (scaldabagno, ~3-5 kW). Una pinza SCT_013_020 (20 A) è il punto ideale tra accuratezza e margine per un sotto-contatore tipico.
In un singolo blocco YAML rbamp: basta dichiarare:
rbamp:
id: home_meter
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
sensor:
- platform: rbamp
rbamp_id: home_meter
voltage:
name: "Mains Voltage"
current:
name: "Lighting Current" # SCT_013_005, channel 0
current_1:
name: "Appliances Current" # SCT_013_030, channel 1
current_2:
name: "Boiler Current" # SCT_013_020, channel 2
# ...power_0/_1/_2, energy_0/_1/_2 likewise
Il componente stesso assegna il modello esatto a ciascun canale all'avvio.
Che cosa fa la chiave sotto il cofano
Con firmware v1.2+, scrivere ct_model: / ct_models: carica in modo atomico i coefficienti di fabbrica (soglia di rumore + guadagno) per il modello scelto nella RAM del modulo e li salva in flash. Dal lato utente non serve alcun passaggio di calibrazione aggiuntivo — il modulo esce di fabbrica con tutte le tabelle di coefficienti necessarie.
Su firmware precedenti il valore viene memorizzato come marcatore di modello.
Lettura-confronto-scrittura (v1.3+) — perché l'avvio ora è «immediato»
All'avvio il componente v1.3 legge l'attuale REG_CT_MODEL_CH0/1/2 (specchi di 0x51-0x53) e lo confronta con i valori richiesti dal YAML. Se coincidono, la scrittura in flash viene saltata del tutto.
| Scenario di avvio | v0.4.0 (scrittura sempre) | v1.3 (lettura-confronto-scrittura) |
|---|---|---|
| Configurazione già applicata (i riflessi corrispondono) | ~700 ms × N canali di cancellazione flash | 0 ms (solo rilettura I²C) |
| Configurazione modificata (un modello) | ~700 ms | ~700 ms (solo delta) |
| UI3 con tre modelli diversi (installazione a freddo) | ~2.8 s di blackout | ~2.1 s (3 × 700 ms + verifica) |
| UI3 con gli stessi modelli (avvio a caldo) | ~2.8 s di blackout ogni volta | ~0 ms |
In pratica: mantenere ct_model: / ct_models: nel YAML in modo permanente — la configurazione è idempotente e non consuma la flash ai riavvii ripetuti.
Il cambio del valore nominale SCT mantiene l'accuratezza
Su un modulo STD ct_model è solo un'etichetta e non imposta alcun guadagno. Il resto di questa sezione descrive i moduli BASIC.
Ogni modulo SCT è calibrato di fabbrica con lo SCT-013-030. Quando si seleziona un altro valore nominale (ct_model: SCT_013_010, ad esempio), corrente, potenza ed energia restano accurate — la calibrazione di fabbrica per unità viene preservata:
-
Sul firmware del modulo fino alla 1.4.19 il componente completa la scrittura del modello con il riavvio del modulo richiesto dalla procedura (salvataggio, reset, nuova identificazione) e scala corrente, potenza attiva/reattiva ed energia sulla sensibilità del sensore selezionato in base al guadagno effettivamente applicato dal modulo. Il riavvio compare nel log ed è normale; i sensori possono saltare un ciclo. Un successivo riavvio del modulo (tuo o esterno) viene rilevato e la scala viene ricalcolata automaticamente.
-
Sui firmware più recenti (1.4.20+) il modulo esegue da solo il cambio; il componente lo rileva e lascia invariate le letture (scrittura semplice del modello, senza riavvio).
-
Tensione e fattore di potenza non ne sono influenzati.
- Se il guadagno applicato dal modulo differisce dal valore atteso di più di ±5 %, il componente registra un avviso e non scala.
Per nulla di tutto questo serve modificare il YAML.
Associazione multi-canale
Il componente associa i canali uno alla volta; l'ordine non conta. Modelli misti su un modulo (ad esempio i codici [1, 3, 6] su un modulo a tre canali) vengono mantenuti ciascuno sul proprio canale.
Il componente stesso alimenta il watchdog (App.feed_wdt()) durante ogni finestra di scrittura in flash — il budget tipico di setup() di ESPHome di 15 s non viene superato nemmeno con un'installazione a freddo di UI3.
Verifica dell'installazione
Dopo il primo avvio, verifica le letture su un carico puramente resistivo — una lampadina a incandescenza, un bollitore, una resistenza di riscaldamento. Un carico resistivo dà una forma del segnale nota:
- Il fattore di potenza (
power_factor) dovrebbe essere vicino a 1.00 (stabilmente > 0.95). - La potenza attiva (
power) dovrebbe essere positiva e stabile. - La corrente RMS (
current) dovrebbe corrispondere aP / Ucon un'accuratezza ragionevole.
Se le letture non tornano:
currentstabilmente ~0 con il carico in funzione → controlla la polarità e che la pinza circondi un solo conduttore (vedi sotto)powercostantemente negativa → invertire la pinza sul conduttore (freccia nel verso opposto)power_factor~0.5..0.7 su una lampadina a incandescenza → può esserci un carico reattivo nelle vicinanze oppure la pinza può essere installata male
La diagnostica dettagliata orientata ai sintomi è in 10_troubleshooting.md.
Polarità della pinza TA
Il corpo della pinza porta una freccia che indica la direzione del flusso di energia «normale» (consumo, verso il carico). Con installazione corretta (freccia nella direzione della corrente verso il carico):
P_real > 0— consumo.P_real < 0— esportazione (solo STANDARD (STD)).
Se la potenza attiva è negativa con un utilizzatore in funzione — inverti fisicamente la pinza sul conduttore. Non correggere la polarità via software: maschera i bug di direzionalità nelle automazioni a valle.
La pinza deve chiudersi completamente attorno a un solo conduttore. Non far passare sia L sia N attraverso la stessa pinza — i loro campi magnetici si annullano e il sensore leggerà quasi zero.
Canale di tensione
Gli SKU UI* contengono un trasformatore di tensione integrato. L'avvolgimento primario si collega a L e N di rete attraverso i blocchi morsetti del modulo, e il modulo lo misura internamente.
La configurazione di fabbrica del trasformatore è fissa sulla revisione della scheda — l'utente non ha nulla da configurare. Il sensore voltage è pronto all'uso.
Gli SKU solo-I (I1 / I2 / I3) non hanno un canale di tensione. Lo slot voltage restituisce 0 su questi e non va dichiarato insieme a power: o energy: (il validatore dello schema controlla questa dipendenza).
Moduli multi-canale
Su UI2 / UI3 ogni canale è un circuito di misura separato e indipendente, non un nucleo magnetico condiviso. Ciò consente di:
- Applicare un unico modello di TA a tutti i canali (
ct_model:) — la configurazione tipica per carichi uniformi. - Assegni modelli diversi a canali diversi (
ct_models:) — per ottimizzare la precisione su installazioni miste (vedi sopra). - Dedica un canale ai consumi e un altro all'immissione del solare — la polarità di ciascun canale è impostata indipendentemente dalla direzione fisica della pinza.
Cosa segue
- 04_hardware.md — cablaggio fisico, scelta dei GPIO, bus multi-modulo
- 05_quickstart.md — primo avvio in 5 minuti con una pinza già configurata
- 10_troubleshooting.md — diagnostica dell'installazione per sintomi
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/03_sensor_selection.md (v1.9.1)