10 · Solución de problemas
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:
- I²C / hardware
- Calidad de los datos
- Energía y persistencia
- Integración con Home Assistant
- Compilación y cadena de herramientas
- Identidad / Capacidad / Error (v1.3)
1. Hardware I2C
Probe failed at 0x50 — sin respuesta
Lo que ve en el registro:
[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:
-
Confirme que
scan: trueestá definido en el bloque YAMLi2c:. Reinicie el ESP32 y observe:Text[I][i2c.arduino:069]: Found i2c device at address 0x50Si el escaneo encontró el dispositivo, la clave
address:de su bloquerbamp:es incorrecta: actualícela. -
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.
-
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.
-
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.
-
Si hizo recientemente un cambio de dirección (la clave
new_address:), el módulo puede estar ya en la nueva dirección. Añadascan: true, localice el dispositivo, actualiceaddress:en consecuencia y eliminenew_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:
[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:
-
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. -
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). -
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:
[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:
[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:
- Apagón de escritura en flash. El módulo está escribiendo un modelo de CT (activado por
ct_model:oct_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. - 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ó.
- 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:
[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:
- 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).
- 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.
- 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:
- El módulo está en una dirección desconocida. Use un YAML de prueba con
i2c: scan: truey un corte de alimentación: encuentre en qué dirección responde el módulo. - Si el módulo aparece en la nueva dirección (por ejemplo 0x51), actualice el YAML a
address: 0x51, eliminenew_address:y vuelva a grabar. El siguiente arranque será limpio. - 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:
[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):
-
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. -
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.
-
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.
: 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:
[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:tienefrequency: 100kHz: cámbielo a50kHz. - La versión del componente es anterior al 2026-05-24: actualícela.
Fix:
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.
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 mantenerfrequency: 100kHzsin 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, entoncesfrequency: 50kHzes obligatorio. Es la configuración en la que el síntoma fantasma del driveri2c_masterse 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:
[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:
- 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).
- Abra el YAML y compruebe que
ct_model:(oct_models:para UI3) coincide con el modelo de pinza físico. - Si
ct_model:está definido en firmware v1.2+ perosensor_class:se omite o tiene un valor distinto deSCT_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:
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:
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.
# 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
Calibración y precisión (resolución de problemas) · 7.5 Conservación del periodo tras un snapshot fallido (referencia de la API)
Lo que ve:
[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:
- 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 (unupdate_intervaldespués del arranque) es la primera que integra. La energía empieza a acumularse tras el primerupdate_intervalcompleto desde el arranque. - 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.
- 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
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:
- 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.
- 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. - Cambio de la disposición de particiones. Grabar un
partitions.csvnuevo que cambie el tamaño o la posición de la particiónnvsinvalida todos los valores guardados. - 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:
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh
Si está presente, la restauración no encontró nada. Además:
[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:
- 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.
- 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 elct_model:del YAML coincide con la pinza física instalada en el conductor. - 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:
- 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. -
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:
ShellpingSi 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).
-
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. - 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:
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed
Causas habituales:
- 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:. -
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 modeFuerce un arranque limpio: mantenga pulsado el botón BOOT al encender, o añada
safe_mode: num_attempts: 10para ampliar el umbral. -
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. - 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 compilepor 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:
-
Edite el YAML:
YAMLrbamp: 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 -
Ejecute
esphome run(por CLI) o Compilar + Subir (mediante el complemento de HA). El nodo recibe el binario nuevo por WiFi OTA. -
Abra
esphome logsy confirme que el mensaje de arranquedump_configmuestra la dirección correcta y queupdate()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:
'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/). Es un cambio cosmético y opcional.
PlatformIO se cierra con 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)
Lo que ve:
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):
# 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:
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:
# 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:
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:
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.
# 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):
text_sensor:
- platform: template
name: "Meter variant"
lambda: 'return id(my_meter).get_variant_str();' # → "UNK" in HA
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK
Qué significa:
-
"UNK": el componente no pudo leerREG_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 de0x55..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_sensorsigue publicando; use una indicación en el lado del YAML mediantetopology: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:
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ábricaclear_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:
[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:
-
Un código fuera del conjunto aceptado: para
SCT_013los códigos aceptados son{1, 2, 3, 4, 5, 6, 7}. -
Modelo de CT fuera del conjunto permitido para la clase, por ejemplo
WIRED_CT_1consensor_class: SCT_013. Véase la tabla por clase de 03_sensor_selection.md. -
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.
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:
[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:
[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):
[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:
- Elimine la causa (sustituya el código de modelo de CT incorrecto, corrija el YAML).
write_clear_error()— esta llamada borraREG_ERRORy el bit3 deEVENT_FLAGSen 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)