rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub [Edit on GitHub]

10 · Solución de problemas

Árbol de decisión para resolver problemas: síntoma → comprobación rápida → acción

Este capítulo está organizado por el síntoma que observa, no por una clasificación interna de errores. Si ha llegado aquí, algo no funciona bien. Busque su síntoma en la lista siguiente, vaya a la sección correspondiente y siga el procedimiento de diagnóstico.

La mayoría de los problemas en el banco caen en tres categorías:

  1. Nivel de bus: el módulo no responde por I²C; las lecturas lanzan RbAmpIOError.

  2. Nivel de datos: el módulo responde, pero los números son incorrectos: ceros, valores extraños, signo equivocado.

  3. Nivel de aplicación: el enlace es inestable, el contador de Wh deriva, el script se cuelga o muere por timeout.

Atajo para los impacientes: en régimen estable, los métodos públicos deben devolver valores o producir instantáneas sin lanzar excepciones. Si ve con frecuencia RbAmpIOError o RbAmpStaleError en los registros, vaya directamente a «El módulo no responde por I²C» más abajo.

El módulo no responde por I²C

Lo que ve: dev.begin() (o entrar en el gestor de contexto with RbAmp(bus, 0x50) as dev:) lanza RbAmpIOError o RbAmpVersionError, o las lecturas RT lanzan RbAmpIOError con regularidad.

Paso 1 — Escaneo del bus

Compruebe primero que el módulo está realmente presente en el bus.

CPython (SBC Linux)

Herramienta externa:

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

O en 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

Salida esperada: Found 0x50 (u otra dirección, si la cambió).

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()])

Salida esperada: Found: ['0x50'] (o su dirección).

Qué hacer si no se encuentra nada

El problema está en el cableado o en la alimentación:

  • SDA / SCL no están intercambiados (véase 04 · Cableado para los valores por defecto de GPIO de cada host).

  • Ambas líneas tienen una pull-up a 3.3 V (la placa del módulo lleva resistencias integradas de 4.7 kΩ; no se necesitan externas para un solo módulo).

  • El pin de alimentación del módulo mide realmente 5 V (4.5–5.5 V).

  • Ningún otro maestro (sonda de depuración, segundo controlador) está colgado en las mismas líneas.

  • En MicroPython, compruebe que freq=50_000 (no 100k ni 400k: en ESP32 + firmware v1 el patrón de NACK de base consumirá el presupuesto de reintentos).

  • En CPython, compruebe que el driver I²C del kernel está habilitado: lsmod | grep i2c_bcm en la RPi.

Qué hacer si el módulo aparece en una dirección inesperada

Alguien le cambió la dirección antes en el banco de pruebas. Actualice el segundo argumento de RbAmp:

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

Paso 2: patrón base de NACK de MicroPython + ESP32

Si el escaneo del bus encuentra el módulo pero dev.read_voltage() lanza RbAmpIOError con frecuencia, y usted está en MicroPython + ESP32, se trata de un patrón base documentado: la pila I²C del puerto ESP32 de MicroPython hereda particularidades del driver ESP-IDF v5, que con el firmware actual de rbAmp provoca NACK frecuentes a 100 kHz.

La mitigación ya está integrada en MachineI2CBackend (3 reintentos × hueco de 5 ms por defecto), pero con mucha carga el presupuesto de reintentos puede agotarse.

Qué hacer en el ESP32:

  1. Baje la velocidad del bus a 50 kHz:
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Aumente el número de reintentos para una carga de trabajo pesada: esto requiere la API avanzada con creación explícita 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. Vigile el contador de agotamiento de reintentos: en régimen estacionario debe permanecer a cero:
Python
if backend.retry_exhaustion_count > 0:
    print("WARN: retry exhausted:", backend.retry_exhaustion_count)

Paso 3 — Plataformas no ESP32 (RP2040 / STM32 / CPython)

En RP2040 / STM32 / Pyboard (mediante MicroPython) no hay un patrón de NACK de base: estas plataformas muestran una tasa de NACK de ~0 % con rbAmp. MachineI2CBackend detecta el puerto automáticamente y reduce el reintento por defecto a 1 intento.

En CPython (mediante smbus2) no hay capa de reintento: el driver I²C del kernel de Linux no está sujeto al patrón de NACK; un único OSError de smbus2 se traduce a RbAmpIOError sin reintentar.

Si se producen NACK en estas plataformas, busque:

  • Capacitancia alta del bus: cables largos y muchos dispositivos. Reduzca la velocidad o acorte el cable.

  • Contención de maestro: el paquete no admite multimaestro.

  • Un SCL flotante entre transacciones: falta una pull-up.
  • En la RPi: compruebe dtparam=i2c_arm_baudrate en /boot/config.txt; se recomienda 100000.

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

