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

10 · Solución de problemas

Árbol de decisión para la solución de problemas: del síntoma a una comprobación rápida y una acción.

Este capítulo se organiza por los síntomas que observa, no por una clasificación interna de errores. Si ha llegado aquí, algo no funciona como debería. 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. A nivel de bus: el módulo no responde por I²C; las lecturas devuelven NaN o RB_ERR_NACK.

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

  3. A nivel de aplicación: el enlace es inestable, el contador de Wh diverge, el boceto se bloquea.

Atajo para los impacientes: los contadores dev.retryExhaustionCount() y dev.sanityRejectCount() deben estar en 0 en régimen estacionario. Si no lo están, vaya directamente a la sección «El módulo no responde por I²C» de abajo.

Compruebe primero: U=0 → L/N no conectados o diferencial desconectado; I=0 → conector de CT no insertado del todo (o sin modelo de CT, véase abajo).

El módulo no responde por I²C

Lo que observa: dev.begin() devuelve false con lastError() == RB_ERR_NACK, o las lecturas en ejecución «filtran» RB_ERR_NACK de forma habitual al código del usuario.

Paso 1 — Escaneo del bus

Primero, confirme que el módulo está realmente en el bus:

C++
#include 

void setup() {
    Serial.begin(115200);
    Wire.begin();
    Serial.println(F("Scanning..."));
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        Wire.beginTransmission(addr);
        if (Wire.endTransmission() == 0) {
            Serial.print(F("Found 0x")); Serial.println(addr, HEX);
        }
    }
}
void loop() {}

Salida esperada: Found 0x50 (o una dirección distinta si la cambió).

Si no se encuentra nada, el problema está en el cableado o en la alimentación:

  • SDA / SCL no están intercambiados.
  • Ambas líneas tienen una pull-up a 3.3 V (la placa del módulo tiene resistencias de pull-up integradas de 4.7 kΩ: no se necesitan externas para un módulo único).

  • El pin de alimentación del módulo lleva realmente 5 V (4.5–5.5 V); las revisiones antiguas de placa no toleran 3.3 V.

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

Si el módulo se encuentra, pero en una dirección inesperada: alguien lo reasignó antes en el banco de pruebas. Actualice el argumento del constructor:

C++
RbAmp dev(Wire, 0x52);   // address from the bus scan

Paso 2 — Patrón base de NACK en ESP32

Si el escaneo del bus encuentra el módulo, pero dev.readVoltage() devuelve periódicamente NaN con RB_ERR_NACK — y usa un ESP32 —, se trata de un patrón base documentado: los controladores i2c_master de ESP-IDF v5 presentan particularidades al trabajar con rbAmp en el firmware v1.0.

La mitigación ya está integrada en la biblioteca (RBAMP_NACK_RETRY_ATTEMPTS=3 por defecto en ESP32), pero con mucha carga el presupuesto de reintentos puede agotarse.

Qué hacer en el ESP32:

  1. Baje la velocidad del bus a 50 kHz:
C++
Wire.begin();
Wire.setClock(50000);
  1. Aumente el número de reintentos para una carga pesada:
C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include 
  1. Vigile el contador de agotamiento de reintentos: en régimen estacionario debe permanecer a cero:
C++
if (dev.retryExhaustionCount() > 0) {
    Serial.print(F("WARN: retry exhausted: "));
    Serial.println(dev.retryExhaustionCount());
}

Paso 3: NACK en plataformas que no son ESP32

En AVR / STM32duino / ESP8266 / SAMD / RP2040 no hay patrón base de NACK: estas plataformas muestran una tasa de NACK de ~0 % con rbAmp. La biblioteca usa por defecto RBAMP_NACK_RETRY_ATTEMPTS=1 en ellas.

Si aquí se producen NACK, busque:

  • Capacidad alta del bus: cables largos + muchos dispositivos. Reduzca la velocidad a 100 kHz o acorte el cable.

  • Contención de maestros: la biblioteca no admite una configuración multimaestro.

  • Un SCL flotante entre transacciones: falta una pull-up.

