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

10 · Solución de problemas

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 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 devuelven ESP_FAIL o ESP_ERR_INVALID_RESPONSE.

  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 se desvía, el proyecto se cuelga.

Atajo para los impacientes: en régimen estable, las funciones públicas rbamp_* deben devolver ESP_OK. Si ve con frecuencia ESP_FAIL o ESP_ERR_INVALID_RESPONSE en los registros, vaya directamente a la sección «El módulo no responde por I²C» más abajo.

Árbol de decisión de solución de problemas, agrupado por síntoma.

El módulo no responde por I²C

Lo que ve: rbamp_begin(dev) devuelve ESP_FAIL o ESP_ERR_INVALID_RESPONSE, o las lecturas RT propagan con regularidad ESP_FAIL a su código.

Paso 1 — Escaneo del bus

Primero, confirme que el módulo está presente en el bus. ESP-IDF v5.x proporciona i2c_master_probe() precisamente para esto:

C
#include "driver/i2c_master.h"
#include "esp_log.h"

static const char *TAG = "i2c_scan";

void bus_scan(i2c_master_bus_handle_t bus) {
    ESP_LOGI(TAG, "Scanning...");
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
            ESP_LOGI(TAG, "Found 0x%02X", addr);
        }
    }
}

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

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

  • SDA / SCL no se intercambian (vea 04 · Cableado para los valores por defecto de GPIO de cada chip).

  • Ambas líneas tienen un pull-up a 3.3 V (la placa del módulo incorpora 4.7 kΩ: para un único módulo no hacen falta externos).

  • El pin de alimentación del módulo recibe en realidad 5 V (4.5–5.5 V).

  • No hay otro master (sonda de depuración, segundo ESP32) en las mismas líneas.

  • flags.enable_internal_pullup = true en su i2c_master_bus_config_t (si no hay pull-ups externos).

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

C
rbamp_new(bus, 0x52, &dev);   /* address from the bus scan */

Paso 2 — Patrón base de NACK en ESP32

Si el escaneo del bus encuentra el módulo pero rbamp_read_voltage(dev, 0, &v) devuelve periódicamente ESP_FAIL, se trata de un patrón de referencia documentado: el driver i2c_master de ESP-IDF v5 tiene particularidades al trabajar con rbAmp en el firmware actual (NACK frecuentes a 100 kHz).

La mitigación ya está integrada en el componente (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 por defecto, 50 kHz mediante CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), pero con carga alta el presupuesto de reintentos puede agotarse.

Qué hacer en idf.py menuconfig → Component config → rbAmp client:

  1. Confirme el valor por defecto de 50 kHz:
Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
  1. Aumente el número de reintentos para carga intensa:
Text
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
  1. Si hace falta, aumente el tiempo límite:
Text
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
  1. Active el nivel DEBUG para la etiqueta rbamp para el diagnóstico:
Text
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

También puede hacerlo en tiempo de ejecución: esp_log_level_set("rbamp", ESP_LOG_DEBUG).

Nota

Sobre los contadores de reintentos y de coherencia. El componente exporta los getters públicos rbamp_retry_exhaustion_count(dev) y rbamp_sanity_reject_count(dev): coinciden en multiplataforma con dev.retryExhaustionCount() / dev.sanityRejectCount() de Arduino. El patrón canónico de instantánea y diferencia para la supervisión en producción se describe en la sección «Monitorización de los contadores» más abajo.

Flota: un módulo acabó en excluded tras rbamp_fleet_scan

Qué se observa: rbamp_fleet_scan(fleet, ...) se ejecutó y devolvió ESP_OK, pero rbamp_fleet_count(fleet) es menor que el número de módulos que conectó físicamente. rbamp_fleet_excluded_count(fleet)

Nota

0; recorra rbamp_fleet_excluded_addr(fleet, i): cada dirección excluida significa «se detectó un módulo pero NO se añadió a la flota: se sospecha un conflicto».

Causa. El detector de conflictos trabaja con dos señales independientes:

  • coherencia de identidad: HW_VARIANT ↔ mapa de bits de CAPABILITY son incoherentes: señal de que dos módulos físicos distintos responden en una misma dirección (la respuesta se «fusiona» parcialmente).
  • live-value: en una misma dirección se observan lecturas «en vivo» incompatibles; por ejemplo, un LABEL distinto o una variante que oscila.

Si se activa al menos una de las señales, la dirección se excluye de la flota y la biblioteca NO se basa en las lecturas de ese módulo. Si ambas señales están en silencio pero los módulos están configurados de forma idéntica (misma variante, mismo CT_MODEL, misma LABEL), el detector no podrá distinguirlos: es un caso físicamente indetectable (vea más abajo lo relativo a la disciplina).

