10 · Solución de problemas
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:
-
Nivel de bus: el módulo no responde por I²C; las lecturas lanzan
RbAmpIOError. -
Nivel de datos: el módulo responde, pero los números son incorrectos: ceros, valores extraños, signo equivocado.
-
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:
i2cdetect -y 1 # bus 1 — the standard one on the RPi 40-pin header
O en 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
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_bcmen 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:
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:
- Baje la velocidad del bus a 50 kHz:
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
- Aumente el número de reintentos para una carga de trabajo pesada: esto requiere la API avanzada con creación explícita 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
- Vigile el contador de agotamiento de reintentos: en régimen estacionario debe permanecer a cero:
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_baudrateen/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:
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
- Compruebe que están configurados la clase de sensor y el modelo de CT:
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.
- 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».
- 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, perodev.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| > 10000en coma flotante (claramente no es un valor físico) llegó desde el bus.
Distíngalos mediante los contadores de diagnóstico (disponibles en 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)
| 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
-
Compruebe la cadencia: 60 s entre instantáneas es cómodo; 30 s es justo; < 10 s garantiza lecturas obsoletas.
-
Compruebe la capacidad de respuesta del módulo entre instantáneas:
if dev.probe():
print("alive")
- Compruebe el indicador directamente:
if dev.is_period_valid():
# avg_p[] can be read
...
- 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
-
Calibración de la pinza de corriente: asegúrese de llamar a
dev.set_sensor_class()ydev.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. -
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). -
Deriva del reloj del maestro:
time.monotonic()(CPython) ytime.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.
⚠ 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):
# 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):
-
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".
-
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.
-
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.
# 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):
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:
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:
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-certificatesdel 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:
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:
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 conRbAmpModeError. En un contexto de servicio usedev.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:
-
Código de modelo no válido: para la clase
SCT_013el 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 lanzanRbAmpParamError(ValueError). -
Índice de canal no válido en la forma por canal
dev.set_ct_model_ch(channel, code): debe ser <dev.channels. -
Un valor de clase de sensor fuera de 0..3. (
WIRED_CT/BUILTIN_CTson valores válidos, pero un módulo emparejado de fábrica se niega a reconfigurarse: eso lanzaRbAmpModeError, 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):
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):
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()
⚠ 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:
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")
⚠ 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.
✅ 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_mso 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
VCCcon 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:
-
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. -
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.
-
dev.is_stdesFalseen 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. Usesmbus2en 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) opython -c "import rbamp; print(rbamp.__version__)". -
Versión de firmware del módulo:
dev.firmware_versionde 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 scanno encuentra nada: lo mismo que en el Paso 1 de la sección «El módulo no responde por I²C» de arriba. Compruebei2cdetect -y 1directamente. Si lo encuentra, es un problema de la autodetección de nuestro backend: abra una incidencia con la salida derbamp --verbose scan. -
rbampfalla conPermissionError: /dev/i2c-1: el usuario no pertenece al grupoi2c. Véase la sección de instalación del README parasudo usermod -aG i2c $USERy volver a iniciar sesión. -
rbamp: command not foundtraspip install: la entrada de consola[project.scripts]no está activa. Compruebe quepip show rbampmuestra la ubicación instalada; asegúrese de que$HOME/.local/binestá en$PATH(parapip install --user).
Enlaces
- 05 · Inicio rápido — su primer script funcional
-
09 · Referencia de la API — la API completa y las advertencias sobre los métodos públicos con ADVERTENCIA
-
03 · Selección del sensor de corriente — la tabla de modelos SCT-013, la topología de doble pinza para un rango dinámico amplio, enfoques para aumentar la sensibilidad con corrientes pequeñas
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/10_troubleshooting.md (v1.6.1)