Lo que ve: SMBus(1) lanza PermissionError, mientras que sudo python funciona. Su usuario no tiene permiso para abrir el dispositivo I²C. Solución:

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

Asegúrese también de que I²C está habilitado (sudo raspi-config → Interface Options → I2C) y de que ls /dev/i2c-* lista el bus; sudo apt install i2c-tools le da i2cdetect -y 1.

La corriente lee cero con una carga encendida

Lo que ve: dev.current[0] (o dev.read_current(0)) devuelve 0.000 (o un valor muy pequeño) aunque un consumidor real esté encendido (un hervidor, una lámpara, una plancha). dev.power_factor[0] puede mostrar un valor extraño (nan / 0 / ±1): es una consecuencia; la causa está en la corriente.

Procedimiento de diagnóstico

  1. Compruebe que están configurados la clase de sensor y el modelo de CT:
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})")

Sin estas dos llamadas no se cargan los coeficientes de calibración y la corriente siempre se lee como cero. Este paso se hace una vez en la primera instalación; la elección se guarda en la flash del módulo.

  1. Compruebe que el modelo de pinza coincide con la carga. Una pinza grande (por ejemplo, SCT-013-100, 100 A) en una carga pequeña (una lámpara de 50 W = ~0.2 A) producirá una señal en el límite del ruido de fondo y las lecturas serán cero. Elija el modelo de pinza más pequeño que cubra su corriente máxima prevista. La tabla completa está en 03 · Selección del sensor de corriente.

Si tiene un módulo multicanal (UI2 / UI3 / UI5 / UI7) y quiere ver tanto cargas pequeñas como picos grandes, considere el patrón de doble CT: una pinza pequeña (SCT-013-005) en un canal para el rango bajo y una grande (SCT-013-030/100) en otro canal para el rango alto; el maestro elige el valor según un umbral. El patrón se trata en 03 · Selección de sensor de corriente, sección «Topología de doble CT».

  1. Compruebe la orientación de la pinza. La flecha del cuerpo de la pinza debe apuntar en el sentido de la corriente hacia la carga. Si la pinza está "al revés", dev.read_current() dará el valor correcto en valor absoluto, pero dev.read_power() dará un valor negativo en una carga consumidora. Confirmación: dev.read_power_factor() mostrará exactamente −1.0 en una carga resistiva (en lugar de +1.0). Solución: o bien recoloque físicamente la pinza (sáquela, gire la flecha en el sentido correcto y vuelva a encajarla), o bien invierta el signo en la aplicación (p = -p; pf = -pf; si sabe que la carga no es un inversor fotovoltaico).

Si los tres pasos superan la prueba y la corriente sigue siendo cero

Entonces la señal en la entrada del módulo está realmente por debajo del suelo de ruido. Compruebe:

  • Si la corriente circula de verdad: mídala con un multímetro (pinza de corriente CC/CA) en el mismo cable.

  • Si la pinza está íntegra: debe haber una tensión alterna en el conector de la pinza proporcional a la corriente (unos pocos milivoltios para cargas domésticas).

  • Si está pinzando el cable correcto: un solo conductor, el vivo (L), no todo el cable (pinzar L y N da ~0).

Las lecturas saltan o se produce un RbAmpIOError

Lo que ve: dev.voltage / dev.read_current(...) lanza RbAmpIOError de forma periódica. El valor de la propiedad no se obtuvo: necesita un reintento en la aplicación o una guarda try/except.

RbAmpIOError del paquete cubre dos clases de problema:

  • NACK tras agotar los reintentos — el enlace es inestable.
  • El filtro de validez rechazó el valor: un NaN / Inf / |x| > 10000 en coma flotante (claramente no es un valor físico) llegó desde el bus.

Distíngalos mediante los contadores de diagnóstico (disponibles en 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)
Contador Qué significa
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 El bus está sano; el paquete recupera en silencio los NACK poco frecuentes. Normal.
retry_count_total ↑, retry_exhaustion_count ↑ Meseta de NACK: aumente retry_attempts (véase el Paso 2 anterior).
retry_count_total bajo, sanity_reject_count ↑ El filtro de validez está captando basura tras agotar los reintentos. Suba retry_attempts=5+.

En CPython (SMBusBackend) no hay capa de reintentos: RbAmpIOError se lanza ya en el primer fallo. Los síntomas son raros (el kernel de Linux suele ser fiable), pero si aparecen, revise el cableado, las pull-ups y la velocidad del bus.