Seguridad

⚠ La detección es de mejor esfuerzo. Es imposible garantizar que la flota atrape a dos módulos idénticos en una misma dirección: precisamente por eso existe la disciplina de aprovisionamiento (vea la sección siguiente).

Qué hacer.

  1. Desconecte físicamente todos los módulos menos uno.
  2. Conecte el resto uno a uno, llamando a rbamp_fleet_scan de nuevo tras cada uno. El módulo tras cuya conexión aparece un excluded está en conflicto con uno ya conectado.

  3. Reaprovisione el módulo en conflicto a una dirección libre mediante rbamp_provision(bus, new_address, ...) (requiere que sea el único en 0x50: véase la disciplina de aprovisionamiento más abajo).

  4. Tras la reasignación, repita rbamp_fleet_scan: excluded_count debe ser 0.

Flota: rbamp_fleet_scan devolvió ESP_ERR_INVALID_STATE y la flota está vacía

Qué se observa: rbamp_fleet_scan devolvió ESP_ERR_INVALID_STATE, y rbamp_fleet_count(fleet) es 0. No se añadió ningún módulo a la flota, aunque están conectados físicamente.

Causa. Centinela de bloqueo de nivel 2 — la biblioteca realizó una comprobación de bus de «¿hay respuesta en una dirección que no debe responder?» (el centinela). Si el centinela recibió un ACK, el bus no está en estado normal: o bien hay ruido eléctrico que produce ACK espurios, o bien todas las direcciones están «atascadas» por un bloqueo, o bien hay un error de topología (varios módulos con el mismo código a la vez y SDA/SCL retenidos a nivel bajo). En ese estado no se puede confiar en ningún resultado del escaneo, así que la flota queda vacía: es mejor abortar que hacer una inicialización que se sabe incorrecta.

Qué hacer.

  1. Reinicie la alimentación de todo el bus (corte la alimentación de los módulos durante unos segundos y reinicie el ESP32). Esto borra los estados bloqueados.

  2. Conecte los módulos estrictamente uno a uno, ejecutando rbamp_fleet_scan (puesta en marcha de un solo módulo) después de cada uno y comprobando el retorno:

  3. ESP_OK + count=1 + excluded=0 → el bus está limpio, el módulo está bien.

  4. ESP_ERR_INVALID_STATE persiste → revise las resistencias de pull-up (vea la sección i2c-hang anterior: una resistencia externa de 4.7 kΩ en SDA/SCL es obligatoria).

  5. Cuando la puesta en marcha de cada módulo por separado haya pasado, añádalos todos al bus a la vez y ejecute de nuevo rbamp_fleet_scan. Si vuelve a obtener INVALID_STATE, el problema está en la electrónica del bus (longitud, interferencias, un pull-up que falta), no en los módulos individuales.

Flota: rbamp_provision devolvió un error

Lo que ve: la llamada rbamp_provision(bus, desired_address, save_config, &out) no terminó con ESP_OK. Según el código devuelto:

esp_err_t Qué ha pasado Qué hacer
ESP_ERR_NOT_FOUND Nada responde en 0x50 (dirección de fábrica) Confirme que el módulo virgen está conectado físicamente y con alimentación (VCC); compruebe el cableado I²C (vea «El módulo no responde por I²C»).
ESP_ERR_INVALID_STATE Se detectó un conflicto en 0x50 o la dirección deseada ya está ocupada Hay más de un módulo virgen en el bus o la dirección deseada ya la ocupa otro módulo. Desconecte todos los módulos «sobrantes» (véase más abajo).
ESP_ERR_TIMEOUT El comando de confirmación de dirección se ejecutó, pero el módulo no apareció en la nueva dirección dentro de la ventana de arranque Corte la alimentación del módulo y reintente. Si se repite, probablemente sea una operación de flash incompleta (se cortó la alimentación durante CMD_SAVE_USER_CONFIG o CMD_COMMIT_ADDR, así que el bloque de flash puede haber quedado escrito a medias). En el siguiente arranque el módulo devuelve REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), carga los valores de fábrica y reaparece en 0x50. Vuelva a aprovisionar desde cero; si también falla, envíelo a servicio técnico.
ESP_ERR_INVALID_ARG desired_addr está fuera del rango válido 0x08..0x77 Use una dirección válida.
Seguridad

⚠ Disciplina de aprovisionamiento: DEBE haber un único módulo virgen cada vez.

