10 · Risoluzione dei problemi
Questo capitolo è organizzato per i sintomi che osserva, non per classificazione interna degli errori. Se è qui, qualcosa non funziona come dovrebbe. Trovi il sintomo nell'elenco qui sotto, passi alla sezione corrispondente e segua la procedura diagnostica.
La maggior parte dei problemi di banco rientra in tre categorie:
-
A livello di bus — il modulo non risponde su I²C, le letture restituiscono
NaNoRB_ERR_NACK. -
Livello dei dati — il modulo risponde, ma i numeri sono sbagliati: zeri, valori strani, segno errato.
-
Livello applicativo — il collegamento è instabile, il contatore Wh diverge, lo sketch si blocca.
Scorciatoia per chi ha fretta: i contatori dev.retryExhaustionCount() e dev.sanityRejectCount() devono essere 0 a regime. Se non lo sono, andare direttamente alla sezione "Il modulo non risponde su I²C" qui sotto.
Verificare prima: U=0 → L/N non collegati o interruttore aperto; I=0 → jack CT non inserito a fondo (o nessun modello CT impostato, vedi sotto).
Il modulo non risponde su I²C
Cosa si osserva: dev.begin() restituisce false con lastError() == RB_ERR_NACK, oppure le letture in esecuzione "perdono" regolarmente RB_ERR_NACK nel codice utente.
Passo 1 — Scansione del bus
Per prima cosa, confermi che il modulo sia effettivamente presente sul bus:
#include
void setup() {
Serial.begin(115200);
Wire.begin();
Serial.println(F("Scanning..."));
for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
Wire.beginTransmission(addr);
if (Wire.endTransmission() == 0) {
Serial.print(F("Found 0x")); Serial.println(addr, HEX);
}
}
}
void loop() {}
Output atteso: Found 0x50 (o un indirizzo diverso se è stato modificato).
Se non si trova nulla — il problema è nel cablaggio o nell'alimentazione:
- SDA / SCL non sono invertiti.
-
Entrambe le linee hanno una pull-up verso 3.3 V (la scheda del modulo ha resistenze di pull-up integrate da 4.7 kΩ — non servono pull-up esterne per un singolo modulo).
-
Il pin di alimentazione del modulo porta effettivamente 5 V (4.5–5.5 V) — le revisioni più vecchie della scheda non tollerano i 3.3 V.
-
Nessun altro master (sonda di debug, un altro Arduino) è in attesa sulle stesse linee.
Se il modulo viene trovato, ma a un indirizzo inatteso — qualcuno lo ha riassegnato in precedenza sul banco. Aggiornare l'argomento del costruttore:
RbAmp dev(Wire, 0x52); // address from the bus scan
Passo 2 — Schema NACK di base dell'ESP32
Se la scansione del bus trova il modulo, ma dev.readVoltage() restituisce periodicamente NaN con RB_ERR_NACK — e lei usa un ESP32 — si tratta di un schema di base documentato: il driver i2c_master di ESP-IDF v5 presenta anomalie con i moduli rbAmp con firmware v1.0.
La mitigazione è già integrata nella libreria (RBAMP_NACK_RETRY_ATTEMPTS=3 di default su ESP32), ma sotto carico pesante il budget dei tentativi può esaurirsi.
Cosa fare su ESP32:
- Abbassi la velocità del bus a 50 kHz:
Wire.begin();
Wire.setClock(50000);
- Aumentare il numero di tentativi di ripetizione per un carico pesante:
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include
- Monitori il contatore di esaurimento dei tentativi — in regime stazionario deve restare a zero:
if (dev.retryExhaustionCount() > 0) {
Serial.print(F("WARN: retry exhausted: "));
Serial.println(dev.retryExhaustionCount());
}
Passo 3 — NACK su piattaforme non ESP32
Su AVR / STM32duino / ESP8266 / SAMD / RP2040 non esiste uno schema di NACK di base — su queste piattaforme si osserva un tasso di NACK di ~0 % con rbAmp. La libreria imposta di default RBAMP_NACK_RETRY_ATTEMPTS=1 su di esse.
Se qui si verificano NACK, cerchi:
-
Capacità del bus elevata — cavi lunghi + molti dispositivi. Abbassi la velocità a 100 kHz o accorci il cavo.
-
Contesa del master — la libreria non supporta una configurazione multi-master.
-
Un SCL flottante tra le transazioni — manca un pull-up.
La corrente legge zero su un carico funzionante
Cosa osserva: dev.readCurrent(0) restituisce 0.000 (o un valore molto piccolo), anche se un vero consumatore è acceso (un bollitore, una lampada, un ferro). dev.readPowerFactor(0) può mostrare un valore strano (NaN / 0 / ±1) — è una conseguenza; la causa è nella corrente.
Procedura diagnostica
- Verificare che la classe del sensore e il modello CT siano configurati:
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) { // or your model: see below
Serial.println(F("model set failed"));
}
Senza queste due chiamate i coefficienti di calibrazione non vengono caricati e la corrente risulta sempre zero. Questo passo si esegue una volta alla prima installazione — la scelta viene salvata nella flash del modulo.
- Verifichi che il modello TA corrisponda al carico. Una pinza TA grande (ad esempio SCT-013-100, 100 A) su un carico piccolo (una lampada da 50 W = ~0.2 A) produce un segnale proprio al livello del rumore di fondo e le letture saranno zero. Scelga la pinza di portata più piccola sopra la sua corrente massima attesa. La tabella completa è in 03 · Scelta del sensore di corrente.
Se ha un modulo multicanale (UI2 / UI3 / UI5 / UI7) e vuole vedere sia i carichi piccoli sia i picchi, valuti il schema a doppio TA: una pinza piccola (ad esempio SCT-013-005) su un canale dedicato per l'intervallo basso + una grande (SCT-013-030/100) su un altro canale per l'intervallo alto; il master seleziona il valore con una soglia. Lo schema è trattato in 03 · Scelta del sensore di corrente, sezione "Topologia a doppio TA".
- Verifichi l'orientamento della pinza. La freccia sul corpo della pinza deve puntare nella direzione della corrente verso il carico. Se la pinza è "al contrario",
readCurrent()darà la grandezza corretta, mareadPower()darà un valore negativo su un carico in consumo. La conferma —readPowerFactor()mostrerà esattamente −1.0 su un carico resistivo (invece di +1.0). La correzione: rimonti fisicamente la pinza (con il circuito scollegato: la sganci, giri la freccia nel verso giusto, la riagganci). Non inverta il segno via software.
Se tutti e tre i passi superano la prova e la corrente è ancora zero
Allora il segnale all'ingresso del modulo è davvero sotto il rumore di fondo. Verificare:
-
Se la corrente sta effettivamente scorrendo — misurarla con un multimetro (pinza DC / pinza AC) sullo stesso filo.
-
Se la pinza è integra — deve esserci una tensione AC al connettore della pinza proporzionale alla corrente (alcuni millivolt per carichi domestici).
-
Se sta agganciando il filo giusto — un solo conduttore, la linea (L); mai l'intero cavo.
Le letture saltano o tornano come NaN
Cosa osserva: dev.readVoltage() o dev.readCurrent() restituiscono periodicamente NaN. dev.lastError() mostra RB_ERR_NACK oppure RB_ERR_NON_PHYSICAL.
Se lastError() mostra RB_ERR_NACK
Vedi la sezione "Il modulo non risponde su I²C" sopra — è la stessa classe di problema, con una differenza: il collegamento è parzialmente funzionante, ma il budget dei tentativi a volte si esaurisce.
Steps:
-
Su ESP32 — ridurre la velocità a 50 kHz e aumentare
RBAMP_NACK_RETRY_ATTEMPTS=5. -
Su altre piattaforme — controlli la capacità del bus e le resistenze di pull-up.
- Monitorare
dev.retryExhaustionCount()per seguire l'andamento.
Se lastError() mostra RB_ERR_NON_PHYSICAL
Il filtro di sanità della libreria è intervenuto: un float è arrivato dal bus ed è NaN, oppure Inf, oppure |x| > 10000 — chiaramente non un valore fisico. La libreria scarta tale valore e segnala RB_ERR_NON_PHYSICAL invece di far passare dati spazzatura nell'applicazione.
Si tratta di un artefatto raro. Il valore in regime stazionario di dev.sanityRejectCount() è 0. Se non è zero:
-
Controlli
dev.retryExhaustionCount(). Se entrambi i contatori sono diversi da zero, il collegamento è instabile e il filtro di sanità intercetta dati spazzatura dopo tentativi falliti. Alzi il budget dei tentativi (vedere sopra). -
Se
retryExhaustionCount == 0masanityRejectCount > 0, un artefatto è passato attraverso il livello di ripetizione. Accade con un carico di bus molto elevato. AumentiRBAMP_NACK_RETRY_ATTEMPTS=5e ripeta il test.
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F(" sanity rejects: "));
Serial.println(dev.sanityRejectCount());
Il fattore di potenza sembra strano
Cosa si osserva: dev.readPowerFactor(0) restituisce un valore che non corrisponde al tipo di carico.
Aspettative per carico:
| Carico | PF atteso |
|---|---|
| Bollitore, ferro da stiro, lampada a incandescenza | +0.95 .. +1.0 (resistivo) |
| Frigorifero, motore del compressore | +0.6 .. +0.85 (induttivo) |
| Lampada LED, TV (alimentatore a commutazione) | +0.5 .. +0.95 (non lineare) |
| Impianto fotovoltaico che esporta potenza | PF negativo |
PF = NaN o 0 quando I = 0
Il PF è definito come P / (U × I). Con corrente zero I=0 il calcolo non è definito. Il valore specifico restituito dipende dal firmware (può essere NaN, 0 o un segnaposto) — è normale finché la corrente è davvero zero. Appena c'è corrente, il PF sarà valido.
Il PF è esattamente −1.0 su un carico puramente in consumo
La pinza è montata "al contrario" — la freccia non punta nella direzione della corrente verso il carico. Rimedio: rimontare correttamente la pinza (girarla fisicamente; non invertire il segno via software).
Il PF oscilla tra +0.3 e +0.7 su un carico resistivo
-
Causa possibile: la pinza TA è agganciata a un filo di una fase diversa da quella a cui è collegato l'ingresso U del modulo. In un quadro di distribuzione con più fasi è facile agganciare la fase sbagliata per errore — uno sfasamento di 120° o 180° tra U e I dà esattamente questi valori di PF. La correzione è installare il modulo in modo che l'ingresso U e il TA siano sulla stessa fase.
-
Alternativa: il carico non è davvero puramente resistivo. Ripeta il test con un carico resistivo noto (un bollitore elettrico alla massima potenza).
Gli snapshot di periodo sono sempre stale
Cosa si osserva: dev.readPeriodSnapshot(snap) restituisce false con lastError() == RB_ERR_STALE. Significa che il modulo non ha finito di integrare il periodo precedente entro il momento della lettura successiva.
La libreria evita il doppio conteggio dei Wh: su una lettura non aggiornata registra un timestamp del master, e lo snapshot valido successivo copre un periodo, non due.
Accettabile: letture non aggiornate rare (1–2 l'ora a una cadenza di 60 s). Non accettabile: letture non aggiornate consecutive — significa che il firmware non risponde o che il master interroga troppo spesso.
Procedura di verifica della cadenza
-
Controlli la cadenza: 60 s tra gli snapshot è comodo; 30 s è al limite; < 10 s garantisce snapshot obsoleti.
-
Verificare la reattività del modulo tra gli snapshot:
if (dev.probe()) {
Serial.println(F("alive"));
}
-
Controllo diretto del flag —
dev.isPeriodValid()esegue una lettura di un solo byte senza effetti collaterali. -
Verificare la versione del firmware —
dev.firmwareVersion()dovrebbe riportare0x04(v1.3, produzione attuale); i firmware più vecchi (0x01v1.0 /0x02v1.1 /0x03v1.2) mostrano più letture non aggiornate.
La contabilità Wh diverge da un riferimento
Cosa osserva: dev.energy().wh(0) diverge, dopo alcune ore / giorni di funzionamento, dalla lettura del contatore del gestore o da un contatore di riferimento (Kill-A-Watt e simili).
Escludere prima il banale
-
Calibrazione del sensore di corrente: assicurarsi che
setSensorClass()esetCTModel()siano stati chiamati con il modello CT corretto (vedi 03 · Selezione del sensore di corrente). Altrimenti la corrente RMS è calcolata con il pavimento predefinito e il valore di potenza risulta sistematicamente distorto. -
Snapshot obsoleti scartati: se
dev.energy().wh()è costantemente più basso del riferimento, potrebbero mancare intervalli — uno snapshot è tornato non aggiornato, la libreria ha evitato il doppio conteggio, ma la misura dell'intervallo è andata persa. Controlli la cadenza (vedere sopra). -
Deriva dell'orologio del master:
millis()di per sé è affidabile. Ma se il master entra in deep-sleep senza conservare l'RTC, l'intervallo tra lo snapshot precedente e il successivo va perso. Abiliti l'RTC per questi scenari.
Precisione dell'accumulatore per piattaforma
| Piattaforma | Tipo di accumulatore |
|---|---|
| ESP32 / ESP8266 / STM32duino / SAMD / RP2040 | double a 64 bit |
| Arduino AVR (Uno, Mega, Nano) | float a 32 bit (toolchain) |
L'integrazione lato master non aggiunge alcun errore proprio oltre all'accuratezza della potenza attiva del modulo.
Per AVR nelle installazioni di lunga durata, azzerare periodicamente l'accumulatore e salvare il totale a lungo termine nel proprio archivio persistente:
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);
snap.latch_ms differisce dal periodo reale
latch_ms è un timer diagnostico del modulo; non lo usi per l'energia — usi l'orologio del master (master_dt_ms).
RB_ERR_STALE su ogni lettura — il master mantiene automaticamente l'ancora
Cosa osserva: dev.readPeriodSnapshot(snap) restituisce periodicamente false con lastError() == RB_ERR_STALE. (Vedere anche la sezione "Gli snapshot di periodo sono sempre obsoleti" sopra.)
Gestione canonica di dt: su una lettura non aggiornata la libreria Arduino NON azzera la propria ancora interna _last_latch_ms. La lettura valida successiva ottiene un master_dt pari all'intervallo completo dallo snapshot valido precedente — cioè copre sia il periodo "perso" non aggiornato sia quello attuale. Il firmware conserva l'accumulatore avg_p attraverso uno snapshot vuoto (persistenza lato firmware): allo snapshot valido successivo è già il valore mediato sull'intero intervallo. L'integrazione dei Wh resta accurata — nessun doppio conteggio, nessun conteggio in meno.
Nel codice del master non serve alcuna gestione speciale per le letture non aggiornate: la libreria fa tutto correttamente, in automatico. Ignorare RB_ERR_STALE se è raro; se è frequente, diagnosticare la cadenza (sezione sopra).
Lo sketch ESP32 si blocca dopo alcuni minuti
Cosa si osserva: lo sketch su ESP32 parte correttamente, poi entra in blocco / loop di riavvio / timeout del WDT dopo 1–30 minuti.
Wire si blocca su un bus marginale — mitigazione a tre livelli
Cosa osserva in particolare: uno sketch su ESP32 (core Arduino-ESP32) interroga rbAmp correttamente per diversi minuti, poi si "blocca" nel mezzo di una chiamata dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Se il task-WDT è abilitato, lo intercetta; altrimenti lo sketch semplicemente smette di rispondere. Il backtrace decodificato termina nella funzione i2c_ll_is_bus_busy (il driver IDF i2c_master, file i2c_master.c:526, attesa di bus occupato prima dell'invio).
Cosa succede: il Wire di Arduino-ESP32 avvolge lo stesso driver IDF i2c_master dei progetti ESP-IDF nativi. Su un bus marginale (pull-up deboli, tracce lunghe, EMI, interferenze ZC), SDA/SCL possono brevemente "bloccarsi" in uno stato indefinito. Prima di ogni transazione l'i2c_master IDF gira nel ciclo i2c_ll_is_bus_busy, in attesa che il bus si liberi — questa attesa NON è limitata dal timeout I²C della libreria. Se il bus occupato dura più a lungo dell'attesa senza cedere il controllo ad altri task, il task IDLE di FreeRTOS non ottiene la CPU e l'intero sketch si blocca.
Non è un "artefatto solo del debugger". Validato sul banco (lo stesso hardware e lo stesso carico):
| Configurazione del bus | Tasso di blocco |
|---|---|
| 2 pull-up deboli del modulo + NRST del debugger collegato | ~1 blocco ogni 2.1 min |
| 1 pull-up debole del modulo, nessun debugger | ~1 blocco ogni 3.3 min (≈ 12 blocchi all'ora) |
| + pull-up esterno da 4.7 kΩ sul SDA/SCL del DUT | 0 blocchi (test di resistenza di 12 minuti, 1300 cicli, 0 riavvii, 0 attivazioni del WDT) |
La correlazione è chiara — la correzione dell'integrità del bus elimina del tutto il blocco. La logica della libreria non è coinvolta: RbAmpFleet::pollAll(), i moduli singoli in MISS e i contatori di ripetizione/sanità sono rimasti puliti in ogni prova fino al blocco stesso.
Mitigazione a tre livelli (applichi tutti e tre):
-
Pull-up esterna (~4.7 kΩ) su SDA e SCL verso 3.3 V in un unico punto del bus. Le pull-up interne dell'ESP32 (~45 kΩ) sono deboli per un bus multimodulo di lunghezza reale, mentre le pull-up da 4.7 kΩ integrate nei moduli, in parallelo, diventano troppo forti. Su un tale bus tagli quelle integrate su tutti i moduli tranne uno (oppure su tutti — allora si affida solo a quelle esterne). Vedere 04 · Cablaggio, sezione "Bus multimodulo — la topologia principale".
-
Non esegua una build di produzione con il debugger NRST collegato. In una sessione di debug la linea di reset può tenere SDA/SCL in uno stato indefinito al distacco/collegamento, provocando un blocco del bus alla transazione successiva. In una build sul campo (senza debugger) questo fattore scompare.
-
WDT di task a livello di app sul task di polling — difesa in profondità. Se per qualche motivo i pull-up restassero marginali, o si presentasse un'altra causa di blocco, il WDT riavvia lo sketch. Test di resistenza da banco di 12 minuti: il WDT ha intercettato e recuperato tutti i 12 blocchi nella configurazione senza pull-up esterno. Pull-up del bus corretti — correzione sul campo; WDT dell'app — postura di recupero.
#include "esp_task_wdt.h"
void setup() {
// Layer 3 setup — defense-in-depth.
esp_task_wdt_config_t wdt_cfg = {
.timeout_ms = 8000, // 8 s with a large margin
.idle_core_mask = 0,
.trigger_panic = true, // on timeout — panic+reboot
};
esp_task_wdt_reconfigure(&wdt_cfg);
esp_task_wdt_add(NULL); // this task (loop) under WDT
// ... rest of the initialization ...
}
void loop() {
fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
// ... processing ...
esp_task_wdt_reset(); // "I'm alive" — every cycle
delay(200);
}
Cosa NON fare: non cercare di aggirare il problema con un parametro Wire.setTimeout() più grande — non limita l'attesa preliminare del bus occupato, che è un percorso di codice diverso nel driver IDF. La correzione è l'integrità del bus (livello 1) + un supervisore (livello 3).
Timeout del watchdog in wifi_connect()
Causa: il ciclo senza limiti while (WiFi.status() != WL_CONNECTED) delay(500) fa scattare il task-WDT dopo ~5 s (predefinito).
Correzione: un'attesa limitata con un ripiego di riavvio:
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
delay(500);
if (millis() - t0 > 30000) { ESP.restart(); }
}
Il broker MQTT si disconnette ogni ~15 s
Causa: PubSubClient usa come default keepalive = 15 s, mentre mqtt.loop() viene chiamato solo nel percorso "lento" (una volta ogni 60 s insieme a readPeriodSnapshot()).
Correzione: imposti il keepalive a 60 s e chiami mqtt.loop() a ogni passaggio di loop():
mqtt.setKeepAlive(60);
void loop() {
if (!mqtt.connected()) mqtt.connect("rbamp-id");
mqtt.loop(); // every iteration, not once every 60 s
// ...rest of the logic, slowed down via millis()...
}
Fallimento dell'handshake TLS (integrazioni cloud)
Causa: l'heap dell'ESP32 non è sufficiente per l'handshake TLS (~30 kB necessari). Spesso si somma a WiFi + MQTT + buffer — lasciando meno di 20 kB.
Fix:
- Ridurre
setBufferSize()del client MQTT al minimo. - Usi
WiFi.mode(WIFI_STA)(nonWIFI_AP_STA). - Disabiliti il BLE:
btStop()insetup().
Se ESP.getFreeHeap() mostra meno di 25 kB prima di client.connect(), l'handshake TLS con ogni probabilità fallirà.
setSensorClass() / setCTModel() restituisce RB_ERR_PARAM
Cosa si osserva: una delle chiamate di configurazione restituisce false, lastError() == RB_ERR_PARAM.
Possibili cause:
-
setCTModel()chiamato prima disetSensorClass(). Prima la classe del sensore, poi il modello — vedere 03 · Scelta del sensore di corrente e 09 · Riferimento API § Configurazione del sensore. -
Codice modello non valido — per la classe
Sct013l'insieme valido è{1, 2, 3, 4, 5, 6, 7}(i codici 5 e 7 sono SCT-013-100 e SCT-013-060). Per le altre classi vedere la tabella degli insiemi accettati per classe in 03 · Scelta del sensore di corrente. I codici che non corrispondono alla classe restituisconoRB_ERR_PARAM(guardia lato libreria prima del bus) oppureDEV_ERR_PARAM(lato firmware, se lo YAML passa). -
Indice di canale non valido nella forma per canale
setCTModel(channel, code)— deve essere <dev.channels(). Un canale pari o superiore aRBAMP_MAX_CHANNELS(7) non viene mai esposto e restituisce comunqueRB_ERR_PARAM. -
Il modulo ha rifiutato il codice — un codice presente nel registro ma che il modulo non accetta viene rifiutato dal modulo; il canale mantiene il modello precedente.
Se la chiamata restituisce invece false con RB_ERR_MODE, il modulo è di una classe accoppiata in fabbrica (WiredCT / BuiltinCT) — è stato fornito e calibrato insieme al suo sensore e i setter non lo riscrivono. Il riaccoppiamento in assistenza è setCTModelChForce().
Comportamento atteso, non un guasto:
-
Impostare una classe o un modello che il modulo già possiede è un'operazione nulla (
true, nessuna scrittura sul bus, nessun ciclo di flash). -
Impostare un modello CT riavvia il modulo sul firmware BASIC fino alla 1.4.19 con la classe SCT-013 (circa un secondo, bloccante). Le letture non sono disponibili durante quel tempo; la libreria rilegge la correzione della portata al termine.
-
Dopo aver cambiato il modello SCT-013, le letture di corrente, potenza ed energia seguono automaticamente la nuova portata (il fattore di potenza e la tensione non sono influenzati).
dev.sctRating(ch, r)mostra lo stato per canale; se segnalaUnexpectedGainoUnknown, non viene applicata alcuna correzione (scala 1).
Note sui moduli STD (STANDARD)
La linea STD usa lo stesso cablaggio I²C del BASIC (vedere 04 · Cablaggio); dev.begin() la rileva e dev.line() indica quale linea possiede. Cose specifiche dello STD:
-
RB_ERR_NOT_IMPLEMENTEDda una chiamatastd*, dareadReactivePower()o dareadApparentPower()— il modulo collegato è BASIC (verificare condev.line()). Viceversa, le chiamate solo-BASIC (factoryReset(), General-Call, funzioni per l'etichetta,readCapability(),readCommitSeq()) la restituiscono su un modulo STD. -
Una funzione risulta "non disponibile" — l'energia a micro-risoluzione (
RbAmpStdEnergy::fine == false), la corrente di avvio per l'energia (RB_ERR_NOT_IMPLEMENTED), gli angoli di fase di tensione (angle_valid == false) e la sequenza di fase (NotAvailable) dipendono dalla versione dell'immagine del modulo: richiedono un'immagine di almeno0x0001007B. Leggerla condev.stdReadImageVersion(); su un'immagine più vecchia il valore non è disponibile, non sbagliato. -
L'angolo di tensione / la sequenza di fase restano "non disponibili" su un'immagine recente — richiedono che tutti gli ingressi di tensione siano alimentati e misurabili, e un modulo a tre tensioni per la sequenza di fase.
-
Le letture dello snapshot di periodo tornano vuote (
RB_ERR_STALE) dopo un riavvio del modulo — previsto: l'armamento dello snapshot vive nella RAM del modulo. La libreria riarma il banco e scarta quel solo periodo; riavvii la sua ancoradt. Attenda almeno 300 ms trastdLatch()estdReadLatch(). -
Nessun record storico — il modulo registra la storia solo mentre il suo orologio è impostato. L'orologio si perde a ogni riavvio del modulo: chiamare
dev.stdSetTime()dopobegin()e ogni volta chestdReadHealth()riportatime_valid == false. -
Un comando restituisce
RB_ERR_PARAM— su STD il verdetto di ogni comando viene riletto; il modulo ha rifiutato il valore ed è rimasto invariato. -
Un salvataggio restituisce
RB_ERR_NOT_READY— il modulo limita la frequenza con cui scrive il suo archivio; la libreria riprova già una volta dopo 5 s.
Gestione errori: ultima scrittura su REG_ERROR + EVENT_FLAGS.bit3 durevole (v1.3)
Comportamento della v1.3: REG_ERROR (0x02) è l'esito dell'ultima scrittura, e NON persistente. A ogni scrittura di registro il firmware imposta reg_error = ERR_OK; una scrittura successiva non correlata cancella l'errore precedente.
Segnale d'errore durevole = EVENT_FLAGS (0x2A) bit3 — persistente (W1C), attivato subito su qualsiasi scrittura o comando rifiutato.
Schema 1 — acquisizione una tantum dopo l'operazione (se l'esito di questa specifica operazione conta):
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02); // IMMEDIATELY, before the next write
Schema 2 — monitoraggio durevole degli errori (canonico):
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
uint8_t last_err = dev.readReg(0x02);
// handle
dev.writeReg(0x2A, (1 << 3)); // W1C clear bit3
// or dev.clearError();
}
⚠ REG_ERROR è l'esito dell'ultima scrittura, non persistente. La durevolezza è fornita da EVENT bit3.
⚠ bit3 è un canale asincrono, non adatto alla validazione sincrona della scrittura: su una scrittura rifiutata, bit3 viene impostato con ritardo rispetto al momento in cui la transazione I²C restituisce. Non interrogare bit3 subito dopo una scrittura per verificarne l'esito — per l'esito della propria scrittura usare il Pattern 1 (cattura una tantum di lastError() subito dopo l'operazione) oppure il codice di ritorno del setter. bit3 serve al monitoraggio prolungato di fatti asincroni (runtime, percorso dei comandi), non a validare un'operazione appena eseguita.
lastError() rispetto a readLastError() — due canali diversi, non sinonimi
Due funzioni con nomi simili, ma semantica completamente diversa:
lastError() |
readLastError(out) |
|
|---|---|---|
| Cosa restituisce | Codice RB_ERR_* memorizzato in cache dalla libreria, dalla chiamata precedente |
Una singola lettura sul filo del registro REG_ERROR (0x02) del dispositivo |
| Un'operazione I²C? | No — solo una lettura di memoria | Sì — una sola transazione di lettura |
| Semantica | Esito della validazione lato libreria (guardia client, stato dei tentativi, ecc.) | Esito dell'ultima scrittura lato dispositivo (mnemonico DEV_ERR_*) |
| Quando viene aggiornato | Dopo ogni metodo della libreria | Dopo ogni scrittura accettata dal bus sul dispositivo |
| Valore di esempio | RB_ERR_PARAM dopo una guardia lato client |
0xFE (DEV_ERR_PARAM) dopo una scrittura respinta sul dispositivo |
| Esempio di mancata corrispondenza | lastError() == RB_ERR_PARAM (il setter lo ha bloccato prima del bus) |
readLastError() → 0x00 (nulla ha raggiunto il dispositivo) |
Quando usare ciascuno:
-
lastError()— per la logica applicativa, l'analisi degli esiti lato libreria (ripetizione, ripiego, classificazione degli errori), senza overhead I²C. -
readLastError()— quando si vuole il codice esteso della causa lato dispositivo (ad esempioDEV_ERR_PARAM (0xFE)rispetto aDEV_ERR_NOT_READYrispetto aDEV_ERR_FLASH_PARAMS_BAD (0xFB)) sul Canale B (rifiuto lato DUT). Vedi il § "modello di errore v1.3 — due canali indipendenti" in 09 · Riferimento API.
La distinzione è particolarmente importante quando si esegue il debug del Canale A (guardia lato client): il setter restituisce false + lastError() == RB_ERR_PARAM, ma readLastError() == 0x00 — perché la libreria l'ha bloccato prima dell'operazione sul filo, e REG_ERROR del dispositivo non è stato toccato.
Avvertenza: DEV_ERR_CLONE (0xF9) NON viene azzerato con CMD_CLEAR_ERROR — è una sentinella anti-clone (solo con un riavvio o un ripristino di fabbrica).
Un modulo appena flashato mostra 0xFB al primo avvio (NORMALE)
Cosa osserva: un modulo appena flashato al primo avvio mostra REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + bit3 di EVENT.
Causa: la pagina dei parametri non è inizializzata → vengono caricati i valori di fabbrica. È NORMALE per un modulo vergine, non fatale.
Correzione: configuri sensor_class + ct_model + (facoltativamente) indirizzo, poi dev.saveUserConfig(). Dopo un SAVE riuscito → REG_ERROR = 0x00, bit3 azzerato.
commitAddressChange() restituisce RB_ERR_TIMEOUT
Cosa osserva: prepareAddressChange() è andato a buon fine, ma commitAddressChange() restituisce false, lastError() == RB_ERR_TIMEOUT.
Causa: la finestra dello stato armato (5 s dopo prepareAddressChange) è scaduta. WiFi/MQTT o qualsiasi I/O bloccante tra prepare e commit è la causa principale della scadenza della finestra. dev.probe() non aiuta qui (il modulo risponde; il problema è nella macchina a stati).
Cosa fare: richiami prepareAddressChange() di nuovo e subito, nella stessa iterazione di loop(), senza chiamate di rete in mezzo, chiami commitAddressChange().
✅ REG_I2C_ADDRESS (0x30) ora legge l'indirizzo ATTIVO all'avvio (v1.3). Dopo un riavvio post-commit, leggere 0x30 mostrerà il nuovo indirizzo attivo. Per la verifica più affidabile di un commit dell'indirizzo in due fasi, provi una lettura al nuovo indirizzo (dovrebbe dare ACK sul bus). Dopo una scrittura dal host (staging), il registro ripete il candidato in staging fino a CMD_COMMIT_ADDR + reset — è un comportamento previsto dal progetto.
Per approfondire il commit dell'indirizzo in due fasi, vedere 09 · Riferimento API e 04 · Cablaggio.
Le letture falliscono durante la commutazione di carichi a relè (transitori EMI)
Cosa si osserva: dev.readVoltage() / dev.readCurrent() restituiscono periodicamente NAN, lastError() == RB_ERR_NACK o RB_ERR_IO — ma solo durante la commutazione attiva di un carico a relè/induttivo sulla stessa installazione. Le letture a regime sono affidabili.
Causa: durante la commutazione dei relè (carico da 5 A) le EMI fanno fallire ~67% delle transazioni I²C (~8/12 nella misura hardware). Il bus si ripristina da solo, nessun blocco si verifica, nessun modulo viene perso — ma la lettura corrente fallisce.
Correzione — ripetizione a livello applicativo:
float robust_read_voltage(RbAmp& dev) {
for (int attempt = 0; attempt < 5; attempt++) {
float v = dev.readVoltage();
if (!isnan(v)) return v;
delay(20); // a short pause before the retry
}
return NAN;
}
⚠ Il recupero del bus lato libreria non basta da solo: quando un disturbo EMI si sovrappone alla finestra di ripetizione del driver, serve una ripetizione esplicita a livello applicativo con una pausa.
Alternativa: se il master vede gli eventi di commutazione dei relè, ritardare le letture di ~50-100 ms dopo la commutazione.
Tabella riepilogativa dei codici di errore
dev.lastError() restituisce uno di questi codici dopo ogni chiamata API pubblica. RbAmp::errorString(code) restituisce una stringa leggibile.
| Codice | Stringa | Quando | Dove guardare |
|---|---|---|---|
RB_OK (0) |
"OK" | successo | — |
RB_ERR_IO (-1) |
"Guasto del trasporto I2C" | il driver del bus ha restituito un esito diverso da OK | cablaggio, alimentazione, pull-up |
RB_ERR_NACK (-2) |
"NACK — dispositivo assente o occupato" | tentativi esauriti | Sezione "Il modulo non risponde su I²C" |
RB_ERR_TIMEOUT (-3) |
"Timeout del bus" | la finestra di waitReady / waitDataReady / commitAddressChange è scaduta |
sezione "commitAddressChange() restituisce RB_ERR_TIMEOUT" |
RB_ERR_NOT_READY (-4) |
"Dispositivo non pronto" | il modulo non è pronto / non esiste tale record storico / nulla è armato / nulla risponde al nuovo indirizzo | le note STD di cui sopra |
RB_ERR_STALE (-5) |
"Snapshot di periodo non aggiornato" | il flag di periodo pronto = 0 | Sezione "Gli snapshot del periodo sono sempre non aggiornati" |
RB_ERR_PARAM (-6) |
"Parametro non valido" | indice di canale non valido / codice modello non valido / intervallo di indirizzi non valido | sezione "setSensorClass() / setCTModel() restituisce RB_ERR_PARAM" |
RB_ERR_MODE (-7) |
"Non consentito nella modalità corrente del modulo (modalità fabbrica / percorso di assistenza richiesto)" | un'operazione riservata alla fabbrica, oppure un setter CT su un modulo di classe WiredCT / BuiltinCT |
non chiami operazioni riservate alla fabbrica sul firmware di produzione; usi setCTModelChForce() solo per il riaccoppiamento in assistenza |
RB_ERR_CHECKSUM (-8) |
"Controllo del valore fallito — checksum / firma / intervallo" | il controllo del valore del modulo non è riuscito (STD: immagine firmware rifiutata, CRC del payload, epoch fuori intervallo, anello della cronologia vuoto) | rinvii la pagina / controlli l'immagine |
RB_ERR_VERSION (-9) |
"Versione del firmware non supportata" | REG_VERSION = 0 / 0xFF |
controlli il collegamento del modulo |
RB_ERR_NOT_IMPLEMENTED (-10) |
"Non implementato su questo firmware" | la chiamata non ha un corrispondente sulla linea rilevata, oppure l'immagine del modulo non fornisce la funzione | dev.line(), dev.stdReadImageVersion() |
RB_ERR_NON_PHYSICAL (-11) |
"Valore non fisico (NaN/Inf/fuori limite)" | il filtro di plausibilità ha respinto un float | Sezione "Letture che saltano o tornano come NaN" |
Tabella riassuntiva dei contatori diagnostici
In un'esecuzione di test di resistenza sana (12 h, lo sketch SoakMonitor) tutti restano a zero:
| Contatore | A regime | Reset |
|---|---|---|
dev.retryExhaustionCount() |
0 | dev.resetCounters() |
dev.sanityRejectCount() |
0 | dev.resetCounters() |
dev.lastError() dopo una lettura |
RB_OK (0) |
automaticamente alla chiamata successiva |
| frazione stale negli snapshot di periodo | < 1 % | (cumulativo — senza azzeramento) |
Se uno qualsiasi di questi è diverso da zero in regime stazionario, torni alla sezione corrispondente sopra.
Debug a livello di bus con un analizzatore logico
Per il debug approfondito, quando la libreria non le può più dire cosa succede sul filo, catturi SDA + SCL con un analizzatore logico (Saleae, DSLogic Plus, uno compatibile Sigrok):
- Frequenza di campionamento ≥ 1 MS/s con I²C a 100 kHz; ≥ 4 MS/s a 400 kHz.
- Il decodificatore I²C di Sigrok / Saleae mostrerà ACK / NACK su ogni byte
- la fase di indirizzo.
- Confrontare le chiamate dello sketch (
dev.readVoltage()ecc.) con la sequenza di byte attesa — devono coincidere esattamente. Le letture a raffica (più byte in una transazione tramite auto-incremento dell'indirizzo) sono supportate. Le scritture NON sono ad auto-incremento — ogni byte è una transazione separata.
Se il comportamento della libreria diverge dalla cattura, apra una segnalazione allegando il file di cattura (.sal / .dsl / .csv).
Quando contattare l'assistenza
Se ha seguito la sezione pertinente sopra e il problema persiste, apra una segnalazione:
github.com/rb-amp/rbamp-arduino/issues
Nella segnalazione, includa:
-
MCU host + versione del core Arduino (ad esempio ESP32-S3 su Arduino-ESP32 3.0.4).
-
Versione della libreria (
RbAmpdal Gestore librerie / Library Manager). - Versione del firmware del modulo —
dev.firmwareVersion(). - Sketch minimo che riproduce il problema (~30 righe di codice).
-
dev.lastError()+dev.errorString(dev.lastError())+dev.retryExhaustionCount()+dev.sanityRejectCount()al momento del guasto. -
(Se disponibile) un file di cattura dell'analizzatore logico dal momento del guasto.
Collegamenti
- 05 · Avvio rapido — il primo sketch funzionante
-
09 · Riferimento API — l'API pubblica completa + avvertenze sui metodi pubblici con AVVERTENZA
-
03 · Scelta del sensore di corrente — la tabella dei modelli SCT-013, la topologia a doppio TA per un ampio intervallo dinamico, gli approcci per migliorare la sensibilità a basse correnti
Sorgente e problemi: rb-amp/rbamp-arduino · questa pagina nel repo: docs/10_troubleshooting.md (v1.6.2)