rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

10 · Solución de problemas

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

Guía de depuración orientada a síntomas para el componente rbamp en ESPHome. Cada entrada sigue la misma estructura: qué ve en el registro, qué significa, cómo diagnosticarlo y una solución concreta.

Contents:

  1. I²C / hardware
  2. Calidad de los datos
  3. Energía y persistencia
  4. Integración con Home Assistant
  5. Compilación y cadena de herramientas
  6. Identidad / Capacidad / Error (v1.3)

1. Hardware I2C

Probe failed at 0x50 — sin respuesta

Lo que ve en el registro:

Text
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

El componente llama entonces a mark_failed() y deja de hacer llamadas a update(). Todos los sensores enlazados permanecen en «Desconocido» en Home Assistant.

Qué significa:

El ESP32 envió la fase de dirección a 0x50 (u otra dirección de address:) y no recibió ACK. El módulo está ausente, sin alimentación o en otra dirección.

Cómo diagnosticarlo:

  1. Confirme que scan: true está definido en el bloque YAML i2c:. Reinicie el ESP32 y observe:

    Text
    [I][i2c.arduino:069]: Found i2c device at address 0x50
    

    Si el escaneo encontró el dispositivo, la clave address: de su bloque rbamp: es incorrecta: actualícela.

  2. Mida la alimentación en el pin VCC del módulo con un multímetro: debe estar entre 4.5 y 5.5 V (5 V nominales, véase 04_hardware.md). Cero o por debajo de 4.5 V significa que falta alimentación o que es insuficiente.

  3. Compruebe la continuidad de SDA y SCL desde el GPIO del ESP32 hasta el conector del módulo. Un cable ausente o cruzado es la causa más común en montajes nuevos.

  4. Compruebe las resistencias de pull-up en SDA y SCL (4.7 kΩ a 3.3 V). Sin pull-ups el bus queda a nivel bajo y cada fase de dirección parece un NACK.

  5. Si hizo recientemente un cambio de dirección (la clave new_address:), el módulo puede estar ya en la nueva dirección. Añada scan: true, localice el dispositivo, actualice address: en consecuencia y elimine new_address:.

Solución: corrija el cableado / la alimentación y actualice address: si el módulo se movió. Si el módulo no responde tras un cambio de dirección, vea más abajo «Dirección cambiada pero el módulo no responde».


Bloque RT no listo: publicación omitida

Lo que ve:

Text
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish

Qué significa: el registro de estado informó de que el módulo no está listo. Esto ocurre cuando el módulo aún no ha confirmado su primer bloque de valores instantáneos tras el arranque, está en mitad de una escritura en flash o en un reinicio blando.

Cómo diagnosticarlo:

  1. Si la entrada aparece una vez al arrancar (en los primeros 30 s tras encender) y luego desaparece, es normal. El módulo necesita un ciclo de confirmación (~100 ms) para poner el bit READY tras encender. El snapshot de arranque en setup() también produce un ciclo omitido.

  2. Si el mensaje se transmite de forma continua tras el calentamiento, el módulo puede estar bloqueado. Busque entradas ct_model: / ct_models: repetidas (por ejemplo, una clave olvidada en el YAML que se escribe en cada arranque, produciendo una ventana de escritura en flash permanente).

  3. Si el mensaje aparece de forma ocasional (una vez cada pocos ciclos), es variabilidad normal ligada a los NACK. El bucle de reintentos atrapa la mayoría de los fallos transitorios; a veces la lectura de estado sigue fallando, y eso dispara esta entrada DEBUG.

Fix:

  • Los saltos de calentamiento al arrancar son normales; espere dos ciclos completos de update_interval.
  • Si ct_model: / ct_models: está definido en el YAML, déjelo: en cada arranque la escritura repetida es idempotente (el módulo no escribe si el valor ya está en flash). Si le molestan las pausas del calentamiento, comente la clave tras una primera ejecución correcta.
  • Si el módulo sigue sin estar listo tras 60+ s, reinicie el módulo (no el ESP32) para un arranque en frío limpio.

"rbamp tardó mucho en una operación (XXX ms)"

Lo que ve:

Text
[W][component:522]: rbamp took a long time for an operation (406 ms), max is 30 ms

Qué significa: este aviso aparece cuando el update() de cualquier componente supera el presupuesto por defecto de 30 ms del planificador cooperativo de ESPHome. Para el componente rbamp es esperable e inofensivo.

En firmware v1.3, la lectura con autoincremento está soportada para el bloque de valores instantáneos (el rango contiguo que cubre U / I / P / PF / Q de todos los canales declarados). El componente emite una única lectura en ráfaga para ese bloque: una fase de dirección seguida de ~36 bytes de datos, lo que cuesta ≈ 8–10 ms de tiempo de bus a 50 kHz. El autoincremento en ESCRITURA no está soportado, así que las escrituras por registro (preparación del modelo de CT, clase de sensor, confirmación de dirección) siguen yendo byte a byte. Si la lectura en ráfaga falla (NACK a mitad, bit de capacidad no activo en firmware antiguo), el componente recurre a lecturas por registro (4 transacciones por float, hasta 36 transacciones ≈ 90 ms a 50 kHz). Con la triple de reintentos por byte (hasta 3 × 5 ms de espera ante un ciclo con muchos NACK), la ruta de respaldo del peor caso suele ser de 300–450 ms, que es lo que produce esta advertencia cuando aparece.