La corriente se lee como cero con una carga en funcionamiento

Lo que observa: dev.readCurrent(0) devuelve 0.000 (o un valor muy pequeño), aunque haya un consumidor real encendido (un hervidor, una lámpara, una plancha). dev.readPowerFactor(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:
C++
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
    Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) {   // or your model: see below
    Serial.println(F("model set failed"));
}

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 sola vez en la primera instalación; la elección se guarda en la flash del módulo.

  1. Compruebe que el modelo de CT corresponde a la carga. Una pinza CT grande (por ejemplo, SCT-013-100, 100 A) en una carga pequeña (una lámpara de 50 W ≈ 0.2 A) produce una señal justo en el nivel de ruido y las lecturas serán cero. Elija la pinza de menor calibre por encima de su mayor corriente 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 sobrecargas punta, considere el patrón de doble TC: una pinza pequeña (por ejemplo, SCT-013-005) en un canal dedicado para el rango bajo, y una grande (SCT-013-030/100) en otro canal para el rango alto; el maestro selecciona el valor mediante un umbral. El patrón se describe en 03 · Selección del sensor de corriente, sección «Topología de doble TC».

  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», readCurrent() dará la magnitud correcta, pero readPower() dará un valor negativo en una carga consumidora. La confirmación: readPowerFactor() mostrará exactamente −1.0 con una carga resistiva (en lugar de +1.0). La solución: reinstale físicamente la pinza (con el circuito desconectado: suéltela, gire la flecha en el sentido correcto y vuelva a encajarla). No invierta el signo en el software.

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 circula corriente de verdad: mídala con un multímetro (pinza de CC / pinza amperimétrica de 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 único conductor, la línea (L); nunca el cable completo.

Las lecturas saltan o vuelven como NaN

Lo que observa: dev.readVoltage() o dev.readCurrent() devuelven periódicamente NaN. dev.lastError() muestra RB_ERR_NACK o RB_ERR_NON_PHYSICAL.

Si lastError() muestra RB_ERR_NACK

Véase la sección «El módulo no responde por I²C» de arriba: es la misma clase de problema, con una diferencia: el enlace funciona parcialmente, pero el presupuesto de reintentos a veces se agota.

Steps:

  1. En ESP32: reduzca la velocidad a 50 kHz y suba RBAMP_NACK_RETRY_ATTEMPTS=5.

  2. En otras plataformas: compruebe la capacidad del bus y las resistencias de pull-up.

  3. Supervise dev.retryExhaustionCount() para vigilar la tendencia.

Si lastError() muestra RB_ERR_NON_PHYSICAL

El filtro de cordura de la biblioteca se activó: llegó un float por el bus que es NaN, o Inf, o |x| > 10000, evidentemente no es un valor físico. La biblioteca descarta ese valor y notifica RB_ERR_NON_PHYSICAL en lugar de filtrar datos basura a la aplicación.

Es un artefacto poco frecuente. El valor en régimen estacionario de dev.sanityRejectCount() es 0. Si no es cero:

  1. Compruebe dev.retryExhaustionCount(). Si ambos contadores son distintos de cero, el enlace es inestable y el filtro de cordura está capturando basura tras los reintentos fallidos. Aumente el presupuesto de reintentos (véase arriba).

  2. Si retryExhaustionCount == 0, pero sanityRejectCount > 0, un artefacto ha pasado la capa de reintentos. Esto ocurre con una carga muy alta del bus. Suba RBAMP_NACK_RETRY_ATTEMPTS=5 y repita la prueba.

C++
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F("  sanity rejects: "));
Serial.println(dev.sanityRejectCount());

El factor de potencia parece extraño

Lo que observa: dev.readPowerFactor(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)
Refrigerador, motor de compresor +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 cuando I = 0

PF se define como P / (U × I). Con corriente cero I=0 la operación no está definida. El valor concreto depende del firmware (puede ser NaN, 0 o un valor de relleno): es normal mientras la corriente sea realmente cero. En cuanto haya corriente, habrá un PF válido.