El factor de potencia parece raro

Qué ve: dev.power_factor[0] (o dev.read_power_factor(0)) devuelve un valor que no coincide con el tipo de carga.

Expectativas por carga:

Carga FP esperado
Hervidor, plancha, lámpara incandescente +0.95 .. +1.0 (resistivo)
Frigorífico, compresor de motor +0.6 .. +0.85 (inductivo)
Lámpara LED, televisor (fuente conmutada) +0.5 .. +0.95 (no lineal)
Inversor fotovoltaico que exporta potencia PF negativo

PF = nan o 0 con I = 0

El PF se define como P / (U × I). Con corriente cero (I=0) la operación no está definida. El valor exacto devuelto depende del firmware (puede ser nan, 0 o un marcador): es normal mientras la corriente sea realmente cero. Cuando aparezca corriente, aparecerá un PF válido.

PF exactamente −1.0 con una carga puramente consumidora

La pinza está montada "al revés": la flecha no apunta en el sentido de la corriente hacia la carga. Solución: o bien reinstale la pinza correctamente, o bien gestione el signo en la aplicación (p = -p; pf = -pf; si sabe que la carga no puede ser un inversor fotovoltaico).

El PF oscila entre +0.3 y +0.7 con una carga resistiva

  • Causa posible: la pinza CT está en un cable de una fase distinta de la que está conectada la entrada U del módulo. En un cuadro de distribución polifásico es fácil pinzar la fase equivocada por error: un desfase de 120° o 180° entre U e I dará exactamente estos valores de PF. La solución es instalar el módulo de modo que la entrada U y el CT estén en la misma fase.

  • Alternativa: la carga realmente no es puramente resistiva. Repita la prueba con una carga resistiva conocida (un hervidor eléctrico a plena potencia).

Las instantáneas de periodo dan siempre RbAmpStaleError

Qué ve: dev.read_period_snapshot() lanza RbAmpStaleError en cada llamada. Esto significa que el módulo no terminó de integrar el periodo anterior cuando llegó la siguiente lectura.

Ante una lectura obsoleta, el paquete conserva la marca de tiempo anterior, así que la siguiente instantánea correcta cubre todo el intervalo desde la última buena y el total de Wh sigue siendo exacto (sin doble conteo ni pérdida).

Aceptable: lecturas obsoletas esporádicas (1–2 por hora con una cadencia de 60 s). No aceptable: lecturas obsoletas consecutivas: significa que el firmware no responde o que el maestro consulta con demasiada frecuencia.

Procedimiento de comprobación de la cadencia

  1. Compruebe la cadencia: 60 s entre instantáneas es cómodo; 30 s es justo; < 10 s garantiza lecturas obsoletas.

  2. Compruebe la capacidad de respuesta del módulo entre instantáneas:

Python
if dev.probe():
    print("alive")
  1. Compruebe el indicador directamente:
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. Compruebe la versión del firmware: dev.firmware_version >= 0x04 (v1.3) tiene el menor número de lecturas obsoletas; 0x02/0x03 (v1.1/v1.2) siguen siendo compatibles, pero la tasa de lecturas obsoletas aumenta; 0x01 (v1.0) es la más ruidosa.

Caso especial — despertar de sueño profundo en MicroPython

Si usa un patrón de deep sleep en MicroPython, el valor por defecto de dev.read_period_snapshot() tras la entrada del gestor de contexto siempre dará un resultado obsoleto (o casi cero): __enter__ toma una instantánea (comando LATCH) que cebar, lo que reinicia el acumulador del firmware. El patrón canónico usa skip_latch=True + una duración de sueño conocida (el argumento de machine.deepsleep(SLEEP_MS)): véase 06 · Ejemplos, Escenario 9.

La contabilidad de Wh se desvía de la referencia

Lo que ve: dev.energy.wh(0) tras varias horas o días de funcionamiento se aleja de la lectura del contador de la compañía o de un contador de referencia (Kill-A-Watt o similar).

Descarte primero lo trivial

  1. Calibración de la pinza de corriente: asegúrese de llamar a dev.set_sensor_class() y dev.set_ct_model() con el modelo de CT correcto (véase 03 · Selección de sensor de corriente). Sin esto, la corriente eficaz se calcula con el suelo por defecto y el valor de potencia quedará sistemáticamente sesgado.

  2. Instantáneas obsoletas descartadas: si dev.energy.wh(0) queda sistemáticamente por debajo de la referencia, puede haber intervalos perdidos. Una sola instantánea obsoleta no pierde energía (la siguiente buena cubre el intervalo completo), pero los fallos repetidos o un script que no estaba en marcha sí. Compruebe la cadencia (véase arriba).

  3. Deriva del reloj del maestro: time.monotonic() (CPython) y time.ticks_ms() (MicroPython) son fiables en funcionamiento normal. Pero si el maestro entra en sueño profundo, use el patrón de memoria RTC + duración conocida del sueño del Escenario 9.