La estabilización del snapshot (set_timeout("rbamp_period", 50, ...)) es no bloqueante: update() cede el control al planificador mientras transcurren los 50 ms. La advertencia refleja el tiempo de pared de toda la lectura bloqueante de valores instantáneos, no una inanición de WiFi o de la API.

No se requiere ninguna acción del usuario. La advertencia es cosmética; los sensores de HA se actualizan correctamente. En módulos v1.3 sanos, la ruta de lectura en ráfaga suele quedarse por debajo de 30 ms y la advertencia no llega a saltar.

Si el aviso se produce en cada ciclo: el bus fuerza el respaldo registro a registro (firmware heredado sin la capacidad de lectura en ráfaga, o pull-ups marginales que provocan NACK a mitad de la ráfaga). Compruebe la versión del firmware (Firmware version: 0x04 en el registro de arranque = v1.3) y la topología de pull-ups (un único par de 4.7 kΩ con 3.3 V limpios).


No se pudo leer el snapshot del periodo

Lo que ve:

Text
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]

Qué significa: tras el comando de snapshot y la espera de 50 ms, el componente no pudo leer el registro de potencia media del periodo del canal N tras tres reintentos. El acumulador de energía de ese canal no se actualiza en este ciclo.

Las causas más habituales:

  1. Apagón de escritura en flash. El módulo está escribiendo un modelo de CT (activado por ct_model: o ct_models: al arrancar) o guardando una nueva dirección. La ventana es de ~700 ms; si el asentamiento de 50 ms de la instantánea cae dentro, la lectura caduca.
  2. Snapshot perdido con sondeo intensivo. Con sondeo I²C intensivo y consecutivo, el lado del módulo puede perder un snapshot. El snapshot queda vacío, pero el indicador de validez valdrá 0: el componente omite la integración con el mensaje «Snapshot de periodo aún no válido; se mantiene la ventana de integración anterior». La advertencia salta solo cuando el indicador de validez está activo pero la lectura del registro falló.
  3. Agotamiento de NACK transitorio. Fallaron los tres reintentos en al menos uno de los cuatro bytes del float. Raro a 50 kHz (< 1 % de los ciclos); más frecuente a 100 kHz.

Qué ocurre con la energía: ante un aviso, last_latch_ms_ no se actualiza. En el siguiente ciclo correcto, dt_ms cubre tanto la ventana perdida como la nueva: la energía se recupera, suponiendo una carga razonablemente estable en el intervalo. Es una pequeña imprecisión aceptable.

Fix:

  • Elimine las claves de cambio de dirección (new_address:) del YAML tras el primer arranque correcto.
  • Si la advertencia salta más de una vez por hora, compruebe la velocidad del bus (se recomienda 50kHz) y las resistencias de pull-up (4.7 kΩ).
  • Si el aviso aparece en cada ciclo, compruebe si hay un conflicto con otro dispositivo del bus.

Dirección cambiada, pero el módulo no responde

Lo que ve:

Text
[E][rbamp:xxx]: Address change applied but slave not responding at 0x51 —
    check wiring and try power-cycling the rbAmp.
[E][component:xxx]: Component rbamp was marked as failed.

Qué significa: el flujo de cambio de dirección recorrió todos los pasos (escribir la nueva dirección, guardar en flash, reinicio blando, cambiar la dirección I²C interna del componente), pero el módulo no respondió en la nueva dirección en la primera comprobación.

Posibles causas:

  1. La dirección se escribió y se guardó, pero el módulo quedó en mal estado (corrupción de los parámetros de flash, un fallo de alimentación durante la ventana de escritura de 700 ms).
  2. En firmware antiguo (v1.0-v1.2): el módulo no estaba en modo de aprovisionamiento de fábrica en el momento del intento. En firmware v1.3 o posterior esta causa no aplica (el commit en dos fases está listo para producción). Si la propia lectura del estado de modo falló (NACK), el componente escribe de forma especulativa, con una advertencia en el log.
  3. Un problema de cableado que existía antes del cambio de dirección (la sonda con la dirección antigua solo tuvo éxito por casualidad en uno de los tres reintentos).

Procedimiento de recuperación:

  1. El módulo está en una dirección desconocida. Use un YAML de prueba con i2c: scan: true y un corte de alimentación: encuentre en qué dirección responde el módulo.
  2. Si el módulo aparece en la nueva dirección (por ejemplo 0x51), actualice el YAML a address: 0x51, elimine new_address: y vuelva a grabar. El siguiente arranque será limpio.
  3. Si el módulo no responde en ninguna dirección, la escritura en flash puede haber corrompido los parámetros. La recuperación requiere intervención física: consulte la documentación del módulo o a su proveedor.

Antecedentes: el flujo de cambio de dirección en firmware v1.3 es una confirmación en dos fases: el maestro escribe la nueva dirección en un registro de preparación y después emite CMD_COMMIT_ADDR para hacerla persistente. La ventana de escritura de 700 ms corresponde al borrado y programación de la flash de la página de configuración de usuario. Véase 09 · Referencia de la API.


i2c_master bloqueado — bucle de arranque del ESP32 o el bloque RT nunca publica

Lo que ve:

Text
[I][i2c.idf:xxx]: Performing I2C bus reset...
[E][i2c.idf:xxx]: i2c_master_send_buf failed: ESP_ERR_TIMEOUT
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

En el peor de los casos, un tiempo de espera del watchdog de tarea reinicia el ESP32 tras varios minutos de prueba de resistencia (bajo carga, no en la puesta en marcha). Puede parecer que «el módulo funcionó una hora y después se paró».

Qué significa: el controlador i2c_master de ESP-IDF v5 tiene un fallo conocido: en un bus marginal (tiempo de subida lento, pull-up débil, ráfaga de EMI) la función interna i2c_ll_is_bus_busy entra en un bucle infinito esperando una condición STOP que nunca llega. En ESPHome 2025.x este bucle puede agotar el presupuesto del WDT de aplicación y provocar un reinicio. Es un problema canónico de ESP-IDF, no específico de rbAmp.

Mitigación en tres capas (todas activas en el componente por defecto, más las recomendaciones de hardware):

  1. Software: la disciplina NACK integrada: 50 kHz por defecto, reintento por byte 3× con 5 ms de pausa y el filtro de sanidad IP-009 std::isfinite(). Ya está en el componente desde v0.2+. La corrección del manejador de parada se incluyó en el firmware v1.1/v1.3, pero se recomienda seguir con 50 kHz en maestros ESP-IDF porque persiste la interacción de temporización del controlador.

  2. Hardware: un par de pull-up externo de 4.7 kΩ en SDA + SCL (un único par externo, con los puentes del módulo cortados; vea §Bus de varios módulos). Los pull-ups internos del ESP32 (~50 kΩ) son débiles: en un bus largo o con una alimentación marginal no bastan. Los pull-ups de 4.7 kΩ a 3.3 V limpios son obligatorios para un despliegue en producción.

  3. Hardware: no mantenga activado el depurador / el reset de la OTA durante las transacciones I²C. Un RESET activado a mitad de una transacción deja el bus bloqueado (el esclavo sigue controlando SDA), que es justo lo que provoca el bucle infinito de bus ocupado.

Tasa de bloqueos observada en una prueba de resistencia de 24 horas:

Capa Tasa de bloqueos Nota
Solo software (sin pull-up externo) ~1 vez cada 10 minutos el perro guardián del puente se dispara y se recupera mediante reinicio, pero Wh pierde una ventana
Software + pull-up externo de 4.7 kΩ ~1 vez cada 24 horas Caso límite de ráfaga EMI; recuperación automática
Software + pull-up externo + reinicio limpio 0 se cuelga tras un soak de 24 h objetivo de producción

Gravedad = tiempo de medición (prueba de resistencia de duración completa), no la puesta en marcha. En la puesta en marcha la disciplina NACK detecta el 99 %+ mediante la triple reintentos: los bloqueos reales solo empiezan tras horas de funcionamiento limpio. Para la referencia completa de la disciplina, véase 09 · Referencia de la API.

Si la recuperación falla

: como último recurso, configure wdt: (núcleo de esphome) con un app_wdt_timeout_seconds: aumentado (predeterminado 5 s; ponga 10–15 s). Esto da tiempo a la recuperación del componente sin reiniciar.


2. Calidad de los datos

La tensión salta — 228 V / 502 V / 1.96 V mezclados

Lo que ve:

Text
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 1.964 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 228.365 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V

En Home Assistant la gráfica de tensión es un diente de sierra entre ~228 V, ~2 V y ~503 V. La corriente puede mostrar al mismo tiempo 0 A o −2 A.

Qué significa: aparecen valores «fantasma» desde una fuga de búfer en el controlador i2c_master de ESP-IDF en condiciones de NACK a 100 kHz. La configuración por defecto de la versión actual del componente debería eliminarlo. Si aparece el síntoma:

  • El bloque i2c: tiene frequency: 100kHz: cámbielo a 50kHz.
  • La versión del componente es anterior al 2026-05-24: actualícela.

Fix:

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # required for reliable operation
  scan: true

Para más sobre el mecanismo de disciplina frente a NACK (50 kHz por defecto + reintento por byte + filtro de cordura para NaN/Inf), vea 09 · Referencia de la API.

Nota

Compatibilidad con framework: type: — el problema de valores fantasma por NACK solo se manifiesta con el driver i2c_master de ESP-IDF. Con framework: type: arduino (el valor por defecto) se usa la pila Wire del framework Arduino, que se comporta de forma distinta ante un NACK y no reproduce este síntoma. Esto significa:

  • Si el YAML tiene esp32: framework: type: arduino, en teoría puede mantener frequency: 100kHz sin picos fantasma visibles, pero el bucle de reintentos por byte del componente sigue ejecutándose sobre Wire y los NACK periódicos a 100 kHz permanecen, solo que sin los fantasmas. Para gráficas estables en HA recomendamos 50 kHz, sea cual sea el framework.
  • Si el YAML tiene esp32: framework: type: esp-idf, entonces frequency: 50kHz es obligatorio. Es la configuración en la que el síntoma fantasma del driver i2c_master se ve con más claridad.

El componente no elige por sí mismo el framework: funciona sobre ambos. Es una decisión exclusiva de su YAML.


La corriente es 0 A permanentemente bajo carga

Lo que ve:

Text
[D][sensor:xxx]: 'Mains Current': Sending state 0.000 A