El FP es exactamente −1.0 con una carga puramente consumidora

La pinza está instalada «al revés»: la flecha no apunta en el sentido de la corriente hacia la carga. Solución: vuelva a instalar la pinza correctamente (gírela físicamente; no invierta el signo por software).

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

  • Causa posible: la pinza CT está en un cable de una fase distinta a la que está conectada la entrada de tensión U del módulo. En un cuadro de distribución con varias fases es fácil pinzar la fase equivocada; un desfase de 120° o 180° entre U e I produce exactamente estos valores de FP. La solución es instalar el módulo de modo que la entrada U y la pinza 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 siempre están stale

Lo que observa: dev.readPeriodSnapshot(snap) devuelve false con lastError() == RB_ERR_STALE. Esto significa que el módulo no terminó de integrar el período anterior cuando llegó la siguiente lectura.

La biblioteca evita la doble contabilización de Wh: ante una lectura obsoleta registra una marca de tiempo del maestro, y la siguiente instantánea válida cubre un período, no dos.

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 sondea 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 marginal; < 10 s garantiza obsolescencias.

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

C++
if (dev.probe()) {
    Serial.println(F("alive"));
}
  1. Comprobación directa del flag: dev.isPeriodValid() hace una lectura de un solo byte sin efectos secundarios.

  2. Compruebe la versión de firmware: dev.firmwareVersion() debería devolver 0x04 (v1.3, producción actual); los firmwares anteriores (0x01 v1.0 / 0x02 v1.1 / 0x03 v1.2) muestran más lecturas obsoletas.

La contabilidad de Wh diverge de una referencia

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

Descarte primero lo trivial

  1. Calibración del sensor de corriente: asegúrese de que setSensorClass() y setCTModel() se llamaron con el modelo de CT correcto (véase 03 · Selección de sensor de corriente). Sin esto, la corriente RMS se calcula con el suelo por defecto y el valor de potencia quedará sesgado de forma sistemática.

  2. Instantáneas obsoletas descartadas: si dev.energy().wh() es sistemáticamente menor que la referencia, podrían faltar intervalos: una instantánea llegó obsoleta, la biblioteca evitó el doble conteo, pero se perdió la medición del intervalo. Compruebe la cadencia (véase arriba).

  3. Deriva del reloj del maestro: millis() por sí solo es fiable. Pero si el maestro entra en sueño profundo sin conservar el RTC, se pierde el intervalo entre la instantánea anterior y la siguiente. Active el RTC en esos escenarios.

Precisión del acumulador por plataforma

Plataforma Tipo de acumulador
ESP32 / ESP8266 / STM32duino / SAMD / RP2040 double de 64 bits
Arduino AVR (Uno, Mega, Nano) float de 32 bits (cadena de herramientas)

La integración en el lado del maestro no añade ningún error propio, más allá de la precisión de potencia activa del módulo.

En instalaciones AVR de larga duración, reinicie periódicamente el acumulador y guarde el total a largo plazo en su propio almacenamiento persistente:

C++
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);

snap.latch_ms difiere del periodo real

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

RB_ERR_STALE en cada lectura: el maestro mantiene automáticamente el ancla

Lo que observa: dev.readPeriodSnapshot(snap) devuelve periódicamente false con lastError() == RB_ERR_STALE. (Véase también la sección «Las instantáneas de periodo siempre están obsoletas» más arriba.)

Gestión canónica de dt: ante una lectura obsoleta, la biblioteca Arduino NO pone a cero su ancla interna _last_latch_ms. La siguiente lectura válida obtiene un master_dt igual al intervalo completo desde la instantánea correcta anterior, es decir, cubre tanto el periodo «perdido» obsoleto como el actual. El firmware conserva el acumulador avg_p a través de una instantánea vacía (persistencia en el lado del firmware): en la siguiente instantánea válida, ese valor ya es la media de todo el intervalo. La integración de Wh sigue siendo exacta: ni doble conteo ni infraconteo.

