10 · Risoluzione dei problemi
Questo capitolo è organizzato per sintomi osservati, non per classificazione interna degli errori. Se è qui, qualcosa non funziona correttamente. Trovi il sintomo nell'elenco sottostante, vada alla sezione corrispondente e segua la procedura diagnostica.
La maggior parte dei problemi di banco rientra in tre categorie:
-
Livello di bus — il modulo non risponde su I²C, le letture restituiscono
ESP_FAILoESP_ERR_INVALID_RESPONSE. -
Livello dei dati — il modulo risponde, ma i numeri sono sbagliati: zeri, valori strani, segno errato.
-
Livello applicativo — il collegamento è instabile, il contatore Wh deriva, il progetto si blocca.
Scorciatoia per chi ha poco tempo: in regime, le funzioni pubbliche rbamp_* dovrebbero restituire ESP_OK. Se vede spesso ESP_FAIL o ESP_ERR_INVALID_RESPONSE nei log, passi direttamente alla sezione "Il modulo non risponde su I²C" qui sotto.
Il modulo non risponde su I²C
Cosa si osserva: rbamp_begin(dev) restituisce ESP_FAIL o ESP_ERR_INVALID_RESPONSE, oppure le letture RT propagano regolarmente ESP_FAIL nel suo codice.
Passo 1 — Scansione del bus
Prima di tutto, verifichi che il modulo sia effettivamente presente sul bus. ESP-IDF v5.x fornisce i2c_master_probe() proprio per questo scopo:
#include "driver/i2c_master.h"
#include "esp_log.h"
static const char *TAG = "i2c_scan";
void bus_scan(i2c_master_bus_handle_t bus) {
ESP_LOGI(TAG, "Scanning...");
for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
ESP_LOGI(TAG, "Found 0x%02X", addr);
}
}
}
Output atteso: Found 0x50 (o un altro indirizzo, se l'ha cambiato).
Se non si trova nulla — il problema è nel cablaggio o nell'alimentazione:
-
SDA / SCL non sono scambiati (vedi 04 · Cablaggio per i default GPIO di ciascun chip).
-
Entrambe le linee hanno un pull-up a 3.3 V (la scheda del modulo ha pull-up integrati da 4.7 kΩ — per un singolo modulo non servono quelli esterni).
-
Il pin di alimentazione del modulo ha in realtà 5 V (da 4.5 a 5.5 V).
-
Nessun altro master (sonda di debug, secondo ESP32) è collegato alle stesse linee.
-
flags.enable_internal_pullup = truenella suai2c_master_bus_config_t(se non ci sono pull-up esterni).
Se il modulo viene trovato ma a un indirizzo inatteso — qualcuno l'ha riassegnato in precedenza sul banco di prova. Aggiorni il secondo argomento di rbamp_new:
rbamp_new(bus, 0x52, &dev); /* address from the bus scan */
Passo 2 — Schema NACK di base dell'ESP32
Se la scansione del bus trova il modulo ma rbamp_read_voltage(dev, 0, &v) restituisce periodicamente ESP_FAIL — questo è un schema di riferimento documentato: il driver i2c_master di ESP-IDF v5 presenta anomalie con rbAmp sul firmware attuale (NACK frequenti a 100 kHz).
La mitigazione è già integrata nel componente (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 di default, 50 kHz tramite CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), ma sotto carico pesante il budget di retry può esaurirsi.
Cosa fare tramite idf.py menuconfig → Component config → rbAmp client:
- Confermi il valore predefinito di 50 kHz:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
- Aumenti il numero di ritentativi per carichi pesanti:
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
- Se serve — aumenti il timeout:
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
- Abiliti il livello DEBUG per il tag
rbampper la diagnostica:
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Può farlo anche a runtime — esp_log_level_set("rbamp", ESP_LOG_DEBUG).
Sui contatori di retry/sanità. Il componente espone i getter pubblici rbamp_retry_exhaustion_count(dev) e rbamp_sanity_reject_count(dev) — corrispondono in modo cross-platform a dev.retryExhaustionCount() / dev.sanityRejectCount() di Arduino. Il pattern canonico snapshot + differenza per il monitoraggio in produzione è descritto nella sezione "Monitoraggio dei contatori" sotto.
Flotta: un modulo è finito in excluded dopo rbamp_fleet_scan
Cosa vede: rbamp_fleet_scan(fleet, ...) è stata eseguita e ha restituito ESP_OK, ma rbamp_fleet_count(fleet) è inferiore al numero di moduli collegati fisicamente. rbamp_fleet_excluded_count(fleet)
0; scorra rbamp_fleet_excluded_addr(fleet, i) — ogni indirizzo escluso significa "un modulo è stato rilevato ma NON aggiunto alla flotta — si sospetta un conflitto".
Causa. Il rilevatore di conflitti lavora su due segnali indipendenti:
- coerenza dell'identità: HW_VARIANT ↔ mappa dei bit di CAPABILITY sono incoerenti — segno che due moduli fisici diversi rispondono a un indirizzo (la risposta "si fonde" in parte).
- valore-live: a un indirizzo si osservano letture «live» incompatibili — per esempio una
LABELdiversa o una variante instabile.
Se almeno uno dei segnali scatta, l'indirizzo viene escluso dalla flotta, e la libreria NON si basa sulle letture di quel modulo. Se entrambi i segnali sono silenziosi ma i moduli sono configurati in modo identico (stessa variante, stesso CT_MODEL, stessa LABEL), il rilevatore non li distinguerà — è un caso fisicamente non rilevabile (vedi sotto sulla disciplina).
⚠ Il rilevamento è best-effort. È impossibile garantire che la flotta catturi due moduli identici allo stesso indirizzo — ed è esattamente per questo che esiste la disciplina del provisioning (vedi la sezione successiva).
Cosa fare.
- Scolleghi fisicamente tutti i moduli tranne uno.
-
Colleghi gli altri uno alla volta, eseguendo di nuovo
rbamp_fleet_scandopo ciascuno. Il modulo dopo la cui connessione compare unexcludedè in conflitto con uno già collegato. -
Rimetta in servizio il modulo in conflitto su un indirizzo libero tramite
rbamp_provision(bus, new_address, ...)(richiede che sia l'unico su0x50— vedi la disciplina di messa in servizio qui sotto). -
Dopo la riassegnazione, ripeta
rbamp_fleet_scan—excluded_countdovrebbe essere0.
Flotta: rbamp_fleet_scan ha restituito ESP_ERR_INVALID_STATE + flotta vuota
Cosa si vede: rbamp_fleet_scan ha restituito ESP_ERR_INVALID_STATE, rbamp_fleet_count(fleet) è 0. Nessun modulo è stato aggiunto alla flotta, anche se sono fisicamente collegati.
Causa. Canarino di blocco di Livello 2 — la libreria ha eseguito un controllo sul bus di «c'è una risposta a un indirizzo che non deve rispondere» (il canarino). Se il canarino ha ricevuto un ACK, il bus non è in stato normale: o rumore elettrico produce ACK spuri, o tutti gli indirizzi sono «bloccati» per effetto di un blocco, oppure c'è un errore di topologia (più moduli con lo stesso codice contemporaneamente, più SDA/SCL tenuti bassi). In quello stato non si può fidarsi di nessun risultato di scansione — quindi la flotta resta vuota; meglio interrompere che eseguire consapevolmente un'inizializzazione errata.
Cosa fare.
-
Riavvii a freddo l'intero bus (tolga l'alimentazione ai moduli per alcuni secondi, riavvii l'ESP32). Questo cancella gli stati bloccati.
-
Colleghi i moduli rigorosamente uno alla volta, eseguendo
rbamp_fleet_scan(messa in servizio di un singolo modulo) dopo ciascuno e controllando il valore di ritorno: -
ESP_OK+count=1+excluded=0→ bus pulito, modulo OK. -
ESP_ERR_INVALID_STATEpersiste → verifichi i pull-up (vedi la sezione i2c-hang sopra — una resistenza esterna da 4.7 kΩ su SDA/SCL è obbligatoria). -
Quando la messa in servizio di un singolo modulo è superata per ciascun modulo individualmente, li aggiunga tutti al bus insieme ed esegua di nuovo
rbamp_fleet_scan. Se ottiene di nuovoINVALID_STATE, il problema è nell'elettrica del bus (lunghezza, interferenze, pull-up mancante), non nei singoli moduli.
Flotta: rbamp_provision ha restituito un errore
Cosa si osserva: la chiamata rbamp_provision(bus, desired_address, save_config, &out) non è terminata con ESP_OK. A seconda del codice restituito:
esp_err_t |
Cosa è successo | Che cosa fare |
|---|---|---|
ESP_ERR_NOT_FOUND |
Nessuna risposta su 0x50 (indirizzo di fabbrica) |
Verifichi che il modulo vergine sia fisicamente collegato e alimentato (VCC); controlli il cablaggio I²C (vedi "Il modulo non risponde su I²C"). |
ESP_ERR_INVALID_STATE |
È stato rilevato un conflitto su 0x50 oppure l'indirizzo desiderato è già occupato |
Sul bus c'è più di un modulo vergine oppure l'indirizzo desiderato è già occupato da un altro modulo. Scolleghi tutti i moduli «in più» (vedi sotto). |
ESP_ERR_TIMEOUT |
Il comando di commit dell'indirizzo è andato a buon fine, ma il modulo non è comparso al nuovo indirizzo entro la finestra di avvio | Spenga e riaccenda il modulo, poi riprovi. Se si ripresenta — probabilmente un'operazione di flash incompleta (alimentazione caduta durante CMD_SAVE_USER_CONFIG o CMD_COMMIT_ADDR, quindi il blocco flash può essere scritto solo in parte). Al successivo avvio il modulo restituisce REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), carica i valori di fabbrica e ricompare a 0x50. Rimetta in servizio da zero; se fallisce anche così, lo invii in assistenza. |
ESP_ERR_INVALID_ARG |
desired_addr è fuori dall'intervallo valido 0x08..0x77 |
Usi un indirizzo valido. |
⚠ Disciplina di provisioning — DEVE essercene uno alla volta.
La causa più comune di INVALID_STATE durante il provisioning è la presenza di più di un modulo sul bus con l'indirizzo di fabbrica 0x50. Distinguerli via I²C è fisicamente impossibile (open-drain wired-AND — entrambi i moduli fanno ACK in modo identico, e la rilettura dei dati torna "fusa").
Quindi la regola è rigida (un MUST normativo, non una raccomandazione): al momento della chiamata rbamp_provision deve esserci esattamente un modulo su 0x50 (nuovo, oppure riportato ai valori di fabbrica con uno strumento da banco separato). Nessun "sono sicuro che questi due moduli siano diversi — li separo adesso" — non funziona; la collisione si manifesterà più tardi, quando si crede già che la flotta sia pulita.
Percorso di recupero in caso di sospetta violazione della disciplina: 1. Riavvii l'alimentazione di tutti i moduli. 2. Scolleghi fisicamente tutti tranne il modulo "vergine" (quello che vuole riassegnare). 3. Chiami rbamp_provision sul bus con un solo modulo. 4. Aggiunga gli altri moduli uno alla volta, facendo il provisioning di ciascuno separatamente.
La corrente legge zero su un carico funzionante
Cosa si osserva: rbamp_read_current(dev, 0, &i) restituisce ESP_OK ma i = 0.000 (o un valore molto piccolo), anche se è acceso un vero utilizzatore (bollitore, lampada, ferro). rbamp_read_power_factor(dev, 0, &pf) può mostrare un valore strano (nan / 0 / ±1) — è una conseguenza; la causa è nella corrente.
Procedura diagnostica
- Verifichi che la classe del sensore e il modello CT siano configurati:
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3); /* or your model */
if (err != ESP_OK) {
ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}
Senza queste due chiamate i coefficienti di calibrazione non vengono caricati e la corrente risulta sempre zero. Questo passo si fa una volta alla prima installazione — la scelta viene salvata nella flash del modulo.
Trappola su RBAMP_SENSOR_UNSET. Se per errore chiama rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET) — la funzione restituisce ESP_OK, ma di fatto azzera la configurazione della classe. Una successiva rbamp_set_ct_model*() comincerà a restituire ESP_ERR_INVALID_STATE. Il rimedio è richiamare rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013), poi di nuovo rbamp_set_ct_model().
- Verifichi che il modello di CT corrisponda al carico. Una pinza CT grande (per esempio SCT-013-100, 100 A) su un carico piccolo (una lampada da 50 W = ~0.2 A) produce un segnale al limite del rumore di fondo, e le letture saranno zero. Scelga il modello CT più piccolo che copre la sua corrente massima attesa. La tabella completa è in 03 · Scelta del sensore di corrente.
Se ha un modulo multi-canale (UI2 / UI3 / UI5 / UI7) e vuole vedere sia carichi piccoli sia picchi, consideri un pattern a doppio CT: una pinza piccola (es. 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 sceglie il valore con una soglia. Il pattern è discusso in 03 · Selezione del sensore di corrente, sezione "Topologia a doppio CT".
- Verifichi l'orientamento della pinza. La freccia sul corpo della pinza deve puntare nella direzione del flusso di corrente verso il carico. Se la pinza è «al contrario»,
rbamp_read_current()dà il valore corretto in assoluto, marbamp_read_power()dà un valore negativo su un carico utente. Conferma:rbamp_read_power_factor()mostrerà esattamente −1.0 su un carico resistivo (invece di +1.0). Il rimedio: o rimonti fisicamente la pinza (la apra, la giri in modo che la freccia vada nel verso giusto, la richiuda), oppure inverta il segno lato master.
Se tutti e tre i passi risultano corretti ma la corrente è ancora zero
Allora il segnale all'ingresso del modulo è davvero sotto il rumore di fondo. Verificare:
-
Scorra davvero la corrente — misuri con un multimetro (pinza CC / pinza CA) sullo stesso filo.
-
La pinza è integra — al connettore della pinza deve esserci una tensione alternata proporzionale alla corrente (pochi millivolt per carichi domestici).
-
Sta misurando il filo giusto — il conduttore di linea (fase), e solo quello (mai l'intero cavo).
Le letture oscillano o restituiscono ESP_FAIL
Cosa si vede: rbamp_read_voltage(dev, ...) o rbamp_read_current(dev, ...) restituiscono periodicamente ESP_FAIL. Il valore in *out è indefinito dopo un errore.
ESP_FAIL dal componente copre due classi di problema:
- NACK dopo l'esaurimento dei ritentativi — il collegamento è instabile.
- Il filtro di plausibilità ha rifiutato il valore — un float
NaN/Inf/|x| > 10000è arrivato dal bus (un valore chiaramente non fisico).
L'API ESP-IDF non le distingue con codici esp_err_t separati (a differenza di RB_ERR_NACK / RB_ERR_NON_PHYSICAL di Arduino) — entrambi restituiscono ESP_FAIL. Può distinguerle dai contatori diagnostici (vedi la sezione «Monitoraggio dei contatori» qui sotto). Entrambi i sintomi si trattano allo stesso modo:
-
Confermi il valore predefinito di 50 kHz e porti il retry a 5 tramite Kconfig — vedi la sezione precedente.
-
Riduca la densità di carico sul bus — se il suo ciclo fa molte letture da un byte, provi
rbamp_read_all()(una transazione I²C invece di ~13). -
Verifichi
CONFIG_RBAMP_I2C_TIMEOUT_MS— se il dispositivo risponde più lentamente del solito (cavo lungo, contatto scarso), aumenti il timeout. -
Abiliti il logging DEBUG tramite
CONFIG_RBAMP_LOG_LEVEL_DEBUG=yoppureesp_log_level_set("rbamp", ESP_LOG_DEBUG)— il componente stampa i dettagli del ciclo di retry e dei rifiuti di sanità sotto il tag"rbamp".
Monitoraggio dei contatori
Il componente espone due contatori monotoni pubblici per il monitoraggio dello stato del bus in produzione:
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);
retry_exhaustion_count viene incrementato quando una transazione a un byte ha esaurito il budget di CONFIG_RBAMP_NACK_RETRY_ATTEMPTS e ha restituito ESP_FAIL. sanity_reject_count viene incrementato quando il filtro di plausibilità scarta un float (!isfinite(x) || |x| > 10000).
Lo schema canonico è snapshot + differenza una volta ogni 60 secondi, per ottenere un «tasso di eventi al minuto»:
uint32_t prev_retry = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta = now_retry - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
retry_delta, sanity_delta);
}
Le soglie di allarme dipendono dal carico di lavoro. Per uno schema di soak intenso (come lo SoakMonitor di Arduino — ~70 byte per ciclo una volta ogni 5 minuti):
retry_delta > 1/ora— rumore benigno, può essere ignorato.-
retry_deltacostantemente > 5/ora — vale la pena indagare (contatti difettosi, capacità del bus, deriva termica dei pull-up). -
sanity_delta > 0a regime — quasi sempre un segno di interferenza elettromagnetica sul bus o di una regressione del firmware.
I contatori crescono solo (non si azzerano mai) — per azzerarli deve ricreare l'handle con rbamp_del(dev) + rbamp_new(...). È una scelta di progetto, così non perde lo storico a causa di race tra "reset" e "lettura nel logger".
Su tutte le piattaforme, questi contatori hanno la stessa semantica dei dev.retryExhaustionCount() / dev.sanityRejectCount() di Arduino — gli stessi nomi (snake_case invece di camelCase), le stesse soglie che funzionano allo stesso modo.
Il fattore di potenza sembra errato
Cosa si osserva: rbamp_read_power_factor(dev, 0, &pf) restituisce ESP_OK ma pf 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
PF è definito come P / (U × I). Con corrente zero I=0 il calcolo non è definito. Il valore restituito dipende dal firmware (può essere 0 o un segnaposto vicino allo zero) — è normale finché la corrente è davvero zero. Appena compare corrente, compare un PF valido. Il filtro di plausibilità del componente non scarta questo valore (quindi il contatore sanityRejectCount equivalente in IDF non sale) — è una misura valida di una grandezza indefinita, non un artefatto di collegamento.
PF esattamente −1.0 su un carico puramente utente
La pinza è montata «al contrario» — la freccia punta in direzione opposta al flusso della corrente verso il carico. Correzione: o rimonti la pinza nel verso giusto, oppure gestisca il segno lato master (p = -p; pf = -pf; se sa che il carico non può essere un inverter fotovoltaico).
Il PF oscilla tra +0.3 e +0.7 su un carico resistivo
-
Possibile causa: la pinza CT è su un filo di 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 — uno sfasamento di 120° o 180° tra U e I dà esattamente questi valori di PF. La soluzione è installare il modulo in modo che l'ingresso U e la CT siano sulla stessa fase.
-
Alternativa: il carico non è davvero puramente resistivo. Ripeta il test con un carico noto come resistivo (un bollitore elettrico a piena potenza).
Gli snapshot di periodo sono sempre stale
Cosa si osserva: rbamp_read_period_snapshot(dev, ...) restituisce ESP_ERR_INVALID_RESPONSE, oppure *out.valid == false. Significa che il modulo non ha completato l'integrazione del periodo precedente al momento della lettura successiva.
Il componente evita il doppio conteggio dei Wh: su una lettura stantia registra un timestamp master (esp_timer_get_time()), 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 (rbamp_probe(dev) == ESP_OK) {
ESP_LOGI(TAG, "alive");
}
- Controlli il flag direttamente —
rbamp_is_period_valid()fa una lettura da un byte senza effetti collaterali:
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
/* avg_p[] can be read */
}
- Verifichi la versione del firmware —
rbamp_firmware_version(dev) >= 0x02mostra meno stalli rispetto a 0x01. Il firmware canonico attuale è0x04(v1.3);0x01=v1.0,0x02=v1.1,0x03=v1.2.
Caso speciale — risveglio da deep-sleep
Se usa uno schema di deep-sleep, la predefinita rbamp_read_period_snapshot() subito dopo rbamp_begin() sarà sempre stantia (o darà valori prossimi a zero) — begin() esegue uno snapshot approssimato che azzera l'accumulatore del firmware. Il pattern canonico usa skip_latch=true + il timestamp salvato in RTC del master — vedi 06 · Esempi, Scenario 9.
La contabilità Wh si discosta da un riferimento
Cosa si vede: rbamp_energy_wh(dev, 0) dopo diverse ore / giorni di funzionamento diverge dalla lettura del contatore del gestore o da un contatore di riferimento (Kill-A-Watt, ecc.).
Escludere prima il banale
-
Calibrazione del sensore di corrente: verifichi che
rbamp_set_sensor_class()erbamp_set_ct_model()siano state chiamate con il modello CT corretto (vedi 03 · Selezione del sensore di corrente). Senza questo la corrente RMS viene calcolata con un valore minimo predefinito e il valore di potenza risulta sistematicamente distorto. -
Snapshot obsoleti scartati: se
rbamp_energy_wh()resta costantemente sotto il riferimento, potrebbero essere intervalli mancati — lo snapshot è arrivato obsoleto, il componente ha evitato il doppio conteggio, ma la misura dell'intervallo è andata persa. Verifichi la cadenza (vedi sopra). -
Deriva dell'orologio del master:
esp_timer_get_time()è affidabile di per sé. Ma se il master entra in deep sleep senza salvare l'RTC, si perde l'intervallo tra lo snapshot precedente e il successivo. Per gli scenari di deep sleep usi lo schema RTC_DATA_ATTR dello Scenario 9.
Precisione dell'accumulatore
L'accumulatore Wh nell'handle è memorizzato come double a 64 bit.
Se ha compilato il componente con CONFIG_RBAMP_DISABLE_ENERGY=y, lo storage e l'API dell'energia vengono rimossi completamente dal binario. In quel caso deve mantenere un proprio contatore Wh nel codice utente.
snap.latch_ms — diagnostico, non per l'energia
latch_ms è un timer diagnostico del modulo; non lo usi per l'energia — usi l'orologio del master.
Il progetto ESP32 si blocca dopo alcuni minuti
Cosa si vede: un progetto ESP32 parte normalmente, poi va in blocco / loop di riavvio / timeout del WDT dopo 1–30 minuti.
Blocchi di IDF i2c_master su un bus marginale — mitigazione a tre livelli
Cosa si vede in particolare: un progetto ESP32 (classico v1.0, IDF v5.4.1, nuovo driver i2c_master) interroga rbAmp correttamente per diversi minuti, poi si "blocca" a metà di una chiamata rbamp_*_read_* o rbamp_fleet_poll_all. Il task-WDT (se abilitato) rileva il blocco; altrimenti il progetto semplicemente smette di rispondere. Il backtrace decodificato termina su i2c_ll_is_bus_busy (file i2c_master.c:526, attesa di bus occupato prima dell'invio).
Cosa succede: su un bus marginale (pull-up deboli, tracce lunghe, EMI, interferenze dai fronti ZC) SDA/SCL possono "bloccarsi" per un istante in uno stato indeterminato. Prima di ogni transazione, IDF i2c_master gira nel loop di attesa i2c_ll_is_bus_busy in attesa che il bus si liberi — questa attesa NON è limitata dal parametro xfer_timeout_ms. Se il bus occupato dura più a lungo di quanto l'attesa possa girare senza cedere il controllo ad altri task, il task IDLE di FreeRTOS non riceve la CPU e l'intera app si blocca.
Non si tratta di un «artefatto solo del debugger». Validato sul banco: con lo stesso hardware di prova 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Ω su SDA/SCL del DUT | 0 blocchi (cicli di 5 e 25 minuti, 0 riavvii) |
La correlazione è chiara — una correzione dell'integrità del bus elimina del tutto il blocco. La logica della libreria non è responsabile: la meccanica per modulo (fleet_poll_all, MISS/desync, controlli di perdita) è rimasta pulita in ogni esecuzione fino al blocco.
Mitigazione a tre livelli (applichi tutti e tre):
-
Pull-up esterno (~4.7 kΩ) su SDA e SCL verso 3.3 V in un unico punto del bus. I pull-up interni dell'ESP32 (~45 kΩ) sono deboli per un bus multi-modulo di lunghezza reale, mentre i pull-up da 4.7 kΩ integrati nei moduli, in parallelo, diventano troppo forti. Su un bus del genere stacchi quelli integrati su tutti i moduli tranne uno (o su tutti — allora si affida solo a quelli esterni). Vedi 04 · Cablaggio, sezione "Bus multi-modulo — topologia primaria".
-
Non esegua una build di produzione con il NRST del debugger collegato. In una sessione di debug la linea di reset può tenere SDA/SCL in uno stato indeterminato al distacco/collegamento, provocando un blocco del bus alla transazione successiva. In una build di campo (senza debugger) questo fattore scompare.
-
WDT di task a livello applicativo sul task di poll — difesa in profondità. Se per qualche motivo i pull-up restano marginali, o sorge un'altra causa di blocco, il WDT riavvia il progetto, e se è presente un supervisore (es. un bootloader di rotazione applicativo o un supervisore tipo systemd) il progetto torna su. In un test di resistenza su banco di oltre un'ora il WDT ha rilevato e recuperato tutti i 12 blocchi nella configurazione senza pull-up esterno.
#include "esp_task_wdt.h"
void app_main(void) {
/* Layer 3 setup — defense-in-depth. */
esp_task_wdt_config_t wdt_cfg = {
.timeout_ms = 10000, /* 10 s with plenty of margin */
.idle_core_mask = 0,
.trigger_panic = true, /* on timeout — panic+reboot */
};
ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
ESP_ERROR_CHECK(esp_task_wdt_add(NULL)); /* this task is under the WDT */
/* ... bus / fleet init ... */
while (1) {
rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
/* ... processing ... */
esp_task_wdt_reset(); /* "I'm alive" — every cycle */
vTaskDelay(pdMS_TO_TICKS(200));
}
}
Cosa NON fare: non cerchi di aggirare il problema con un xfer_timeout_ms più grande — non limita l'attesa di bus occupato prima dell'invio, che è un percorso di codice diverso nel driver. La soluzione è l'integrità del bus (livello 1) + supervisore (livello 3).
Timeout del watchdog durante la connessione al WiFi
Causa: un ciclo di attesa illimitato della connessione WiFi dentro un gestore di eventi fa scattare il task-WDT dopo ~5 s (predefinito).
Correzione: usi uno schema guidato dagli eventi invece di un'attesa attiva. Il driver WiFi di ESP-IDF emette gli eventi WIFI_EVENT_STA_DISCONNECTED e IP_EVENT_STA_GOT_IP — vi reagisca tramite esp_event_handler_register() invece di interrogare in un ciclo.
Schema minimo:
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT BIT1
static void wifi_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data) {
if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
esp_wifi_connect(); /* auto-reconnect */
} else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
}
}
/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
esp_restart();
}
il broker MQTT si disconnette ogni ~15 s
Causa: nella maggior parte dei casi non è il keepalive. Il valore predefinito di session.keepalive in esp_mqtt_client_config_t è 120 s, e disable_keepalive vale false per impostazione predefinita (cioè il keepalive è attivo). Riscrivere esplicitamente questi campi con gli stessi valori non cambia nulla — se la connessione cade ogni 15 s, la causa reale è nella rete (un NAT/firewall intermedio che scarta il TCP inattivo) oppure in una caduta del WiFi.
Soluzione: registri MQTT_EVENT_DISCONNECTED e si riconnetta esplicitamente. esp_mqtt_client_start() lancia un proprio task internamente; non serve far girare un mqtt.loop() separato — basta riconnettersi sull'evento.
static void mqtt_event_handler(void *arg, esp_event_base_t base,
int32_t event_id, void *event_data) {
if (event_id == MQTT_EVENT_DISCONNECTED) {
ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
/* esp-mqtt reconnects automatically with backoff;
* this handler is the place to clean up application state
* (retained flags, discovery payload caches). */
}
}
const esp_mqtt_client_config_t cfg = {
.broker.address.uri = "mqtt://192.168.1.10:1883",
/* leave keepalive at the default — 120 s;
* for aggressive NATs, lower it to 30 s: */
/* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
mqtt_event_handler, NULL);
esp_mqtt_client_start(client);
Se le disconnessioni coincidono nel tempo con le cadute di WiFi, la causa reale è nel WiFi (RSSI, un canale congestionato), non in MQTT. Controlli il payload di MQTT_EVENT_ERROR e i log WiFi prima di toccare il keepalive.
Fallimento dell'handshake TLS (integrazioni cloud)
Causa: l'heap dell'ESP32 è insufficiente per l'handshake TLS (~30 kB richiesti). Spesso combinato con WiFi + MQTT + buffer, lasciando < 20 kB.
Fix:
- Usi
WiFi.mode(WIFI_MODE_STA)(nonSTA+AP). -
Disattivi il BLE se non lo usa:
CONFIG_BT_ENABLED=nin sdkconfig. -
Riduca le dimensioni dei buffer MQTT in
esp_mqtt_client_config_t. - Passaggio all'ESP32-S2 (senza Bluetooth — ~30 kB di heap in più).
Se esp_get_free_heap_size() mostra meno di 25 kB prima di esp_mqtt_client_start() o esp_http_client_perform(), l'handshake TLS molto probabilmente fallirà.
Gestione errori: ultima scrittura su REG_ERROR + EVENT_FLAGS.bit3 durevole (v1.3)
Canone v1.3 (confermato su HW): REG_ERROR (0x02) è l'esito dell'ultima scrittura, NON persistente. A ogni scrittura di registro il firmware imposta reg_error = ERR_OK; una scrittura successiva non correlata azzera l'errore precedente.
Segnale d'errore durevole = EVENT_FLAGS (0x2A) bit3 — persistente (W1C), attivato subito su qualsiasi scrittura o comando rifiutato.
Schema 1 — cattura una tantum dopo l'operazione (se conta l'esito di QUESTA specifica operazione):
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err); /* IMMEDIATELY, before the next write */
Pattern 2 — monitoraggio durevole degli errori (canonico per le esecuzioni lunghe):
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
uint8_t last_err;
rbamp_read_last_error(dev, &last_err); /* what was the last rejected */
/* handle the error */
rbamp_clear_error(dev); /* clears REG_ERROR ... */
rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR); /* ... then the sticky bit */
}
⚠ INVERSIONE della documentazione "sticky" precedente (canone v1.3 A3). REG_ERROR è l'esito dell'ultima scrittura, non sticky. La durabilità è garantita 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 ritorna. Non interroghi bit3 subito dopo una scrittura per verificarne l'esito — per l'esito della propria scrittura usi il Pattern 1 (una cattura immediata di REG_ERROR dopo l'operazione) o 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.
Avvertenza: DEV_ERR_CLONE (0xF9) NON viene cancellato tramite CMD_CLEAR_ERROR — è una sentinella anti-clonazione (solo riavvio o reset di fabbrica).
Modulo appena flashato mostra 0xFB al primo avvio (NORMALE)
Cosa si osserva: un modulo appena flashato mostra al primo avvio REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + bit3 di EVENT.
Causa: pagina dei parametri non inizializzata → caricati i valori di fabbrica. È NORMALE per un modulo vergine, non fatale.
Soluzione: configuri sensor_class + ct_model + (facoltativamente) l'indirizzo, poi CMD_SAVE_USER_CONFIG. Dopo un SAVE riuscito → REG_ERROR = 0x00, bit3 a zero.
rbamp_set_sensor_class / rbamp_set_ct_model* restituisce ESP_ERR_INVALID_STATE
Cosa si vede: una delle chiamate di configurazione restituisce ESP_ERR_INVALID_STATE.
ESP_ERR_INVALID_STATE da questo gruppo di funzioni è un codice ombrello per tre cause distinte. Le distingue dalla riga ESP_LOGW che il componente stampa sotto il tag "rbamp" subito prima di restituire:
| Riga di log (ESP_LOGW, TAG="rbamp") | Causa | Soluzione |
|---|---|---|
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) |
Precondizione: la classe di sensore va impostata prima di scrivere il modello CT | Chiami rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) prima di rbamp_set_ct_model*(). |
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) |
Il tracker di lotto interno del componente non è sincronizzato con lo stato di staging del firmware | Sul firmware v1.3 l'ordine di associazione dei canali è arbitrario (Fix-A pure staging — vedi 03 · Selezione del sensore di corrente). Richiami rbamp_set_sensor_class() per resettare il tracker del lotto, poi associ i canali in qualsiasi ordine. La formulazione "ordine decrescente richiesto" dei vecchi messaggi di log si riferisce al comportamento precedente alla v1.3 e non è più in vigore. |
C'è anche il caso di un handle inizializzato ma per cui rbamp_begin() non è stato chiamato — restituisce ESP_ERR_INVALID_STATE senza una riga ESP_LOGW (l'handle è ancora "freddo"). Soluzione: chiami rbamp_begin(dev) dopo rbamp_new() e prima di qualsiasi rbamp_set_*.
Il pattern di disambiguazione tramite log è un idioma standard di ESP-IDF: lo si confronti con esp_driver_i2c, che restituisce ESP_ERR_TIMEOUT sia per un timeout di ACK sia per un timeout di bus occupato, distinguendoli tramite il log. Se vede ESP_ERR_INVALID_STATE senza una causa chiara, alzi il livello di log con esp_log_level_set("rbamp", ESP_LOG_WARN) (o _DEBUG) e ripeta la chiamata: il componente le dirà quale dei tre casi si verifica. rbamp_err_to_str(ESP_ERR_INVALID_STATE) restituisce una descrizione generica: "Wrong call sequence (check log: factory mode / sensor class UNSET / bind batch out of sync)".
rbamp_set_sensor_class / rbamp_set_ct_model* restituisce ESP_ERR_INVALID_ARG
Cosa si vede: la chiamata restituisce ESP_ERR_INVALID_ARG.
Possibili cause:
-
Codice modello non valido per la classe — i codici validi dipendono dalla classe di sensore:
SCT013accetta{1, 2, 3, 4, 5, 6, 7}(vedi la tabella in 03 · Selezione del sensore di corrente);WIRED_CTaccetta1–10e12. Un codice sconosciuto per la classe restituisceESP_ERR_INVALID_ARG. -
Indice di canale non valido nella forma per canale
rbamp_set_ct_model_ch(dev, channel, code)— deve essere <rbamp_channels(dev). -
Un valore non valido di
rbamp_sensor_class_t— una classe superiore a3restituisceESP_ERR_INVALID_ARG. I moduli forniti tarati insieme al proprio sensore (RBAMP_SENSOR_WIRED_CT,RBAMP_SENSOR_BUILTIN_CT) rifiutano una modifica di classe o di modello (ESP_ERR_INVALID_STATE); per la pinza amperometrica SCT-013 da agganciare usiRBAMP_SENSOR_SCT013. -
dev == NULLoppureout == NULL— verifichi cherbamp_new()sia riuscita (ha restituitoESP_OK).
rbamp_commit_address_change restituisce ESP_ERR_TIMEOUT
Se prepare è andato a buon fine ma commit restituisce ESP_ERR_TIMEOUT, la finestra di "armamento" è scaduta (5 secondi dopo prepare). rbamp_probe() non aiuta qui (il modulo risponde; il problema è nella macchina a stati). La soluzione: richiami rbamp_prepare_address_change() e subito dopo — nella stessa iterazione di app_main, senza chiamate di rete tra le due — rbamp_commit_address_change(). WiFi / MQTT / qualsiasi I/O bloccante tra prepare e commit è la causa principale della scadenza della finestra.
Per i metodi pubblici con avvertenza, veda 09 · Riferimento API, sezione «Configurazione del sensore».
Le letture falliscono quando si commutano carichi a relè (transitori EMI)
Cosa si vede: rbamp_read_* restituisce periodicamente ESP_FAIL / ESP_ERR_INVALID_RESPONSE, ma solo mentre un carico a relè o induttivo sta commutando nello stesso impianto. Le letture a regime sono affidabili.
Causa (C.12 confermata su HW): durante la commutazione dei relè (un carico da 5A) l'EMI fa fallire ~67% delle transazioni I²C (~8/12 nella misura hardware). Il bus si autoripristina, non si verifica alcun blocco, nessun modulo viene perso — ma la lettura di corrente fallisce.
Soluzione — ritentativo a livello applicativo:
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
for (int attempt = 0; attempt < 5; attempt++) {
esp_err_t err = rbamp_read_voltage(dev, 0, v);
if (err == ESP_OK) return ESP_OK;
vTaskDelay(pdMS_TO_TICKS(20)); // short pause before retry
}
return ESP_FAIL;
}
⚠ Un bus_reset lato master da solo non basta: quando un glitch EMI si sovrappone alla finestra di retry del driver, serve un retry esplicito a livello applicativo con una pausa.
Alternativa: se il master vede eventi di commutazione dei relè — ritardi le letture di ~50-100 ms dopo la commutazione.
Riavvio del task-WDT sotto EMI / carico pesante
Cosa si osserva: l'ESP32 si riavvia inaspettatamente con motivo TASK_WDT. Accade di solito durante eventi EMI (commutazione di relè, transitori induttivi).
Causa: con letture rallentate dall'EMI (cicli di NACK-retry + bus_reset) il driver i2c_master di ESP-IDF può allungare una transazione fino a ~100 ms e oltre. Se un task esegue un ciclo di lettura in blocco serrato senza cedere la CPU — timeout del task-WDT.
Soluzione — cedere la CPU nel ciclo di lettura in blocco:
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}
// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
vTaskDelay(1); // yield + WDT feed
}
Alternativa: esp_task_wdt_reset() esplicito se il task è monitorato dal WDT.
Tabella riassuntiva dei codici di errore
Le funzioni rbamp_* restituiscono valori standard esp_err_t. rbamp_err_to_str(err) restituisce una stringa leggibile.
| Codice | Quando | Dove guardare |
|---|---|---|
ESP_OK (0) |
successo | — |
ESP_FAIL (-1) |
NACK dopo il ritentativo; oppure il filtro di plausibilità ha rifiutato il valore | Sezione "Il modulo non risponde su I²C" |
ESP_ERR_INVALID_ARG (0x102) |
dev == NULL, channel/phase fuori intervallo, un cls non riconosciuto, un valore che il modulo rifiuta |
verifichi gli argomenti della chiamata |
ESP_ERR_TIMEOUT (0x107) |
rbamp_wait_ready scaduto (modulo che non risponde) OPPURE è scaduta la finestra di 5 s tra prepare_address_change e commit_address_change |
per wait_ready — tramite rbamp_probe(); per il commit — riarmi: prepare + commit di seguito, senza I/O bloccante tra di loro |
ESP_ERR_INVALID_STATE (0x103) |
precondizione: set_ct_model* prima di set_sensor_class |
la sezione set_* qui sopra |
ESP_ERR_NOT_SUPPORTED (0x106) |
la funzione non è disponibile sullo SKU attuale (per esempio l'API di tensione su una variante I*) | verifichi rbamp_line(dev) e rbamp_variant(dev) |
ESP_ERR_INVALID_RESPONSE (0x108) |
snapshot di periodo obsoleto; oppure REG_VERSION = 0/0xFF su rbamp_begin |
Sezione "Gli snapshot di periodo sono sempre stantii" / "Il modulo non risponde" |
ESP_ERR_NO_MEM (0x101) |
impossibile allocare la memoria per l'handle | verifichi il budget dell'heap (esp_get_free_heap_size()) |
Debug a livello di bus con un analizzatore logico
Per il debug approfondito, quando il componente non è più in grado di dirle cosa accade sul filo, catturi SDA + SCL con un analizzatore logico (Saleae, DSLogic Plus, compatibile Sigrok):
- Frequenza di campionamento ≥ 1 MS/s con I²C a 100 kHz; ≥ 4 MS/s a 400 kHz.
-
Il decoder I²C in Sigrok / Saleae mostrerà ACK / NACK per ogni byte + la fase di indirizzo.
-
Confronti le chiamate del suo codice (
rbamp_read_voltage(), 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.
Se il comportamento del componente diverge dalla cattura, apra una segnalazione allegando il file di cattura (.sal / .dsl / .csv).
Quando contattare l'assistenza
Se ha seguito la sezione pertinente qui sopra e il problema persiste, apra una segnalazione:
github.com/rb-amp/rbamp-esp-idf/issues
Nella segnalazione, includa:
-
SoC di destinazione (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + versione di ESP-IDF (output di
idf.py --version). -
Versione del componente rbamp (per esempio 1.1.0).
-
Versione del firmware del modulo —
rbamp_firmware_version(dev)nei log. -
Un progetto IDF minimo che riproduca il problema (~30 LOC in
main/main.c). -
I valori
esp_err_t+rbamp_err_to_str(err)al momento del guasto, dai log con il tagrbamp. -
Kconfig rilevante:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ,CONFIG_RBAMP_NACK_RETRY_ATTEMPTS,CONFIG_RBAMP_LOG_LEVEL_*. -
(Se disponibile) un file di cattura dell'analizzatore logico dal momento del guasto.
Collegamenti
- 05 · Guida rapida — il suo primo progetto funzionante
-
09 · Riferimento API — API completa + avvertenze sui metodi pubblici con WARNING + sezione Kconfig
-
03 · Selezione del sensore di corrente — tabella dei modelli SCT-013, topologia a doppio CT per un ampio intervallo dinamico, approcci per migliorare la sensibilità a basse correnti
Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/10_troubleshooting.md (v1.7.3)