rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub (Edit on GitHub)

10 · Risoluzione dei problemi

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

Questo capitolo è organizzato in base al sintomo che osserva, non per classificazione interna degli errori. Se è qui, qualcosa non funziona come dovrebbe. Trovi il suo sintomo nell'elenco qui sotto, vada alla sezione corrispondente e segua la procedura diagnostica.

La maggior parte dei problemi di banco rientra in tre categorie:

  1. A livello di bus — il modulo non risponde su I²C; le letture sollevano RbAmpIOError.

  2. A livello di dati — il modulo risponde, ma i numeri sono sbagliati: zeri, valori anomali, segno errato.

  3. Livello applicativo — il collegamento è instabile, il contatore Wh deriva, lo script si blocca / termina per timeout.

Scorciatoia per chi ha fretta: a regime, i metodi pubblici dovrebbero restituire valori / produrre snapshot senza sollevare eccezioni. Se nei log compaiono spesso RbAmpIOError o RbAmpStaleError, andare direttamente a «Il modulo non risponde su I²C» qui sotto.

Il modulo non risponde su I²C

Cosa si vede: dev.begin() (o l'ingresso nel context manager with RbAmp(bus, 0x50) as dev:) solleva RbAmpIOError o RbAmpVersionError, oppure le letture RT sollevano regolarmente RbAmpIOError.

Passo 1 — Scansione del bus

Verifichi prima che il modulo sia davvero presente sul bus.

CPython (SBC Linux)

Strumento esterno:

Shell
i2cdetect -y 1     # bus 1 — the standard one on the RPi 40-pin header

Oppure in Python:

Python
from smbus2 import SMBus

with SMBus(1) as bus:
    print("Scanning...")
    for addr in range(0x08, 0x78):
        try:
            bus.write_quick(addr)
            print(f"Found 0x{addr:02X}")
        except OSError:
            pass

Output atteso: Found 0x50 (o un altro indirizzo, se l'ha cambiato).

MicroPython

Python
from machine import I2C, Pin

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
print("Found:", [hex(a) for a in i2c.scan()])

Output atteso: Found: ['0x50'] (o l’indirizzo impostato).

Che cosa fare se non si trova nulla

Il problema è nel cablaggio o nell'alimentazione:

  • SDA / SCL non sono scambiati (vedi 04 · Cablaggio per i GPIO predefiniti per host).

  • Entrambe le linee hanno un pull-up a 3.3 V (la scheda del modulo ha resistenze integrate da 4.7 kΩ — non servono resistenze esterne per un singolo modulo).

  • Il pin di alimentazione del modulo legge effettivamente 5 V (4.5–5.5 V).

  • Nessun altro master (sonda di debug, secondo controller) è agganciato alle stesse linee.

  • Su MicroPython verifichi che freq=50_000 (non 100k o 400k — su ESP32 + firmware v1 lo schema di NACK di base consuma il budget dei tentativi).

  • Su CPython controllare che il driver I²C del kernel sia abilitato — lsmod | grep i2c_bcm sul RPi.

Che cosa fare se il modulo compare a un indirizzo inatteso

Qualcuno lo ha riassegnato in precedenza sul banco di prova. Aggiorni il secondo argomento di RbAmp:

Python
dev = RbAmp(bus, 0x52)   # address from the bus scan

Passo 2 — MicroPython + pattern di NACK di base su ESP32

Se la scansione del bus trova il modulo ma dev.read_voltage() solleva periodicamente RbAmpIOError — e si usa MicroPython + ESP32 — si tratta di uno schema di base documentato: lo stack I²C della porta ESP32 di MicroPython ha ereditato difetti del driver ESP-IDF v5, che con il firmware attuale di rbAmp produce NACK frequenti a 100 kHz.

La mitigazione è già integrata in MachineI2CBackend (3 tentativi con pausa di 5 ms per default), ma sotto carico elevato il budget dei tentativi può esaurirsi.

Cosa fare su ESP32:

  1. Abbassi la velocità del bus a 50 kHz:
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Aumenti il numero di tentativi per un carico pesante — serve l'API avanzata con la creazione esplicita del backend:
Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5, retry_gap_ms=5)
dev = RbAmp(backend, 0x50)   # the address goes to RbAmp, not to the backend
  1. Monitori il contatore di esaurimento dei tentativi — in regime stazionario deve restare a zero:
Python
if backend.retry_exhaustion_count > 0:
    print("WARN: retry exhausted:", backend.retry_exhaustion_count)

Passaggio 3 — Piattaforme non ESP32 (RP2040 / STM32 / CPython)

Su RP2040 / STM32 / Pyboard (tramite MicroPython) non c'è uno schema di NACK di base — queste piattaforme mostrano un tasso di NACK di circa 0 % con rbAmp. MachineI2CBackend riconosce automaticamente la porta e abbassa il valore predefinito dei tentativi a 1.

Su CPython (tramite smbus2) non esiste affatto uno strato di retry — il driver I²C del kernel Linux non è soggetto allo schema di NACK; un singolo OSError da smbus2 viene tradotto in RbAmpIOError senza retry.

Se su queste piattaforme si verificano NACK, cerchi:

  • Capacità del bus elevata — cavi lunghi e molti dispositivi. Abbassare la velocità o accorciare il cavo.

  • Contesa del master — il pacchetto non supporta il multi-master.

  • Un SCL flottante tra le transazioni — manca un pull-up.
  • Su RPi: controllare dtparam=i2c_arm_baudrate in /boot/config.txt — si consiglia 100000.

PermissionError: [Errno 13] su /dev/i2c-1 (Linux)

Cosa si vede: SMBus(1) solleva PermissionError, mentre sudo python funziona. L'utente non può aprire il dispositivo I²C. Correzione:

Shell
sudo usermod -aG i2c $USER   # then log out and in again

Verificare anche che l'I²C sia abilitato (sudo raspi-config → Opzioni di interfaccia / Interface Options → I2C) e che ls /dev/i2c-* elenchi il bus; sudo apt install i2c-tools fornisce i2cdetect -y 1.

La corrente legge zero con un carico in funzione

Cosa si vede: dev.current[0] (o dev.read_current(0)) restituisce 0.000 (o un valore molto piccolo) anche se un utilizzatore reale è acceso (un bollitore, una lampada, un ferro). dev.power_factor[0] può mostrare un valore strano (nan / 0 / ±1) — ne è una conseguenza; la causa è nella corrente.

Procedura diagnostica

  1. Verificare che la classe del sensore e il modello CT siano configurati:
Python
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass, RbAmpModeError

try:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
except RbAmpError as e:
    print("set_sensor_class failed:", e)

try:
    dev.set_ct_model(3)   # or your model — see the table in 03
except RbAmpModeError:
    print("Class must be set first!")
except ValueError:
    print("Code not in per-class accept-set (SCT_013: {1,2,3,4,5,6,7})")

Senza queste due chiamate i coefficienti di calibrazione non vengono caricati e la corrente risulta sempre zero. Questo passaggio va eseguito una sola volta alla prima installazione — la scelta viene salvata nella flash del modulo.

  1. Verifichi che il modello TA corrisponda al carico. Una pinza TA grande (per esempio SCT-013-100, 100 A) su un carico piccolo (una lampada da 50 W = ~0.2 A) darà un segnale al limite del rumore di fondo e le letture risulteranno zero. Scelga il modello TA più piccolo che copre la sua corrente massima prevista. La tabella completa è in 03 · Selezione del sensore di corrente.

Se si ha un modulo multi-canale (UI2 / UI3 / UI5 / UI7) e si vogliono vedere sia piccoli carichi sia picchi, valutare lo schema a doppio TA: una pinza piccola (SCT-013-005) su un canale separato per la gamma bassa + una grande (SCT-013-030/100) su un altro canale per la gamma alta; il master sceglie il valore per soglia. Lo schema è discusso in 03 · Selezione del sensore di corrente, nella sezione «Topologia a doppio TA».

  1. Controlli l'orientamento della pinza. La freccia sul corpo della pinza deve puntare nella direzione del flusso di corrente verso il carico. Se la pinza è montata "al contrario", dev.read_current() darà il valore corretto in termini assoluti, ma dev.read_power() darà un valore negativo su un carico consumatore. Conferma — dev.read_power_factor() mostrerà esattamente −1.0 su un carico resistivo (invece di +1.0). Rimedio: o rimonta fisicamente la pinza (la sgancia, gira la freccia nel verso giusto, la riaggancia), oppure inverte il segno lato applicazione (p = -p; pf = -pf; se sa che il carico non è un inverter fotovoltaico).

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 davvero scorrendo — misurarla con un multimetro (una pinza DC / 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 si sta stringendo il filo giusto — un solo conduttore, il filo vivo (L), non l'intero cavo (includendo L e N si legge ~0).

Le letture oscillano o sollevano RbAmpIOError

Cosa si vede: dev.voltage / dev.read_current(...) solleva periodicamente RbAmpIOError. Il valore della proprietà non è stato ottenuto — serve un nuovo tentativo lato applicazione o una guardia try/except.

RbAmpIOError dal pacchetto copre due classi di problemi:

  • NACK dopo l'esaurimento dei ritentativi — il collegamento è instabile.
  • Il filtro di sanità ha scartato il valore — un NaN / Inf / |x| > 10000 float (chiaramente non un valore fisico) è arrivato dal bus.

Li distingua tramite i contatori diagnostici (disponibili su MicroPython):

Python
from rbamp._io_micropython import MachineI2CBackend

# Build the backend yourself, then pass IT (not the raw I2C object) to RbAmp.
# This is where `backend` comes from; the address belongs to RbAmp.
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)

# After a period of operation:
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)
Contatore Che cosa significa
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 Il bus è in buono stato; il pacchetto recupera silenziosamente i rari NACK. Normale.
retry_count_total ↑, retry_exhaustion_count ↑ Plateau di NACK — aumenti retry_attempts (vedere Passaggio 2 sopra).
retry_count_total basso, sanity_reject_count in aumento Il filtro di sanità sta catturando dati spazzatura dopo i tentativi falliti. Aumenti retry_attempts=5+.