La potencia es 0 W, la energía no crece, pero la tensión se lee bien (por ejemplo 228 V).

Qué significa: una de dos causas habituales:

Causa 1 — ct_model: no está definido o no coincide con la pinza física. En el firmware v1.2 o posterior, el módulo usa los coeficientes de fábrica del modelo seleccionado en el YAML. Si ct_model: no está definido, o está definido como, por ejemplo, SCT_013_050 con una SCT-013-005 real, el rango de medida es tan superior a la señal física que el módulo no puede resolverla e informa cero.

Causa 2 — la pinza está mal instalada en el conductor (vea la polaridad en 03_sensor_selection.md y que se rodee solo un conductor).

Cómo diagnosticarlo:

  1. Confirme que la pinza está instalada físicamente sobre un conductor por el que circula corriente y que el conductor realmente transporta corriente (use un amperímetro de pinza como referencia, si dispone de uno).
  2. Abra el YAML y compruebe que ct_model: (o ct_models: para UI3) coincide con el modelo de pinza físico.
  3. Si ct_model: está definido en firmware v1.2+ pero sensor_class: se omite o tiene un valor distinto de SCT_013, el módulo rechaza la escritura del modelo. El registro de arranque muestra un aviso que señala la condición previa que falta.

Fix:

YAML
rbamp:
  id: meter1
  sensor_class: SCT_013       # default; required on v1.2+ before ct_model
  ct_model: SCT_013_005       # match the physical clamp

Tras el arranque, el módulo graba el modelo en flash una vez (~700 ms) y carga los coeficientes de fábrica. La siguiente publicación de valores instantáneos ya da una corriente correcta.

Precisión en pequeñas corrientes en UI2 / UI3: el patrón de doble CT. Si quiere alta resolución en cargas pequeñas (iluminación, modo en espera) y un rango amplio para los picos (hervidor, lavadora) a la vez, use dos canales de corriente en la misma fase simultáneamente con pinzas distintas:

YAML
rbamp:
  id: home_meter
  sensor_class: SCT_013
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
  # CH0 — SCT-013-005 for resolving idle loads (~5..50 W)
  # CH1 — SCT-013-030 for the main household load (~50..7000 W)
  # CH2 — SCT-013-050 for the peak (EV-charging headroom up to 11.5 kW)
  # For peaks above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A) on that channel

Las tres pinzas rodean el mismo conductor de fase L. SCT-013-005 da ~10× mejor resolución en corrientes pequeñas que SCT-013-030, pero satura en ~5 A. SCT-013-030 cubre el «centro» del rango útil; SCT-013-050 capta picos de hasta ~11.5 kW sin saturar. En el lado de HA, un sensor de plantilla selecciona la medición «activa» por umbral:

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

YAML
# configuration.yaml — select the active channel by range
template:
  - sensor:
      - name: "Mains Current (active)"
        unit_of_measurement: "A"
        device_class: current
        state_class: measurement
        state: >
          {% set i0 = states('sensor.rbamp_ch0_current') | float(0) %}
          {% set i1 = states('sensor.rbamp_ch1_current') | float(0) %}
          {% set i2 = states('sensor.rbamp_ch2_current') | float(0) %}
          {% if i2 > 25 %}{{ i2 }}
          {% elif i1 > 4 %}{{ i1 }}
          {% else %}{{ i0 }}
          {% endif %}

Esto cubre el rango desde la pinza de menor corriente nominal hasta la de mayor (5 A … 50 A). Compromiso: tres pinzas de CT en un mismo conductor son físicamente voluminosas, y cada una ocupa un canal del módulo (en UI3, todo el módulo). En la mayoría de los despliegues una sola pinza con un rango ajustado a la carga cubre el 99 % de los escenarios; el patrón de doble o triple CT solo se necesita cuando hace falta un rango dinámico amplio.


Snapshot de periodo no válido — la energía no crece

Lo que ve:

Text
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window

El sensor energy en Home Assistant muestra un valor constante, o se queda en 0 Wh tras el arranque, aunque la potencia se lee correctamente.

Qué significa: el indicador de snapshot de periodo válido era 0 cuando el componente lo comprobó 50 ms después del comando de snapshot. El módulo todavía no ha confirmado un snapshot de periodo válido.

Causas normales:

  1. Primera instantánea tras el arranque. La instantánea de arranque en setup() descarta siempre su resultado: el acumulador del módulo se reinicia con el primer comando de instantánea. La segunda instantánea (un update_interval después del arranque) es la primera que integra. La energía empieza a acumularse tras el primer update_interval completo desde el arranque.
  2. Arranque en frío del módulo. El módulo necesita al menos un ciclo de confirmación de ~100 ms para que haya datos en el acumulador de período. Si la primera instantánea llega antes, el indicador de validez es 0.
  3. Snapshot perdido con mucha carga de sondeo. Con mucha carga I²C el lado del módulo puede perder un snapshot. El snapshot queda vacío; el siguiente debería funcionar.

Si la entrada se dispara en cada ciclo de update() indefinidamente (no solo las dos primeras veces), el módulo puede estar en un estado en el que el acumulador del periodo nunca se confirma. Reiniciar la alimentación del módulo borra este estado.


3. Energía y persistencia

El contador de energía se pone a 0 tras un reinicio

Módulos STANDARD (STD).