El código del maestro no necesita ningún tratamiento especial para las lecturas obsoletas: la biblioteca lo hace todo correctamente y de forma automática. Ignore RB_ERR_STALE si es poco frecuente; si es frecuente, diagnostique la cadencia (sección anterior).

El boceto del ESP32 se bloquea tras unos minutos

Lo que observa: el boceto en el ESP32 arranca bien, pero después entra en un bloqueo / bucle de reinicios / timeout del WDT tras 1–30 minutos.

Wire se bloquea en un bus marginal: mitigación en tres capas

Lo que observa concretamente: un sketch en ESP32 (núcleo Arduino-ESP32) consulta bien a rbAmp durante varios minutos y después «se queda colgado» en mitad de una llamada dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Si el WDT de tareas está activo, lo detecta; si no, el sketch simplemente deja de responder. El backtrace decodificado termina en la función i2c_ll_is_bus_busy (el driver IDF i2c_master, archivo i2c_master.c:526, espera de bus ocupado antes del envío).

Lo que ocurre: el Wire de Arduino-ESP32 envuelve el mismo driver IDF i2c_master que los proyectos nativos de ESP-IDF. En un bus marginal (pull-ups débiles, pistas largas, EMI, interferencia de cruce por cero), SDA/SCL pueden «quedarse pegados» brevemente en un estado indefinido. Antes de cada transacción el i2c_master de IDF gira en el bucle i2c_ll_is_bus_busy, esperando a que el bus se libere; este giro NO está acotado por el timeout de I²C de la biblioteca. Si el bus ocupado se mantiene más de lo que dura el giro sin ceder a otras tareas, la tarea IDLE de FreeRTOS no obtiene CPU y todo el sketch se bloquea.

Esto no es un «artefacto exclusivo del depurador». Validado en banco (el mismo arnés de hardware y la 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 externa de 4.7 kΩ en SDA/SCL del DUT 0 bloqueos (prueba de 12 min, 1300 ciclos, 0 reinicios, 0 disparos del WDT)

La correlación es clara: la corrección de la integridad del bus elimina el bloqueo por completo. La lógica de la biblioteca no está implicada: RbAmpFleet::pollAll(), los módulos con MISS individuales y los contadores de reintentos/coherencia se mantuvieron limpios en todas las pruebas, hasta el propio bloqueo.

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 de 4.7 kΩ integradas en los módulos, en paralelo, resultan demasiado fuertes. En ese bus desconecte las integradas en todos los módulos menos uno (o en todos, y entonces dependa solo de las externas). Véase 04 · Cableado, sección «Bus multimódulo: la topología principal».

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

  3. WDT de tarea a nivel de aplicación en la tarea de sondeo: defensa en profundidad. Si por algún motivo las resistencias de pull-up siguen siendo marginales, o surge otra causa de bloqueo, el WDT reinicia el boceto. Prueba de estrés de 12 min en banco: el WDT detectó y recuperó los 12 bloqueos en la configuración sin pull-up externo. Pull-ups del bus correctos: corrección en campo; WDT de aplicación: postura de recuperación.

C++
#include "esp_task_wdt.h"

void setup() {
    // Layer 3 setup — defense-in-depth.
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 8000,            // 8 s with a large margin
        .idle_core_mask = 0,
        .trigger_panic = true,         // on timeout — panic+reboot
    };
    esp_task_wdt_reconfigure(&wdt_cfg);
    esp_task_wdt_add(NULL);            // this task (loop) under WDT

    // ... rest of the initialization ...
}

void loop() {
    fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
    // ... processing ...
    esp_task_wdt_reset();              // "I'm alive" — every cycle
    delay(200);
}

Qué NO hacer: no intente resolver el problema con un parámetro Wire.setTimeout() mayor: no acota la espera previa de bus ocupado, que es otra ruta de código del driver de IDF. La solución es la integridad del bus (capa 1) + un supervisor (capa 3).

Timeout del watchdog en wifi_connect()

Causa: el bucle sin límite while (WiFi.status() != WL_CONNECTED) delay(500) dispara el WDT de tareas tras ~5 s (por defecto).

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

