rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub

10 · Risoluzione dei problemi

Albero decisionale per la risoluzione dei problemi: sintomo → verifica rapida → azione

Una guida al debug orientata ai sintomi per il componente rbamp in ESPHome. Ogni voce segue la stessa forma: che cosa vedi nel log, che cosa significa, come diagnosticarlo e una correzione concreta.

Contents:

  1. I2C / hardware
  2. Qualità dei dati
  3. Energia e persistenza
  4. Integrazione con Home Assistant
  5. Build e toolchain
  6. Identità / Capacità / Errore (v1.3)

1. I2C / hardware

Probe failed at 0x50 — nessuna risposta

Che cosa vedi nel log:

Text
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

Il componente chiama quindi mark_failed() e interrompe ulteriori chiamate a update(). Tutti i sensori collegati restano "Unknown" [Sconosciuto] in Home Assistant.

Che cosa significa:

L'ESP32 ha inviato la fase di indirizzo a 0x50 (o a un altro indirizzo da address:) e non ha ricevuto ACK. Il modulo è assente, non alimentato, oppure su un altro indirizzo.

Come diagnosticarlo:

  1. Verificare che scan: true sia impostato nel blocco YAML i2c:. Riavviare l'ESP32 e osservare:

    Text
    [I][i2c.arduino:069]: Found i2c device at address 0x50
    

    Se la scansione ha trovato il dispositivo, la chiave address: nel blocco rbamp: è sbagliata — aggiornarla.

  2. Misura l'alimentazione sul pin VCC del modulo con un multimetro: deve essere 4.5..5.5 V (5 V nominali, vedi 04_hardware.md). Zero o sotto 4.5 V significa alimentazione assente o marginale.

  3. Verifica la continuità di SDA e SCL dal GPIO dell'ESP32 al connettore del modulo. Un filo mancante o invertito è la causa più comune nelle installazioni nuove.

  4. Controlla le resistenze di pull-up su SDA e SCL (4.7 kΩ verso 3.3 V). Senza pull-up il bus resta basso e ogni fase di indirizzo sembra un NACK.

  5. Se di recente è stato eseguito un cambio di indirizzo (chiave new_address:), il modulo potrebbe ora trovarsi sul nuovo indirizzo. Aggiungere scan: true, individuare il dispositivo, aggiornare di conseguenza address: e rimuovere new_address:.

Correzione: correggere il cablaggio / l'alimentazione e aggiornare address: se il modulo si è spostato. Se il modulo non risponde dopo un cambio di indirizzo, vedere sotto "Indirizzo cambiato ma modulo non risponde".


Blocco RT non pronto — pubblicazione saltata

Cosa si vede:

Text
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish

Cosa significa: il registro di stato ha segnalato che il modulo non è pronto. Accade quando il modulo non ha ancora committato il primo blocco di valori istantanei dopo l'avvio, è nel mezzo di una scrittura flash, o è in un soft reset.

Come diagnosticarlo:

  1. Se la voce compare una volta all'avvio (nei primi 30 s dopo l'accensione) e poi scompare, è normale. Il modulo ha bisogno di un ciclo di commit (~100 ms) per impostare il bit READY dopo l'accensione. Lo snapshot di avvio in setup() produce anch'esso un ciclo saltato.

  2. Se i messaggi continuano a fluire dopo il riscaldamento, il modulo potrebbe essere bloccato. Controlla voci ct_model: / ct_models: ripetute (per esempio una chiave lasciata nel YAML che viene scritta a ogni avvio, producendo una finestra di scrittura in flash permanente).

  3. Se il messaggio compare occasionalmente (una volta ogni alcuni cicli), è una variabilità normale legata ai NACK. Il ciclo di ritentativo cattura la maggior parte dei transitori; a volte la lettura dello stato fallisce ancora, e ciò fa comparire questa voce DEBUG.