Su CPython (SMBusBackend) non c'è un livello di ripetizione — RbAmpIOError viene sollevata al primo errore. I sintomi sono rari (il kernel Linux è di solito affidabile), ma se compaiono controlli cablaggio / pull-up / velocità del bus.

Il Power Factor sembra strano

Che cosa si vede: dev.power_factor[0] (oppure dev.read_power_factor(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, compressore a motore +0.6 .. +0.85 (induttivo)
Lampada LED, TV (alimentatore switching) +0.5 .. +0.95 (non lineare)
Impianto fotovoltaico che esporta potenza PF negativo

PF = nan o 0 con I = 0

Il PF è definito come P / (U × I). A corrente zero I=0 il calcolo non è definito. Il valore restituito dipende dal firmware (può essere nan, 0 oppure un segnaposto) — è normale finché la corrente è davvero zero. Appena compare la corrente, compare un PF valido.

PF esattamente −1.0 su un carico puramente consumatore

La pinza è montata "al contrario" — la freccia non punta nella direzione della corrente verso il carico. Rimedio: o rimonti la pinza correttamente, oppure gestisca il segno lato applicazione (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 TA è su un filo di fase diversa da quella a cui è collegato l'ingresso U del modulo. In un quadro di distribuzione multifase è facile stringere 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 noto come resistivo (un bollitore elettrico a piena potenza).

Le istantanee di periodo sono sempre RbAmpStaleError

Che cosa si vede: dev.read_period_snapshot() solleva RbAmpStaleError a ogni chiamata. Ciò significa che il modulo non ha finito di integrare il periodo precedente quando è avvenuta la lettura successiva.

Su una lettura non aggiornata il pacchetto mantiene il timestamp precedente, così lo snapshot valido successivo copre l'intero intervallo dall'ultimo buono e il totale Wh resta esatto (nessun doppio conteggio, nessuna perdita).

Accettabile: letture non aggiornate rare (1–2 l'ora con 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

  1. Verifichi la cadenza: 60 s tra le istantanee sono comodi; 30 s sono al limite; < 10 s garantiscono letture non aggiornate.

  2. Verificare la reattività del modulo tra gli snapshot:

Python
if dev.probe():
    print("alive")
  1. Controllare direttamente il flag:
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. Verifichi la versione del firmware — dev.firmware_version >= 0x04 (v1.3) ha il minor numero di letture non aggiornate; 0x02/0x03 (v1.1/v1.2) sono ancora supportate ma il tasso di letture non aggiornate aumenta; 0x01 (v1.0) è la più rumorosa.

Caso speciale — risveglio MicroPython da deep sleep

Se si usa uno schema deep-sleep su MicroPython, la lettura predefinita dev.read_period_snapshot() dopo l'ingresso del context manager darà sempre un risultato non aggiornato (o quasi zero) — __enter__ esegue uno snapshot di priming (comando LATCH) che azzera l'accumulatore del firmware. Lo schema canonico usa skip_latch=True + una durata di sleep nota (l'argomento di machine.deepsleep(SLEEP_MS)) — vedi 06 · Esempi, Scenario 9.

La contabilità dei Wh si discosta dal riferimento

Cosa si vede: dev.energy.wh(0) dopo diverse ore o giorni di funzionamento si discosta dalla lettura del contatore della rete o da un misuratore di riferimento (Kill-A-Watt o simili).

Escludere prima il banale

  1. Taratura del sensore di corrente: assicurarsi che dev.set_sensor_class() e dev.set_ct_model() siano chiamate con il modello TA corretto (vedi 03 · Selezione del sensore di corrente). Senza questo, la corrente RMS viene calcolata con il fondo di scala predefinito e il valore di potenza risulterà sistematicamente distorto.

  2. Snapshot non aggiornati scartati: se dev.energy.wh(0) è costantemente inferiore al riferimento, potrebbero essere intervalli mancati. Un singolo snapshot non aggiornato non fa perdere energia (il successivo buono copre l'intero intervallo), ma guasti ripetuti o uno script non in esecuzione sì. Controllare la cadenza (vedi sopra).

  3. Deriva dell'orologio del master: time.monotonic() (CPython) e time.ticks_ms() (MicroPython) sono affidabili in funzionamento normale. Ma se il master va in deep sleep, usi lo schema memoria RTC + durata nota del sonno dello Scenario 9.

Sicurezza

⚠ ticks_ms() — riavvolgimento su MicroPython. time.ticks_ms() si riavvolge a 2**30 ms (~12.4 giorni) — una sottrazione ingenua t1 - t0 attraverso il limite di 12.4 giorni dà un numero negativo o enorme. Internamente il pacchetto usa time.ticks_diff(t1, t0), che è sicuro rispetto al riavvolgimento. Se master_dt_ms viene calcolato nel codice utente (fuori dal pacchetto), usare ticks_diff, non la sottrazione diretta.

Precisione dell'accumulatore

L'accumulatore dei Wh all'interno dell'handle:

Runtime Tipo
CPython float a 64 bit (float di Python)
MicroPython (build a doppia precisione) float a 64 bit
MicroPython su porte senza double-float float a 32 bit

Verifica della precisione su MicroPython (sys.float_info esiste solo su CPython; su uPy usiamo un controllo empirico):

Python
# On CPython:
import sys
print(sys.float_info.dig)   # 15 → double; 7 → single

# On MicroPython — empirically:
import sys
print(sys.implementation.name)   # 'micropython'
test = 1.0 + 1e-15
print("double" if test != 1.0 else "single")   # 1.0 + 1e-15 != 1.0 only on double

Per le piattaforme MicroPython a float singolo in installazioni di lunga durata, reimpostare periodicamente dev.energy.reset(0) e conservare il totale a lungo termine nella propria memoria persistente (per esempio tramite un messaggio MQTT con retain in HA).

Lo script si blocca / termina per timeout

Che cosa si vede: lo script Python si avvia normalmente, poi dopo alcuni minuti si blocca o genera un RuntimeError.

MicroPython su ESP32: un'operazione I²C si blocca su un bus marginale — mitigazione a tre livelli

Che cosa si vede in particolare: uno script su ESP32 (MicroPython machine.I2C) interroga rbAmp regolarmente per diversi minuti, poi si blocca "morto" nel mezzo di una chiamata dev.read_period_snapshot() / fleet.poll_all(). Il WDT (se ne ha uno attivo) intercetta il blocco; altrimenti lo script semplicemente smette di rispondere. Se ha un REPL, anche quello si blocca.

Che cosa succede: MicroPython su ESP32 machine.I2C incapsula lo stesso driver IDF i2c_master che usano i progetti nativi ESP-IDF. Su un bus marginale (pull-up deboli, tracce lunghe, EMI, rumore ZC) SDA/SCL possono momentaneamente "bloccarsi" in uno stato indefinito. Prima della transazione successiva, IDF i2c_master gira in un ciclo i2c_ll_is_bus_busy in attesa che il bus si liberi — questo ciclo non è limitato dal timeout I²C della libreria.

Questo non è un "artefatto solo del debugger". Validato sul banco (tra librerie, stesso banco di prova hardware e 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 (soak di 12 minuti, 0 riavvii)

La correlazione è netta — una correzione dell'integrità del bus elimina del tutto il blocco. La logica della libreria non è colpevole.

Mitigazione a tre livelli (applichi tutti e tre):

  1. 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 4.7 kΩ integrati nei moduli, in parallelo, diventano troppo forti. Su un bus del genere tagli quelli integrati su tutti i moduli tranne uno. Vedere 04 · Cablaggio, la sezione "Bus multi-modulo — la topologia principale".

  2. Non eseguire 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 indefinito al distacco/riattacco, provocando un blocco del bus alla transazione successiva.

  3. Un WDT di task a livello applicativo sul task di interrogazione — difesa in profondità. I pull-up corretti sul bus sono la soluzione sul campo; il WDT di task è una postura di ripristino.

Python
# MicroPython-on-ESP32
from machine import WDT
import time

wdt = WDT(timeout=8000)   # 8 s

while True:
    snap = dev.read_period_snapshot()
    # ... processing ...
    wdt.feed()             # "I'm alive" — every cycle
    time.sleep_ms(200)

Che cosa NON fare: non tenti di aggirare il problema con un parametro I2C(..., timeout=ms) più grande — non limita il pre-ciclo di bus occupato, che è un percorso di codice diverso nel driver IDF. Ciò che serve è correggere l'integrità del bus (livello 1) + il supervisore (livello 3).

CPython su SBC Linux: il kernel I²C non soffre di questo problema

I driver del kernel Linux (i2c-bcm2835 sul Raspberry Pi, i2c-i801 su x86, ecc.) eseguono la verifica di bus occupato con un timeout — su un bus bloccato restituiscono IOError(Errno 110: ETIMEDOUT) o EREMOTEIO invece di bloccarsi. La libreria lo incapsula in RbAmpIOError. Di conseguenza, la mitigazione a tre livelli non serve su CPython — Linux se ne occupa da sé. Un pull-up esterno da circa ~4.7 kΩ resta comunque desiderabile per l'integrità del segnale su un bus lungo.

latch_ms non corrisponde al periodo dell'orologio a parete

latch_ms è un timer diagnostico del modulo; non lo usi per l'energia — usi l'orologio del master.

La libreria integra l'energia con l'orologio a parete del master: CPython — time.monotonic(); MicroPython — time.ticks_ms() + time.ticks_diff(). L'integrazione lato master non aggiunge errori propri oltre a quelli dell'accuratezza della potenza attiva del modulo.

Se il suo codice si basa su snap.latch_ms per i calcoli sotto-periodo, passi al proprio time.monotonic() / time.ticks_diff().

RbAmpStaleError a ogni lettura — la libreria mantiene l'ancoraggio automaticamente

Cosa si vede: dev.read_period_snapshot() solleva periodicamente RbAmpStaleError.

Gestione canonica di dt: su una lettura non aggiornata la libreria Python non azzera l'ancora interna _last_latch_ms. La lettura valida successiva ottiene un master_dt_ms uguale all'intervallo completo dall'ultimo snapshot riuscito — 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à un valore mediato sull'intero intervallo. L'integrazione dei Wh resta esatta — nessun doppio conteggio, nessun conteggio mancante.

Schema per l'avvio a freddo (prime-until-valid, budget di circa 25 tentativi sufficiente):

Python
from rbamp import RbAmpStaleError

while True:
    try:
        snap = dev.read_period_snapshot()
        break
    except RbAmpStaleError:
        time.sleep(3.0)

Dopo il priming — ignorare RbAmpStaleError se è raro; se è frequente, diagnosticare la cadenza (la sezione «Gli snapshot di periodo generano sempre RbAmpStaleError» sopra).

CPython: signal.SIGTERM / KeyboardInterrupt non vengono gestiti

Causa: un time.sleep(60) lungo blocca il gestore del segnale. In un deploy di produzione (systemd), systemctl stop rbamp attende la risposta a SIGTERM fino a un timeout (predefinito 90 s) e poi termina con SIGKILL — i Wh possono andare persi.

Rimedio: un ciclo consapevole dei segnali:

Python
import signal, time
shutdown = False

def on_sig(sig, frame):
    global shutdown
    shutdown = True

signal.signal(signal.SIGTERM, on_sig)
signal.signal(signal.SIGINT,  on_sig)

while not shutdown:
    snap = dev.read_period_snapshot()
    # ... publish ...
    for _ in range(60):           # wake on signal every second
        if shutdown: break
        time.sleep(1)

Oppure usi asyncio con un signal_handler — vedere la sezione qui sotto.

MicroPython (ESP32): timeout del watchdog alla connessione WiFi

Causa: un ciclo di connessione WiFi senza limite fa scattare il watchdog del task dopo ~5 s (il valore predefinito).

Correzione: un'attesa limitata con un ripiego di riavvio:

Python
import network, time, machine

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "pass")

t0 = time.ticks_ms()
while not wlan.isconnected():
    time.sleep_ms(100)
    if time.ticks_diff(time.ticks_ms(), t0) > 30_000:
        machine.reset()

Il broker MQTT si disconnette

Su CPython (paho-mqtt): il keepalive predefinito è 60 s, ma mqtt.connect() è bloccante e mqtt.loop() deve essere chiamato in un ciclo di eventi. Usi mqtt.loop_start() (un thread in background) oppure la variante asyncio aiomqtt.

Su MicroPython (umqtt.simple): sincrono senza keepalive — bisogna chiamare mqtt.ping() a mano ogni ~30 s. L'alternativa è il pacchetto asincrono mqtt_as, con keepalive integrato.

Fallimento dell'handshake TLS (cloud da CPython + RPi con poca RAM)

Raramente un problema su un Pi con 1+ GB di RAM, ma su un Pi Zero / Zero W (512 MB) un handshake TLS con un archivio di certificati grande può essere terminato dall'OOM killer.

Fix:

  • Usi un CA specifico invece dei ca-certificates di sistema — meno memoria.

  • Ridurre i buffer MQTT.

  • Passi a un Pi 3/4/5 per un deployment cloud in produzione.

set_sensor_class() / set_ct_model() solleva RbAmpModeError

Che cosa si vede: una delle chiamate di configurazione solleva RbAmpModeError con il messaggio:

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Causa: set_ct_model[_ch] richiede che set_sensor_class() sia stata chiamata prima. È una guardia intenzionale.

Cosa fare:

Python
from rbamp import RbAmpSensorClass

# Class first — MANDATORY
dev.set_sensor_class(RbAmpSensorClass.SCT_013)

# Then the model
dev.set_ct_model(3)   # or per-channel dev.set_ct_model_ch(ch, code)

Altri dettagli — 03 · Selezione del sensore di corrente e 09 · Riferimento API, la sezione «Configurazione del sensore».

Dalla 1.6.0 questi setter sono protetti da una guardia di lettura prima della scrittura:

  • Impostare la classe o il modello che il modulo già possiede è un no-op silenzioso (riscrivere cancellerebbe la taratura dei canali).

  • Su un modulo preaccoppiato in fabbrica (classe WIRED_CT / BUILTIN_CT) una classe o un modello diversi vengono rifiutati con RbAmpModeError. In un contesto di assistenza usi dev.set_ct_model_ch_force(ch, code).

RbAmpModeError deriva anche da dev.factory_reset() e dev.save_gains() (le operazioni di fabbrica richiedono la modalità fabbrica). Un cambio di indirizzo sulla v1.3 è adatto alla produzione e non solleva RbAmpModeError.

set_sensor_class() / set_ct_model*() solleva RbAmpParamError o ValueError

Cosa si vede: la chiamata solleva RbAmpParamError (su CPython eredita anche ValueError tramite multi-base).

Possibili cause:

  1. Codice modello non valido — per la classe SCT_013 l'insieme accettato è {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 di un modello SCT-013. I valori fuori dall'insieme accettato sollevano RbAmpParamError(ValueError).

  2. Indice di canale non valido nella forma per canale dev.set_ct_model_ch(channel, code) — deve essere < dev.channels.

  3. Un valore di classe del sensore fuori da 0..3. (WIRED_CT / BUILTIN_CT sono valori validi, ma un modulo accoppiato in fabbrica rifiuta di essere riconfigurato — questo solleva RbAmpModeError, vedi sotto.)

Gestione errori: ultima scrittura su REG_ERROR + EVENT_FLAGS.bit3 durevole (v1.3)

v1.3: 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 cancella l'errore precedente.

Il segnale di errore durevole = EVENT_FLAGS (0x2A) bit3 — persistente (W1C), asserito immediatamente su qualsiasi scrittura o comando rifiutato.

Schema 1 — cattura una tantum dopo l'operazione (l'esito di esattamente questa operazione):

Python
dev.save_user_config()
dev_err = dev.read_reg(0x02)   # IMMEDIATELY, before the next write

Schema 2 — monitoraggio durevole (canonico per il funzionamento a lungo termine):

Python
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear bit3
    # or dev.clear_error()
Sicurezza

⚠ INVERSIONE della prima documentazione «persistente» (v1.3). REG_ERROR è l'esito dell'ultima scrittura, non persistente. La durata è garantita dal bit3 di EVENT.

⚠ 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 torna (alcune centinaia di millisecondi). Non interroghi bit3 subito dopo una scrittura per verificarne l'esito — per l'esito della sua scrittura usi il Schema 1 (cattura una tantum con read_last_error(), immediata) oppure la RbAmpParamError sollevata dal setter. bit3 serve per il monitoraggio prolungato di fatti asincroni (tempo di funzionamento, percorso dei comandi), non per validare un'operazione appena eseguita.

Attenzione: DEV_ERR_CLONE (0xF9) non viene azzerato da CMD_CLEAR_ERROR — è una sentinella anti-clone.

Un 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: la pagina dei parametri non è inizializzata → vengono caricati i valori di fabbrica. È NORMALE per un modulo vergine, non fatale.

Rimedio: configuri sensor_class + ct_model + (facoltativamente) l'indirizzo, poi dev.save_user_config(). Dopo un SAVE riuscito → REG_ERROR = 0x00, bit3 azzerato.

Le letture falliscono durante la commutazione di carichi a relè (transitori EMI)

Che cosa si vede: dev.voltage / dev.current() sollevano periodicamente RbAmpIOError / OSError — ma solo durante la commutazione attiva di un carico a relè/induttivo sullo stesso impianto. Le letture a regime sono affidabili.

Causa (C.12 confermata su hardware): durante la commutazione dei relè (carico da 5 A) le EMI fanno fallire circa il 67% delle transazioni I²C. Il bus si riprende da solo, non si blocca e nessun modulo viene perso.

Correzione — ripetizione a livello applicativo:

Python
def robust_read_voltage(dev, attempts=5, gap_s=0.020):
    for _ in range(attempts):
        try:
            return dev.voltage
        except (RbAmpIOError, OSError):
            time.sleep(gap_s)
    raise RbAmpIOError("read failed after retries")
Sicurezza

⚠ Il solo tentativo del backend non basta: quando un disturbo EMI supera la finestra di tentativi del backend, serve un nuovo tentativo esplicito a livello applicativo con una pausa.

commit_address_change() solleva RbAmpIOError dopo un reset del bus

Che cosa si vede: prepare_address_change() è riuscita, ma dopo il commit + il reset il modulo non risponde al nuovo indirizzo.

Nota

✅ v1.3: REG_I2C_ADDRESS (0x30) legge l'indirizzo attivo all'avvio. Dopo il riavvio successivo al commit, leggere 0x30 al nuovo indirizzo mostrerà lo stesso indirizzo — questo conferma che il commit è andato a buon fine. Se il modulo non risponde al nuovo indirizzo, provare una scansione del bus tramite _io_smbus (mostrerà a quale indirizzo si trova realmente il modulo).

Per approfondire il commit in due fasi — vedi 09 · Riferimento API e 04 · Cablaggio.

commit_address_change() solleva RbAmpTimeoutError

Se prepare è riuscita ma commit solleva RbAmpTimeoutError, la finestra di «armamento» è scaduta (5 secondi dopo prepare). dev.probe() non aiuta qui (il modulo risponde; il problema è nella macchina a stati del modulo). La correzione è richiamare dev.prepare_address_change(new_addr) e poi subito, nella stessa funzione/iterazione, senza chiamate di rete in mezzo, dev.commit_address_change(). Qualsiasi I/O bloccante tra prepare e commit (WiFi, MQTT, HTTP) è la causa principale della scadenza della finestra.

wait_ready() solleva RbAmpTimeoutError

Il flag di pronto del modulo non è stato impostato entro timeout_ms. Possibili cause:

  • Il modulo non ha ancora completato l'avvio a freddo (~250 ms) — aumenti timeout_ms oppure ripeta la chiamata.

  • Il modulo non risponde via I²C — vedere la sezione "Il modulo non risponde via I²C" qui sopra.

  • Il livello di alimentazione è sceso sotto 4.5 V — verificare VCC con un multimetro.

Altri dettagli sui metodi pubblici ma segnalati — vedi 09 · Riferimento API, la sezione «Configurazione del sensore» (la sottosezione sul cambio di indirizzo è lì insieme a save_gains e factory_reset).

RbAmpNotSupportedError (chiamate STD)

Cosa si vede: una chiamata come dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() o dev.set_time() solleva RbAmpNotSupportedError.

Cause e che cosa fare:

  1. Il modulo è un modulo BASIC. Le chiamate riservate allo STD non sono disponibili su BASIC. Verifichi dev.is_std; su BASIC usi i lettori comuni (voltage, current, power, power_factor, frequency) e invece l'API di periodo.

  2. L'immagine del modulo è troppo vecchia per quella funzione. I contatori di energia in micro-unità, gli angoli di tensione e la corrente di avviamento richiedono un'immagine del modulo abbastanza recente; su una più vecchia la chiamata segnala «non disponibile». Le letture comuni continuano a funzionare.

  3. dev.is_std è False su un modulo STD. La libreria rileva la linea con una transazione di bus a 16 bit; un oggetto bus o un adattatore che non può farla viene trattato come BASIC. Usi smbus2 su CPython (validato), e vedere 04 · Hardware.

Lo stesso cablaggio I²C vale per entrambe le linee di moduli. Si noti che le funzioni di energia sul dispositivo, angolo e corrente di avviamento sono validate su CPython; il percorso MicroPython a 16 bit non è ancora validato su hardware.

Tabella riassuntiva delle eccezioni

RbAmpError (una sottoclasse di OSError) è la classe base. Un gestore except OSError: già presente nell'applicazione continua a intercettare gli errori rbAmp senza modifiche — la convenzione Python standard per i driver di I/O hardware.

Eccezione Quando Dove guardare
RbAmpIOError NACK dopo i tentativi; scarto per controllo di sanità; guasto a livello di bus la sezione «Il modulo non risponde su I²C»
RbAmpTimeoutError wait_ready() scaduto; la finestra di commit_address_change (5 s) scaduta la sezione «commit_address_change restituisce RbAmpTimeoutError» più sotto
RbAmpNotReadyError (riservato; non sollevato dalla libreria, esportato per compatibilità futura) se si cattura questo tipo — riprodurlo in una segnalazione (issue)
RbAmpStaleError snapshot di periodo non aggiornato la sezione "Le istantanee del periodo sono sempre RbAmpStaleError"
RbAmpParamError (su CPython anche ValueError) argomento errato: dev=None, ch fuori intervallo, code non nell'insieme ammesso per la classe (per SCT_013 — {1, 2, 3, 4, 5, 6, 7}), un cls riservato. Inoltre una violazione di precondizione: set_ct_model*() senza una precedente set_sensor_class() verificare gli argomenti della chiamata e che set_sensor_class() sia stata chiamata
RbAmpModeError funzionamento solo in fabbrica (modalità fabbrica non impostata; un cambio di indirizzo sulla v1.3 è ammesso in produzione); classe del sensore non impostata; un modulo preaccoppiato in fabbrica rifiuta il cambio di classe/modello controlli il flag di modalità; set_sensor_class() prima; set_ct_model_ch_force() per uso di assistenza
RbAmpNotSupportedError Chiamata riservata allo STD su un modulo BASIC, oppure una funzione STD che l'immagine del modulo non fornisce la sezione "RbAmpNotSupportedError" qui sotto
RbAmpVersionError REG_VERSION = 0/0xFF su begin() (il modulo non risponde o il firmware è corrotto). set_ct_model_ch per canale su v1.0/v1.1 può ricevere NACK (l'opcode non esiste) e sollevare RbAmpIOError, non RbAmpVersionError — il controllo di versione NON è implementato lato client: verificare dev.firmware_version ≥ 0x03 prima della chiamata verifichi dev.firmware_version

Tutte le eccezioni hanno un messaggio __str__ significativo — il pacchetto costruisce con cura i messaggi di errore con il contesto.

Tabella riassuntiva dei contatori diagnostici

In una prova di soak in regime (il banco di soak di 1 ora) restano tutti a zero:

Contatore A regime Reset Disponibilità
dev.sanity_reject_count 0 dev.reset_counters() entrambi i runtime
MachineI2CBackend.retry_exhaustion_count 0 backend.reset_counters() Solo MicroPython
MachineI2CBackend.retry_count_total basso (sono normali circa 5-20 all'ora) backend.reset_counters() Solo MicroPython
frazione stale negli snapshot di periodo < 1 % (cumulativo — senza azzeramento) entrambi i runtime

Se una di queste è diversa da zero a regime, tornare alla sezione corrispondente sopra.

Debug a livello di bus con un analizzatore logico

Per il debug approfondito, quando il pacchetto non può più dire che cosa accade sul filo, catturi SDA + SCL con un analizzatore logico (Saleae, DSLogic Plus, qualsiasi dispositivo 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 script (dev.voltage, ecc.) con la sequenza di byte attesa — devono coincidere esattamente. Le letture sono ammesse a raffica (auto-incremento). Le scritture non sono auto-incrementali (un byte alla volta per i registri multi-byte).

Se il comportamento del pacchetto diverge dalla cattura, apra una segnalazione allegando il file di cattura (.sal / .dsl / .csv).

Quando contattare l'assistenza

Se ha seguito la sezione corrispondente qui sopra e il problema persiste, apra una segnalazione:

github.com/rb-amp/rbamp-python/issues

Nella segnalazione includa:

  • Runtime + versione: python --version / mpremote eval 'import sys; print(sys.version, sys.implementation)'.

  • Piattaforma host: "RPi 4B Bookworm", "ESP32-S3 N16R8 MicroPython 1.22", ecc.

  • Versione del pacchetto: rbamp --version (CPython) oppure python -c "import rbamp; print(rbamp.__version__)".

  • Versione del firmware del modulo — dev.firmware_version dai log.

  • Uno script minimo (~30 LOC) che riproduce il problema.
  • Il traceback dell'eccezione con il contesto completo.
  • I contatori al momento del guasto: dev.sanity_reject_count, backend.retry_exhaustion_count (solo uPy).

  • I log dettagliati della libreria — il modo più semplice per raccoglierli è dev.set_logger(print) prima dell'operazione che fallisce. Il pacchetto stamperà i suoi passaggi interni (il ciclo di ripetizione, i timeout di stabilizzazione, il primer dell'istantanea, ecc.) — alleghi lo stdout alla segnalazione.

  • (Se disponibile) il file di cattura dell'analizzatore logico.

CLI — rbamp scan / rbamp read / rbamp address

La CLI rbamp è un thin wrapper su RbAmp.* per le operazioni da banco (vedi 09 · Riferimento API, la sezione «CLI»). Poiché usa la stessa classe RbAmp, valgono TUTTI i sintomi sopra. Errori specifici della CLI:

  • rbamp scan non trova nulla — come nel Passo 1 della sezione «Il modulo non risponde su I²C» sopra. Controllare direttamente con i2cdetect -y 1. Se lo trova, è un problema del rilevamento automatico del backend; aprire una segnalazione con l'output di rbamp --verbose scan.

  • rbamp fallisce con PermissionError: /dev/i2c-1 — l'utente non è nel gruppo i2c. Vedi la sezione Installation del README per sudo usermod -aG i2c $USER + nuovo accesso.

  • rbamp: command not found dopo pip install — la voce di console [project.scripts] non è attiva. Verificare che pip show rbamp mostri il percorso installato; assicurarsi che $HOME/.local/bin sia in $PATH (per pip install --user).


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/10_troubleshooting.md (v1.6.1)