C++
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    if (millis() - t0 > 30000) { ESP.restart(); }
}

El broker MQTT se desconecta cada ~15 s

Causa: PubSubClient usa por defecto keepalive = 15 s, mientras que mqtt.loop() solo se llama en la ruta «lenta» (una vez cada 60 s junto con readPeriodSnapshot()).

Solución: ponga el keepalive a 60 s y llame a mqtt.loop() en cada pasada de loop():

C++
mqtt.setKeepAlive(60);

void loop() {
    if (!mqtt.connected()) mqtt.connect("rbamp-id");
    mqtt.loop();    // every iteration, not once every 60 s
    // ...rest of the logic, slowed down via millis()...
}

Fallo del handshake TLS (integraciones en la nube)

Causa: el heap del ESP32 es insuficiente para el handshake TLS (se necesitan ~30 kB). A menudo se combina con WiFi + MQTT + buffers, dejando menos de 20 kB.

Fix:

  • Reduzca setBufferSize() del cliente MQTT al mínimo.
  • Use WiFi.mode(WIFI_STA) (no WIFI_AP_STA).
  • Desactive BLE: btStop() en setup().

Si ESP.getFreeHeap() muestra < 25 kB antes de client.connect(), el handshake TLS fallará con mucha probabilidad.

setSensorClass() / setCTModel() devuelve RB_ERR_PARAM

Lo que observa: una de las llamadas de configuración devuelve false, lastError() == RB_ERR_PARAM.

Posibles causas:

  1. setCTModel() llamado antes que setSensorClass(). Primero la clase de sensor, después el modelo; véase 03 · Selección del sensor de corriente y 09 · Referencia de API § Configuración del sensor.

  2. Código de modelo no válido: para la clase Sct013 el conjunto válido es {1, 2, 3, 4, 5, 6, 7} (los códigos 5 y 7 son SCT-013-100 y SCT-013-060). Para las demás clases, véase la tabla de conjuntos aceptados por clase en 03 · Selección del sensor de corriente. Los códigos que no corresponden a la clase devuelven RB_ERR_PARAM (guarda del lado de la biblioteca, antes del bus) o DEV_ERR_PARAM (en el firmware, si el YAML se cuela).

  3. Índice de canal no válido en la forma por canal setCTModel(channel, code): debe ser < dev.channels(). Un canal igual o superior a RBAMP_MAX_CHANNELS (7) nunca se expone y también devuelve RB_ERR_PARAM.

  4. El módulo rechazó el código: un código que está en el registro pero que el módulo no acepta es rechazado por el propio módulo; el canal conserva su modelo anterior.

Si la llamada devuelve false con RB_ERR_MODE, el módulo es de una clase con emparejamiento de fábrica (WiredCT / BuiltinCT): se suministró y se calibró junto con su sensor, y los setters no lo reescriben. El reemparejamiento en servicio se hace con setCTModelChForce().

Comportamiento esperado, no es un fallo:

  • Establecer una clase o un modelo que el módulo ya tiene es una operación nula (true, sin escritura en el bus ni ciclo de flash).

  • Configurar un modelo de CT reinicia el módulo en firmware BASIC hasta la 1.4.19 con la clase SCT-013 (unos segundos, de forma bloqueante). Las lecturas no están disponibles durante ese tiempo; la biblioteca vuelve a leer la corrección de clasificación después.

  • Tras cambiar un modelo SCT-013, las lecturas de corriente, potencia y energía siguen automáticamente el nuevo calibre (el factor de potencia y la tensión no se ven afectados). dev.sctRating(ch, r) muestra el estado por canal; si devuelve UnexpectedGain o Unknown, no se aplica corrección (escala 1).

Notas de módulos STD (STANDARD)

