10 · Risoluzione dei problemi
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:
-
A livello di bus — il modulo non risponde su I²C; le letture sollevano
RbAmpIOError. -
A livello di dati — il modulo risponde, ma i numeri sono sbagliati: zeri, valori anomali, segno errato.
-
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:
i2cdetect -y 1 # bus 1 — the standard one on the RPi 40-pin header
Oppure in 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
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_bcmsul 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:
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:
- Abbassi la velocità del bus a 50 kHz:
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
- Aumenti il numero di tentativi per un carico pesante — serve l'API avanzata con la creazione esplicita del backend:
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
- Monitori il contatore di esaurimento dei tentativi — in regime stazionario deve restare a zero:
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_baudratein/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:
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
- Verificare che la classe del sensore e il modello CT siano configurati:
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.
- 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».
- 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, madev.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| > 10000float (chiaramente non un valore fisico) è arrivato dal bus.
Li distingua tramite i contatori diagnostici (disponibili su MicroPython):
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
-
Verifichi la cadenza: 60 s tra le istantanee sono comodi; 30 s sono al limite; < 10 s garantiscono letture non aggiornate.
-
Verificare la reattività del modulo tra gli snapshot:
if dev.probe():
print("alive")
- Controllare direttamente il flag:
if dev.is_period_valid():
# avg_p[] can be read
...
- 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
-
Taratura del sensore di corrente: assicurarsi che
dev.set_sensor_class()edev.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. -
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). -
Deriva dell'orologio del master:
time.monotonic()(CPython) etime.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.
⚠ 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):
# 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):
-
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".
-
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.
-
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.
# 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):
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:
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:
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-certificatesdi 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:
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:
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 conRbAmpModeError. In un contesto di assistenza usidev.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:
-
Codice modello non valido — per la classe
SCT_013l'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 sollevanoRbAmpParamError(ValueError). -
Indice di canale non valido nella forma per canale
dev.set_ct_model_ch(channel, code)— deve essere <dev.channels. -
Un valore di classe del sensore fuori da 0..3. (
WIRED_CT/BUILTIN_CTsono valori validi, ma un modulo accoppiato in fabbrica rifiuta di essere riconfigurato — questo sollevaRbAmpModeError, 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):
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):
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()
⚠ 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:
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")
⚠ 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.
✅ 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_msoppure 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
VCCcon 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:
-
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. -
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.
-
dev.is_stdèFalsesu 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. Usismbus2su 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) oppurepython -c "import rbamp; print(rbamp.__version__)". -
Versione del firmware del modulo —
dev.firmware_versiondai 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 scannon trova nulla — come nel Passo 1 della sezione «Il modulo non risponde su I²C» sopra. Controllare direttamente coni2cdetect -y 1. Se lo trova, è un problema del rilevamento automatico del backend; aprire una segnalazione con l'output dirbamp --verbose scan. -
rbampfallisce conPermissionError: /dev/i2c-1— l'utente non è nel gruppoi2c. Vedi la sezione Installation del README persudo usermod -aG i2c $USER+ nuovo accesso. -
rbamp: command not founddopopip install— la voce di console[project.scripts]non è attiva. Verificare chepip show rbampmostri il percorso installato; assicurarsi che$HOME/.local/binsia in$PATH(perpip install --user).
Collegamenti
- 05 · Avvio rapido — il suo primo script funzionante
-
09 · Riferimento API — l'API completa + avvertenze sui metodi pubblici con AVVERTENZA
-
03 · Selezione del sensore di corrente — la tabella dei modelli SCT-013, la topologia dual-CT per un ampio intervallo dinamico, gli approcci per aumentare la sensibilità a correnti basse
Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/10_troubleshooting.md (v1.6.1)