Seguridad

⚠ Desbordamiento de ticks_ms() en MicroPython. time.ticks_ms() da la vuelta en 2**30 ms (~12.4 días): una resta ingenua t1 - t0 a través del límite de 12.4 días da un número negativo o enorme. Internamente el paquete usa time.ticks_diff(t1, t0), que es seguro frente al desbordamiento. Si calcula usted master_dt_ms en su código (fuera del paquete), use ticks_diff, no la resta directa.

Precisión del acumulador

El acumulador de Wh dentro del handle:

Ejecución Tipo
CPython float de 64 bits (float de Python)
MicroPython (compilación de doble precisión) float de 64 bits
MicroPython en puertos sin doble precisión float de 32 bits

Comprobación de precisión en MicroPython (sys.float_info existe solo en CPython; en uPy usamos una comprobación empírica):

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

Para las versiones de MicroPython de coma flotante simple en instalaciones de funcionamiento prolongado, reinicie periódicamente dev.energy.reset(0) y guarde el total a largo plazo en su propio almacenamiento persistente (por ejemplo, mediante un mensaje MQTT con retain en HA).

El script se cuelga o muere por timeout

Qué ve: el script de Python arranca con normalidad y, al cabo de unos minutos, se cuelga o produce un RuntimeError.

MicroPython en ESP32: una operación I²C se cuelga en un bus marginal — mitigación en tres capas

Qué ve exactamente: un script en ESP32 (machine.I2C de MicroPython) sondea rbAmp sin problemas durante varios minutos, y luego se queda "muerto" en mitad de una llamada a dev.read_period_snapshot() / fleet.poll_all(). El WDT (si tiene uno activado) detecta el bloqueo; si no, el script simplemente deja de responder. Si tiene un REPL, también se cuelga.

Qué ocurre: machine.I2C de MicroPython en ESP32 envuelve el mismo driver i2c_master de IDF que usan los proyectos nativos de ESP-IDF. En un bus marginal (pull-ups débiles, pistas largas, EMI, ruido de cruce por cero), SDA/SCL pueden "quedarse pegados" momentáneamente en un estado indefinido. Antes de la siguiente transacción, IDF i2c_master gira en un bucle i2c_ll_is_bus_busy esperando a que el bus se libere; este giro no está acotado por el timeout I²C de la biblioteca.

Esto no es un "artefacto solo del depurador". Validado en el banco (entre bibliotecas, mismo arnés de hardware y misma carga):

Configuración del bus Tasa de bloqueos
2 pull-ups débiles del módulo + NRST del depurador conectado ~1 bloqueo / 2.1 min
1 pull-up débil del módulo, sin depurador ~1 bloqueo / 3.3 min (≈ 12 bloqueos por hora)
+ pull-up externo de 4.7 kΩ en SDA/SCL del DUT 0 cuelgues (prueba de resistencia de 12 min, 0 reinicios)

La correlación es clara: una corrección de integridad del bus elimina el bloqueo por completo. El fallo no está en la lógica de la biblioteca.

Mitigación en tres capas (aplique las tres):

  1. Pull-up externa (~4.7 kΩ) en SDA y SCL a 3.3 V en un único punto del bus. Las pull-ups internas del ESP32 (~45 kΩ) son débiles para un bus multimódulo de longitud real, mientras que las pull-ups de 4.7 kΩ integradas en los módulos, en paralelo, resultan demasiado fuertes. En ese bus corte las integradas en todos los módulos menos uno. Véase 04 · Cableado, sección "Bus multimódulo: la topología principal".

  2. No ejecute una compilación de producción con el NRST del depurador conectado. En una sesión de depuración, la línea de reinicio puede dejar SDA/SCL en un estado indefinido al desconectar/conectar, provocando un bloqueo del bus en la siguiente transacción.

  3. Un WDT de tarea a nivel de aplicación sobre la tarea de sondeo — defensa en profundidad. Las pull-ups de bus bien dimensionadas son la solución de campo; el WDT de tarea es una postura de recuperación.

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)

Qué NO hacer: no intente evitar el problema con un parámetro I2C(..., timeout=ms) mayor: no acota el giro previo de bus ocupado, que es otra ruta de código en el driver de IDF. Lo que hay que arreglar es la integridad del bus (capa 1) y el supervisor (capa 3).