La línea STD usa el mismo cableado I²C que BASIC (véase 04 · Cableado); dev.begin() lo detecta y dev.line() le indica cuál tiene. Particularidades de STD:

  • RB_ERR_NOT_IMPLEMENTED desde una llamada std*, readReactivePower() o readApparentPower(): el módulo conectado es BASIC (compruebe dev.line()). A la inversa, las llamadas exclusivas de BASIC (factoryReset(), General-Call, funciones de etiqueta, readCapability(), readCommitSeq()) la devuelven en un módulo STD.

  • Una función indica «no disponible»: la energía de microresolución (RbAmpStdEnergy::fine == false), la corriente de arranque para la energía (RB_ERR_NOT_IMPLEMENTED), los ángulos de fase de tensión (angle_valid == false) y la secuencia de fases (NotAvailable) dependen de la versión de imagen del módulo: necesitan una imagen de al menos 0x0001007B. Léala con dev.stdReadImageVersion(); con una imagen anterior el valor no está disponible, no es incorrecto.

  • El ángulo de tensión / la secuencia de fases siguen «no disponibles» en una imagen reciente: necesitan que todas las entradas de tensión estén energizadas y sean medibles, y un módulo de tres tensiones para la secuencia de fases.

  • Las lecturas de instantánea de periodo llegan vacías (RB_ERR_STALE) tras un reinicio del módulo: es lo esperado, porque el armado de la instantánea reside en la RAM del módulo. La biblioteca vuelve a armar el banco y descarta ese periodo; reinicie su propio ancla dt. Espere al menos 300 ms entre stdLatch() y stdReadLatch().

  • Sin registros de historial: el módulo registra el historial solo mientras su reloj esté ajustado. El reloj se pierde en cada reinicio del módulo: llame a dev.stdSetTime() después de begin() y siempre que stdReadHealth() informe time_valid == false.

  • Un comando devuelve RB_ERR_PARAM: en STD el veredicto de cada comando se lee de vuelta; el módulo rechazó el valor y no cambió.

  • Un guardado devuelve RB_ERR_NOT_READY: el módulo limita la frecuencia con la que escribe su almacén; la biblioteca ya reintenta una vez tras 5 s.

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

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

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

Patrón 1 — captura puntual tras una operación (si el resultado de esta operación concreta importa):

C++
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02);   // IMMEDIATELY, before the next write

Patrón 2 — supervisión duradera de errores (canónico):

C++
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
    uint8_t last_err = dev.readReg(0x02);
    // handle
    dev.writeReg(0x2A, (1 << 3));        // W1C clear bit3
    // or dev.clearError();
}
Seguridad

⚠ REG_ERROR refleja el resultado de la última escritura, no es persistente. La durabilidad la aporta el bit3 de EVENT.

⚠ bit3 es un canal asíncrono, no sirve para validar una escritura síncrona: ante una escritura rechazada, bit3 se activa con retardo respecto al momento en que la transacción I²C devuelve el control. No sondee bit3 justo después de una escritura para comprobar el resultado de esa escritura: para el resultado de su propia escritura use el Patrón 1 (captura única de lastError() justo después de la operación) o el código de retorno del setter. bit3 sirve para la monitorización prolongada de hechos asíncronos (tiempo de ejecución, ruta de comandos), no para validar una operación que acaba de realizar.

lastError() frente a readLastError(): dos canales distintos, no sinónimos

Dos funciones con nombres parecidos, pero con semánticas completamente distintas:

lastError() readLastError(out)
Lo que devuelve Código RB_ERR_* en caché de la biblioteca de la llamada anterior Una sola lectura por cable del registro REG_ERROR (0x02) del dispositivo
¿Una operación I²C? No: solo una lectura de memoria Sí — una sola transacción de lectura
Semántica Resultado de la validación del lado de la biblioteca (guarda del cliente, estado de reintentos, etc.) Resultado de la última escritura en el dispositivo (mnemónico DEV_ERR_*)
Cuándo se actualiza Tras cada método de la biblioteca Tras cada escritura aceptada por el bus en el dispositivo
Valor de ejemplo RB_ERR_PARAM tras una guarda del lado cliente 0xFE (DEV_ERR_PARAM) tras una escritura rechazada en el dispositivo
Ejemplo de discrepancia lastError() == RB_ERR_PARAM (el método establecedor lo bloqueó antes del bus) readLastError() → 0x00 (nada llegó al dispositivo)