La causa más frecuente de INVALID_STATE durante el aprovisionamiento es que haya más de un módulo en el bus con la dirección de fábrica 0x50. Distinguirlos por I²C es físicamente imposible (colector abierto con AND cableado: ambos módulos responden ACK de forma idéntica, y la lectura de vuelta de los datos sale «fusionada»).

Así que la regla es estricta (un MUST normativo, no una recomendación): en el momento de llamar a rbamp_provision debe haber exactamente un módulo en 0x50 (nuevo, o devuelto a valores de fábrica mediante una herramienta de banco aparte). Nada de «estoy seguro de que estos dos módulos son distintos: los separo ahora»: no funcionará; la colisión aparecerá más tarde, cuando ya crea que la flota está limpia.

Ruta de recuperación ante una sospecha de violación de disciplina: 1. Reinicie la alimentación de todos los módulos. 2. Desconecte físicamente todos menos el módulo «virgen» (el que quiere reasignar). 3. Llame a rbamp_provision en el bus de un solo módulo. 4. Añada el resto de módulos uno a uno, aprovisionando cada uno por separado.

La corriente se lee como cero con una carga en funcionamiento

Lo que ve: rbamp_read_current(dev, 0, &i) devuelve ESP_OK pero i = 0.000 (o un valor muy pequeño), aunque hay un consumidor real encendido (hervidor, lámpara, plancha). rbamp_read_power_factor(dev, 0, &pf) 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 la clase de sensor y el modelo de CT están configurados:
C
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3);   /* or your model */
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}

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.

Nota

Trampa con RBAMP_SENSOR_UNSET. Si llama por error a rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET), la función devuelve ESP_OK, pero en la práctica reinicia la configuración de clase. Una rbamp_set_ct_model*() posterior empezará a devolver ESP_ERR_INVALID_STATE. La solución es volver a llamar a rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) y después a rbamp_set_ct_model().

  1. Compruebe que el modelo de CT corresponde a la carga. Una pinza CT grande (por ejemplo, SCT-013-100, 100 A) sobre una carga pequeña (una lámpara de 50 W = ~0.2 A) produce una señal en el límite del ruido, y las lecturas serán cero. Elija el modelo de CT 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, considere un patrón de doble CT: una pinza pequeña (p. ej., 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 master elige el valor según un umbral. El patrón se trata en 03 · Selección del 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», rbamp_read_current() da el valor correcto en términos absolutos, pero rbamp_read_power() da un valor negativo en una carga de consumo. Confirmación: rbamp_read_power_factor() mostrará exactamente −1.0 en una carga resistiva (en lugar de +1.0). Solución: volver a montar la pinza físicamente (abrirla, girarla para que la flecha apunte en el sentido correcto y cerrarla de nuevo), o invertir el signo en el lado del maestro.

Si los tres pasos se superan pero la corriente sigue siendo cero

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

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

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

  • ¿Está pinzando el cable correcto? El conductor de línea (fase), y solo ese conductor (nunca todo el cable).

Las lecturas saltan o devuelven ESP_FAIL

Qué se observa: rbamp_read_voltage(dev, ...) o rbamp_read_current(dev, ...) devuelven periódicamente ESP_FAIL. El valor en *out no está definido tras un error.

ESP_FAIL del componente cubre dos clases de problema:

  • NACK tras agotar los reintentos — el enlace es inestable.
  • El filtro de cordura rechazó el valor — un float NaN / Inf / |x| > 10000 llegó por el bus (un valor claramente no físico).

La API de ESP-IDF no distingue entre ellos con códigos esp_err_t distintos (a diferencia de RB_ERR_NACK / RB_ERR_NON_PHYSICAL de Arduino): ambos devuelven ESP_FAIL. Puede distinguirlos por los contadores de diagnóstico (véase la sección «Monitorización de los contadores» más abajo). Ambos síntomas se tratan igual:

  1. Confirme el valor por defecto de 50 kHz y suba los reintentos a 5 mediante Kconfig: vea la sección anterior.

  2. Reduzca la densidad de carga en el bus: si su bucle hace muchas lecturas de un byte, pruebe rbamp_read_all() (una transacción I²C en lugar de unas 13).

  3. Compruebe CONFIG_RBAMP_I2C_TIMEOUT_MS — si el dispositivo responde más lento de lo habitual (cable largo, mal contacto), aumente el tiempo de espera.

  4. Active el registro DEBUG mediante CONFIG_RBAMP_LOG_LEVEL_DEBUG=y o esp_log_level_set("rbamp", ESP_LOG_DEBUG): el componente imprimirá el detalle del ciclo de reintentos y de los rechazos de coherencia bajo la etiqueta "rbamp".

Monitorización de los contadores

El componente exporta dos contadores monótonos públicos para la supervisión de la salud del bus en producción:

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);