CPython en SBC Linux: el I²C del kernel no sufre este problema

Los drivers del kernel de Linux (i2c-bcm2835 en la Raspberry Pi, i2c-i801 en x86, etc.) hacen su sondeo de bus ocupado con un timeout: ante un bus bloqueado devuelven IOError(Errno 110: ETIMEDOUT) o EREMOTEIO en lugar de colgarse. La biblioteca lo envuelve en RbAmpIOError. Por tanto, la mitigación en tres capas no hace falta en CPython: Linux se encarga por sí mismo. Una pull-up externa de ~4.7 kΩ sigue siendo deseable para la integridad de la señal en un bus largo.

latch_ms no coincide con el periodo de reloj de pared

latch_ms es un temporizador de diagnóstico del módulo; no lo use para la energía: use el reloj del maestro.

La biblioteca integra la energía con el reloj de pared del maestro: CPython — time.monotonic(); MicroPython — time.ticks_ms() + time.ticks_diff(). La integración en el lado del maestro no añade error propio más allá de la precisión de potencia activa del módulo.

Si su código depende de snap.latch_ms para cálculos de subperiodo, cámbielo a su propio time.monotonic() / time.ticks_diff().

RbAmpStaleError en cada lectura — la biblioteca mantiene el ancla automáticamente

Lo que ve: dev.read_period_snapshot() lanza RbAmpStaleError de forma periódica.

Tratamiento canónico de dt: ante una lectura obsoleta, la biblioteca Python no pone a cero el ancla interna _last_latch_ms. La siguiente lectura válida obtiene un master_dt_ms igual al intervalo completo desde la instantánea correcta anterior, es decir, cubre tanto el periodo «perdido» como el actual. El firmware conserva el acumulador avg_p ante una instantánea vacía (persistencia en el firmware): en la siguiente instantánea válida ya es un valor promediado sobre todo el intervalo. La integración de Wh sigue siendo exacta: sin doble conteo ni infraconteo.

Patrón para arranque en frío (prime-until-valid, presupuesto de ~25 reintentos correcto):

Python
from rbamp import RbAmpStaleError

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

Tras el cebado, ignore RbAmpStaleError si es esporádico; si es frecuente, diagnostique la cadencia (la sección «Las instantáneas de periodo siempre dan RbAmpStaleError» de arriba).

CPython: signal.SIGTERM / KeyboardInterrupt no se gestionan

Causa: un time.sleep(60) largo bloquea el manejador de señales. En un despliegue de producción (systemd), systemctl stop rbamp espera la respuesta a SIGTERM hasta un timeout (por defecto 90 s) y luego lo mata con SIGKILL; los Wh pueden perderse.

Solución: un bucle sensible a señales:

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)

O use asyncio con un signal_handler; véase la sección siguiente.

MicroPython (ESP32): timeout del watchdog al conectar a WiFi

Causa: un bucle de conexión WiFi sin límite dispara el watchdog de tarea tras ~5 s (el valor por defecto).

Solución: una espera acotada con alternativa de reinicio:

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()

El broker MQTT se desconecta

En CPython (paho-mqtt): el keepalive por defecto es de 60 s, pero mqtt.connect() es bloqueante y mqtt.loop() debe llamarse en un bucle de eventos. Use mqtt.loop_start() (un hilo en segundo plano) o la variante asyncio aiomqtt.

En MicroPython (umqtt.simple): síncrono y sin keepalive: hay que llamar a mqtt.ping() manualmente cada ~30 s. La alternativa es el paquete asíncrono mqtt_as, con keepalive integrado.

Fallo del handshake TLS (nube desde CPython + RPi con poca RAM)

Raramente es un problema en una Pi con 1 GB o más de RAM, pero en una Pi Zero / Zero W (512 MB) un handshake TLS con un almacén de certificados grande puede ser eliminado por el OOM killer.

Fix:

  • Use una CA concreta en lugar del ca-certificates del sistema: ocupa menos memoria.

  • Reduzca los búferes de MQTT.

  • Pase a una Pi 3/4/5 para un despliegue en la nube en producción.

set_sensor_class() / set_ct_model() lanza RbAmpModeError

Qué ve: una de las llamadas de configuración lanza RbAmpModeError con el mensaje:

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

Causa: set_ct_model[_ch] requiere que se llame antes a set_sensor_class(). Es una protección intencionada.

Qué hacer:

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)

Más detalle: 03 · Selección de sensor de corriente y 09 · Referencia de la API, sección «Configuración del sensor».