Cuándo usar cada uno:

  • lastError(): para la lógica de la aplicación, el análisis de resultados internos de la biblioteca (reintento, alternativa, clasificación de errores), sin sobrecarga de I²C.

  • readLastError(): cuando quiera el código de causa extendido del dispositivo (por ejemplo, DEV_ERR_PARAM (0xFE) frente a DEV_ERR_NOT_READY frente a DEV_ERR_FLASH_PARAMS_BAD (0xFB)) en el Canal B (rechazo en el lado del DUT). Véase la sección «modelo de errores v1.3: dos canales independientes» en 09 · Referencia de la API.

La distinción es especialmente importante al depurar el canal A (guarda del lado cliente): el método establecedor devuelve false + lastError() == RB_ERR_PARAM, pero readLastError() == 0x00, porque la biblioteca lo bloqueó antes de la operación de bus, y REG_ERROR del dispositivo no se tocó.

Advertencia: DEV_ERR_CLONE (0xF9) NO se borra con CMD_CLEAR_ERROR: es un centinela anticlonación (solo lo borra un reinicio o un restablecimiento de fábrica).

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

Lo que observa: un módulo recién flasheado en su primer arranque muestra 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.saveUserConfig(). Tras un GUARDADO correcto → REG_ERROR = 0x00, bit3 a cero.

commitAddressChange() devuelve RB_ERR_TIMEOUT

Lo que observa: prepareAddressChange() se ejecutó correctamente, pero commitAddressChange() devuelve false, lastError() == RB_ERR_TIMEOUT.

Causa: expiró la ventana de estado armado (5 s tras prepareAddressChange). Las operaciones de WiFi/MQTT o cualquier E/S bloqueante entre prepare y commit es la principal causa de que la ventana expire. dev.probe() no ayuda aquí (el módulo responde; el problema está en la máquina de estados).

Qué hacer: llame de nuevo a prepareAddressChange() de inmediato y, en la misma iteración de loop(), sin llamadas de red en medio, llame a commitAddressChange().

Nota

✅ REG_I2C_ADDRESS (0x30) ahora lee la dirección ACTIVA al arrancar (v1.3). Tras un reinicio posterior al commit, leer 0x30 mostrará la nueva dirección activa. Para la verificación más fiable de un commit de dirección en dos fases, pruebe una lectura en la nueva dirección (debe recibir ACK en el bus). Tras una escritura del host (preparación), el registro refleja el candidato preparado hasta CMD_COMMIT_ADDR + reinicio: es un comportamiento por diseño.

Para más sobre el commit de dirección en dos fases, véanse 09 · Referencia de API y 04 · Cableado.

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

Lo que observa: dev.readVoltage() / dev.readCurrent() devuelven periódicamente NAN, lastError() == RB_ERR_NACK o RB_ERR_IO, pero solo durante la conmutación activa de un relé o una carga inductiva en la misma instalación. Las lecturas en régimen estacionario son fiables.

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

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

C++
float robust_read_voltage(RbAmp& dev) {
    for (int attempt = 0; attempt < 5; attempt++) {
        float v = dev.readVoltage();
        if (!isnan(v)) return v;
        delay(20);   // a short pause before the retry
    }
    return NAN;
}
Seguridad

⚠ La recuperación del bus en el lado de la biblioteca no basta por sí sola: cuando un parásito de EMI se solapa con la ventana de reintento del driver, hace falta un reintento explícito a nivel de aplicación con una pausa.

Alternativa: si el maestro ve los eventos de conmutación de relés, retrase las lecturas unos 50-100 ms tras la conmutación.

Tabla resumen de códigos de error

dev.lastError() devuelve uno de estos códigos tras cada llamada pública a la API. RbAmp::errorString(code) devuelve una cadena legible.