retry_exhaustion_count se incrementa cuando una transacción de un solo byte agota el presupuesto CONFIG_RBAMP_NACK_RETRY_ATTEMPTS y devuelve ESP_FAIL. sanity_reject_count se incrementa cuando el filtro de cordura descarta un float (!isfinite(x) || |x| > 10000).

El patrón canónico es instantánea + diferencia una vez cada 60 segundos, para obtener una «tasa de eventos por minuto»:

C
uint32_t prev_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta  = now_retry  - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
    ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
             retry_delta, sanity_delta);
}

Los umbrales de alarma dependen de la carga de trabajo. Para un patrón de prueba de resistencia intensa (como el SoakMonitor de Arduino — ~70 bytes por ciclo cada 5 minutos):

  • retry_delta > 1/hora — ruido benigno, puede ignorarse.
  • retry_delta constantemente > 5/hora — merece investigarse (malos contactos, capacidad del bus, deriva térmica de las pull-ups).

  • sanity_delta > 0 en régimen estable: casi siempre indica interferencia electromagnética en el bus o una regresión del firmware.

Los contadores solo aumentan (nunca se reinician). Para ponerlos a cero debe recrear el manejador mediante rbamp_del(dev) + rbamp_new(...). Es así por diseño, para no perder el historial en las carreras entre «reinicio» y «lectura en el registrador».

Nota

Multiplataforma: estos contadores coinciden en significado con dev.retryExhaustionCount() / dev.sanityRejectCount() de Arduino: los mismos nombres (snake_case frente a camelCase) y los mismos umbrales con el mismo funcionamiento.

El factor de potencia parece incorrecto

Lo que ve: rbamp_read_power_factor(dev, 0, &pf) devuelve ESP_OK pero pf no corresponde al tipo de carga.

Expectativas por carga:

Carga FP esperado
Hervidor, plancha, lámpara incandescente +0.95 .. +1.0 (resistivo)
Frigorífico, motor del 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 devuelto depende del firmware (puede ser 0 o un valor de relleno cercano a cero): es normal mientras la corriente sea realmente cero. Cuando aparece corriente, aparece un PF válido. El filtro de cordura del componente no rechaza este valor (por eso el equivalente sanityRejectCount en IDF no se incrementa): es una medida válida de una magnitud indefinida, no un artefacto del enlace.

PF estrictamente −1.0 en una carga puramente de consumo

La pinza está montada «al revés»: la flecha apunta en sentido contrario al flujo de corriente hacia la carga. La solución: volver a montar la pinza correctamente, o gestionar el signo en el lado del maestro (p = -p; pf = -pf; si sabe que la carga no puede ser un inversor fotovoltaico).

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

  • Causa posible: la pinza de CT está en un cable de otra fase distinta a la que está conectada la entrada 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 da exactamente esos valores de PF. La solución es instalar el módulo de forma que la entrada U y la 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 de agua a plena potencia).

Las instantáneas de periodo siempre están stale

Lo que ve: rbamp_read_period_snapshot(dev, ...) devuelve ESP_ERR_INVALID_RESPONSE, o *out.valid == false. Significa que el módulo no terminó de integrar el periodo anterior cuando llegó la siguiente lectura.

El componente evita el doble cómputo de Wh: ante una instantánea obsoleta, registra una marca de tiempo del master (esp_timer_get_time()), 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 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 (rbamp_probe(dev) == ESP_OK) {
    ESP_LOGI(TAG, "alive");
}
  1. Compruebe el indicador directamente: rbamp_is_period_valid() hace una lectura de un byte sin efectos secundarios:
C
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
    /* avg_p[] can be read */
}
  1. Compruebe la versión del firmware: rbamp_firmware_version(dev) >= 0x02 muestra menos datos obsoletos que 0x01. El firmware canónico actual es 0x04 (v1.3); 0x01=v1.0, 0x02=v1.1, 0x03=v1.2.

Caso especial — despertar de suspensión profunda

Si usa un patrón de deep sleep, la instantánea por defecto rbamp_read_period_snapshot() justo después de rbamp_begin() siempre estará obsoleta (o dará valores casi nulos): begin() hace una instantánea aproximada que reinicia el acumulador del firmware. El patrón canónico usa skip_latch=true + la marca de tiempo guardada en RTC por el propio master: vea 06 · Ejemplos, escenario 9.

La contabilidad de Wh se desvía de una referencia