Desde la 1.6.0 estos métodos set tienen protección de lectura antes de escritura:

  • Ajustar la clase o el modelo que el módulo ya tiene es un no-op silencioso (volver a aplicarlo borraría la calibración de canal).

  • En un módulo emparejado de fábrica (clase WIRED_CT / BUILTIN_CT), una clase o modelo distinto se rechaza con RbAmpModeError. En un contexto de servicio use dev.set_ct_model_ch_force(ch, code).

RbAmpModeError también aparece en dev.factory_reset() y dev.save_gains() (las operaciones de fábrica exigen el modo de fábrica). Un cambio de dirección en v1.3 es válido en producción y no lanza RbAmpModeError.

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

Lo que ve: la llamada lanza RbAmpParamError (en CPython también hereda ValueError mediante herencia múltiple).

Posibles causas:

  1. Código de modelo no válido: para la clase SCT_013 el conjunto aceptado es {1, 2, 3, 4, 5, 6, 7} (los códigos 5 y 7 son SCT-013-100 y SCT-013-060). Para otras clases, véase la tabla de conjuntos aceptados por clase en 03 · Elegir un modelo SCT-013. Los valores fuera del conjunto aceptado lanzan RbAmpParamError(ValueError).

  2. Índice de canal no válido en la forma por canal dev.set_ct_model_ch(channel, code): debe ser < dev.channels.

  3. Un valor de clase de sensor fuera de 0..3. (WIRED_CT / BUILTIN_CT son valores válidos, pero un módulo emparejado de fábrica se niega a reconfigurarse: eso lanza RbAmpModeError, véase abajo.)

Gestión de errores: última escritura de REG_ERROR + EVENT_FLAGS.bit3 duradero (v1.3)

v1.3: REG_ERROR (0x02) es el resultado de la última escritura, no persistente. En cada escritura de registro el firmware pone reg_error = ERR_OK; una escritura posterior no relacionada borra el error anterior.

La señal de error duradera = EVENT_FLAGS (0x2A) bit3: pegajosa (W1C), se activa de inmediato ante cualquier escritura o comando rechazado.

Patrón 1: captura puntual tras la operación (el resultado de exactamente esta operación):

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

Patrón 2: monitorización duradera (canónico para el funcionamiento prolongado):

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()
Seguridad

⚠ INVERSIÓN de la documentación temprana «pegajosa» (v1.3). REG_ERROR es el resultado de la última escritura, no es pegajoso. La durabilidad la proporciona EVENT bit3.

⚠ bit3 es un canal asíncrono, no sirve para validar una escritura síncrona: ante una escritura rechazada, bit3 se activa con retraso respecto al momento en que la transacción I²C devuelve el control (unos cientos de milisegundos). No sondee bit3 justo después de una escritura para comprobar su resultado; para el resultado de su propia escritura use el Patrón 1 (captura puntual con read_last_error(), inmediata) o el RbAmpParamError que lanza el método set. bit3 sirve para la monitorización prolongada de hechos asíncronos (tiempo de funcionamiento, vía de comandos), no para validar una operación recién realizada.

Advertencia: DEV_ERR_CLONE (0xF9) no se borra con CMD_CLEAR_ERROR; es un centinela anticlonado.

Un módulo recién flasheado muestra 0xFB en el primer arranque (NORMAL)

Lo que ve: un módulo recién grabado muestra en el primer arranque REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + bit3 de EVENT.

Causa: la página de parámetros no está inicializada → se cargan los valores de fábrica. Es NORMAL en un módulo virgen, no es fatal.

Solución: configure sensor_class + ct_model + (opcionalmente) la dirección, y después dev.save_user_config(). Tras un SAVE correcto → REG_ERROR = 0x00, bit3 a cero.

Las lecturas fallan al conmutar cargas con relé (transitorios EMI)

Qué ve: dev.voltage / dev.current() lanza periódicamente RbAmpIOError / OSError, pero solo durante la conmutación activa de un relé o una carga inductiva en la misma instalación. Las lecturas en régimen estable son fiables.

Causa (confirmada en hardware C.12): durante la conmutación de relés (una carga de 5 A), la EMI hace fallar ~67 % de las transacciones I²C. El bus se recupera solo, no se produce bloqueo y no se pierde ningún módulo.

Solución — reintento a nivel de aplicación:

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")
Seguridad

⚠ El reintento del backend por sí solo no basta: cuando un fallo de EMI dura más que la ventana de reintentos del backend, hace falta un reintento explícito a nivel de aplicación con una pausa.

commit_address_change() lanza RbAmpIOError tras un reinicio del bus

Qué ve: prepare_address_change() tuvo éxito, pero tras la confirmación + el reinicio el módulo no responde en la nueva dirección.

Nota