Código Cadena Cuándo Dónde buscar
RB_OK (0) "OK" éxito —
RB_ERR_IO (-1) "Fallo de transporte I2C" el driver del bus devolvió un resultado distinto de OK cableado, alimentación, resistencias de pull-up
RB_ERR_NACK (-2) "NACK — dispositivo ausente u ocupado" reintentos agotados Sección «El módulo no responde por I²C»
RB_ERR_TIMEOUT (-3) "Bus timeout" expiró la ventana de waitReady / waitDataReady / commitAddressChange Sección «commitAddressChange() devuelve RB_ERR_TIMEOUT»
RB_ERR_NOT_READY (-4) «Dispositivo no listo» el módulo no está listo / no hay ningún registro de historial así / no hay nada armado / nada responde en la nueva dirección las notas STD de arriba
RB_ERR_STALE (-5) "Instantánea de periodo obsoleta" el indicador de período listo = 0 Sección «Los instantáneas de período siempre están obsoletas»
RB_ERR_PARAM (-6) «Parámetro incorrecto» índice de canal no válido / código de modelo no válido / rango de dirección no válido Sección «setSensorClass() / setCTModel() devuelve RB_ERR_PARAM»
RB_ERR_MODE (-7) «No permitido en el modo actual del módulo (se requiere modo fábrica / ruta de servicio)» una operación exclusiva de fábrica, o un setter de CT en un módulo de clase WiredCT / BuiltinCT no llame a operaciones solo de fábrica en firmware de producción; use setCTModelChForce() solo para el reemparejamiento de servicio
RB_ERR_CHECKSUM (-8) "Comprobación de valores fallida: suma de verificación / firma / rango" la comprobación de valores del módulo falló (STD: imagen de firmware rechazada, CRC de la carga útil, época fuera de rango, anillo de historial vacío) vuelva a enviar la página / compruebe la imagen
RB_ERR_VERSION (-9) «Versión de firmware no compatible» REG_VERSION = 0 / 0xFF compruebe la conexión del módulo
RB_ERR_NOT_IMPLEMENTED (-10) "No implementado en este firmware" la llamada no tiene equivalente en la línea detectada, o la imagen del módulo no ofrece la función dev.line(), dev.stdReadImageVersion()
RB_ERR_NON_PHYSICAL (-11) "Valor no físico (NaN/Inf/fuera de límites)" el filtro de coherencia rechazó un float Sección «Las lecturas saltan o devuelven NaN»

Tabla resumen de contadores de diagnóstico

En una prueba de estrés sana (12 h, boceto SoakMonitor) todos se mantienen en cero:

Contador En régimen estacionario Reinicio
dev.retryExhaustionCount() 0 dev.resetCounters()
dev.sanityRejectCount() 0 dev.resetCounters()
dev.lastError() tras una lectura RB_OK (0) automáticamente en la siguiente llamada
fracción de datos obsoletos en las instantáneas de periodo < 1 % (acumulado — sin reinicio)

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

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

Para depuración profunda, cuando la biblioteca ya no puede indicarle lo que sucede en el cable, capture SDA + SCL con un analizador lógico (Saleae, DSLogic Plus, o 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 en cada byte
  • la fase de dirección.
  • Compare las llamadas de su boceto (dev.readVoltage(), etc.) con la secuencia de bytes esperada: deben coincidir exactamente. Las lecturas en ráfaga (varios bytes en una sola transacción mediante autoincremento de dirección) están admitidas. Las escrituras NO son de autoincremento: cada byte es una transacción separada.

Si el comportamiento de la biblioteca diverge de 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 de arriba y el problema persiste, abra una incidencia:

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

En la incidencia, incluya:

  • MCU host y versión del núcleo Arduino (por ejemplo, ESP32-S3 con Arduino-ESP32 3.0.4).

  • Versión de la biblioteca (RbAmp desde el Gestor de bibliotecas).

  • Versión de firmware del módulo: dev.firmwareVersion().
  • Boceto mínimo que reproduce el problema (~30 líneas de código).
  • dev.lastError() + dev.errorString(dev.lastError()) + dev.retryExhaustionCount() + dev.sanityRejectCount() en el momento del fallo.

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


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