Qué se observa: rbamp_energy_wh(dev, 0) tras varias horas / días de funcionamiento diverge de la lectura del contador de la compañía o de un medidor de referencia (Kill-A-Watt, etc.).

Descarte primero lo trivial

  1. Calibración del sensor de corriente: confirme que rbamp_set_sensor_class() y rbamp_set_ct_model() se llamaron con el modelo de CT correcto (vea 03 · Selección del sensor de corriente). Sin esto, la corriente RMS se calcula con un suelo por defecto y el valor de potencia queda sistemáticamente sesgado.

  2. Instantáneas caducadas descartadas: si rbamp_energy_wh() queda constantemente por debajo de la referencia, pueden ser intervalos perdidos: la instantánea llegó caducada, el componente evitó el doble conteo, pero se perdió la medición del intervalo. Compruebe la cadencia (véase más arriba).

  3. Deriva del reloj del maestro: esp_timer_get_time() es fiable por sí solo. Pero si el maestro entra en suspensión profunda sin guardar el RTC, se pierde el intervalo entre la instantánea anterior y la siguiente. Para escenarios de suspensión profunda, use el patrón RTC_DATA_ATTR del escenario 9.

Precisión del acumulador

El acumulador de Wh dentro del manejador se guarda como un double de 64 bits.

Si compiló el componente con CONFIG_RBAMP_DISABLE_ENERGY=y, el almacenamiento y la API de energía se eliminan del binario por completo. En ese caso debe mantener su propio contador de Wh en el código de usuario.

snap.latch_ms: diagnóstico, no para la energía

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

El proyecto ESP32 se cuelga tras unos minutos

Qué se observa: un proyecto ESP32 arranca con normalidad y después entra en un bloqueo / bucle de reinicios / tiempo límite del WDT transcurridos entre 1 y 30 minutos.

Un i2c_master de IDF se bloquea en un bus marginal: mitigación de tres capas

Qué se observa concretamente: un proyecto ESP32 (clásico v1.0, IDF v5.4.1, nuevo driver i2c_master) sondea rbAmp sin problemas durante varios minutos y después se «cuelga» en medio de una llamada rbamp_*_read_* o de rbamp_fleet_poll_all. El WDT de tarea (si lo tiene activado) detecta el bloqueo; si no, el proyecto simplemente deja de responder. El backtrace decodificado termina en i2c_ll_is_bus_busy (archivo i2c_master.c:526, espera de bus ocupado previa al envío).

Qué ocurre: en un bus marginal (pull-ups débiles, trazas largas, EMI, interferencia de los flancos de cruce por cero) SDA/SCL pueden «quedarse pegados» un momento en un estado indeterminado. Antes de cada transacción, el i2c_master de IDF gira en el bucle de espera i2c_ll_is_bus_busy esperando a que el bus se libere: esta espera NO está acotada por el parámetro xfer_timeout_ms. Si el bus ocupado dura más de lo que la espera puede aguantar sin ceder a otras tareas, la tarea IDLE de FreeRTOS no recibe CPU y toda la aplicación se cuelga.

Esto no es un «artefacto solo del depurador». Validado en banco: con el mismo montaje 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 externo de 4.7 kΩ en SDA/SCL del DUT 0 bloqueos (ejecuciones de 5 y 25 minutos, 0 reinicios)

La correlación es clara: una corrección de la integridad del bus elimina el bloqueo por completo. La lógica de la biblioteca no tiene la culpa: la mecánica por módulo (fleet_poll_all, MISS/desincronización, comprobaciones de fugas) se mantuvo limpia en todas las ejecuciones hasta el bloqueo.

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

  1. Pull-up externo (~4.7 kΩ) en SDA y SCL a 3.3 V en un único punto del bus. Los pull-ups internos del ESP32 (~45 kΩ) son débiles para un bus con varios módulos de longitud real, mientras que los de 4.7 kΩ integrados en los módulos, en paralelo, resultan demasiado fuertes. En un bus así, corte los integrados de todos los módulos menos uno (o de todos, y entonces dependa solo de los externos). Vea 04 · Cableado, sección «Bus con varios módulos: 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 mantener SDA/SCL en un estado indeterminado al desconectar/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 alguna razón los pull-ups siguen siendo marginales, o surge otra causa de bloqueo, el WDT reinicia el proyecto y, si hay un supervisor presente (por ejemplo, un bootloader de rotación de la aplicación o un supervisor tipo systemd), vuelve a arrancar. En una prueba de resistencia en banco de más de una hora, el WDT detectó y recuperó los 12 bloqueos en la configuración sin pull-up externo.

C
#include "esp_task_wdt.h"

