01 · Visión general
Qué es rbAmp
rbAmp es un módulo hardware compacto para la medición de precisión de parámetros de la red de CA. Desde el punto de vista del integrador es un esclavo I²C corriente: se alimenta, se lee un registro y se obtiene un valor listo para usar en unidades físicas. No hace falta procesado de señal en el lado del maestro. La calibración de fábrica se realiza una vez en producción y se guarda en la flash del módulo; al usuario solo le queda elegir el modelo de pinza de CT (véase 03_sensor_selection.md) y cablear el bus.
Flujo de datos (en una línea)
La característica clave: las magnitudes físicas llegan del módulo listas para usar. En el lado del ESP32 no hay procesado de señal, ni tablas de calibración, ni cálculo de RMS/potencia. El componente de ESPHome es un cliente I²C ligero, un acumulador de energía y una capa de publicación hacia HA. No se necesita matemática de lambda: para el funcionamiento básico.
rbAmp en el ecosistema ESPHome
Si ya ha usado los medidores de energía integrados (pzemac por UART, atm90e32 por SPI, cse7766 por UART), esto sigue exactamente la misma estructura. El componente rbamp es un «buen ciudadano» de ESPHome: usa el transporte estándar i2c:, la sintaxis estándar sensor.platform: rbamp, las ranuras de sensor estándar con device_class / state_class / unit_of_measurement, y admite el conjunto completo de filtros y propiedades de sensor.
Compare la anatomía (el modelo mental es idéntico):
# ATM90E32 (SPI meter) — shown for comparison only, not part of an rbAmp config:
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: atm90e32
cs_pin: GPIO5
voltage_a:
name: "Mains Voltage"
power_a:
name: "Mains Power"
# rbAmp (I²C meter) — a separate file, do not paste both:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current: # power needs voltage AND current declared
name: "Mains Current"
power:
name: "Mains Power"
Las únicas diferencias son el transporte (i2c: en lugar de spi:) y el hecho de que rbamp: se declara como bloque independiente (necesita un id: + address: para un bus de varios módulos). Lo demás es ESPHome estándar: los nombres de ranura (voltage, current, power, energy, frequency, power_factor) son reconocibles, y la personalización (name, update_interval, accuracy_decimals, filters:) funciona como de costumbre. Para un ejemplo de personalización detallado, vea 06_examples.md §1.1 «UI1 con personalización — todos los ajustes estándar de ESPHome».
Despliegue canónico: una flota de varios módulos
El caso de uso principal de rbAmp en ESPHome es la monitorización de varias cargas desde un único maestro ESP32. Una vivienda, un taller o un cuadro suele tener una acometida principal y varios ramales: una caldera, un aire acondicionado, un VE, habitaciones individuales. Un UI1 de rbAmp se coloca en la acometida y cuenta la potencia y la energía totales; varios módulos rbAmp I2/I3 se colocan en los ramales y solo cuentan las corrientes de cada canal.
Todos los módulos viven en un único bus I²C del ESP32, cada uno con su dirección del rango 0x50..0x77. El componente soporta MULTI_CONF = True, así que un único archivo YAML puede declarar varios bloques rbamp: y publicarlos todos como conjuntos de entidades independientes en Home Assistant.
En este escenario el ESP32 es el único maestro: emite un broadcast de snapshot de llamada general compartido cuando fleet_gc_enable: true, y todos los módulos inician de forma atómica un nuevo periodo de acumulación en un único instante del bus. Esto da una sincronización estrecha entre submedidores: las sumas de los canales coinciden con las de la alimentación dentro de la duración de un único periodo.
Una configuración de un solo módulo (UI1 en la red, sin submedidores) es el caso mínimo, no el canon. En v1.3 ambas son válidas; la configuración de varios módulos se recomienda en el primer capítulo de la documentación, porque el 80 % de los despliegues de campo son exactamente ese caso.
Lo que mide
| Magnitud | Ranura YAML | Rango | Precisión típica |
|---|---|---|---|
| Tensión RMS | voltage |
0..300 V | ±0.5% |
| Corriente RMS (por canal) | current / current_1 / current_2 |
0..100 A (según el SKU) | ±0.5..1% (módulo) |
| Potencia activa (con signo) | power / power_1 / power_2 |
±23 kW | ±1% (módulo) |
| Factor de potencia (con signo) | power_factor / power_factor_1 / power_factor_2 |
−1..+1 | ±0.01 con FP ≈ 1 (carga resistiva) con sensores SCT-013 de 10 A o más; el desfase propio del sensor de 5 A añade hasta ~0.015 de error de lectura: una carga puramente resistiva lee ~0.985–0.993 |
| Potencia reactiva (sin signo, √(S² − P²), incluye distorsión; sin precisión declarada) | reactive_power / reactive_power_1 / reactive_power_2 |
igual que P | — |
| Potencia aparente | apparent_power (solo CH0; para CH1/CH2 use un sensor de plantilla de HA, véase Integraciones DIY §6) |
igual que P | ±2% |
| Frecuencia de red | frequency |
50 / 60 Hz (detectado en BASIC) | — |
| Energía acumulada (Wh) | energy / energy_1 / ... (por canal); energy_total / energy_exported_total / energy_net (STANDARD (STD), todos los canales) |
64-bit | depende de la precisión de P |
| Energía reactiva (varh) | reactive_energy / reactive_energy_exported (STANDARD) |
64-bit | — |
Estas son las cifras propias del módulo. Lo que se lee es el módulo más el sensor que se instala, así que el total depende del sensor y de su potencia nominal: los suelos detectables, los suelos legibles y las clases de precisión por potencia nominal para la familia SCT-013 se publican en la tabla de precisión de BASIC. Los módulos con sensor CT emparejado de fábrica, y los módulos STD, se especifican por separado allí.
Hay ranuras para hasta siete canales de corriente (current_3 ... current_6 y los power_N, energy_N, power_factor_N correspondientes en las variantes de más canales).
Todas las magnitudes instantáneas las actualiza el módulo de forma autónoma con un paso de ~100 ms. En los módulos BASIC la acumulación de Wh la hace el ESP32 a partir de la potencia media que devuelve el módulo en el intervalo entre dos llamadas a update(); en los módulos STANDARD el componente acumula los contadores de energía del propio módulo. El componente de ESPHome oculta estos protocolos: el usuario solo ve sensores listos para usar en Home Assistant.
Lo que añade el componente de ESPHome
- Sensores de HA listos para usar: cada ranura ya tiene definidos su
device_class,state_classy unidades. El sensorenergyaparece de inmediato en el panel de energía, sin configuración manual. - Un único YAML para ambas líneas de módulos: al arrancar, el componente identifica si hay un módulo BASIC o STANDARD conectado y toma el número de canales, la variante y las funciones del propio módulo.
topology:no hace falta. Las claves que solo se aplican a una generación se ignoran con una línea de registro en la otra. - Energía en el dispositivo (STANDARD) — el módulo mantiene sus propios contadores acumulados; el componente los acumula, así que los totales sobreviven a reinicios tanto del ESP32 como del módulo y se mantienen monótonos. Sensores de total general:
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported.start_current_ua:fija la corriente por debajo de la cual un canal no cuenta energía. - Persistencia en NVS de Wh: la energía total se escribe en la flash del ESP32 cada 5 minutos (y al apagar limpiamente, de modo que un reinicio u OTA no pierda el último intervalo) y se restaura antes del primer
publish_state. Home Assistant nunca ve un cero momentáneo tras un reinicio ni lo interpreta como un reinicio del contador. - Configuración declarativa de sensores: dos líneas YAML (
sensor_class:+ct_models:para UI3, oct_model:para UI1) fijan la familia y el modelo de CT de cada canal. El módulo carga automáticamente los coeficientes de fábrica: no hay pasos de calibración en la secuencia de arranque. - Programación del sondeo mediante
PollingComponent::update()con unupdate_intervalconfigurable (60 s por defecto). - Cadencias de lectura RT y de snapshot desacopladas (v1.4+) — la clave opcional
latch_interval:permite que el ciclo de snapshot → integración de Wh funcione a su propia cadencia, mientras queupdate_interval:sigue controlando con qué frecuencia el componente ESPHome lee el bloque de tiempo real V/I/P/PF/Q. Uso típico:update_interval: 3s+latch_interval: 60s— valores frescos en el panel cada 3 s, carga de snapshot en el bus solo una vez por minuto. La integración de energía no añade error propio más allá de la precisión de la potencia activa del módulo (la integración en el lado del maestro usa el dt de tiempo de pared real entre eventos de snapshot). - Resistencia a NACK — está implementada una disciplina en tres capas: 50 kHz por defecto, reintento por byte y un filtro de cordura para NaN/Inf. Detalles más abajo.
- Aprovisionamiento de dirección en un solo paso: la clave
new_address:cambia la dirección I²C del módulo en un único ciclo de arranque. En firmware v1.3 funciona en modo de producción sin protección por aprovisionamiento de fábrica (confirmación de dirección en dos fases, detectada automáticamente). Es útil para la configuración en serie de un lote de dispositivos tras instalarlos en un cuadro. - Bus de varios módulos —
MULTI_CONF = Truepermite declarar varios bloquesrbamp:en un mismo ESP32 y sondearlos todos por turnos. - Sincronización GC de flota (v1.3) — la clave
fleet_gc_enable: trueactiva la recepción del broadcast de snapshot GC desde el ESP32. Todos los módulos con esta marca y ungroup_id:coincidente inician un nuevo periodo a la vez. Condicionado por capacidad; en firmware antiguo registra una advertencia y omite sin aplicar. Solo módulos BASIC. - Superficie de identidad (v1.3) — los métodos públicos
get_variant_str()/get_capability_hex()/get_uid_hex()/get_firmware_version()/get_last_error_str()son accesibles desde unlambda:y a través de untext_sensor.platform: template. Le permiten mostrar en HA la variante actual del módulo (UI1/UI3/I2…), el mapa de capacidades, el UID y la versión de firmware. - Arranque leer-comparar-escribir (v1.3):
sensor_class:/ct_model:/ct_models:solo se escriben en flash si el valor solicitado difiere del almacenado. La reescritura de configuración al arrancar baja de ~2.8 s (instalación en frío de UI3) a ~0 ms con una configuración estable. El antiguo consejo de «eliminect_model:del YAML tras verificar» ya no vale: la configuración es idempotente. - Protección de la calibración de fábrica (v1.8.1+): en un módulo calibrado en pareja con su propio sensor integrado (
WIRED_CT/BUILTIN_CT), un cambio de clase o de modelo desde el YAML se rechaza con una línea de registro. La opción de servicioct_model_force: truelo anula de forma deliberada. - El cambio de rango del SCT mantiene la precisión (v1.9): al seleccionar otro rango de SCT-013 mediante
ct_model:, se conserva la calibración individual de fábrica: en firmware hasta la 1.4.19 el componente completa el cambio con el reinicio necesario del módulo y escala las lecturas; los firmware más nuevos lo hacen en el módulo.
Arquitectura
El motor de medida reside en el módulo; el ESP32 actúa como puente hacia HA. En los módulos BASIC, los Wh se integran en el ESP32 contra su propio reloj, lo que mantiene la acumulación coherente entre varios módulos. Los módulos STANDARD conservan sus propios contadores de energía acumulada y el ESP32 los acumula.
Flujo de datos dentro de un único update()
La descripción siguiente corresponde al flujo BASIC. En un módulo STANDARD la rama instantánea es la misma; la rama de período se sustituye por una única lectura coherente de los contadores de energía del módulo, cuya diferencia con la instantánea anterior se suma a los totales acumulados (sin paso de instantánea).
Cada llamada update() en un módulo BASIC ejecuta dos ramas en paralelo:
Rama 1 — valores instantáneos (bloque RT)
- Compruebe el registro de estado. Si el módulo está ocupado (arranque, apagón por escritura en flash), omita sin escribir.
- Para cada sensor RT declarado, lea un float32 del registro correspondiente.
- Filtro de cordura
std::isfinite()— descarta NaN/Inf, que pueden surgir de desgarros al leer registros no atómicos. sensor->publish_state(val).
En firmware v1.3 el bloque de valores instantáneos (U / I / P / PF / Q de todos los canales declarados) se obtiene en una única lectura en ráfaga con autoincremento en LECTURA: una fase de dirección seguida de los bytes del bloque. Si la lectura en ráfaga falla o el firmware no soporta la capacidad, el componente recurre a lecturas por registro (4 transacciones por float, cada una con su propia fase de dirección). El autoincremento en ESCRITURA no está soportado; las escrituras por registro siempre van byte a byte.
Rama 2 — medición por periodos (acumulación de energía)
- Registre
t_latch = millis(). - Envíe el comando de instantánea: cierra el período de acumulación actual y abre el siguiente de inmediato. Una sola transacción cierra y abre; no se pierde ninguna muestra en el límite.
- Tras 50 ms (tiempo de espera no bloqueante), lea el indicador de validez. Si el módulo aún no ha terminado de integrar (sondeo más rápido que el período de integración, o una instantánea obsoleta), omita: el siguiente ciclo recogerá el intervalo perdido.
- Lea la potencia activa media del período para cada canal.
E_Wh[ch] += avg_p_W[ch] × (t_latch − last_latch_ms_) / 3_600_000.- Actualice
last_latch_ms_solo tras un éxito en todos los canales. - Guardar en NVS si han pasado más de 5 minutos desde el último guardado.
El primer snapshot tras el arranque reinicia el acumulador del módulo y calibra el reloj maestro; su resultado se descarta mediante el indicador primed_.
Persistencia de la energía en NVS
Los valores acumulados se guardan en la estructura RbAmpPrefData (total por canal para hasta siete canales + exportación por canal para los canales 0..2):
struct RbAmpPrefData {
double energy_total_wh[7];
double energy_export_wh[3];
} __attribute__((packed));
En los módulos STANDARD los acumuladores de total general y reactivos (energy_total, energy_exported_total, reactive_energy*) residen en una segunda ranura NVS separada, de modo que una actualización no altera los valores por canal. Ambas ranuras se escriben cada 5 minutos y al apagar limpiamente (reinicio / OTA).
La clave NVS se deriva del ID del componente combinado mediante XOR con RBAMP_PREF_VERSION (0x52424D31 = «RBM1»). Si la estructura cambia alguna vez, incrementar la constante de versión descarta silenciosamente los datos obsoletos en lugar de interpretarlos mal.
Al arrancar, setup() restaura los totales antes del primer update(). Si el componente publicara primero 0 Wh y luego saltara al valor guardado, Home Assistant interpretaría el salto como un reinicio de contador e iniciaría un nuevo segmento de historial. Restaurar antes de la primera publicación lo evita.
La frecuencia de guardado depende de dos condiciones:
- Por tiempo: cada 5 minutos (
SAVE_INTERVAL_MS = 300000). - Por evento: tras cada ciclo completo de integración correcto (todos los canales leídos sin NACK) y al apagarse limpiamente.
La peor pérdida de datos ante un corte de alimentación repentino del ESP32 son 5 minutos de energía acumulada. Con una carga media de 60 W, son 5 Wh, por debajo de la resolución de la barra diaria del panel de energía.
Desgaste de NVS: ¿puede «desgastarse» la flash?
Cada guardado escribe unos 16 bytes en la sección NVS del ESP32. La capa NVS del ESP-IDF agrupa las escrituras pequeñas en un único bloque y borra una página (4 KB) solo cuando el bloque está lleno. Con un ciclo de 5 minutos:
| Métrica | Valor |
|---|---|
| Ahorro por día | 288 |
| Guardados por año | ~105120 |
| Tamaño de escritura | ~16 bytes |
| Tamaño de página NVS | 4096 bytes |
| Borrados de página por año | ~411 (≈ 105120 × 16 ÷ 4096) |
| Límite de ciclos de borrado (hoja de datos de la flash NOR del ESP32) | 100000 ciclos |
| Tiempo hasta el fallo (TTF) | ~240 años por página NVS |
La NVS del ESP-IDF además realiza nivelación de desgaste entre las páginas NVS disponibles (la partición por defecto tiene 4 páginas), lo que multiplica el TTF por ~4×. La conclusión práctica: el desgaste de la NVS con un ciclo de guardado de 5 minutos no es un factor limitante; el hardware quedará obsoleto antes.
Cuándo merece la pena reducir la frecuencia: si un usuario fuerza SAVE_INTERVAL_MS por debajo del valor por defecto (por ejemplo 30 s) mediante código propio, recalcule el TTF con la misma fórmula. Un límite inferior seguro para 10 años de funcionamiento es ~30 s.
Disciplina frente a NACK
Las placas ESP32 que ejecutan el driver i2c_master de ESP-IDF v5 (que usan ESPHome, arduino-esp32 v3.x y MicroPython en ESP32) hacen NACK periódicamente a las lecturas del módulo a 100 kHz, en aproximadamente un 20 % de las transacciones. El mismo módulo, pero con otro maestro (por ejemplo otro MCU de 32 bits o una Raspberry Pi), da 0 % de NACK. Así que el problema está en el lado del maestro, no en el módulo. Los detalles están en la referencia de la API, bajo «Disciplina eléctrica I²C».
Hay una segunda complicación: cuando i2c_master_transmit_receive() devuelve ESP_FAIL por un NACK, el driver IDF v5 no pone a cero el búfer del usuario. Los datos de la transacción anterior permanecen. Algunos de esos patrones obsoletos parecen floats plausibles (por ejemplo 0x3C 0x2F 0xFB 0x3F → 1.962 V) y superan una comprobación ingenua de isfinite().
El componente implementa tres capas de mitigación:
| Capa | Implementación | Efecto |
|---|---|---|
| Bus a 50 kHz por defecto | frequency: 50kHz en el bloque YAML i2c: |
Reduce la tasa de NACK ~5× de forma empírica |
| Reintento por byte | 3 intentos, pausa de 5 ms, en cada byte de cada float32 | Borra un NACK transitorio antes de usar los datos |
| Filtro de sanidad relajado | std::isfinite() sin límites físicos estrictos |
Detecta NaN/Inf/denormales del búfer obsoleto; deja pasar valores límite válidos (caída de tensión, desconexión) |
Con las tres capas activas, el componente logra más del 99 % de lecturas válidas en el banco de pruebas a la frecuencia recomendada de 50 kHz. El firmware v1.1 y v1.3 reforzó la ventana de recuperación I²C del módulo, pero 50 kHz sigue siendo el ajuste recomendado en maestros basados en ESP-IDF, porque la interacción de temporización del controlador persiste a 100 kHz.
La familia de bibliotecas de rbAmp
Este componente es un miembro de la familia multiplataforma de bibliotecas cliente de rbAmp. Todas implementan el mismo protocolo de cable (referencia de la API).
| Plataforma | Repositorio |
|---|---|
| ESPHome (este componente) | rb-amp/rbamp-esphome |
| Arduino / arduino-esp32 | rb-amp/rbamp-arduino |
| ESP-IDF | rb-amp/rbamp-esp-idf |
| Python (CPython + MicroPython) | rb-amp/rbamp-python |
Todas las bibliotecas usan las mismas convenciones de cable: escrituras byte a byte con lectura en ráfaga opcional, la misma máquina de estados de snapshot de medición por periodos, la misma detección de variante SKU al arrancar y los mismos códigos REG_ERROR. El código de cualquiera de estas plataformas se porta a otra con una traducción sintáctica mecánica: la lógica del protocolo es idéntica. Vea 09 · Referencia de la API para el mapa de registros canónico.
SKU compatibles
| Variante | Canal de tensión | Canales de corriente | Potencia | Ranuras de ESPHome disponibles |
|---|---|---|---|---|
| UI1 | sí | 1 | sí | voltage, current, power, energy, frequency, power_factor, reactive_power, apparent_power |
| UI2 | sí | 2 | sí | + current_1, power_1, energy_1, power_factor_1, reactive_power_1 |
| UI3 | sí | 3 | sí | + current_2, power_2, energy_2, power_factor_2, reactive_power_2 |
| I1 | no | 1 | no | current, frequency |
| I2 | no | 2 | no | + current_1 |
| I3 | no | 3 | no | + current_2 |
Los módulos con más de una entrada de tensión usan en su lugar las ranuras con fases (voltage_a/b/c, current_a/b/c, ...); véase 09 §2.2. Los dos grupos no pueden mezclarse en un mismo bloque sensor:.
En las variantes solo de corriente, las ranuras power, energy y power_factor requieren una ranura voltage declarada (lo comprueba el validador del esquema): decláralas solo en los SKU UI*.
Lo que viene después
- 02_tiers.md: las líneas de módulos BASIC / STANDARD (STD) y qué claves YAML están disponibles en cada una
- 03_sensor_selection.md — elección de la pinza CT y comportamiento de las claves
ct_model:/ct_models: - 04_hardware.md: pinout de GPIO, pull-ups, el bus de varios módulos
Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/01_overview.md (v1.9.1)