Fix:

  • I salti di riscaldamento all'avvio sono previsti; attendere due cicli completi di update_interval.
  • Se ct_model: / ct_models: è impostato nel YAML, lascialo: a ogni avvio la scrittura ripetuta è idempotente (il modulo non scrive se il valore è già in flash). Se le attese di riscaldamento ti infastidiscono, commenta la chiave dopo una prima esecuzione riuscita.
  • Se il modulo resta non pronto per 60+ s, spegnere e riaccendere il modulo (non l'ESP32) per un avvio a freddo pulito.

"rbamp took a long time for an operation (XXX ms)"

Cosa si vede:

Text
[W][component:522]: rbamp took a long time for an operation (406 ms), max is 30 ms

Che cosa significa: questo avviso scatta quando l'update() di un componente supera il budget predefinito di 30 ms dello scheduler cooperativo di ESPHome. Per il componente rbamp è previsto e innocuo.

Sul firmware v1.3, la lettura con auto-incremento è supportata per il blocco dei valori istantanei (l'intervallo contiguo che copre U / I / P / PF / Q per tutti i canali dichiarati). Il componente emette un'unica lettura a raffica per quel blocco — una fase di indirizzo seguita da ~36 byte di dati, che costa ≈ 8–10 ms di tempo di filo a 50 kHz. La scrittura con auto-incremento non è supportata, quindi le scritture per registro (staging del modello TA, classe del sensore, commit dell'indirizzo) restano byte per byte. Se la lettura a raffica fallisce (NACK a metà, bit di capacità non impostato sul firmware legacy), il componente ricade sulle letture per registro (4 transazioni per float, fino a 36 transazioni ≈ 90 ms a 50 kHz). Con la terna di ripetizione per byte (fino a 3 × 5 ms di pausa su un ciclo ricco di NACK) il percorso di ripiego nel caso peggiore dura normalmente 300–450 ms — ed è ciò che produce questo avviso quando compare.

L'assestamento dello snapshot (set_timeout("rbamp_period", 50, ...)) è non bloccante — update() cede il controllo allo scheduler mentre passano i 50 ms. L'avviso riflette il tempo reale dell'intera lettura bloccante dei valori istantanei, non uno stallo di WiFi o API.

Non è richiesta alcuna azione dell'utente. L'avviso è estetico; i sensori di HA si aggiornano correttamente. Sui moduli v1.3 sani il percorso di lettura a raffica resta normalmente sotto 30 ms e l'avviso non scatta affatto.

Se l'avviso scatta a ogni ciclo: il bus costringe il ripiego su letture per singolo registro (firmware legacy senza la capacità di lettura a raffica, oppure pull-up marginali che producono NACK a metà raffica). Controlla la versione del firmware (Firmware version: 0x04 nel log di avvio = v1.3) e la topologia dei pull-up (una sola coppia integrata da 4.7 kΩ verso 3.3 V puliti).


Impossibile leggere lo snapshot del periodo

Cosa si vede:

Text
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]

Cosa significa: dopo il comando di snapshot e l'attesa di 50 ms, il componente non è riuscito a leggere il registro della potenza media di periodo per il canale N dopo tre tentativi. L'accumulatore di energia per quel canale non viene aggiornato in questo ciclo.

Le cause più comuni:

  1. Blackout durante la scrittura in flash. Il modulo sta scrivendo un modello TA (attivato da ct_model: o ct_models: all'avvio) oppure sta salvando un nuovo indirizzo. La finestra è di ~700 ms; se l'attesa di assestamento di 50 ms dello snapshot cade dentro, la lettura va in timeout.
  2. Snapshot mancato sotto polling intenso. Sotto intenso carico I²C in sequenza il lato modulo può perdere uno snapshot. Lo snapshot resta vuoto, ma il flag di validità sarà 0 — il componente salta l'integrazione con il messaggio "Period snapshot not yet valid; keeping previous integration window" [Snapshot del periodo non ancora valido; si mantiene la finestra di integrazione precedente]. L'avviso scatta solo se il flag di validità è impostato ma la lettura del registro è comunque fallita.
  3. Esaurimento dei NACK transitori. Tutti e tre i tentativi su almeno uno dei quattro byte del float sono falliti. Raro a 50 kHz (< 1% dei cicli); più frequente a 100 kHz.

Che cosa succede all'energia: in caso di avviso, last_latch_ms_ non viene aggiornato. Al ciclo riuscito successivo, dt_ms copre sia la finestra mancata sia quella nuova — l'energia si recupera, supponendo un carico circa stabile nell'intervallo. È un'imprecisione lieve e accettabile.

Fix:

  • Rimuovere le chiavi di cambio indirizzo (new_address:) dal YAML dopo il primo avvio riuscito.
  • Se l'avviso scatta più di una volta all'ora, verificare la velocità del bus (si raccomanda 50kHz) e i resistori di pull-up (4.7 kΩ).
  • Se l'avviso scatta a ogni ciclo, verifica un conflitto con un altro dispositivo sul bus.

Indirizzo cambiato ma modulo non risponde

Cosa si vede:

Text
[E][rbamp:xxx]: Address change applied but slave not responding at 0x51 —
    check wiring and try power-cycling the rbAmp.
[E][component:xxx]: Component rbamp was marked as failed.

Cosa significa: il flusso di cambio indirizzo ha eseguito tutti i passaggi (scrittura del nuovo indirizzo, salvataggio in flash, soft reset, cambio dell'indirizzo I²C interno del componente), ma il modulo non ha risposto sul nuovo indirizzo al primo controllo.

Possibili cause:

  1. L'indirizzo è stato scritto e salvato, ma il modulo è entrato in uno stato errato (corruzione dei parametri in flash, un glitch di alimentazione durante la finestra di scrittura di 700 ms).
  2. Sul firmware legacy (v1.0-v1.2): il modulo non era in modalità di provisioning di fabbrica al momento del tentativo. Sul firmware v1.3+ questa causa non si applica (il commit in due fasi è adatto alla produzione). Se la lettura dello stato di modalità stessa è fallita (NACK), il componente esegue la scrittura in via speculativa, con un avviso nel log.
  3. Un problema di cablaggio già presente prima della modifica dell'indirizzo (la sonda sul vecchio indirizzo ha riuscito solo per coincidenza, in uno dei tre tentativi).

Procedura di ripristino:

  1. Il modulo è su un indirizzo sconosciuto. Usa un YAML di test con i2c: scan: true e un power cycle — scopri a quale indirizzo risponde il modulo.
  2. Se il modulo viene trovato sul nuovo indirizzo (ad esempio 0x51), aggiorna il YAML a address: 0x51, rimuovi new_address: e riflasha. Il prossimo avvio sarà pulito.
  3. Se il modulo non risponde su nessun indirizzo, la scrittura in flash potrebbe aver corrotto i parametri. Il ripristino richiede un intervento fisico: consulta la documentazione del modulo o il tuo fornitore.

Contesto: il flusso di cambio indirizzo sul firmware v1.3 è un commit in due fasi — il master scrive il nuovo indirizzo in un registro di staging, poi emette CMD_COMMIT_ADDR per renderlo persistente. La finestra di scrittura di 700 ms è il cancellamento + programmazione della pagina di configurazione utente in flash. Vedi 09 · Riferimento API.


i2c_master bloccato — loop di avvio dell'ESP32 o il blocco RT non pubblica mai

Cosa si vede:

Text
[I][i2c.idf:xxx]: Performing I2C bus reset...
[E][i2c.idf:xxx]: i2c_master_send_buf failed: ESP_ERR_TIMEOUT
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

Nel caso peggiore, un timeout del task watchdog riavvia l'ESP32 dopo diversi minuti di soak (sotto carico, non in fase di messa in servizio). Può sembrare «il modulo ha funzionato per un'ora e poi si è fermato».

Che cosa significa: il driver ESP-IDF v5 i2c_master ha un problema noto: su un bus marginale (tempo di salita lento, pull-up debole, burst EMI) la funzione interna i2c_ll_is_bus_busy gira all'infinito in attesa di una condizione STOP che non arriva mai. In ESPHome 2025.x questo ciclo può consumare il budget del WDT dell'app e provocare un riavvio. È un problema canonico di ESP-IDF, non specifico di rbAmp.

Mitigazione a tre livelli (tutti attivi nel componente per impostazione predefinita, più raccomandazioni hardware):

  1. Software: la disciplina NACK integrata — 50 kHz di default + 3× ripetizione per byte con pausa di 5 ms + il filtro di sanità IP-009 std::isfinite(). Già nel componente dalla v0.2+. La correzione di robustezza dell'arresto è arrivata con il firmware v1.1/v1.3, ma 50 kHz resta consigliato sui master ESP-IDF perché l'interazione di temporizzazione del driver persiste.

  2. Hardware: un pull-up esterno da 4.7 kΩ su SDA + SCL (una sola coppia di pull-up esterni, con i ponticelli nel modulo tagliati — vedere §Bus multi-modulo). I pull-up interni dell'ESP32 (~50 kΩ) sono deboli — su un bus lungo o con un'alimentazione marginale non bastano. Per un deployment in produzione sono obbligatori pull-up da 4.7 kΩ verso 3.3 V puliti.

  3. Hardware: non tenere premuto il reset del debugger / OTA durante le transazioni I²C. Un RESET asserito a metà di una transazione lascia il bus bloccato (lo slave continua a pilotare SDA), che è esattamente ciò che provoca il ciclo infinito di bus occupato.

Frequenza di blocco osservata in un test di resistenza di 24 ore:

Livello Tasso di blocco Nota
Solo software (senza pull-up esterno) ~1 volta ogni 10 minuti il watchdog del bridge scatta e si ripristina con un reset, ma i Wh perdono una finestra
Software + pull-up esterno da 4.7kΩ ~1 volta ogni 24 ore Caso limite di burst EMI; ripristino automatico
Software + pull-up esterno + reset pulito 0 si blocca dopo un soak di 24 h target di produzione

Gravità = tempo di misura (soak di durata completa), non messa in servizio. In messa in servizio la disciplina NACK intercetta il 99%+ tramite la terna di ripetizioni — i blocchi reali iniziano solo dopo ore di soak pulito. Per il riferimento completo della disciplina, vedi 09 · Riferimento API.

Se il ripristino fallisce

: come ultima risorsa, configurare wdt: (core di esphome) con un app_wdt_timeout_seconds: aumentato (predefinito 5 s; impostare 10–15 s). Ciò concede tempo al recupero del componente senza un riavvio.


2. Qualità dei dati

La tensione oscilla — 228 V / 502 V / 1.96 V mescolati

Cosa si vede:

Text
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 1.964 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 228.365 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V

In Home Assistant il grafico della tensione è a dente di sega tra ~228 V, ~2 V e ~503 V. La corrente può contemporaneamente mostrare 0 A oppure −2 A.

Che cosa significa: valori «fantasma» emergono da una perdita di buffer nel driver ESP-IDF i2c_master in condizioni di NACK a 100 kHz. Questo dovrebbe essere eliminato dalla configurazione predefinita dell'attuale versione del componente. Se il sintomo compare:

  • Il blocco i2c: ha frequency: 100kHz — cambialo in 50kHz.
  • La versione del componente è anteriore al 2026-05-24 — aggiornarla.

Fix:

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # required for reliable operation
  scan: true

Per approfondire il meccanismo di disciplina dei NACK (50 kHz predefinito + ritentativo per byte + filtro di integrità per NaN/Inf), vedere 09 · API reference.

Nota

Compatibilità con framework: type: — il problema dei valori fantasma da NACK si manifesta solo con il driver ESP-IDF i2c_master. Con framework: type: arduino (il predefinito), viene usato lo stack Wire del framework Arduino, che si comporta diversamente con i NACK e non riproduce questo sintomo. Ciò significa:

  • Se il YAML contiene esp32: framework: type: arduino, in teoria si può mantenere frequency: 100kHz senza picchi fantasma visibili, ma il ciclo di ripetizione per byte del componente gira comunque sopra Wire e i NACK periodici a 100 kHz restano — solo senza i fantasmi inquietanti. Per grafici HA stabili raccomandiamo 50 kHz indipendentemente dal framework.
  • Se il YAML contiene esp32: framework: type: esp-idf, allora frequency: 50kHz è obbligatorio. È la configurazione in cui il driver i2c_master mostra in modo più evidente il sintomo fantasma.

Il componente non sceglie il framework — gira sopra entrambi. È una decisione puramente nel tuo YAML.


La corrente è permanentemente 0 A sotto carico

Cosa si vede:

Text
[D][sensor:xxx]: 'Mains Current': Sending state 0.000 A

La potenza è 0 W, l'energia non cresce, ma la tensione viene letta correttamente (ad esempio 228 V).

Cosa significa: una delle due cause tipiche:

Causa 1 — ct_model: non impostato o non corrispondente alla pinza fisica. Sul firmware v1.2+ il modulo usa i coefficienti di fabbrica del modello selezionato nel YAML. Se ct_model: non è impostato, oppure è impostato ad esempio su SCT_013_050 con una vera SCT-013-005, l'intervallo di misura è tanto più ampio del segnale fisico che il modulo non riesce a risolverlo e riporta zero.

Causa 2 — la pinza è installata in modo errato sul conduttore (vedere la polarità in 03_sensor_selection.md e l'aggancio di un solo conduttore).

Come diagnosticarlo:

  1. Verifica che la pinza sia fisicamente installata su un conduttore percorso da corrente e che il conduttore sia davvero attraversato da corrente (usa una pinza amperometrica come riferimento, se ne hai una).
  2. Aprire il YAML e verificare che ct_model: (o ct_models: per UI3) corrisponda al modello di pinza fisica.
  3. Se ct_model: è impostato con firmware v1.2+ ma sensor_class: è omesso o impostato a un valore diverso da SCT_013, il modulo rifiuta la scrittura del modello. Il log di avvio mostra un avviso che indica la condizione preliminare mancante.

Fix:

YAML
rbamp:
  id: meter1
  sensor_class: SCT_013       # default; required on v1.2+ before ct_model
  ct_model: SCT_013_005       # match the physical clamp

Dopo l'avvio il modulo scrive il modello in flash una volta (~700 ms) e carica i coefficienti di fabbrica. La successiva pubblicazione dei valori istantanei fornisce già la corrente corretta.

Precisione sulle piccole correnti su UI2 / UI3 — il pattern a doppio TA. Se vuoi alta risoluzione sui piccoli carichi (illuminazione, stand-by) e un ampio range per i picchi (bollitore, lavatrice) contemporaneamente, usa due canali di corrente sulla stessa fase con pinze diverse:

YAML
rbamp:
  id: home_meter
  sensor_class: SCT_013
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
  # CH0 — SCT-013-005 for resolving idle loads (~5..50 W)
  # CH1 — SCT-013-030 for the main household load (~50..7000 W)
  # CH2 — SCT-013-050 for the peak (EV-charging headroom up to 11.5 kW)
  # For peaks above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A) on that channel

Tutte e tre le pinze stringono lo stesso conduttore di fase L. SCT-013-005 dà circa 10× più risoluzione su correnti piccole rispetto a SCT-013-030, ma satura intorno ai 5 A. SCT-013-030 copre la parte «centrale» dell'intervallo utile; SCT-013-050 cattura i picchi fino a ~11.5 kW senza saturare. Lato HA, un sensore template seleziona la misura «attiva» in base a una soglia:

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel YAML del nodo.

YAML
# configuration.yaml — select the active channel by range
template:
  - sensor:
      - name: "Mains Current (active)"
        unit_of_measurement: "A"
        device_class: current
        state_class: measurement
        state: >
          {% set i0 = states('sensor.rbamp_ch0_current') | float(0) %}
          {% set i1 = states('sensor.rbamp_ch1_current') | float(0) %}
          {% set i2 = states('sensor.rbamp_ch2_current') | float(0) %}
          {% if i2 > 25 %}{{ i2 }}
          {% elif i1 > 4 %}{{ i1 }}
          {% else %}{{ i0 }}
          {% endif %}

Copre l'intervallo dalla portata più piccola alla più grande delle tre pinze (da 5 A a 50 A). Compromesso: tre pinze TA sullo stesso conduttore sono fisicamente ingombranti, e ciascuna occupa un canale del modulo (su UI3 è l'intero modulo). Per la maggior parte delle installazioni una sola pinza con portata adatta al carico copre il 99% degli scenari — il pattern doppio/triplo TA serve solo quando è richiesto un ampio range dinamico.


Snapshot del periodo non valido — l'energia non cresce

Cosa si vede:

Text
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window

Il sensore energy in Home Assistant mostra un valore costante (oppure resta a 0 Wh dopo l'avvio), anche se la potenza viene letta correttamente.

Cosa significa: il flag di validità dello snapshot del periodo era 0 quando il componente lo ha controllato 50 ms dopo il comando di snapshot. Il modulo non ha ancora committato uno snapshot valido del periodo.

Cause normali:

  1. Primo snapshot dopo l'avvio. Lo snapshot di avvio in setup() scarta sempre il suo risultato — l'accumulatore del modulo viene azzerato al primo comando di snapshot. Il secondo snapshot (un update_interval dopo l'avvio) è il primo che integra. L'energia inizia ad accumularsi dopo il primo update_interval completo dall'avvio.
  2. Avvio a freddo del modulo. Il modulo ha bisogno di almeno un ciclo di commit di circa 100 ms prima che esistano dati nell'accumulatore di periodo. Se il primo snapshot avviene prima, il flag di validità è 0.
  3. Snapshot mancato sotto carico intenso. Sotto carico I²C intenso il lato modulo può perdere uno snapshot. Lo snapshot resta vuoto; il successivo dovrebbe riuscire.

Se la voce scatta a ogni ciclo di update() indefinitamente (non solo i primi due), il modulo potrebbe trovarsi in uno stato in cui l'accumulatore del periodo non si committa mai. Spegnere e riaccendere il modulo cancella questo stato.


3. Energia e persistenza

Contatore di energia azzerato a 0 dopo un riavvio

Moduli STANDARD (STD).

L'energia viene dai contatori integrati del modulo ed è anche salvata nella flash dell'ESP32 (NVS), quindi un riavvio dell'ESP32 o del modulo non la azzera e i totali non tornano indietro. Se un sensore di un modulo STANDARD parte ancora da 0, la causa è un azzeramento della NVS (cancellazione del flash, tabella delle partizioni cambiata) e un azzeramento del contatore nel modulo nello stesso momento. I sensori del totale complessivo (energy_total, energy_exported_total, energy_net, reactive_energy*) usano uno slot NVS proprio, separato dagli slot energy per canale, quindi un aggiornamento del componente non cancella i valori per canale.

Che cosa vedi nella dashboard Energia di HA: un calo netto a 0 Wh, poi accumulo normale da 0. La vecchia cronologia in Wh viene conservata nelle statistiche a lungo termine di HA, ma la «lettura attuale del contatore» sembra azzerata.

Che cosa significa: durante il ripristino da NVS non sono stati trovati dati oppure sono stati caricati dati non validi. Possibili cause:

  1. Incremento della versione del layout NVS. La chiave NVS deriva dall'ID del componente, in XOR con una costante di versione del layout. Se il layout della struttura è cambiato (con l'aggiornamento del componente), la chiave dello slot NVS cambia e i vecchi dati non vengono più trovati. Il ripristino riparte silenziosamente da 0.
  2. Frammentazione o corruzione della NVS. La partizione NVS dell'ESP32 usa il wear-leveling della flash. Su deployment molto vecchi o dopo molti flash, la frammentazione può far fallire un salvataggio. Il log mostra: [W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle.
  3. Modifica della struttura delle partizioni. Il flash di un nuovo partitions.csv che modifica dimensione o posizione della partizione nvs invalida tutti i valori salvati.
  4. Primo avvio dopo un ripristino di fabbrica o una cancellazione completa della flash. Atteso: la NVS è vuota, l'accumulatore parte da 0.

Come diagnosticarlo:

Cercare nel log di avvio:

Text
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh

Se presente, il ripristino non ha trovato nulla. Inoltre:

Text
[C][rbamp:xxx]: Restored Wh from NVS: total[0.310, 0.000, 0.000] export[...]

Se il valore ripristinato è sensibilmente più basso del previsto, il salvataggio NVS dei 5 minuti precedenti potrebbe essere stato saltato (perdita nel caso peggiore: ≈ 5 Wh con una media di 60 W).

Fix:

  • Con un aggiornamento del componente che modifica il layout NVS, i vecchi totali non si ripristinano automaticamente. Le statistiche a lungo termine di HA conservano la storia anche se la "lettura attuale" torna a zero.
  • Per preservare i Wh durante una cancellazione forzata della NVS, leggere i valori correnti dei sensori negli Strumenti per sviluppatori di HA prima della cancellazione e annotarli. Non esiste un modo per iniettare un valore iniziale nel componente.

L'energia in HA non corrisponde a un contatore di riferimento

Cosa si osserva: il sensore energy in HA risulta sensibilmente più basso (ad esempio del 10–20%) rispetto a un contatore intelligente di riferimento o al contatore di utenza nello stesso periodo.

Cosa significa: sui moduli BASIC il componente integra la potenza media del periodo sul tempo lato ESP32 tra i comandi di snapshot. Sui moduli STANDARD accumula i contatori di energia propri del modulo.

Se l'energia risulta bassa, controlla tra queste:

  1. Carattere del carico. Il registro della potenza media del periodo è davvero la potenza mediata nel tempo su un periodo chiuso, non un valore istantaneo. Un carico a impulsi (motore, compressore) con un breve tempo di accensione nei 60 secondi del periodo ha una media inferiore alla potenza di picco.
  2. Posizionamento della pinza e calibrazione del carico. Se il modello TA di fabbrica (ct_model:) non corrisponde alla realtà, gli intervalli dei coefficienti risulteranno sfalsati. Verifica che ct_model: nel YAML corrisponda alla pinza fisica sul conduttore.
  3. Livello firmware BASIC. Sul SKU BASIC, i campioni di P per finestra vengono portati a 0 prima dell'integrazione. Se il carico ha una componente rigenerativa (ad esempio un motore di pompa con forza controelettromotrice), BASIC sottostima.

4. Integrazione con Home Assistant

HA mostra "Unavailable" [Non disponibile] per tutti i sensori rbamp

Cosa si vede in HA: tutte le entità sensor.rbamp_* mostrano "Unavailable" [Non disponibile].

Cause e correzioni:

  1. ESP32 offline. Esegui esphome logs --device — se non riesci a connetterti, l'ESP32 è offline. Controlla le credenziali WiFi e l'access point di ripiego, se è configurato.
  2. Connessione API persa. L'API nativa di ESPHome (porta 6053) può essere bloccata da un firewall. Verifica che l'ESP32 sia raggiungibile via IP:

    Shell
    ping 
    

    Se il ping riesce ma HA continua a mostrare non disponibile, l'integrazione ESPHome in HA va rimossa e riaggiunta (Impostazioni → Integrazioni → ESPHome → Elimina, poi rileva di nuovo). [Settings → Integrations → ESPHome → Delete]

  3. Mancata corrispondenza della chiave di crittografia API. Se in YAML è configurato api: encryption: key:, l'integrazione HA deve conoscere la stessa chiave. Una discrepanza fa sì che HA consideri il dispositivo offline. Rimuovi e riaggiungi l'integrazione dopo aver aggiornato la chiave.

  4. mDNS non funziona nella topologia di rete. Se l'ESP32 è su una VLAN diversa da HA, il multicast mDNS potrebbe non attraversare il confine. Aggiungere il dispositivo manualmente tramite IP nell'integrazione ESPHome.

Il flash OTA non riesce

Cosa si vede:

Text
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed

Cause comuni:

  1. L'indirizzo IP è cambiato. L'ESP32 ha ottenuto un nuovo lease DHCP. Controllare la tabella DHCP del router, trovare il dispositivo tramite MAC e assegnare un IP statico, oppure usare la chiave YAML wifi: use_address:.
  2. L'ESP32 è in modalità provvisoria. Dopo tre avvii falliti consecutivi ESPHome entra in modalità provvisoria (senza componenti personalizzati, solo WiFi + OTA). L'OTA in modalità provvisoria funziona, ma il dispositivo esegue un firmware ridotto. Il marcatore in esphome logs:

    Text
    [I][safe_mode:xxx]: Entering safe mode
    

    Forzare un avvio pulito: tenere premuto il pulsante BOOT all'accensione, oppure aggiungere safe_mode: num_attempts: 10 per allargare la soglia.

  3. La porta 3232 (OTA) è bloccata. Il protocollo OTA usa TCP 3232. Verificare che nessuna regola del firewall lo blocchi tra la macchina che esegue esphome run (o l'host HA) e l'IP dell'ESP32.

  4. Un firmware grande dopo aver aggiunto rbamp. Il primo OTA dopo aver aggiunto un componente esterno può superare la dimensione della partizione OTA nel layout predefinito ESP32 da 4 MB. Controllare l'output di esphome compile per gli avvisi sulla dimensione del binario e passare a un layout con partizione OTA più grande, se necessario.

OTA subito dopo il provisioning di new_address: non si carica

Sintomo: dopo un primo avvio riuscito con la chiave new_address: (il log mostra Address change SUCCESS, new address 0x51), il successivo OTA fallisce con un errore di compilazione o un avviso a runtime address 0x50 NACK.

Cosa è successo: il modulo ora si trova sul nuovo indirizzo (0x51), ma il YAML punta ancora a quello vecchio (address: 0x50). Al successivo update() il componente prova 0x50, non ottiene nulla e registra NACK costanti. L'OTA in sé non fallisce davvero qui — è solo un sintomo collaterale: si vede un flusso di errori rbamp in esphome logs e si conclude che il dispositivo è guasto.

Ripristino in 3 passaggi:

  1. Modificare il YAML:

    YAML
    rbamp:
      id: meter1
      address: 0x51        # new address — set instead of 0x50
      # new_address: 0x51  # ← REMOVE this line. Do not comment it out,
      #                       delete it entirely, otherwise the component
      #                       tries to provision again and logs a warning
      update_interval: 60s
      ct_model: SCT_013_030
    
  2. Eseguire esphome run (tramite CLI) oppure Compila + Carica (tramite l'Add-on HA). Il nodo riceve il nuovo binario via OTA su Wi-Fi.

  3. Aprire esphome logs e verificare che il messaggio di avvio dump_config mostri l'indirizzo corretto e che update() giri senza NACK.

Regola — new_address: è un'operazione di provisioning una tantum. Una volta che il modulo si è spostato sul nuovo indirizzo e lo ha salvato in flash, la chiave va rimossa dal YAML. Altrimenti, a ogni avvio il componente tenterà di nuovo il provisioning (sul firmware v1.2+ il modulo ignora la scrittura ripetuta, ma l'avviso resta nel log e ingombra la notify di HA).

Se il modulo non risponde su nessun indirizzo dopo il cambio, vedi «Indirizzo cambiato ma modulo non risponde» sopra.


5. Build e toolchain

Errore di compilazione: 'esphome/core/component.h' file not found

Cosa si vede in VS Code / clangd: sottolineature rosse ovunque in rbamp.h e rbamp.cpp. Popup:

Text
'esphome/core/component.h' file not found

Che cosa significa: clangd (l'IntelliSense C++ di VS Code) non ha accesso ai percorsi di include di ESPHome + PlatformIO. Il sistema di build li risolve correttamente durante esphome compile; clangd no.

Non è un errore di compilazione. Se esphome compile example/ui1.yaml termina senza errori, il codice è corretto.

Se vuoi eliminare le sottolineature rosse: crea un file .clangd nella directory del componente che punti ai percorsi di include generati dall'output di build di ESPHome (.esphome/build//src/). È solo estetico e facoltativo.


PlatformIO si blocca con 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)

Cosa si vede:

Text
Error: Failed to install Python dependencies (exit code: 3221225501)

(0xC0000001D = 3221225501 in decimale)

Che cosa significa: PlatformIO 6.1.19+ usa il binario Rust uv per installare le dipendenze Python nel suo penv interno. Su alcune CPU Intel per laptop recenti uv va in crash con EXCEPTION_ILLEGAL_INSTRUCTION per un'incompatibilità del set di istruzioni. Questo riguarda il passaggio penv_setup.py install su una installazione PlatformIO nuova.

Soluzione alternativa (preinstalla tutte le dipendenze via pip, bypassando uv):

Text
# Step 1: install the ESP32 platform's Python dependencies directly
& "$env:USERPROFILE\.platformio\penv\Scripts\python.exe" -m pip install `
    "littlefs-python>=0.16.0" "fatfs-ng>=0.1.14" "pyyaml>=6.0.2" `
    "rich-click>=1.8.6" "zopfli>=0.2.2" "intelhex>=2.3.0" "rich>=14.0.0" `
    "cryptography>=45.0.3" "certifi>=2025.8.3" "ecdsa>=0.19.1" `
    "bitstring>=4.3.1" "reedsolo>=1.5.3,<1.8" "esp-idf-size>=2.0.0" `
    "esp-coredump>=1.14.0" "pyelftools>=0.32"

# Step 2: bootstrap the nested ESP-IDF venv (see the next entry)
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Una volta installati questi pacchetti, get_packages_to_install() in penv_setup.py restituisce vuoto e l'installazione pip via uv non viene chiamata. Le successive esecuzioni di esphome compile funzionano normalmente.

La soluzione alternativa va riapplicata dopo una nuova installazione di PlatformIO o dopo aver svuotato la cache ~/.platformio.


venv ESP-IDF: nessun modulo idf_component_manager

Cosa si vede:

Text
ModuleNotFoundError: No module named 'idf_component_manager'

Compare alla prima esphome compile su una macchina dove PlatformIO ha scaricato il framework ESP-IDF ma non ha eseguito il bootstrap completo dei suoi requisiti.

Che cosa significa: il framework ESP-IDF di PlatformIO è installato nel venv annidato ~/.platformio/penv/.espidf-5.5.4/ (il numero di versione può differire). Quel venv ha bisogno di requirements.core.txt dal pacchetto del framework. Quando si applica la soluzione alternativa uv di cui sopra, il passaggio 2 avvia pip nel venv e installa i requisiti.

Se l'errore compare dopo aver applicato la soluzione alternativa con uv, ma il passaggio 2 è stato saltato:

Text
# Find the IDF venv (the version number may differ):
ls "$env:USERPROFILE\.platformio\penv\" | Where-Object { $_.Name -like ".espidf-*" }

# Bootstrap pip into the IDF venv:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip

# Install the IDF core requirements:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Sostituire 5.5.4 con il proprio numero di versione IDF (verificare in ~/.platformio/penv/).


esphome compile fallisce: get_object_id_hash non trovato

Cosa si vede:

Text
error: 'class esphome::rbamp::RbAmpComponent' has no member named 'get_object_id_hash'

Cosa significa: una vecchia versione di rbamp.cpp chiamava this->get_object_id_hash() per inizializzare lo slot NVS. Questo metodo è stato rimosso da PollingComponent in ESPHome 2025.x.

Correzione: aggiornare il componente alla versione corrente. Il codice moderno usa una generazione di hash compatibile con ESPHome 2025.x e successivi.


ESPHome troppo vecchio — set_i2c_address non trovato

Cosa si vede:

Text
error: 'class esphome::i2c::I2CDevice' has no member named 'set_i2c_address'

Che cosa significa: il flusso di cambio indirizzo new_address: chiama i2c::I2CDevice::set_i2c_address(), che una versione più vecchia di ESPHome non ha.

Correzione: aggiornare a ESPHome 2025.3.0 o successivo. L'Add-on ESPHome di HA segue automaticamente l'ultima release — il percorso di installazione consigliato.

Shell
# If using a local Python venv:
pip install --upgrade esphome

6. Identità / capacità / errore (v1.3)

Questa sezione spiega che cosa significano i singoli valori delle entità di identità (un text_sensor template tramite lambda:), la bitmap delle capacità e i codici REG_ERROR aggiunti in v1.3.

Le letture di identità restituiscono "UNK" / "UNREADABLE"

Cosa si vede (text_sensor template):

YAML
text_sensor:
  - platform: template
    name: "Meter variant"
    lambda: 'return id(my_meter).get_variant_str();'  # → "UNK" in HA
Text
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK

Che cosa significa:

  • "UNK" — il componente non è riuscito a leggere REG_HW_VARIANT (0x55) dopo tutti i tentativi. Cause: il modulo è su firmware legacy (v1.0–v1.1, prima del rilevamento della variante), oppure un bus I²C marginale con NACK esauriti su questo specifico registro.

  • "UNREADABLE" — la lettura ha restituito un valore fuori da 0x55..0x5A, oltre l'intervallo dei codici di variante validi. Questo indica un firmware corrotto o una collisione grezza di registro (per esempio un buffer obsoleto).

Fix:

  • Con firmware inferiore alla v1.2 il rilevamento della variante non è disponibile. Il text_sensor viene comunque pubblicato; usa un suggerimento lato YAML tramite topology: oppure reinizializza tramite un template di HA.

  • Se il firmware è v1.3+ e il bus è marginale, vedi i2c_master bloccato.

Bitmap CAPABILITY = 0x0000

Cosa si vede:

YAML
text_sensor:
  - platform: template
    name: "Meter capability"
    lambda: 'return id(my_meter).get_capability_hex();'  # → "0x0000"

Che cosa significa: il registro delle capacità non esiste su questo firmware — legge come 0 (il comportamento standard «registro non implementato» del firmware rbAmp). Questo è firmware legacy v1.0–v1.2.

Comportamento del componente: tutte le funzioni condizionate dalle capacità (GC di flotta, commit dell'indirizzo in due fasi, save_user_config, clear_error) ricadono automaticamente sul percorso legacy:

  • fleet_gc_enable: true → avviso + salto (non pubblicizzato dal firmware)
  • new_address: → ripiego monofase, richiede la modalità di provisioning di fabbrica
  • clear_error() → ripiego sull'opcode del fornitore (best effort)

Nessuna regressione: le installazioni v0.4.0 esistenti continuano a funzionare senza modifiche al YAML o al comportamento. È il canone C5 — la funzione condizionata dalle capacità non rompe mai il legacy.

last_error_str() mostra "ERR_PARAM" dopo un cambio di ct_model: o sensor_class:

Cosa si vede:

Text
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)

get_last_error_str() → "ERR_PARAM".

Cosa significa: il firmware ha rifiutato il valore scritto. Le cause più comuni:

  1. Un codice fuori dall'insieme ammesso — per SCT_013 i codici ammessi sono {1, 2, 3, 4, 5, 6, 7}.

  2. Modello TA non nel set ammesso per la classe — per esempio WIRED_CT_1 con sensor_class: SCT_013. Vedi tabella per classe di 03_sensor_selection.md.

  3. Codice 0 (UNSET) — tentativo di cancellare il modello TA tramite 0. Non supportato; usare dev.factoryReset() per un ripristino completo.

Ripristino: chiamare id(my_meter).write_clear_error(); tramite un servizio YAML o tramite lambda: in on_boot: per cancellare REG_ERROR + il bit3 di EVENT_FLAGS. Dopodiché si può ritentare con un valore corretto.

YAML
api:
  services:
    - service: my_meter_clear_error
      then:
        - lambda: 'id(my_meter).write_clear_error();'

Il cambio di ct_model: / sensor_class: viene rifiutato (riga di log, nessuna scrittura)

Cosa si vede:

Text
[W][rbamp:xxx]: ct_model refused: module is calibrated with its fitted sensor (class N) — ...
[W][rbamp:xxx]: sensor_class refused: module is calibrated with its fitted sensor (class N); ...

Che cosa significa: il modulo è stato calibrato in coppia con il proprio sensore montato (WIRED_CT / BUILTIN_CT). Scrivere una classe o un modello generico sostituirebbe quella calibrazione individuale, quindi il componente rifiuta. È la guardia di scrittura, non un guasto. Un valore uguale non viene mai scritto (per questo non viene registrato nulla a livello di avviso).

Correzione: rimuovi sensor_class: / ct_model: / ct_models: dal YAML per un modulo del genere. Solo se vuoi deliberatamente il preset generico, imposta ct_model_force: true insieme al modello, fai il flash una volta e rimuovi entrambe le righe dopo (lo schema rifiuta ct_model_force: senza una chiave di modello).

ct_models: non supportato da questo dispositivo (modulo STANDARD)

Cosa si vede:

Text
[W][rbamp:xxx]: ct_models: (per-channel) not supported by this device — it does not advertise persistent per-channel model storage ... Use the global `ct_model:` key. (Keys ignored.)

Cosa significa: il modulo non può mantenere i modelli per canale dopo un ciclo di alimentazione, quindi scriverli silenziosamente li annullerebbe. Il componente rifiuta invece di perdere il valore.

Correzione: usa la singola chiave ct_model: per tutti i canali.

Modificare ct_model: riavvia il modulo una volta

Sui moduli SCT con firmware fino a 1.4.19, il passaggio a un altro valore nominale si completa con un riavvio del modulo (salvataggio, reset, re-identificazione). Il log mostra il riavvio e, successivamente, che corrente/potenza/energia sono scalati al nuovo valore nominale; i sensori possono saltare un update() nel frattempo. Questo fa parte del flusso normale. Il firmware 1.4.20 e successivi esegue il cambio sul modulo e non avviene alcun riavvio. Se il log segnala che il guadagno applicato è fuori dall'intervallo atteso, il componente non scala; verificare che ct_model: corrisponda alla pinza effettivamente installata.

I sensori di totale complessivo / angolo non pubblicano mai

Che cosa vedi (log di avvio):

Text
[W][rbamp:xxx]: energy_total/energy_net/reactive_energy sensors need on-device energy counters, which this device does not advertise — they will never publish. Per-channel `energy:` keys still work ...
[W][rbamp:xxx]: voltage_angle_*/phase_sequence sensors need a newer device firmware — they will never publish on this device

Che cosa significa: il modulo collegato (o il suo firmware) non fornisce questi valori. Le chiavi vengono validate, ma non viene pubblicato nulla.

Correzione: usa i sensori energy: per canale, oppure aggiorna il firmware del modulo.

start_current_ua: ignorata

[W][rbamp:xxx]: start_current_ua: not supported by this device firmware — key ignored — il modulo conta l'energia a qualsiasi corrente. La chiave ha effetto solo sui moduli STANDARD con contatori di energia integrati. I valori diversi da 0 o da 10..2540 a passi di 10 vengono rifiutati in esphome config.

update_interval rifiutato

update_interval inferiore a 1s viene rifiutato dallo schema in esphome config. latch_interval non deve essere più breve di update_interval.

EVENT_FLAGS bit3 (ERR_LATCH) — comportamento di riattivazione

Che cosa vedi: dopo clear_error(), qualche centinaio di millisecondi più tardi bit3 in EVENT_FLAGS è di nuovo impostato (riattivazione persistente).

Che cosa significa: il canale di errore durevole del firmware riattiva bit3 dopo un azzeramento se la condizione di errore originale non è stata risolta. È per progetto — il master potrebbe perdere il primo azzeramento e non deve dare per scontato che l'errore sia sparito per sempre se il parametro è ancora sbagliato.

Correzione: il ripristino completo richiede due passaggi:

  1. Eliminare la causa (sostituire il codice del modello TA errato, correggere il YAML).
  2. write_clear_error() — questa chiamata cancella sia REG_ERROR sia EVENT_FLAGS bit3 in un'unica operazione.

Se il bit3 continua a riagganciarsi, il parametro è ancora errato; rileggere get_last_error_str() per scoprire esattamente cosa rifiuta il firmware.


Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/10_troubleshooting.md (v1.9.1)