void app_main(void) {
    /* Layer 3 setup — defense-in-depth. */
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 10000,           /* 10 s with plenty of margin */
        .idle_core_mask = 0,
        .trigger_panic = true,         /* on timeout — panic+reboot */
    };
    ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
    ESP_ERROR_CHECK(esp_task_wdt_add(NULL));   /* this task is under the WDT */

    /* ... bus / fleet init ... */

    while (1) {
        rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
        /* ... processing ... */
        esp_task_wdt_reset();            /* "I'm alive" — every cycle */
        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

Qué NO hacer: no intente sortear el problema con un xfer_timeout_ms mayor: no acota la espera de bus ocupado, que es otra ruta de código en el driver. La solución es la integridad del bus (capa 1) + el supervisor (capa 3).

Tiempo límite del watchdog al conectar a WiFi

Causa: una espera sin límite de conexión WiFi dentro de un manejador de eventos activa el WDT de tarea tras ~5 s (por defecto).

Solución: use un patrón dirigido por eventos en lugar de una espera activa. El driver WiFi de ESP-IDF emite los eventos WIFI_EVENT_STA_DISCONNECTED e IP_EVENT_STA_GOT_IP: reaccione a ellos mediante esp_event_handler_register() en lugar de sondear en un bucle.

Patrón mínimo:

C
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT      BIT1

static void wifi_event_handler(void *arg, esp_event_base_t event_base,
                                int32_t event_id, void *event_data) {
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        esp_wifi_connect();   /* auto-reconnect */
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
    wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
    pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
    esp_restart();
}

El broker MQTT se desconecta cada ~15 s

Causa: en la mayoría de los casos no es keepalive. El session.keepalive por defecto en esp_mqtt_client_config_t es 120 s, y disable_keepalive vale por defecto false (es decir, el keepalive está activo). Reescribir estos campos con los mismos valores no cambia nada: si la conexión se cae cada 15 s, la causa real está en la red (un NAT/cortafuegos intermedio que descarta el TCP inactivo) o en una caída de WiFi.

Solución: registre MQTT_EVENT_DISCONNECTED y reconecte explícitamente. esp_mqtt_client_start() lanza internamente su propia tarea; no hace falta llamar a un mqtt.loop() aparte: basta con reconectar al recibir el evento.

C
static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t event_id, void *event_data) {
    if (event_id == MQTT_EVENT_DISCONNECTED) {
        ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
        /* esp-mqtt reconnects automatically with backoff;
         * this handler is the place to clean up application state
         * (retained flags, discovery payload caches). */
    }
}

const esp_mqtt_client_config_t cfg = {
    .broker.address.uri = "mqtt://192.168.1.10:1883",
    /* leave keepalive at the default — 120 s;
     * for aggressive NATs, lower it to 30 s: */
    /* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
                                mqtt_event_handler, NULL);
esp_mqtt_client_start(client);

Si las desconexiones coinciden en el tiempo con caídas de WiFi, la causa real está en WiFi (RSSI, un canal congestionado), no en MQTT. Revise la carga de MQTT_EVENT_ERROR y los registros de WiFi antes de tocar el keepalive.

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, lo que deja menos de 20 kB.

Fix:

  • Use WiFi.mode(WIFI_MODE_STA) (no STA+AP).
  • Desactive BLE si no lo necesita: CONFIG_BT_ENABLED=n en sdkconfig.

  • Reduzca los tamaños de búfer MQTT en esp_mqtt_client_config_t.

  • Pase al ESP32-S2 (sin Bluetooth: unos 30 kB de heap adicionales).

Si esp_get_free_heap_size() muestra menos de 25 kB antes de esp_mqtt_client_start() o esp_http_client_perform(), el handshake TLS probablemente fallará.

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

Canon v1.3 (confirmado en HW): REG_ERROR (0x02) es el resultado de la última escritura, NO persistente. En cada escritura de registro el firmware fija 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 importa el resultado de ESTA operación concreta):

C
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err);   /* IMMEDIATELY, before the next write */

Patrón 2: supervisión duradera de errores (canónico para ejecuciones prolongadas):

C
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
    uint8_t last_err;
    rbamp_read_last_error(dev, &last_err);   /* what was the last rejected */
    /* handle the error */
    rbamp_clear_error(dev);                  /* clears REG_ERROR ... */
    rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR);  /* ... then the sticky bit */
}
Seguridad

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

⚠ bit3 es un canal asíncrono, no sirve para validar síncronamente una escritura: ante una escritura rechazada, bit3 se activa con retraso respecto al momento en que la transacción I²C devuelve el control. 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 (una captura de REG_ERROR inmediatamente después de la operación) o el código de retorno del setter. bit3 sirve para la supervisión prolongada de hechos asíncronos (tiempo de ejecución, ruta de comandos), no para validar una operación que acaba de realizar.