✅ v1.3: REG_I2C_ADDRESS (0x30) lee la dirección activa al arrancar. Tras el reinicio posterior a la confirmación, leer 0x30 en la nueva dirección mostrará esa misma dirección: eso confirma que la confirmación se aplicó. Si el módulo no responde en la nueva dirección, pruebe un escaneo del bus con _io_smbus (mostrará en qué dirección está realmente el módulo).

Más sobre el commit en dos fases: véanse 09 · Referencia de la API y 04 · Cableado.

commit_address_change() lanza RbAmpTimeoutError

Si prepare tuvo éxito pero commit lanza RbAmpTimeoutError, la ventana de «armado» expiró (5 segundos después de prepare). dev.probe() no servirá de nada aquí (el módulo responde; el problema está en su máquina de estados). La solución es volver a llamar a dev.prepare_address_change(new_addr) y luego, de inmediato, en la misma función o iteración, sin llamadas de red entre ambas, llamar a dev.commit_address_change(). Cualquier E/S bloqueante entre prepare y commit (WiFi, MQTT, HTTP) es la causa principal de que la ventana expire.

wait_ready() lanza RbAmpTimeoutError

El bit de listo del módulo no se activó dentro de timeout_ms. Causas posibles:

  • El módulo aún no ha terminado su arranque en frío (~250 ms): aumente timeout_ms o repita la llamada.

  • El módulo no responde por I²C: véase la sección "El módulo no responde por I²C" más arriba.

  • La tensión de alimentación bajó de 4.5 V: compruebe VCC con un multímetro.

Más sobre los métodos públicos pero advertidos: véase 09 · Referencia de la API, sección «Configuración del sensor» (la subsección de cambio de dirección está ahí, junto con save_gains y factory_reset).

RbAmpNotSupportedError (llamadas STD)

Lo que ve: una llamada como dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() o dev.set_time() lanza RbAmpNotSupportedError.

Causas y qué hacer:

  1. El módulo es un módulo BASIC. Las llamadas exclusivas de STD no están disponibles en BASIC. Compruebe dev.is_std; en BASIC use los lectores comunes (voltage, current, power, power_factor, frequency) y la API de periodos.

  2. La imagen del módulo es demasiado antigua para esa función. Los contadores de energía en micro-unidades, los ángulos de tensión y la corriente de arranque necesitan una imagen de módulo suficientemente reciente; con una más antigua, la llamada indica «no disponible». Los lectores comunes siguen funcionando.

  3. dev.is_std es False en un módulo STD. La biblioteca detecta la línea mediante una transacción de bus de 16 bits; un objeto de bus o adaptador que no pueda hacerla se trata como BASIC. Use smbus2 en CPython (validado); y véase 04 · Hardware.

El mismo cableado I²C se aplica a ambas líneas de módulos. Tenga en cuenta que las funciones de energía en el dispositivo, ángulo y corriente de arranque están validadas en CPython; la ruta de 16 bits de MicroPython aún no está validada en hardware.

Tabla resumen de excepciones

RbAmpError (subclase de OSError) es la clase base. Un manejador except OSError: existente en la aplicación sigue capturando los errores de rbAmp sin cambios: es la convención estándar de Python para drivers de E/S de hardware.

Excepción Cuándo Dónde buscar
RbAmpIOError NACK tras reintento; rechazo por filtro de validez; fallo a nivel de bus la sección «El módulo no responde por I²C»
RbAmpTimeoutError wait_ready() caducó; la ventana de commit_address_change (5 s) caducó la sección «commit_address_change devuelve RbAmpTimeoutError» más abajo
RbAmpNotReadyError (reservado; la biblioteca no lo lanza, se exporta para compatibilidad futura) si captura este tipo, reprodúzcalo en una incidencia
RbAmpStaleError instantánea de periodo obsoleta la sección "Las instantáneas de periodo siempre dan RbAmpStaleError"
RbAmpParamError (en CPython también ValueError) argumento incorrecto: dev=None, ch fuera de rango, code fuera del conjunto aceptado por la clase (para SCT_013 — {1, 2, 3, 4, 5, 6, 7}), un cls reservado. También una violación de precondición: set_ct_model*() sin un set_sensor_class() previo compruebe los argumentos de la llamada y que se llamó a set_sensor_class()
RbAmpModeError operación solo de fábrica (modo de fábrica no activado; un cambio de dirección en v1.3 es válido en producción); clase de sensor sin definir; un módulo emparejado de fábrica rechaza el cambio de clase/modelo compruebe el indicador de modo; set_sensor_class() primero; set_ct_model_ch_force() para uso de servicio
RbAmpNotSupportedError Llamada exclusiva de STD en un módulo BASIC, o una función de STD que la imagen del módulo no proporciona la sección "RbAmpNotSupportedError" más abajo
RbAmpVersionError REG_VERSION = 0/0xFF en begin() (el módulo no responde o el firmware está dañado). set_ct_model_ch por canal en v1.0/v1.1 puede recibir NACK (el opcode no existe) y lanzar RbAmpIOError, no RbAmpVersionError; la comprobación de versión NO está implementada en el cliente: verifique dev.firmware_version ≥ 0x03 antes de la llamada compruebe dev.firmware_version