La energía procede de los contadores del propio módulo y además se guarda en la flash del ESP32 (NVS), de modo que un reinicio del ESP32 o del módulo no la pone a cero y los totales no retroceden. Si un sensor de un módulo STANDARD sigue empezando desde 0, la causa es un borrado de la NVS (borrado de flash, tabla de particiones cambiada) y un reinicio del contador en el módulo a la vez. Los sensores de total general (energy_total, energy_exported_total, energy_net, reactive_energy*) usan su propia ranura NVS, separada de las ranuras energy por canal, de modo que una actualización del componente no borra los valores por canal.

Lo que ve en el panel de energía de HA: una caída brusca a 0 Wh y después una acumulación normal desde 0. El historial antiguo de Wh se conserva en las estadísticas a largo plazo de HA, pero la «lectura actual del contador» parece reiniciada.

Qué significa: al restaurar desde NVS no se encontraron datos o se cargaron datos no válidos. Causas posibles:

  1. Cambio de versión del diseño NVS. La clave NVS se deriva del ID del componente combinado mediante XOR con una constante de versión de diseño. Si cambió el diseño de la estructura (con una actualización del componente), la clave de la ranura NVS cambia y los datos antiguos ya no se encuentran. La restauración empieza desde 0 sin avisar.
  2. Fragmentación o corrupción de NVS. La partición NVS del ESP32 usa nivelación de desgaste de la flash. En despliegues muy antiguos o tras muchas grabaciones, la fragmentación puede hacer que un guardado falle. El log muestra: [W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle.
  3. Cambio de la disposición de particiones. Grabar un partitions.csv nuevo que cambie el tamaño o la posición de la partición nvs invalida todos los valores guardados.
  4. Primer arranque tras un reinicio de fábrica o un borrado completo de flash. Esperado: NVS está vacía, el acumulador empieza en 0.

Cómo diagnosticarlo:

Busque en el log de arranque:

Text
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh

Si está presente, la restauración no encontró nada. Además:

Text
[C][rbamp:xxx]: Restored Wh from NVS: total[0.310, 0.000, 0.000] export[...]

Si el valor restaurado es notablemente menor de lo esperado, puede que se haya omitido el último guardado NVS de 5 minutos (pérdida en el peor caso: ≈ 5 Wh con una media de 60 W).

Fix:

  • En una actualización del componente que cambie el diseño de NVS, los totales antiguos no se restauran automáticamente. Las estadísticas de larga duración de HA conservan el historial aunque la «lectura actual» se ponga a cero.
  • Para conservar los Wh tras un borrado forzado de NVS, lea los valores actuales del sensor en las Herramientas de desarrollo de HA antes del borrado y anótelos. No hay forma de inyectar un valor inicial en el componente.

La energía en HA no coincide con un contador de referencia

Lo que ve: el sensor energy en HA marca notablemente menos (por ejemplo, 10–20 %) que un contador inteligente de referencia o el contador de la compañía en el mismo periodo.

Qué significa: en módulos BASIC el componente integra la potencia media del periodo sobre el tiempo del lado del ESP32 entre comandos de snapshot. En módulos STANDARD acumula los contadores de energía propios del módulo.

Si la energía sale baja, busque entre estas causas:

  1. Carácter de la carga. El registro de potencia media del período es realmente la potencia promediada en el tiempo sobre un período cerrado, no un valor instantáneo. Una carga pulsante (motor, compresor) con un tiempo de encendido corto dentro del período de 60 segundos promedia por debajo de su potencia de pico.
  2. Colocación de la pinza y calibración de la carga. Si el modelo de CT de fábrica (ct_model:) no coincide con la realidad, los rangos de coeficientes quedarán desplazados. Compruebe que el ct_model: del YAML coincide con la pinza física instalada en el conductor.
  3. Nivel de firmware BASIC. En el SKU BASIC, las muestras de P por ventana se fijan a 0 antes de integrar. Si la carga tiene una componente regenerativa (por ejemplo, un motor de bomba con fuerza contraelectromotriz), BASIC cuenta de menos.

4. Integración con Home Assistant

HA muestra «No disponible» para todos los sensores rbamp

Lo que ve en HA: todas las entidades sensor.rbamp_* muestran «No disponible».

Causas y soluciones:

  1. ESP32 sin conexión. Ejecute esphome logs --device : si no puede conectarse, el ESP32 está fuera de línea. Compruebe las credenciales de WiFi y el punto de acceso de respaldo, si hay uno configurado.
  2. Conexión con la API perdida. La API nativa de ESPHome (puerto 6053) puede estar bloqueada por un cortafuegos. Compruebe que el ESP32 responde por IP:

    Shell
    ping 
    

    Si el ping responde pero HA sigue mostrando «unavailable», hay que eliminar y volver a añadir la integración ESPHome en HA (Ajustes → Integraciones → ESPHome → Eliminar, y después volver a descubrir).

  3. Discrepancia de la clave de cifrado de la API. Si en el YAML está configurado api: encryption: key:, la integración de HA debe conocer la misma clave. Una discrepancia hace que HA considere el dispositivo desconectado. Elimine y vuelva a añadir la integración tras actualizar la clave.

  4. mDNS no funciona en su topología de red. Si el ESP32 está en una VLAN distinta a la de HA, la multidifusión mDNS puede no cruzar el límite. Añada el dispositivo por IP manualmente en la integración ESPHome.

Falla la carga OTA

Lo que ve:

Text
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed

Causas habituales:

  1. La dirección IP cambió. El ESP32 obtuvo una concesión DHCP nueva. Revise la tabla DHCP del router, localice el dispositivo por MAC y asígnele una IP fija, o use la clave YAML wifi: use_address:.
  2. El ESP32 está en modo seguro. Tras tres arranques fallidos seguidos, ESPHome entra en modo seguro (sin componentes personalizados, solo WiFi + OTA). La OTA en modo seguro funciona, pero el dispositivo ejecuta un firmware reducido. La marca en esphome logs:

    Text
    [I][safe_mode:xxx]: Entering safe mode
    

    Fuerce un arranque limpio: mantenga pulsado el botón BOOT al encender, o añada safe_mode: num_attempts: 10 para ampliar el umbral.

  3. El puerto 3232 (OTA) está bloqueado. El protocolo OTA usa TCP 3232. Compruebe que ninguna regla de cortafuegos lo bloquea entre la máquina que ejecuta esphome run (o el host de HA) y la IP del ESP32.

  4. Un firmware grande tras añadir rbamp. La primera OTA tras añadir un componente externo puede superar el tamaño de la partición OTA en la disposición predeterminada de 4 MB del ESP32. Revise la salida de esphome compile por si hay advertencias de tamaño de binario, y cambie a una disposición con una partición OTA mayor si hace falta.

La OTA justo después del aprovisionamiento new_address: no carga

Síntoma: tras un primer arranque correcto con la clave new_address: (el log muestra Address change SUCCESS, new address 0x51), la siguiente OTA falla con un error de compilación o una advertencia en ejecución address 0x50 NACK.

Qué pasó: el módulo está ahora en la nueva dirección (0x51), pero el YAML sigue apuntando a la antigua (address: 0x50). En el siguiente update() el componente prueba 0x50, no obtiene nada y registra NACK constantes. La OTA en sí no falla aquí: es un síntoma contiguo; verá una cascada de errores de rbamp en esphome logs y concluirá que el dispositivo está roto.

Recuperación en 3 pasos:

  1. Edite el YAML:

    YAML
    rbamp:
      id: meter1
      address: 0x51        # new address — set instead of 0x50
      # new_address: 0x51  # ← REMOVE this line. Do not comment it out,
      #                       delete it entirely, otherwise the component
      #                       tries to provision again and logs a warning
      update_interval: 60s
      ct_model: SCT_013_030
    
  2. Ejecute esphome run (por CLI) o Compilar + Subir (mediante el complemento de HA). El nodo recibe el binario nuevo por WiFi OTA.

  3. Abra esphome logs y confirme que el mensaje de arranque dump_config muestra la dirección correcta y que update() se ejecuta sin NACK.

Regla: new_address: es una operación de aprovisionamiento de una sola vez. Una vez que el módulo se ha movido a la nueva dirección y la ha guardado en flash, la clave debe eliminarse del YAML. Si no, en cada arranque el componente intentará aprovisionar de nuevo (en v1.2 o posterior el módulo ignora la escritura repetida, pero la advertencia permanece en el log y ensucia la notify de HA).

Si el módulo no responde en ninguna dirección tras el cambio, véase «Dirección cambiada, pero el módulo no responde» más arriba.


5. Compilación y cadena de herramientas

Error de compilación: no se encuentra 'esphome/core/component.h'

Lo que ve en VS Code / clangd: subrayados rojos en todo rbamp.h y rbamp.cpp. Ventana emergente:

Text
'esphome/core/component.h' file not found

Qué significa: clangd (el IntelliSense de C++ de VS Code) no tiene acceso a las rutas de inclusión de ESPHome + PlatformIO. El sistema de compilación las resuelve correctamente durante esphome compile; clangd no.

No es un error de compilación. Si esphome compile example/ui1.yaml termina sin errores, el código es correcto.

Si quiere eliminar las líneas rojas onduladas: cree un archivo .clangd en el directorio del componente que apunte a las rutas de inclusión generadas por la compilación de ESPHome (.esphome/build//src/). Es un cambio cosmético y opcional.


PlatformIO se cierra con 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)

Lo que ve:

Text
Error: Failed to install Python dependencies (exit code: 3221225501)

(0xC0000001D = 3221225501 en decimal)

Qué significa: PlatformIO 6.1.19+ usa el binario Rust uv para instalar dependencias de Python en su penv interno. En algunas CPU Intel para portátil recientes, uv falla con EXCEPTION_ILLEGAL_INSTRUCTION por incompatibilidad del conjunto de instrucciones. Afecta al paso penv_setup.py install en una instalación nueva de PlatformIO.

Solución alternativa (instale antes todas las dependencias con pip, evitando uv):

Text
# Step 1: install the ESP32 platform's Python dependencies directly
& "$env:USERPROFILE\.platformio\penv\Scripts\python.exe" -m pip install `
    "littlefs-python>=0.16.0" "fatfs-ng>=0.1.14" "pyyaml>=6.0.2" `
    "rich-click>=1.8.6" "zopfli>=0.2.2" "intelhex>=2.3.0" "rich>=14.0.0" `
    "cryptography>=45.0.3" "certifi>=2025.8.3" "ecdsa>=0.19.1" `
    "bitstring>=4.3.1" "reedsolo>=1.5.3,<1.8" "esp-idf-size>=2.0.0" `
    "esp-coredump>=1.14.0" "pyelftools>=0.32"

# Step 2: bootstrap the nested ESP-IDF venv (see the next entry)
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Una vez instalados estos paquetes, get_packages_to_install() en penv_setup.py devuelve vacío y no se llama a la instalación de pip mediante uv. Las ejecuciones posteriores de esphome compile funcionan con normalidad.

La solución alternativa debe volver a aplicarse tras una instalación nueva de PlatformIO o tras borrar la caché de ~/.platformio.


Entorno virtual de ESP-IDF: no existe el módulo idf_component_manager

Lo que ve:

Text
ModuleNotFoundError: No module named 'idf_component_manager'

Aparece en la primera esphome compile en una máquina donde PlatformIO descargó el framework ESP-IDF pero no ejecutó el arranque completo de sus requisitos.

Qué significa: el framework ESP-IDF de PlatformIO está instalado en el entorno virtual anidado ~/.platformio/penv/.espidf-5.5.4/ (el número de versión puede variar). Ese venv necesita requirements.core.txt del paquete del framework. Cuando se aplica la solución alternativa de uv indicada arriba, el paso 2 instala pip en el venv e instala los requisitos.

Si el error aparece tras aplicar la solución uv pero se omitió el paso 2:

Text
# Find the IDF venv (the version number may differ):
ls "$env:USERPROFILE\.platformio\penv\" | Where-Object { $_.Name -like ".espidf-*" }

# Bootstrap pip into the IDF venv:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip

# Install the IDF core requirements:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Sustituya 5.5.4 por su número de versión de IDF (compruébelo en ~/.platformio/penv/).


esphome compile falla: no se encuentra get_object_id_hash

Lo que ve:

Text
error: 'class esphome::rbamp::RbAmpComponent' has no member named 'get_object_id_hash'

Qué significa: una versión antigua de rbamp.cpp llamaba a this->get_object_id_hash() para sembrar la ranura NVS. Este método se eliminó de PollingComponent en ESPHome 2025.x.

Solución: actualice el componente a la versión actual. El código moderno usa una generación de hash compatible con ESPHome 2025.x y posteriores.


ESPHome demasiado antiguo — no se encuentra set_i2c_address

Lo que ve:

Text
error: 'class esphome::i2c::I2CDevice' has no member named 'set_i2c_address'

Qué significa: el flujo de cambio de dirección new_address: llama a i2c::I2CDevice::set_i2c_address(), que una versión antigua de ESPHome no tiene.

Solución: actualice a ESPHome 2025.3.0 o posterior. El complemento ESPHome de HA sigue la versión actual automáticamente: es la vía de instalación recomendada.

Shell
# If using a local Python venv:
pip install --upgrade esphome

6. Identidad / capacidad / error (v1.3)

Esta sección explica qué significan los valores individuales de las entidades de identidad (un text_sensor de plantilla mediante lambda:), el mapa de capacidades y los códigos REG_ERROR añadidos en v1.3.

Las lecturas de identidad devuelven «UNK» / «UNREADABLE»

Qué ve (text_sensor template):

YAML
text_sensor:
  - platform: template
    name: "Meter variant"
    lambda: 'return id(my_meter).get_variant_str();'  # → "UNK" in HA
Text
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK

Qué significa:

  • "UNK": el componente no pudo leer REG_HW_VARIANT (0x55) tras todos los reintentos. Causas: el módulo tiene firmware heredado (v1.0–v1.1, anterior a la detección de variante), o un bus I²C marginal con agotamiento de NACK en este registro concreto.

  • "UNREADABLE": la lectura devolvió un valor fuera de 0x55..0x5A, fuera del rango de códigos de variante válidos. Indica corrupción del firmware o una colisión de registro bruto (por ejemplo, un búfer obsoleto).

Fix:

  • Si el firmware es anterior a v1.2, la detección de variante no está disponible. El text_sensor sigue publicando; use una indicación en el lado del YAML mediante topology: o reinicialice mediante una plantilla de HA.

  • Si el firmware es v1.3+ y el bus es marginal, véase i2c_master bloqueado.

Mapa de bits de CAPACIDAD = 0x0000

Lo que ve:

YAML
text_sensor:
  - platform: template
    name: "Meter capability"
    lambda: 'return id(my_meter).get_capability_hex();'  # → "0x0000"

Qué significa: el registro de capacidades no existe en este firmware: se lee como 0 (el comportamiento estándar de «registro no implementado» en el firmware de rbAmp). Esto corresponde al firmware heredado v1.0–v1.2.

Comportamiento del componente: todas las funciones condicionadas por capacidad (GC de flota, confirmación de dirección en dos fases, save_user_config, clear_error) recurren automáticamente a la ruta heredada:

  • fleet_gc_enable: true → advertencia + omisión (no anunciado por el firmware)
  • new_address: → respaldo monofásico, requiere el modo de aprovisionamiento de fábrica
  • clear_error() → respaldo por código de proveedor (mejor esfuerzo)

Cero regresiones: los despliegues v0.4.0 existentes siguen funcionando sin cambios en el YAML ni en el comportamiento. Esto es el canon C5: la ruta condicionada por capacidad nunca rompe lo heredado.

last_error_str() muestra "ERR_PARAM" tras un cambio de ct_model: o sensor_class:

Lo que ve:

Text
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)

get_last_error_str() → "ERR_PARAM".

Qué significa: el firmware rechazó el valor escrito. Los desencadenantes más habituales:

  1. Un código fuera del conjunto aceptado: para SCT_013 los códigos aceptados son {1, 2, 3, 4, 5, 6, 7}.

  2. Modelo de CT fuera del conjunto permitido para la clase, por ejemplo WIRED_CT_1 con sensor_class: SCT_013. Véase la tabla por clase de 03_sensor_selection.md.

  3. Código 0 (UNSET) — un intento de borrar el modelo de CT mediante 0. No soportado; use dev.factoryReset() para un reinicio completo.

Recuperación: llame a id(my_meter).write_clear_error(); mediante un servicio YAML o mediante lambda: en on_boot: para borrar REG_ERROR + bit3 de EVENT_FLAGS. Después puede reintentar con un valor correcto.

YAML
api:
  services:
    - service: my_meter_clear_error
      then:
        - lambda: 'id(my_meter).write_clear_error();'

El cambio de ct_model: / sensor_class: se rechaza (línea de registro, sin escritura)

Lo que ve:

Text
[W][rbamp:xxx]: ct_model refused: module is calibrated with its fitted sensor (class N) — ...
[W][rbamp:xxx]: sensor_class refused: module is calibrated with its fitted sensor (class N); ...

Qué significa: el módulo se calibró en pareja con su propio sensor integrado (WIRED_CT / BUILTIN_CT). Escribir una clase o un modelo genérico sustituiría esa calibración individual, por lo que el componente lo rechaza. Es la protección de escritura, no un fallo. Un valor igual tampoco se escribe nunca (no se registra nada a nivel de aviso en ese caso).

Solución: elimine sensor_class: / ct_model: / ct_models: del YAML para ese módulo. Solo si quiere deliberadamente el preajuste genérico, ponga ct_model_force: true junto con el modelo, grabe una vez y elimine ambas líneas después (el esquema rechaza ct_model_force: sin una clave de modelo).

ct_models: no admitido por este dispositivo (módulo STANDARD)

Lo que ve:

Text
[W][rbamp:xxx]: ct_models: (per-channel) not supported by this device — it does not advertise persistent per-channel model storage ... Use the global `ct_model:` key. (Keys ignored.)

Qué significa: el módulo no puede conservar modelos por canal tras un corte de alimentación, así que escribirlos los revertiría en silencio. El componente lo rechaza en lugar de perder el valor.

Solución: use la clave única ct_model: para todos los canales.

Cambiar ct_model: reinicia el módulo una vez

En módulos SCT con firmware hasta 1.4.19, cambiar a otra potencia nominal se completa con un reinicio del módulo (guardar, reiniciar, reidentificar). El log muestra el reinicio y, después, que la corriente / potencia / energía se escalan a la nueva potencia nominal; los sensores pueden omitir un update() mientras tanto. Esto forma parte del flujo normal. El firmware 1.4.20 y posteriores realiza el cambio en el módulo y no hay reinicio. Si el log indica que la ganancia aplicada está fuera del rango esperado, el componente no escala; compruebe que ct_model: coincide con la pinza instalada físicamente.

Los sensores de total general y de ángulo nunca publican

Lo que ve (registro de arranque):

Text
[W][rbamp:xxx]: energy_total/energy_net/reactive_energy sensors need on-device energy counters, which this device does not advertise — they will never publish. Per-channel `energy:` keys still work ...
[W][rbamp:xxx]: voltage_angle_*/phase_sequence sensors need a newer device firmware — they will never publish on this device

Qué significa: el módulo conectado (o su firmware) no proporciona estos valores. Las claves se validan, pero no se publica nada.

Solución: use los sensores energy: por canal, o actualice el firmware del módulo.

start_current_ua: ignorada

[W][rbamp:xxx]: start_current_ua: not supported by this device firmware — key ignored: el módulo cuenta energía a cualquier corriente. La clave solo tiene efecto en módulos STANDARD con contadores de energía en el dispositivo. Los valores distintos de 0 o de 10..2540 en pasos de 10 se rechazan en esphome config.

update_interval rechazado

update_interval por debajo de 1s lo rechaza el esquema en esphome config. latch_interval no puede ser menor que update_interval.

Bit 3 de EVENT_FLAGS (ERR_LATCH): comportamiento de reactivación

Lo que ve: tras clear_error(), unos cientos de milisegundos después el bit3 de EVENT_FLAGS vuelve a estar activado (reactivación persistente).

Qué significa: el canal de errores duradero del firmware vuelve a activar el bit3 tras un borrado si la condición de error original no se ha resuelto. Es intencionado: el maestro puede perder el primer borrado y no debe suponer que el error ha desaparecido para siempre si el parámetro sigue mal.

Solución: la recuperación completa requiere dos pasos:

  1. Elimine la causa (sustituya el código de modelo de CT incorrecto, corrija el YAML).
  2. write_clear_error() — esta llamada borra REG_ERROR y el bit3 de EVENT_FLAGS en una sola operación.

Si el bit3 sigue volviéndose a enganchar, el parámetro sigue siendo incorrecto; vuelva a leer get_last_error_str() para saber exactamente qué rechaza el firmware.


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