Advertencia: DEV_ERR_CLONE (0xF9) NO se borra mediante CMD_CLEAR_ERROR: es un centinela anticlonado (solo lo borra un reinicio o un reinicio de fábrica).

Un módulo con flash recién grabada 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. Esto es NORMAL en un módulo virgen, no es un fallo.

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

rbamp_set_sensor_class / rbamp_set_ct_model* devuelve ESP_ERR_INVALID_STATE

Qué se observa: una de las llamadas de configuración devuelve ESP_ERR_INVALID_STATE.

ESP_ERR_INVALID_STATE en este grupo de funciones es un código paraguas para tres causas distintas. Puede distinguirlas por la línea ESP_LOGW que imprime el componente con la etiqueta "rbamp" justo antes de devolver el control:

Línea de registro (ESP_LOGW, TAG="rbamp") Causa Solución
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) Condición previa: la clase de sensor debe establecerse antes de escribir el modelo de CT Llame a rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) antes de rbamp_set_ct_model*().
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) El seguimiento interno de lotes del componente está desincronizado con el estado de preparación del firmware En firmware v1.3, el orden de asociación de canales es arbitrario (Fix-A: solo preparación; vea 03 · Selección del sensor de corriente). Llame de nuevo a rbamp_set_sensor_class() para reiniciar el seguimiento del lote, y después asocie los canales en cualquier orden. La redacción «orden descendente obligatorio» de mensajes de registro antiguos se refiere al comportamiento anterior a la v1.3 y ya no está vigente.

También existe el caso de un manejador inicializado pero en el que no se ha llamado a rbamp_begin(): devuelve ESP_ERR_INVALID_STATE sin línea ESP_LOGW (el manejador sigue «frío»). Solución: llame a rbamp_begin(dev) después de rbamp_new() y antes de cualquier rbamp_set_*.

Nota

El patrón de desambiguación mediante registro es un modismo estándar de ESP-IDF: compárelo con esp_driver_i2c, que devuelve ESP_ERR_TIMEOUT tanto para un tiempo límite de ACK como para un tiempo límite de bus ocupado, distinguiéndolos por el registro. Si ve ESP_ERR_INVALID_STATE sin una causa clara, suba el nivel de registro mediante esp_log_level_set("rbamp", ESP_LOG_WARN) (o _DEBUG) y repita la llamada: el componente le indicará cuál de los tres casos es. rbamp_err_to_str(ESP_ERR_INVALID_STATE) devuelve una descripción genérica: "Secuencia de llamadas incorrecta (revise el registro: modo de fábrica / clase de sensor UNSET / lote de asociación desincronizado)".

rbamp_set_sensor_class / rbamp_set_ct_model* devuelve ESP_ERR_INVALID_ARG

Qué se observa: la llamada devuelve ESP_ERR_INVALID_ARG.

Posibles causas:

  1. Código de modelo no válido para la clase: los códigos válidos dependen de la clase de sensor: SCT013 acepta {1, 2, 3, 4, 5, 6, 7} (vea la tabla en 03 · Selección del sensor de corriente); WIRED_CT acepta 1–10 y 12. Un código desconocido para la clase devuelve ESP_ERR_INVALID_ARG.

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

  3. Un valor de rbamp_sensor_class_t no válido — una clase superior a 3 devuelve ESP_ERR_INVALID_ARG. Los módulos suministrados calibrados junto con su propio sensor (RBAMP_SENSOR_WIRED_CT, RBAMP_SENSOR_BUILTIN_CT) rechazan un cambio de clase o de modelo (ESP_ERR_INVALID_STATE); para una pinza SCT-013 de tipo clip use RBAMP_SENSOR_SCT013.

  4. dev == NULL o out == NULL: confirme que rbamp_new() tuvo éxito (devolvió ESP_OK).

rbamp_commit_address_change devuelve ESP_ERR_TIMEOUT

Si prepare tuvo éxito pero commit devuelve ESP_ERR_TIMEOUT, la ventana de «armado» ha expirado (5 segundos tras prepare). rbamp_probe() no ayuda aquí (el módulo responde; el problema está en la máquina de estados). La solución: vuelva a llamar a rbamp_prepare_address_change() e inmediatamente después, en la misma iteración de app_main, sin llamadas de red entre ambas, llame a rbamp_commit_address_change(). WiFi / MQTT o cualquier E/S bloqueante entre prepare y commit es la causa principal de que expire la ventana.

