03 · Selezione del sensore di corrente
Questo capitolo risponde a due domande:
- Quale sensore di corrente scegliere per un dato carico.
- Come comunicare al modulo rbAmp la sua scelta, in modo che la calibrazione di fabbrica per quella combinazione si carichi automaticamente.
Il collegamento fisico del sensore (orientamento della pinza, verifica della polarità L/N) è trattato in 04_hardware.md. Questo capitolo riguarda la scelta del modello e le chiamate API.
Classe del sensore
I moduli rbAmp lavorano con pinze CT della famiglia SCT-013. Deve indicare al modulo la classe del sensore una volta, con rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013), prima di scegliere un modello specifico di pinza CT con rbamp_set_ct_model().
Scelta del modello SCT-013
La famiglia SCT-013 comprende sette modelli che differiscono per la corrente massima del circuito primario. Tutti e sette i codici {1, 2, 3, 4, 5, 6, 7} sono supportati.
code |
Modello | Intervallo di corrente | Stato | Uso tipico |
|---|---|---|---|---|
| 1 | SCT-013-005 | 0…5 A | ✅ caratterizzato | Carichi piccoli — lampade, elettronica a bassa potenza, un singolo interruttore |
| 2 | SCT-013-010 | 0…10 A | ✅ caratterizzato | Un singolo apparecchio di media potenza — frigorifero, lavatrice, condizionatore fino a 2 kW |
| 3 | SCT-013-030 | 0…30 A | ✅ caratterizzato | Ingresso di servizio di una famiglia di media dimensione — fino a ~7 kW |
| 4 | SCT-013-050 | 0…50 A | ✅ caratterizzato | Grande ingresso di servizio — riscaldamento elettrico, caricatore EV, casa con carichi di picco |
| 5 | SCT-013-100 | 0…100 A | ✅ caratterizzato | Presa di servizio principale di una casa o di un piccolo ufficio |
| 6 | SCT-013-020 | 0…20 A | ✅ caratterizzato | Ingresso di servizio medio — apparecchi da 3–4 kW, grandi elettrodomestici domestici |
| 7 | SCT-013-060 | 0…60 A | ✅ caratterizzato | Sotto-contatore industriale |
Codici accettati — {1, 2, 3, 4, 5, 6, 7}. Un codice fuori da questo insieme (per esempio 0 o 8) passato a rbamp_set_ct_model_ch restituisce ESP_ERR_INVALID_ARG + REG_ERROR = 0xFE (ERR_PARAM). Vedi 09 · Riferimento API, sezione "Modello di errore v1.3", per i dettagli su come il componente restituisce questo errore.
Come scegliere il modello giusto
La regola di base:
-
Determini la corrente massima che può circolare nel circuito (in base al carico più grande + margine del 30 %).
-
Scelga la pinza nominale più piccola sopra questo valore.
- Non sovradimensioni di oltre 5×. Una pinza SCT-013-100 su un circuito con massimo 5 A funzionerà, ma dà bassa risoluzione e grande errore sui valori tipici.
Margine
Una pinza SCT-013 opera senza saturazione entro il proprio intervallo nominale. Picchi brevi (avviamento del compressore, carico induttivo) possono superare il valore nominale di 5–7× — è normale, la pinza lo sopporta fisicamente, ma la misura diventa non lineare sopra il valore nominale.
Se il carico ha una corrente di picco superiore alla portata della pinza, scelga la taglia successiva. Per esempio, per una lavatrice con corrente di spunto di 12 A (mentre la portata di funzionamento è 2–3 A): 12 A × 1.3 = 15.6 A, quindi la pinza di portata più piccola superiore è la SCT-013-020 (codice 6) — meglio di una SCT-013-005.
Come comunicare al modulo la sua scelta
Due chiamate sono obbligatorie, nell'ordine corretto — prima rbamp_set_sensor_class(), poi rbamp_set_ct_model(). Se chiama rbamp_set_ct_model() prima di rbamp_set_sensor_class(), il componente restituisce ESP_ERR_INVALID_STATE e il preset NON viene caricato.
Un modello CT è un preset funzionale, non un'etichetta. Scrivere il modello CT applica subito la linea di base NF, il guadagno e il fattore di forma alla pipeline di misura del modulo; le letture di corrente cambiano. Cambiare sensor_class riporta il modello CT al predefinito (0) e va impostato di nuovo.
#include "driver/i2c_master.h"
#include "rbamp.h"
void setup_sensor(rbamp_handle_t dev) {
/* Step 1: select the sensor family.
* MANDATORY before rbamp_set_ct_model(). */
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
ESP_LOGE("app", "set_sensor_class: %s", rbamp_err_to_str(err));
return;
}
/* Step 2: select the model within the family.
* 1 = SCT-013-005, 2 = SCT-013-010, 3 = SCT-013-030,
* 4 = SCT-013-050, 5 = SCT-013-100, 6 = SCT-013-020, 7 = SCT-013-060. */
err = rbamp_set_ct_model(dev, 3); /* e.g. SCT-013-030 */
if (err != ESP_OK) {
/* Possible causes:
* ESP_ERR_INVALID_STATE — rbamp_set_sensor_class() was not called
* before rbamp_set_ct_model()
* ESP_ERR_INVALID_ARG — code not in {1,2,3,4,5,6,7}
* ESP_FAIL — communication error (NACK after retry)
*/
ESP_LOGE("app", "set_ct_model: %s", rbamp_err_to_str(err));
return;
}
}
Il componente non chiama deliberatamente rbamp_set_sensor_class() al posto suo. Se questo passo viene saltato, rbamp_set_ct_model() restituisce ESP_ERR_INVALID_STATE senza scrivere in flash. Questo serve a mantenere il comportamento prevedibile ed esplicito — nessuna "magia" nell'API pubblica.
Dopo queste due chiamate:
-
Il modulo memorizza entrambi i valori in flash — l'impostazione sopravvive a un reset, a un ciclo di alimentazione e a un nuovo flash del firmware.
-
I coefficienti di calibrazione per questa specifica combinazione (classe del sensore + modello) sono caricati dalla tabella di preset di fabbrica. Non serve toccare alcun registro di calibrazione manuale.
-
La successiva chiamata
rbamp_read_current(dev, 0, &i)restituisce già un valore in ampere con la scala corretta.
Tempo totale per entrambe le chiamate è di circa 1.4 secondi (due operazioni di scrittura in flash × ~700 ms ciascuna, limitate dal tempo di cancellazione della pagina flash). Si fa una volta alla prima installazione; l'impostazione è memorizzata in flash e non viene più ripetuta.
Se ha già selezionato il sensore al primo avvio e sta solo riavviando l'ESP32, non deve ripetere le chiamate rbamp_set_sensor_class() e rbamp_set_ct_model() — il modulo ricorda la scelta precedente. Non fa però danno ripeterle — richiamare con lo stesso valore riscrive semplicemente lo stesso byte.
Verifica della configurazione
Una semplice verifica dopo rbamp_set_ct_model():
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
static const char *TAG = "rbamp_check";
void sanity_check(rbamp_handle_t dev) {
ESP_LOGI(TAG, "Ready. Connect a purely resistive load "
"(e.g. an incandescent lamp).");
ESP_LOGI(TAG, "Expect a stable PF ~= 1.0 and positive P.");
while (1) {
float u = NAN, i = NAN, p = NAN, pf = NAN;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i);
rbamp_read_power(dev, 0, &p);
rbamp_read_power_factor(dev, 0, &pf);
ESP_LOGI(TAG, "U=%.1f V I=%.2f A P=%.1f W PF=%.2f",
(double)u, (double)i, (double)p, (double)pf);
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
Su un carico puramente resistivo (lampada a incandescenza, bollitore elettrico, elemento riscaldante) ci si deve aspettare:
U≈ 220–240 V (per una rete a 230 V)I≈ corrisponde alla potenza del carico (P / U)P> 0 e stabilePF≈ 1.0 (nettamente positivo)
Se qualcosa non torna, veda 10_troubleshooting.md.
Moduli con più canali di corrente
Gamma di SKU — cosa si adatta all'attività
| SKU | Canali I | Canale U | Uso tipico |
|---|---|---|---|
| UI1 | 1 | sì | Un singolo carico con calcolo completo della potenza (P, PF, Q, Wh) — il tipico contatore di rete |
| UI2 | 2 | sì | Due carichi indipendenti su una fase con potenza per canale (1 U + 2 I) |
| UI3 | 3 | sì | Tre carichi su una fase con potenza per canale (1 U + 3 I) |
| I1 | 1 | no | Sotto-contatore senza calcolo di potenza (solo corrente) — quando la misura di rete è gestita da un UI1 separato |
| I2 | 2 | no | Sotto-contatore di corrente a due canali — ripartizione per circuito |
| I3 | 3 | no | Sotto-contatore di corrente a tre canali — ripartizione per circuito / topologia a doppio TA |
Cosa misura ciascun canale
- Canale U (solo UI): U_rms, U_peak, frequenza. Uno* per modulo (legato alla fase di ingresso).
- I-channels:
- sulle varianti UI — ogni canale fornisce I_rms, I_peak, P (potenza attiva), PF, avg_p sul periodo.
- sulle varianti I — solo corrente (I_rms, I_peak). Potenza attiva e PF non sono calcolate — richiedono la tensione, che la variante I non ha. I registri
power[]/power_factor[]sulle varianti I restituiscono 0. - Multifase contro multipunto: il modulo NON distingue a quale fase è collegato ciascun canale I. Questa semantica sta sul lato master.
Modello di CT per canale — calibrazione indipendente per canale
Sui moduli multi-canale (I2, I3) ogni canale di corrente ha una scelta indipendente del modello SCT-013. Può collegare, per esempio, un SCT-013-005 al canale 0 (una sola presa), un SCT-013-030 al canale 1 (la linea della cucina elettrica) e un SCT-013-020 al canale 2 (uno scaldabagno o una caldaia).
L'API per la selezione per canale è rbamp_set_ct_model_ch(dev, channel, code):
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013); /* once for all */
/* v1.3: channel binding order is arbitrary. */
rbamp_set_ct_model_ch(dev, 0, 1); /* channel 0: SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3); /* channel 1: SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6); /* channel 2: SCT-013-020 */
✅ L'ordine di associazione è arbitrario (canone v1.3). Scrivere REG_CT_MODEL (0x05) prepara il valore ma non lo applica automaticamente a nessun canale. L'applicazione avviene solo tramite CMD_SET_CT_MODEL_CHn per canale, che prende il valore attualmente preparato e lo scrive sul proprio canale. I canali si possono configurare in qualsiasi ordine (ch0 per primo, per ultimo, alternati — non fa differenza); non si verifica alcuna sovrascrittura. Ogni menzione di "crescente / decrescente / associare ch0 per ultimo" nei documenti e nel codice più vecchi si riferisce al comportamento precedente alla v1.3 — può essere rimossa.
Ogni canale viene associato in due passi: (1) scrive il modello in REG_CT_MODEL (predisposizione), (2) CMD_SET_CT_MODEL_CHn (associazione). La validazione (classe, modello) è eseguita dal firmware nel passo di associazione.
Se più canali ottengono lo stesso modello, può chiamare con lo stesso codice — l'applicazione ripetuta è idempotente:
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model_ch(dev, 0, 1);
rbamp_set_ct_model_ch(dev, 1, 1);
rbamp_set_ct_model_ch(dev, 2, 1);
Un'alternativa per il tipico caso I2/I3 è rbamp_configure_channels(dev, class, models[], n): un'unica operazione configura la classe + tutti i canali + scrive tutto in flash con un unico CMD_SAVE_USER_CONFIG finale (favorevole alla flash — un ciclo di cancellazione invece di N). Vedi il capitolo 09 · Riferimento API, sezione "Configurazione multi-canale".
La forma a parametro singolo rbamp_set_ct_model(dev, code) è una forma di comodo per gli SKU a canale singolo (applicata al canale 0). Sui moduli multicanale equivale a rbamp_set_ct_model_ch(dev, 0, code).
Configurazione avanzata: due pinze di portata diversa su un unico filo
⚙ Un pattern aggiuntivo, non uno di base. Questa sezione descrive una tecnica facoltativa per migliorare la risoluzione a correnti basse. Per la maggior parte delle installazioni basta una singola pinza dimensionata sull'intervallo del carico. Usi il doppio CT solo se ha un requisito di precisione specifico a correnti < 1 A.
Quando si applica
- Moduli multicanale I2 / I3 (hardware attuale).
-
Lo stesso filo va misurato sia per carichi piccoli (≤ 1 A) sia per eventi di picco (≥ 5 A), con la stessa qualità.
-
Un esempio tipico: la presa di servizio di un appartamento, dove c'è un consumo in standby di 50–100 W durante il giorno e lo spunto di un bollitore o di un fornello elettrico da 3+ kW la sera.
L'idea
Due pinze SCT-013 di portate diverse montate sullo stesso filo:
-
Canale 0 — la piccola pinza (es. SCT-013-005, 5 A): vede correnti piccole con migliore risoluzione e un rumore di fondo più basso.
-
Canale 1 — la pinza grande (es. SCT-013-030 o superiore): gestisce correnti superiori al punto di sovraccarico della pinza piccola senza saturazione.
Il master sceglie da sé quale canale usare in base al valore di corrente — finché la pinza piccola è nel suo intervallo lineare la sua lettura è più accurata; quando viene superata, passa a quella grande.
Configurazione
La classe del sensore una volta, poi i modelli per canale in qualsiasi ordine (v1.3 pura predisposizione, l'ordine non conta):
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013); /* once */
rbamp_set_ct_model_ch(dev, 0, 1); /* ch0 = SCT-013-005 (0..5 A) — small clamp */
rbamp_set_ct_model_ch(dev, 1, 3); /* ch1 = SCT-013-030 (0..30 A) — large clamp */
Stato finale: ch0 = SCT-013-005, ch1 = SCT-013-030. ✓
In alternativa tramite rbamp_configure_channels() — un'operazione invece di due:
uint8_t models[2] = { 1, 3 }; /* ch0=5A, ch1=30A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 2);
Logica di aggregazione lato master
Il modello più semplice consiste nel commutare su una soglia:
float read_combined_current(rbamp_handle_t dev) {
float i_low = NAN;
float i_high = NAN;
esp_err_t err_low = rbamp_read_current(dev, 0, &i_low); /* small */
esp_err_t err_high = rbamp_read_current(dev, 1, &i_high); /* large */
/* While the small clamp is far from saturation, it gives better
* accuracy at small currents. Switch to the large one as it
* approaches the overload point.
*
* The 4.5 A threshold for the SCT-013-005 is an example value;
* figures for low-current dual-CT use are not published. */
if (err_low == ESP_OK && i_low < 4.5f) {
return i_low;
}
return (err_high == ESP_OK) ? i_high : NAN;
}
Due pinze sullo stesso filo sono fisicamente possibili sulla maggior parte dei cavi di sezione domestica, ma richiedono un po' di spazio nel quadro.
⚙ Cifre del doppio CT. Le cifre per l'uso del doppio CT a bassa corrente (comportamento vicino alla soglia, divergenza delle due pinze nell'intervallo di sovrapposizione) non sono pubblicate. Consideri il doppio CT come un pattern pilota; per applicazioni critiche è preferibile una singola pinza dimensionata sull'intervallo di carico superiore.
Moduli multicanale — I2 e I3 (solo corrente)
I moduli di sola corrente per la topologia multi-canale sono I2 (due canali di corrente) e I3 (tre canali di corrente). Entrambi i moduli non hanno un canale U, quindi il calcolo di P / PF / Q lato modulo è impossibile — forniscono corrente per canale (I_rms, I_peak su ciascun canale) e nient'altro.
UI2 e UI3 aggiungono il canale U (1 U + 2 I / 1 U + 3 I), così la potenza per canale viene calcolata sul modulo. Dove serve solo una suddivisione di corrente, usi le I2/I3 come sotto-contatori di corrente insieme a una UI1 separata all'ingresso di servizio, che fornisce l'energia di rete + la tensione.
Lettura dei canali (I2 / I3)
float i0, i1, i2;
rbamp_read_current(dev, 0, &i0); /* ch0 */
rbamp_read_current(dev, 1, &i1); /* ch1 */
rbamp_read_current(dev, 2, &i2); /* ch2 — I3 only */
/* On an I variant rbamp_read_power(...) returns 0 — this is by design. */
float p_dummy; rbamp_read_power(dev, 0, &p_dummy); /* = 0.0f */
Se serve la potenza attiva su ogni sotto-linea, metta un UI1 all'ingresso di servizio e ripartisca la sua potenza totale in proporzione alla corrente per canale I[k] dagli I2/I3. Questo è il tipico impianto domestico:
/* Pseudo-pattern: UI1 on mains, I3 on 3 sub-lines */
float p_mains_total, i0, i1, i2;
rbamp_read_power(mains_ui1, 0, &p_mains_total);
rbamp_read_current(loads_i3, 0, &i0);
rbamp_read_current(loads_i3, 1, &i1);
rbamp_read_current(loads_i3, 2, &i2);
float i_sum = i0 + i1 + i2;
if (i_sum > 0.01f) {
float p0 = p_mains_total * i0 / i_sum; /* approximation */
/* ... */
}
Questa è un'approssimazione: la suddivisione per corrente funziona quando il fattore di potenza è all'incirca lo stesso su tutti i carichi. Per una contabilizzazione accurata della potenza per carico, usi una variante UI (UI1 / UI2 / UI3 / UI5 / UI7) su ciascuna linea.
Applicazioni di I2 / I3
-
Sotto-misurazione della corrente: ripartizione della corrente per circuito, un unico punto di installazione al quadro invece di un modulo separato per linea.
-
Disaggregazione insieme a una UI1: la UI1 fornisce energia / potenza della rete, e le I2/I3 scompongono il consumo per derivazione (vedi capitolo 06, scenario 1).
-
Monitoraggio della corrente senza contabilità della potenza: controllo di sovraccarico, rilevamento di accensione/spegnimento del carico, profilo I(t).
-
Doppio CT + un terzo canale (I3): una pinza grande sul canale 0 per un ampio intervallo, una piccola sul canale 1 per la precisione a correnti basse, il terzo canale per una linea ausiliaria separata. Vedi la sezione "Configurazione avanzata: due pinze di valori diversi" sopra.
Calcolo della potenza lato master:
float i;
rbamp_read_current(dev, ch, &i);
/* If the voltage is known (from a UI module upstream or fixed) */
const float U_nominal = 230.0f;
float p_estimated = U_nominal * i; /* without PF — guaranteed overestimate */
Per una contabilità della potenza accurata, usi un modulo UI (con un canale U).
Approcci per migliorare la sensibilità a basse correnti
Se il carico ha un ampio intervallo dinamico (per esempio 1 W in standby per un router contro uno scaldabagno da 2000 W sulla stessa presa), una sola pinza dimensionata per il limite superiore perde le correnti basse nel rumore.
Tre strategie, in ordine di crescente complessità:
-
Dimensioni la CT sul massimo, non "con margine". L'errore più comune è mettere una SCT-013-100 (100 A) su una presa domestica con un consumo tipico di 0.5–10 A. Il segnale sta nel 1–10 % inferiore dell'intervallo del sensore — dove il rumore diventa paragonabile al segnale. Per lo scenario domestico (presa da 16 A) la SCT-013-030 è ottimale; per collegare un singolo apparecchio (≤ 5 A) la SCT-013-005.
-
Topologia a doppio CT (richiede uno SKU I2/I3 — due canali di corrente su un modulo): una pinza piccola per l'intervallo inferiore e una grande per quello superiore, con il master che sceglie in base a una soglia. Veda la sezione «Topologia a doppio CT» sopra — lo schema è un pilota; i valori per l'uso a doppio CT con basse correnti non sono pubblicati.
-
Rumore di fondo (lato fabbrica): la calibrazione del modulo ne tiene già conto. Lato utente non c'è nulla da fare oltre a
setSensorClass()+setCTModel(). Valori di precisione concreti a correnti basse non sono pubblicati.
Modalità produzione vs fabbrica (riferimento sulla persistenza)
Il modulo rbAmp opera in due modalità che differiscono per cosa esattamente viene salvato in flash. La modalità corrente si legge dal relativo registro di stato del modulo.
| Comando (opcode) | Produzione | Persiste |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | ct_model / sensor_class / fleet_config / group_id / label |
CMD_COMMIT_ADDR (0x30, armato con magic) |
✅ OK | Indirizzo I²C (vedi 04 · Cablaggio — modifica dell'indirizzo) |
CMD_RESET (0x01) |
✅ OK | — (reset software) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (snapshot di periodo) |
CMD_CLEAR_ERROR |
✅ OK | — |
CMD_SAVE_GAINS |
❌ BLOCCATA in produzione (restituisce ERR_PARAM) | guadagni / NF / fase (calibrazione di fabbrica) |
CMD_FACTORY_RESET |
❌ BLOCCATO in produzione | — |
In modalità produzione, le scritture della calibrazione di fabbrica (CMD_SAVE_GAINS, CMD_FACTORY_RESET) sono rifiutate dal firmware — questo protegge dalla cancellazione accidentale dei coefficienti di fabbrica. Portare il modulo in modalità fabbrica è un'operazione lato produttore; gli utenti finali non ne hanno bisogno.
La guardia di produzione accetta una scrittura in RAM (una lettura successiva restituisce il valore scritto), ma il salvataggio in flash può essere rifiutato. Dopo un riavvio il valore torna allo stato precedente alla scrittura. L'unico modo valido per confermare la persistenza è riavviare il modulo tramite CMD_RESET e rileggere:
rbamp_set_ct_model(dev, code);
rbamp_reset(dev); // CMD_RESET 0x01, works in production
vTaskDelay(pdMS_TO_TICKS(400)); // boot complete
uint8_t check; rbamp_read_ct_model(dev, 0, ✓);
assert(check == code); // ONLY now is persistence confirmed
Rimando incrociato: 09 · Riferimento API — dettagli sui singoli opcode; 10 · Diagnostica — cosa fare se la persistenza non è confermata.
Cosa c'è dopo
-
04 · Cablaggio — collegamento fisico della pinza, orientamento della freccia, polarità L/N
-
05 · Guida rapida — il progetto completo della prima accensione
-
06 · Esempi — scenari di lavoro per carichi diversi
-
10 · Diagnostica — cosa fare se le letture sono anomale (PF negativo, I instabile, ecc.)
Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/03_sensor_selection.md (v1.7.3)