Todas las excepciones tienen un mensaje __str__ significativo: el paquete construye cuidadosamente los mensajes de error con contexto.

Tabla resumen de contadores de diagnóstico

En una prueba de resistencia sana (el arnés de resistencia de 1 hora) todos se mantienen en cero:

Contador En régimen estacionario Reinicio Disponibilidad
dev.sanity_reject_count 0 dev.reset_counters() ambos entornos de ejecución
MachineI2CBackend.retry_exhaustion_count 0 backend.reset_counters() Solo MicroPython
MachineI2CBackend.retry_count_total bajo (~5–20 por hora es normal) backend.reset_counters() Solo MicroPython
fracción de datos obsoletos en las instantáneas de periodo < 1 % (acumulado — sin reinicio) ambos entornos de ejecución

Si alguno de estos valores es distinto de cero en régimen estable, vuelva a la sección correspondiente de arriba.

Depuración a nivel de bus con analizador lógico

Para depurar a fondo, cuando el paquete ya no puede decirle qué ocurre en el cable, capture SDA + SCL con un analizador lógico (Saleae, DSLogic Plus, cualquiera compatible con Sigrok):

  • Frecuencia de muestreo ≥ 1 MS/s a 100 kHz de I²C; ≥ 4 MS/s a 400 kHz.
  • El decodificador I²C de Sigrok / Saleae mostrará ACK / NACK para cada byte y la fase de dirección.

  • Compare las llamadas de su script (dev.voltage, etc.) con la secuencia de bytes esperada: deben coincidir exactamente. Las lecturas admiten ráfaga (autoincremento). Las escrituras NO autoincrementan (un byte cada vez en registros de varios bytes).

Si el comportamiento del paquete no coincide con la captura, abra una incidencia adjuntando el archivo de captura (.sal / .dsl / .csv).

Cuándo contactar con soporte

Si ha seguido la sección correspondiente anterior y el problema persiste, abra una incidencia:

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

En la incidencia incluya:

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

  • Plataforma del host: «RPi 4B Bookworm», «ESP32-S3 N16R8 MicroPython 1.22», etc.

  • Versión del paquete: rbamp --version (CPython) o python -c "import rbamp; print(rbamp.__version__)".

  • Versión de firmware del módulo: dev.firmware_version de los registros.

  • Un script mínimo (~30 líneas) que reproduzca el problema.
  • La traza de la excepción con contexto completo.
  • Los contadores en el momento del fallo: dev.sanity_reject_count, backend.retry_exhaustion_count (solo uPy).

  • Los registros detallados de la biblioteca: la forma más sencilla de recogerlos es dev.set_logger(print) antes de la operación que falla. El paquete imprimirá sus pasos internos (el bucle de reintentos, los timeouts de asentamiento, el primer cebado de instantánea, etc.); adjunte la salida estándar a la incidencia.

  • (Si está disponible) el archivo de captura del analizador lógico.

CLI: rbamp scan / rbamp read / rbamp address

La CLI rbamp es una capa fina sobre RbAmp.* para las operaciones de banco (véase 09 · Referencia de la API, sección «CLI»). Como usa la misma clase RbAmp, TODOS los síntomas anteriores se aplican. Errores específicos de la CLI:

  • rbamp scan no encuentra nada: lo mismo que en el Paso 1 de la sección «El módulo no responde por I²C» de arriba. Compruebe i2cdetect -y 1 directamente. Si lo encuentra, es un problema de la autodetección de nuestro backend: abra una incidencia con la salida de rbamp --verbose scan.

  • rbamp falla con PermissionError: /dev/i2c-1: el usuario no pertenece al grupo i2c. Véase la sección de instalación del README para sudo usermod -aG i2c $USER y volver a iniciar sesión.

  • rbamp: command not found tras pip install: la entrada de consola [project.scripts] no está activa. Compruebe que pip show rbamp muestra la ubicación instalada; asegúrese de que $HOME/.local/bin está en $PATH (para pip install --user).


Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/10_troubleshooting.md (v1.6.1)