Para más información sobre los métodos públicos con advertencia, véase 09 · Referencia de API, sección «Configuración del sensor».

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

Qué se observa: rbamp_read_* devuelve periódicamente ESP_FAIL / ESP_ERR_INVALID_RESPONSE, pero solo mientras una carga de relé o inductiva está conmutando en la misma instalación. Las lecturas en régimen estable son fiables.

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

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

C
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
    for (int attempt = 0; attempt < 5; attempt++) {
        esp_err_t err = rbamp_read_voltage(dev, 0, v);
        if (err == ESP_OK) return ESP_OK;
        vTaskDelay(pdMS_TO_TICKS(20));   // short pause before retry
    }
    return ESP_FAIL;
}
Seguridad

⚠ Un bus_reset del master por sí solo no basta: cuando una perturbación 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 detecta eventos de conmutación de relés, retrase las lecturas ~50-100 ms tras la conmutación.

Reinicio por WDT de tarea bajo EMI / carga alta

Lo que ve: el ESP32 se reinicia inesperadamente con el motivo TASK_WDT. Suele ocurrir durante eventos de EMI (conmutación de relés, transitorios inductivos).

Causa: con lecturas ralentizadas por EMI (ciclos de reintento NACK + bus_reset), el driver i2c_master de ESP-IDF puede alargar una transacción hasta ~100 ms o más. Si una tarea ejecuta un bucle de lectura masiva sin ceder el control — timeout del WDT de tarea.

Solución — ceder el control en el bucle de lectura masiva:

C
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}

// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
    vTaskDelay(1);   // yield + WDT feed
}

Alternativa: esp_task_wdt_reset() explícito si la tarea está vigilada por el WDT.

Tabla resumen de códigos de error

Las funciones rbamp_* devuelven valores esp_err_t estándar. rbamp_err_to_str(err) devuelve una cadena legible.

Código Cuándo Dónde buscar
ESP_OK (0) éxito —
ESP_FAIL (-1) NACK tras el reintento; o el filtro de cordura rechazó el valor Sección «El módulo no responde por I²C»
ESP_ERR_INVALID_ARG (0x102) dev == NULL, channel/phase fuera de rango, un cls no reconocido, un valor que el módulo rechaza compruebe los argumentos de la llamada
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready expiró (el módulo no responde) O expiró la ventana de 5 s entre prepare_address_change y commit_address_change para wait_ready: mediante rbamp_probe(); para commit: rearme con prepare + commit seguidos, sin E/S bloqueante entre ambos
ESP_ERR_INVALID_STATE (0x103) condición previa: set_ct_model* antes de set_sensor_class la sección set_* de más arriba
ESP_ERR_NOT_SUPPORTED (0x106) la función no está disponible en el SKU actual (p. ej., la API de tensión en una variante I*) compruebe rbamp_line(dev) y rbamp_variant(dev)
ESP_ERR_INVALID_RESPONSE (0x108) instantánea de periodo desactualizada; o REG_VERSION = 0/0xFF en rbamp_begin Sección «Las instantáneas de período siempre están obsoletas» / «El módulo no responde»
ESP_ERR_NO_MEM (0x101) no se pudo reservar memoria para el manejador compruebe el presupuesto de memoria heap (esp_get_free_heap_size())

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

Para depurar a fondo, cuando el componente ya no puede indicarle lo que ocurre en el cable, capture SDA + SCL con un analizador lógico (Saleae, DSLogic Plus, 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 código (rbamp_read_voltage(), etc.) con la secuencia de bytes esperada: deben coincidir exactamente. Se admiten las lecturas en ráfaga (varios bytes en una sola transacción mediante el autoincremento de dirección).

Si el comportamiento del componente diverge de la captura, abra una incidencia adjuntando el archivo de captura (.sal / .dsl / .csv).

Cuándo contactar con soporte

Si ha revisado la sección correspondiente de arriba y el problema persiste, abra una incidencia:

github.com/rb-amp/rbamp-esp-idf/issues

En la incidencia, incluya:

  • SoC objetivo (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + versión de ESP-IDF (salida de idf.py --version).

  • Versión del componente rbamp (por ejemplo, 1.1.0).

  • Versión del firmware del módulo — rbamp_firmware_version(dev) en los registros.

  • Un proyecto IDF mínimo que reproduce el problema (~30 líneas de código en main/main.c).

  • Los valores esp_err_t + rbamp_err_to_str(err) en el momento del fallo, desde los registros bajo la etiqueta rbamp.

  • Kconfig relevante: CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_LOG_LEVEL_*.

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


Fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/10_troubleshooting.md (v1.7.3)