06 · Recetario YAML
Este capítulo abre con los escenarios principales, los patrones de despliegue reales para los que se diseñó el componente en v1.3 (red + N subcargas en un mismo bus con sincronización fleet_gc_enable, flujo de aprovisionamiento, mixto multicanal con CT y sincronización GC de flota). Después vienen los escenarios de un solo módulo, desde un UI1 mínimo hasta un despliegue de producción con automatizaciones de HA.
Cada ejemplo es autónomo: cópielo, rellene el nombre de su placa y las credenciales Wi-Fi, compile y grabe. Allí donde un ejemplo se aparta de la plantilla mínima, una explicación le indica por qué.
Cross-references:
- Esquema de componente, mapa de registros, protocolo de medición por período, topología de varios módulos, sincronización GC de flota y la regla de NACK de sanidad relajada: 09 · Referencia de la API
| # | Escenario | Topología | Cuándo usarlo |
|---|---|---|---|
| 1 | Red + N subcargas: el canon del 80 % | UI1 + N× I2/I3 | Medición de toda la vivienda con desglose por subramales |
| 2 | Flujo de aprovisionamiento (virgen → flota) | secuencial, único | Puesta en marcha de un lote nuevo de módulos |
| 3 | Mixto multicanal con CT (UI3 con pinzas distintas) | UI3 | Medición de cargas mixtas con optimización de precisión |
| 4 | Sincronización GC de flota (sincronía estricta) | N× UI/I | Clústeres multiinquilino y submedición |
| 5 | UI1: monocanal (mínimo) | UI1 | Hola mundo con un solo módulo |
| 6 | UI1 con personalización | UI1 | Todos los parámetros estándar de ESPHome |
| 7 | UI3 — tres canales con pinzas mixtas | UI3 | Un solo módulo multicanal |
| 8 | Bus de varios módulos (sincronización GC) | N× UI/I | fleet_gc_enable + group_id en tres módulos |
| 9 | Cambio de dirección I²C único | único | Aprovisionamiento de un solo módulo |
| 10..20 | Integraciones y automatizaciones de HA | mixto | Patrones de despliegue en producción |
| 21 | Módulo STANDARD (STD): totales de energía en el propio dispositivo | cualquiera | Totales generales, energía reactiva, start_current_ua: |
| 22 | Cambio del rango del SCT: ct_model_force |
cualquiera | Cambio de potencia nominal sin perder precisión |
Los escenarios 1-4 son los principales, orientados al despliegue canónico v1.3 del paquete. Su código usa fleet_gc_enable + superficie de identidad + lectura-comparación-escritura, y se prueba en una configuración heterogénea UI1+I2+I3. Los escenarios 5-22 son patrones de un solo módulo y compactos. El escenario 8 es la configuración corta de bus de tres módulos.
1 · Red + N subcargas (el canon del 80 %): sistema de medición integrado
Objetivo: el despliegue canónico del paquete — un sistema de medición coherente en una flota heterogénea, cerrado dentro de un único arranque de ESPHome (descubrimiento → configurar → activar GC → bucle[publish_state + tick GC de emisión automática]).
Hardware (montaje de pruebas UI1 + I2 + I3): UI1@0x50 + I2@0x51 + I3@0x52; carga de ~0.58 A; pull-ups según la fila de 3 módulos de la tabla de 04_hardware.md (corte de todos, un par externo de 2.7–3.3 kΩ).
esphome:
name: home-fleet
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three rbAmp modules on shared bus, all with fleet_gc_enable + group_id=1
# for synchronized period snapshots (tight sync between mains + sub-meters).
rbamp:
- id: mains_meter # UI1 on the mains feed
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: boiler_meter # I2 on the boiler + washing machine
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
- id: panel_meter # I3 on the distribution-panel branches
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power", id: mains_power_state }
power_factor: { name: "Mains PF" }
energy: { name: "Mains Energy" }
frequency: { name: "Mains Frequency" }
- platform: rbamp
rbamp_id: boiler_meter
# I2 is a current-only module: it has no voltage input, so it reports currents only
# (power and energy need a UI module with voltage).
current: { name: "Boiler Current" } # 20A CT
current_1: { name: "Washer Current" } # 10A CT
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # 5A CT
current_1: { name: "Appliances Current" } # 30A CT
current_2: { name: "Sub-panel Current" } # 20A CT
# Optional: template sensor for the household power (same sensor: list, not a second sensor: key)
- platform: template
name: "Household Total Power"
update_interval: 60s
accuracy_decimals: 0
unit_of_measurement: "W"
device_class: power
lambda: |-
// Sum of power from the mains meter only (sub-meters are a subset of the same mains)
auto v = id(mains_power_state);
return v.has_state() ? v.state : 0.0f;
Salida de ejemplo (carga de ~0.58 A)
[I][i2c:136]: Found i2c device at address 0x50
[I][i2c:136]: Found i2c device at address 0x51
[I][i2c:136]: Found i2c device at address 0x52
[C][rbamp:450]: mains_meter: variant=UI1, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: boiler_meter: variant=I2, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: panel_meter: variant=I3, capability=0x…, fleet_gc=on, group=1
[I][rbamp:493]: GC latch enabled fleet-wide: 3 modules in group 1
ITER 1 @ 60s: GC tick=1, 3/3 in_sync
mains: V=232.6 I=5.79 P=1259 W E_total: 0 → 0.35 Wh
boiler: I=[11.58, 3.87] ; current-only
panel: I=[3.84, 2.55, 5.84] ; current-only
Notas de uso
-
Un solo bucle sincronizado — todo el sistema. En cada tick de
update_interval, el ESP32 emite una trama GC a 0x00 → los 3 módulos toman un snapshot de sus acumuladores de periodo en el mismo instante del bus (validado 3/3 in_sync bajo carga). -
mains_poweren una flota heterogénea = la potencia activa de UI1 (mains_meter). Los submedidores (I2/I3) solo miden corriente, sin P canónica. En el canon del 80 %,mains_power≈ la potencia total de todas las cargas (mains_meter cubre la alimentación). -
Los Wh en módulos BASIC se integran en el ESP32 contra su propio reloj (el tiempo entre snapshots), así que todos los módulos de la flota comparten una misma base temporal. Los módulos STANDARD mantienen sus propios contadores de energía, que el componente acumula.
-
Tolerante a fallos (MISS). Si un módulo sale del bus (aprovisionamiento / corte de alimentación), el resto sigue funcionando; HA muestra «No disponible» para sus entidades hasta que se recupere.
2 · Flujo de aprovisionamiento (virgen → flota)
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference)
Objetivo: el procedimiento canónico de puesta en marcha de módulos nuevos, desde la 0x50 de fábrica hasta las direcciones únicas de la flota. Demuestra el commit de dirección en dos fases (v1.3 apta para producción) y la disciplina obligatoria de «un solo virgen en el bus a la vez».
Paso 2.1 — aprovisionar la red UI1 (0x50 → 0x50, sensor_class + ct_model)
# Connect ONLY the UI1 to the bus. Flash this YAML.
rbamp:
- id: provisioning_target
address: 0x50
# new_address not needed — 0x50 is already fine for UI1
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: provisioning_target
voltage: { name: "Provision UI1 Voltage" }
current: { name: "Provision UI1 Current" }
text_sensor:
- platform: template
name: "Provision UI1 variant"
update_interval: 5s
lambda: 'return id(provisioning_target).get_variant_str();'
- platform: template
name: "Provision UI1 UID"
update_interval: 5s
lambda: 'return id(provisioning_target).get_uid_hex();'
- platform: template
name: "Provision UI1 capability"
update_interval: 5s
lambda: 'return id(provisioning_target).get_capability_hex();'
Comprobación: en HA debe ver sensor.provision_ui1_variant == "UI1" + sensor.provision_ui1_capability mostrando un mapa de bits hexadecimal distinto de cero ("0x0000" indica firmware antiguo). Anote el UID para el inventario.
Paso 2.2 — aprovisionar I2 (0x50 → 0x51 mediante commit en dos fases)
Desconecte el UI1 del bus (si no habrá conflicto de dirección). Conecte el módulo I2. Grabe el YAML actualizado:
rbamp:
- id: provisioning_target
address: 0x50 # virgin address
new_address: 0x51 # ⚠ two-phase commit — production-OK on v1.3
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
Qué ocurre al arrancar:
[I][rbamp:xxx]: provisioning_target: probe at 0x50 → OK (variant=I2)
[I][rbamp:xxx]: provisioning_target: new_address=0x51 requested
[I][rbamp:xxx]: provisioning_target: two-phase address change supported → production path
[D][rbamp:xxx]: provisioning_target: stage REG_I2C_ADDRESS=0x51
[D][rbamp:xxx]: provisioning_target: write REG_ADDR_COMMIT_MAGIC=0xA5
[D][rbamp:xxx]: provisioning_target: send CMD_COMMIT_ADDR → wait 700ms
[I][rbamp:xxx]: provisioning_target: re-probe 0x51 → OK, re-enumeration complete
[I][rbamp:xxx]: provisioning_target: i2c address handle updated to 0x51
Tras el éxito: actualice el YAML a address: 0x51 y elimine new_address:. El siguiente arranque no ejecutará el flujo de cambio.
Paso 2.3 — aprovisionar I3 (0x50 → 0x52) + repetir con el resto
Mismo patrón que 2.2: desconecte el I2, conecte el I3 virgen, grabe el YAML con new_address: 0x52, espere la reenumeración y actualice el YAML a address: 0x52.
🛑 OBLIGATORIO: un solo módulo virgen en el bus a la vez. Si dos módulos vírgenes están ambos en 0x50, ambos responderán en la fase de dirección y pelearán por SDA → estado indeterminado, y ningún procedimiento de aprovisionamiento funcionará.
Paso 2.4 — montar la flota
Cuando termine el aprovisionamiento de todos los módulos, actualice el YAML a la configuración final de la flota (véase el escenario §1 más arriba), desactive los pull-ups internos de todos los módulos (3 módulos = corte todos) y añada un par externo de 2.7–3.3 kΩ en el ESP32 — véase la tabla de pull-up de 04_hardware.md. Grabe el YAML final: todos los módulos deberían descubrirse:
[D][i2c:136]: Found i2c device at address 0x50
[D][i2c:136]: Found i2c device at address 0x51
[D][i2c:136]: Found i2c device at address 0x52
Modos de fallo (aprovisionamiento)
| Síntoma | Causa | Recuperación |
|---|---|---|
Probe failed at 0x50 tras grabar |
Módulo sin alimentación o contacto roto | Compruebe la conectividad de VCC + GND + SDA + SCL |
[W] cambio de dirección en dos fases no soportado |
Módulo con firmware heredado (v1.0-v1.2) | El respaldo monofásico requiere el modo de aprovisionamiento de fábrica (vea 04_hardware.md) |
[E] address change committed but re-probe at 0x51 failed |
Bus marginal o confirmación abortada | Reintente el arranque; si se repite, el pull-up externo es demasiado débil o hay una ráfaga de EMI |
[W] WARN_FACTORY_MODE_REQUIRED |
Firmware heredado sin cambio de dirección en dos fases | El proveedor activa el modo de fábrica (fuera del alcance de la biblioteca) |
3 · Multicanal con CT mixtas (UI3 con pinzas distintas)
Objetivo: mostrar que el modelo de CT en distintos canales de un solo módulo puede mezclarse según la característica de carga. El componente asigna los canales uno a uno; el orden no importa.
rbamp:
- id: panel_meter
address: 0x52
sensor_class: SCT_013
# Mixed-CT: small/medium/large on channels 0/1/2
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# The component binds channels one by one; the order does not matter.
# Each channel keeps its own model: ch0 = 5 A, ch1 = 30 A, ch2 = 20 A
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Panel Lighting (5A CT)" } # ch0
current_1: { name: "Panel Appliances (30A CT)" } # ch1
current_2: { name: "Panel Boiler (20A CT)" } # ch2
# No voltage / power — this is an I3 SKU, current-only
text_sensor:
- platform: template
name: "Panel last error"
update_interval: 30s
lambda: 'return id(panel_meter).get_last_error_str();'
# → "OK" in a healthy state; "ERR_PARAM" if a CT model code is rejected
Verificar la vinculación del modelo de CT al arrancar
Tras grabar y arrancar, en el log:
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH0 mirror = 1 (SCT_013_005)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH1 mirror = 3 (SCT_013_030)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH2 mirror = 6 (SCT_013_020)
[I][rbamp:xxx]: panel_meter: CT binding verified, all mirrors match YAML request
[C][component:246]: Setup panel_meter took ~2100ms (cold install: 3 × 700ms flash + verify)
En un arranque en caliente (las copias coinciden), sin escritura en flash:
[I][rbamp:xxx]: panel_meter: CT_MODEL[0..2] match YAML → SKIP flash erase
[C][component:246]: Setup panel_meter took 72ms (warm boot: read-compare only)
Comportamiento observado
- Vinculación de CT mixta: los códigos [1, 3, 6] en un módulo de tres canales en 0x52 se mantienen cada uno en su propio canal.
-
Rechazo de códigos no válidos: un intento con un código fuera del conjunto aceptado por la clase →
esphome configrechaza el esquema (cv.Invalid). Si el YAML se cuela por el validador (edición manual / compilación heredada), el firmware devuelveREG_ERROR = 0xFE DEV_ERR_PARAM, dejando el espejo con su valor anterior. -
Tiempo de instalación en frío: ~2.1 s en la UI3 (3 × ~700 ms de borrado de flash).
- Tiempo de arranque en caliente: ~70 ms (la lectura-comparación-escritura omite todo el borrado de flash).
- Medición de latencia: ~1.4 s desde el inicio de
setup()hasta la primera publicación (banco de pruebas).
4 · Sincronización GC de flota (sincronía estrecha)
Objetivo: demostrar que la sincronización de flota 3/3 no es académica, sino un requisito real para despliegues multiinquilino (submedición de apartamentos en un cuadro compartido) y para una submedición precisa (la red de UI1 debe coincidir con la suma de las potencias de los submedidores, dentro de la duración de un único periodo).
# Fleet config — all modules in one group for synchronized snapshots:
rbamp:
- id: tenant1_mains
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: tenant1_panel
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
- id: tenant2_mains # Independent tenant (separate group)
address: 0x52
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 2 # ⚠ different group → independent sync timeline
# Native API services for manual sync verification:
api:
port: 6053
services:
- service: emit_gc_tenant1
then:
- lambda: 'id(tenant1_mains).transmit_gc_frame();' # group = tenant1_mains group_id
- service: emit_gc_tenant2
then:
- lambda: 'id(tenant2_mains).transmit_gc_frame();' # group = tenant2_mains group_id
- service: check_sync_all
then:
- lambda: |-
uint16_t t1m = id(tenant1_mains).read_gc_tick_received();
uint16_t t1p = id(tenant1_panel).read_gc_tick_received();
uint16_t t2m = id(tenant2_mains).read_gc_tick_received();
ESP_LOGI("rbamp", "GC tick state: tenant1[mains=%u, panel=%u] tenant2[mains=%u]",
t1m, t1p, t2m);
text_sensor:
- platform: template
name: "Tenant1 GC tick (mains)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_mains).read_gc_tick_received());'
- platform: template
name: "Tenant1 GC tick (panel)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_panel).read_gc_tick_received());'
Salida de ejemplo (prueba de sincronización de 10 iteraciones)
[I][rbamp:572]: GC frame emit: group=1, tick=42, all 2 tenant1 modules ACK'd
[I][rbamp:580]: check_sync: tenant1_mains.tick=42 tenant1_panel.tick=42 → 2/2 in_sync
[I][rbamp:572]: GC frame emit: group=2, tick=42, tenant2 module ACK'd
[I][rbamp:580]: check_sync: tenant2_mains.tick=42 → 1/1 in_sync (tenant2 isolated)
ROUND 0: GC tick=1 → tenant1[1, 1] tenant2[1] → 3/3 in_sync
ROUND 1: GC tick=2 → tenant1[2, 2] tenant2[2] → 3/3 in_sync
ROUND 2: GC tick=3 → tenant1[3, 3] tenant2[3] → 3/3 in_sync
...
ROUND 9: GC tick=10 → tenant1[10,10] tenant2[10] → 3/3 in_sync
L8 soak: 180 cycles, 0 sync drops, 0 identity drops
Cómo ayuda group_id en entornos multiinquilino
Sin group_id no hay separación de inquilinos: todos los módulos reaccionan a cualquier fotograma GC. Con group_id:
- Los módulos del inquilino 1 responden solo a fotogramas GC con
group=1(o a la llamada generalgroup=0) - Los módulos del inquilino 2 responden solo a fotogramas GC con
group=2
Esto permite que el maestro emita tramas GC separadas para los inquilinos en momentos independientes, por ejemplo, por periodo de inquilino:
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
automation:
- alias: "Tenant 1 period snapshot"
trigger:
platform: time_pattern
seconds: "/60" # every 60 s
action:
- service: esphome._emit_gc_tenant1
- alias: "Tenant 2 period snapshot"
trigger:
platform: time_pattern
seconds: "/15" # every 15 s (high-resolution tenant)
action:
- service: esphome._emit_gc_tenant2
Validación en producción
- Sensor template de HA"mains_minus_subsum" — un indicador de discrepancia:YAML
sensor: - platform: template name: "Mains - SubSum (W)" update_interval: 60s unit_of_measurement: "W" lambda: |- // here the sub-meters are current-only, so this is a rough estimate: // mains_power - sum(sub_currents × V_mains) float v_mains = id(mains_voltage_state).state; float sub_i = id(sub_i0).state + id(sub_i1).state + id(sub_i2).state; return id(mains_power_state).state - sub_i * v_mains;
Una discrepancia < 1 % de mains_power en el banco = sincronización correcta.
- Integración por reloj de pared: incluso con la sincronización GC 3/3, los módulos BASIC se integran con el reloj propio del ESP32, de modo que un pequeño desfase entre módulos no distorsiona los Wh.
5 · UI1 — canal único (mínimo)
Fuente: ../example/ui1.yaml
La configuración más útil y sencilla: un canal de tensión, un canal de corriente y seis magnitudes derivadas de ellos. Un punto de partida para cualquier instalación nueva: amplíela con más campos según haga falta.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32; 100 kHz causes periodic NACKs due to ESP-IDF i2c_master driver interaction;
# 50 kHz reduces them ~5-10× — see the chapter end link.
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
ct_model: SCT_013_030 # CT clamp model — change it to match yours
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
Qué demuestra: la configuración mínima viable. Los seis sensores cubren el caso principal: medición de toda la vivienda o de una sola carga. El sensor energy ya tiene definidos device_class: energy + state_class: total_increasing, así que entra directamente en el panel de energía de HA sin configuración adicional. El protocolo de medición por período (instantánea / asentamiento de 50 ms / lectura de la potencia media, integrada con el reloj del maestro) está documentado en 09 · Referencia de la API.
6 · UI1 con personalización: todos los parámetros estándar de ESPHome
rbAmp es un componente ESPHome «buen ciudadano». Cada ranura (voltage, current, power, …) es un objeto sensor: ordinario de ESPHome. Funciona todo el conjunto estándar de propiedades y filtros. No necesita lambda: ni plantillas personalizadas: todo lo que hace con pzemac / atm90e32 / cse7766 funciona aquí exactamente igual. El ejemplo muestra las personalizaciones más habituales en un solo bloque:
esphome:
name: rbamp-ui1-tuned
esp32:
board: esp32dev
framework:
type: arduino
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 10s # ↑ Poll once / 10 s instead of the default 60 s —
# a denser graph, ~6× the I²C traffic.
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
# ──────────── Customizing names + precision + filters ────────────
voltage:
name: "Mains voltage" # Any name — it becomes the HA entity_id
accuracy_decimals: 1 # 226.7 instead of the default 226.70
filters:
# Linear calibration against a reference multimeter:
- calibrate_linear:
- 0.0 -> 0.0
- 230.0 -> 230.5
# Smoothing of sharp spikes (standard ESPHome):
- exponential_moving_average:
alpha: 0.3
send_every: 1
current:
name: "Load current"
accuracy_decimals: 3 # 0.755 instead of 0.75
filters:
# Mask the noise floor — drop values below 50 mA (50 mW at 230 V).
# The equivalent of the `noise_floor` option in pzemac / cse7766.
- lambda: 'return x < 0.05 ? 0.0f : x;'
power:
name: "Power"
accuracy_decimals: 1
filters:
# Throttle publications: no more than once / 30 s, even with update_interval 10 s.
- throttle: 30s
energy:
name: "Energy (Wh)"
# The standard device_class: energy + state_class: total_increasing
# are already set by the component — the Energy dashboard works.
filters:
# Convert Wh → kWh for a more familiar scale in Lovelace.
# (The HA Energy dashboard itself expects Wh, but if you want a graph in kWh,
# declare a second template sensor with a division rather than changing units here.)
- multiply: 0.001
unit_of_measurement: "kWh" # ← overrides the default "Wh"
accuracy_decimals: 3
frequency:
name: "Mains frequency"
accuracy_decimals: 2
power_factor:
name: "Power factor"
accuracy_decimals: 3
# Optional: a filter to hide PF at zero load (P ~ 0)
filters:
- lambda: 'return isnan(x) ? 0.0f : x;'
Qué demuestra:
-
Nombres personalizados (
name:) se convierten en elentity_idde HA; por ejemplo,sensor.rbamp_ui1_tuned_mains_voltage. Funcionan nombres en cualquier idioma, incluido el cirílico. -
Precisión de salida (
accuracy_decimals:) es independiente del módulo; el módulo devuelve float32 con la máxima precisión, y ESPHome lo trunca para la interfaz. -
update_interval:no hace falta cambiarlo por sensor: es una propiedad del componente (PollingComponent), definida una vez en el bloquerbamp:. Si quiere publicaciones menos frecuentes de sensores concretos, añadafilters: - throttle:. -
filters:— el conjunto completo de ESPHome: -
calibrate_linear: calibración puntual frente a su referencia (multímetro, amperímetro de referencia). -
exponential_moving_average/sliding_window_moving_average— suavizado. lambda: una transformación arbitraria (máscara de suelo de ruido, cero condicional).multiply/offset: aritmética (por ejemplo, Wh → kWh).throttle/delta: reducir la frecuencia de publicación.-
unit_of_measurement:puede sustituirse (por ejemplo, porkWhconmultiply: 0.001). HA recoge la nueva unidad automáticamente. -
Sin
lambda:para el funcionamiento básico: todos los cálculos de RMS, potencia, frecuencia y FP los hace el módulo. El ESP32 solo renombra, da formato y filtra.
⚠ No anule device_class: para energy: el panel de energía de HA espera estrictamente device_class: energy + state_class: total_increasing. La conversión de unidades mediante multiply + unit_of_measurement: mantiene la compatibilidad, pero cambiar el device_class romperá el panel.
La lista completa de propiedades y filtros estándar de sensor está en la documentación oficial de ESPHome Sensor Component. Esa documentación es plenamente aplicable a las ranuras de rbAmp: no hay desviaciones respecto al estándar.
7 · UI3 — tres canales con pinzas mixtas
Fuente: ../example/ui3.yaml
El SKU UI3 tiene una entrada de tensión y tres canales de corriente independientes. El escenario canónico es poner modelos de pinza distintos en canales distintos: una pinza pequeña en consumidores de baja corriente (para máxima resolución) y una grande en la alimentación principal (margen para los picos).
esphome:
name: rbamp-ui3
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
# drdy_pin: GPIO15
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby consumers and LED lighting,
# CH1=30A for the main household loads,
# CH2=20A for the boiler / a medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A).
sensor:
- platform: rbamp
rbamp_id: meter1
# Common (topology-independent)
voltage:
name: "Mains Voltage"
frequency:
name: "Mains Frequency"
apparent_power:
name: "CH0 Apparent Power"
# Channel 0 — primary current input (small consumers, 5A)
current:
name: "CH0 Current"
power:
name: "CH0 Power"
energy:
name: "CH0 Energy"
power_factor:
name: "CH0 Power Factor"
reactive_power:
name: "CH0 Reactive Power"
# Channel 1 — main loads (30A)
current_1:
name: "CH1 Current"
power_1:
name: "CH1 Power"
energy_1:
name: "CH1 Energy"
power_factor_1:
name: "CH1 Power Factor"
reactive_power_1:
name: "CH1 Reactive Power"
# Channel 2 — boiler / medium-power branch (20A)
current_2:
name: "CH2 Current"
power_2:
name: "CH2 Power"
energy_2:
name: "CH2 Energy"
power_factor_2:
name: "CH2 Power Factor"
reactive_power_2:
name: "CH2 Reactive Power"
Qué demuestra: los tres canales del SKU UI3 + modelos de pinza mixtos mediante ct_models:. El validador del esquema comprueba que power_N y energy_N (y power_factor_N, reactive_power_N) requieren current_N y voltage: si declara power_1 sin current_1, la compilación falla con un mensaje claro. Cada canal tiene su propio acumulador energy_* persistido en NVS. Si todos los canales usan el mismo modelo de pinza, use el ct_model: global en lugar de ct_models:.
8 · Bus de varios módulos (tres rbAmp en 0x50 / 0x51 / 0x52)
Fuente: ../example/multi_module.yaml
Tres módulos en un mismo bus I²C: la alimentación principal de la casa, la salida de generación solar y la carga del VE. Cada uno tiene su propio bloque rbamp: (en el esquema del componente, MULTI_CONF = True).
esphome:
name: rbamp-multi
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended: at 100 kHz the ESP-IDF i2c_master driver interaction causes periodic
# NACKs are almost inevitable on every cycle
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three independent rbamp: blocks — MULTI_CONF = True in the schema.
# On v1.3 firmware the general-call snapshot is opt-in via fleet_gc_enable +
# group_id (capability-gated on the firmware side). Modules in the same
# group snapshot in a single transaction, with ~540 µs skew per module. On legacy
# firmware (v1.0..v1.2) the component falls back to a sequential snapshot
# and logs an informational line. (The old broadcast_latch: key is still
# accepted by the schema but has no effect.)
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
fleet_gc_enable: true
group_id: 1
- id: meter_solar
address: 0x51
update_interval: 60s
fleet_gc_enable: true
group_id: 1
bidirectional: true # needed for energy_exported_*; on BASIC it
# publishes 0, on STANDARD it is real export energy
- id: meter_evcharger
address: 0x52
update_interval: 60s
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
current:
name: "House Current"
power:
name: "House Power"
energy:
name: "House Energy"
frequency:
name: "Mains Frequency"
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true # hidden from HA — the same mains as House Voltage
current:
name: "Solar Current"
power:
name: "Solar Power"
energy:
name: "Solar Energy"
energy_exported:
name: "Solar Energy Exported"
- platform: rbamp
rbamp_id: meter_evcharger
voltage:
name: "EV Charger Voltage"
internal: true
current:
name: "EV Charger Current"
power:
name: "EV Charger Power"
energy:
name: "EV Charger Energy"
Qué demuestra: el patrón MULTI_CONF = True. Declare tantos bloques rbamp: como módulos tenga en el bus. Cada uno mantiene su propio acumulador NVS, cuya clave se deriva de la dirección I²C, de modo que los tres contadores son independientes tras los reinicios. El indicador internal: true en los sensores de tensión duplicados oculta en HA las tres entidades de tensión de red casi idénticas cuando todos los módulos miden la misma fase. Para el procedimiento de asignación de direcciones, véase el Ejemplo 2 más abajo.
Semántica de internal: true. El indicador no desactiva la lectura del registro del módulo: el componente sigue leyendo la tensión de cada módulo en cada update_interval (es necesario para el cálculo de potencia). El indicador solo oculta el sensor de la API de Home Assistant: no se crea ninguna entidad, no aparece en Lovelace y no cuenta en el panel de energía. Si quiere reducir el tráfico I²C, no declare la ranura voltage: bajo sensor.platform: rbamp: el componente entonces no consulta el registro. Si la declara, el indicador internal: es puramente cosmético.
Hay una segunda restricción relativa a la unicidad de la dirección en el bus:
⚠ Las direcciones únicas son responsabilidad de la configuración. El esquema del componente (MULTI_CONF = True) no valida solapamientos de valores address: entre bloques rbamp:. Si dos bloques especifican la misma address: 0x50, ambas declaraciones se aceptan y en el bus responderán los dos destinos a la vez: espere conflictos I²C, respuestas corruptas o síntomas parecidos a un módulo ausente. Antes de confirmar el YAML, compruebe que todos los valores address: son únicos (y que no chocan con otros dispositivos I²C del bus). Tras cada aprovisionamiento con new_address:, actualice la sección rbamp: a la nueva dirección: la entrada antigua no se invalida automáticamente.
Pull-ups en un bus de varios módulos
Los tres módulos salen de fábrica con pull-ups de 4.7 kΩ. En un bus de tres módulos, la combinación en paralelo es ~1.6 kΩ: mayor consumo de corriente e integridad de señal marginal a 50 kHz. Corte los puentes de soldadura de pull-up en los tres módulos y coloque un par externo de 2.7–3.3 kΩ junto al ESP32 (la fila de 3 módulos de la tabla de 04_hardware.md).
Avanzado: cadencia de instantánea desacoplada para flotas de varios módulos (v1.4+)
Las instalaciones de flota pagan el coste del ciclo de snapshot por módulo y por ciclo: en un bus de 3 módulos sondeado con update_interval: 10s, son 3× la escritura del snapshot + 3× la ventana de estabilización de 50 ms cada 10 s, más las lecturas del bloque RT encima. En hosts ESP8266 (un solo núcleo; las ISR de WiFi compiten por la CPU durante las transacciones I²C) o en buses I²C compartidos con otros dispositivos, esa sobrecarga se hace visible como fallos de WiFi o lecturas obsoletas en entidades que no son de rbAmp.
latch_interval: (disponible desde v1.4, módulos BASIC) desacopla las dos cadencias: las lecturas del bloque en tiempo real (V/I/P/PF/Q) se mantienen en update_interval:, de modo que el panel sigue mostrando valores frescos, mientras que la integración instantánea → Wh solo se ejecuta cada latch_interval:. La integración usa el tiempo real de reloj de pared entre eventos de instantánea, así que un intervalo de instantánea de 60 s produce pasos de integración de 60 s de ancho (y siguen siendo correctos). latch_interval debe ser ≥ update_interval.
rbamp:
- id: mod_mains
address: 0x50
update_interval: 10s # dashboard: fresh V/I/P/PF every 10 s
latch_interval: 60s # bus: snapshot + Wh integration once a minute
ct_models: [SCT_013_050, SCT_013_030, SCT_013_030]
fleet_gc_enable: true
group_id: 1
- id: mod_branches
address: 0x51
update_interval: 10s
latch_interval: 60s
ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
fleet_gc_enable: true
group_id: 1
Reducción de carga del bus frente a la misma flota sin latch_interval:: con update_interval: 10s, cada módulo aporta ~15 ms de lectura RT + ~65 ms de snapshot+estabilización por ciclo → ~80 ms por módulo y ciclo. Con latch_interval: 60s, el snapshot+estabilización se dispara solo una vez por minuto → las lecturas RT siguen siendo baratas cada 10 s + una ráfaga corta de snapshot cada 60 s, aproximadamente un ciclo de bus medio 3 veces menor. Las flotas más grandes ven ahorros proporcionalmente mayores.
Cuándo omitir latch_interval:: despliegues de un solo módulo en hosts ESP32 donde la carga base no cuesta nada; el valor por defecto de cadencia única de v1.3 es más sencillo y igual de correcto.
9 · Cambio de dirección I²C único (0x50 → 0x51)
Fuente: ../example/address_change.yaml
Todos los módulos rbAmp salen de fábrica con la dirección 0x50. Para colocar varios módulos en un bus, debe reflashear cada uno con su propia dirección única antes de conectarlos en paralelo.
esphome:
name: rbamp-addr-change
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG # DEBUG shows the address-change lines
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50 # current address — before the change
new_address: 0x51 # one-time target — DELETE this line after success
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "rbAmp Voltage (post-relocate)"
current:
name: "rbAmp Current (post-relocate)"
Qué demuestra: el flujo de cambio de dirección único. Grabar este YAML hace que el componente ejecute el procedimiento una vez en el arranque:
-
Sondee
0x50. Si0x50está en silencio y0x51ya responde, el cambio se aplicó en un arranque anterior; el componente se adapta y registra una advertencia pidiendo que limpie el YAML. -
Compruebe que el módulo está listo para aceptar una operación de aprovisionamiento.
-
Escriba la nueva dirección en flash (~700 ms), un reinicio blando (~300 ms) y vuelva a sincronizarse con el ciclo de CA.
-
Confirme en la nueva dirección. Si tiene éxito — el log
Address change confirmed at 0x51yIMPORTANTE: actualice el YAML a address: 0x51 y elimine new_address:.
Compatibilidad de firmware: en firmware v1.3 o posterior, el cambio de dirección es apto para producción: el componente usa el protocolo de commit en dos fases (preparar → armar → confirmar → reiniciar) sin necesidad de modo especial. En firmware antiguo (v1.0-v1.2), el respaldo monofásico requiere el modo de aprovisionamiento de fábrica; consulte la documentación del módulo o a su proveedor para el procedimiento de activación temporal.
Tras el éxito: edite el YAML a address: 0x51 y elimine la línea new_address: 0x51. Grabe de nuevo. A partir del siguiente arranque, el componente usa 0x51 con normalidad y el procedimiento de cambio ya no se ejecuta.
Lista de comprobación para revertir tras un aprovisionamiento correcto
Para no dejar una variante de aprovisionamiento «colgada» en el repositorio (dos alternativas, nunca pegue ambas en el mismo archivo):
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# AFTER (production — applied next flash):
rbamp:
id: meter1
address: 0x51 # ← replaced with the new address
# new_address: 0x51 # ← DELETE the line (do not comment it out)
update_interval: 60s
Exactamente tres cambios:
- Cambie el valor de
address:del antiguo al nuevo. - Elimine (no comente) la línea
new_address:. - Vuelva a grabar por OTA o USB.
Tras el paso 3, el registro debe mostrar una línea dump_config normal sin el aviso address change requested but current address matches new_address, lo que indica que la reversión fue correcta. Véase también 10_troubleshooting §4 «La OTA justo después del aprovisionamiento con new_address: no carga» si la primera OTA tras la reversión no arranca.
10 · Configuración de banco de pruebas con secrets
Fuente: ../example/bench-ui1.yaml
El patrón bench-*.yaml es para equipos de desarrollo donde las credenciales Wi-Fi deben estar en la configuración pero no deben acabar en un commit. example/.gitignore excluye bench-*.yaml y secrets.yaml del control de versiones.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
web_server:
port: 80
version: 3 # optional: a local HTTP UI — handy for bench testing
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
El secrets.yaml correspondiente (en example/, sin seguimiento):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Qué demuestra: separar las credenciales de tiempo de compilación del YAML versionado mediante !secret de ESPHome. Incluir bench-*.yaml en .gitignore le permite conservar cuantas variantes de banco quiera sin riesgo de filtración. Use esphome run --device 192.168.0.173 example/bench-ui1.yaml para OTA tras la primera conexión de red, o esphome run --device COM6 example/bench-ui1.yaml para la primera grabación por USB.
11 · Caída de tensión y pérdida de la red
Cuando se interrumpe la alimentación de red, la interfaz analógica aislada del módulo deja de recibir señal. El registro de tensión cae a 0.0 V: un float IEEE 754 finito y válido que pasa el filtro de cordura isfinite() del componente. La política de filtrado del componente es intencionada:
Sin límites físicos inferiores: la caída de tensión (U=0 V al desconectar la red), la bajada de tensión, la prueba fuera de red / SAI y el disparo del interruptor DEBEN llegar a HA, para que el usuario vea el estado real.
No hace falta YAML especial para detectar una pérdida de red: el propio sensor de voltage lee 0.0 V.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # reads 0.0 V when mains is disconnected
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
Automatización de HA: alerta por pérdida de red
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
# configuration.yaml or the Automations UI
automation:
- alias: "rbAmp mains loss alert"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_voltage
below: 10 # U < 10 V = mains disconnected or a severe brownout
for:
seconds: 5 # debounce: sustained, not transient
action:
- service: notify.mobile_app_your_phone
data:
title: "Mains power lost"
message: >
Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V
at {{ now().strftime('%H:%M:%S') }}.
Qué demuestra: usar el comportamiento de paso de 0 V como fuente de un evento de «pérdida de red». Como el componente publica 0.0 V en lugar de omitir la publicación, las automatizaciones de HA y el panel de energía ven el evento de caída de tensión en tiempo real. La condición for: 5 seconds bloquea los disparos falsos durante el calentamiento de ~250 ms al arrancar (cuando los registros leen 0 antes de la primera medida válida).
12 · Panel de energía de HA
El sensor energy (y energy_1, energy_2, energy_exported, etc.) se configura automáticamente con device_class: energy y state_class: total_increasing, exactamente lo que espera el panel de energía de HA para sensores de consumo o generación acumulados. No hace falta YAML adicional.
Tras el descubrimiento:
- Ajustes → Paneles → Energía (Settings → Dashboards → Energy).
-
Añadir consumo → elija «Mains Energy» (o la entidad de medición de importación que desee).
-
Si tiene solar: Añadir producción → elija Solar Energy (desde
meter_solaren el ejemplo de varios módulos).
Los valores de energía están en Wh. HA los convierte a kWh para mostrarlos. La persistencia NVS del componente garantiza que el acumulador sobreviva a un reinicio del ESP32 sin un falso «reinicio de contador» en las estadísticas de HA.
# Example: consumption + solar export for the HA Energy dashboard
# (assumes the rbamp: blocks meter_house and meter_solar from the multi-module example)
# energy / energy_exported need voltage AND current in the same block;
# internal: true keeps them out of Home Assistant.
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
internal: true
current:
name: "House Current"
internal: true
energy:
name: "House Grid Import" # → HA Energy: grid consumption
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true
current:
name: "Solar Current"
internal: true
energy:
name: "Solar Production" # → HA Energy: solar production
energy_exported:
name: "Solar Grid Export" # → HA Energy: return to grid
# needs bidirectional: true in rbamp:;
# real values on STANDARD (STD) modules,
# reads 0 on BASIC
13 · Automatizaciones de HA sobre los sensores de rbAmp
8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
Desconexión de carga: un relé se desactiva cuando se supera un umbral
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
automation:
- alias: "Load shedding — turn off non-critical loads at 3 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
above: 3000 # 3 kW threshold
for:
seconds: 10
action:
- service: switch.turn_off
target:
entity_id: switch.ev_charger_relay # the non-critical load relay
- alias: "Load shedding — restore when it drops below 2 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
below: 2000
for:
seconds: 30
action:
- service: switch.turn_on
target:
entity_id: switch.ev_charger_relay
Recordatorio sobre la corrección del factor de potencia
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
automation:
- alias: "Poor power factor notification"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_power_factor
below: 0.7
for:
minutes: 5
action:
- service: persistent_notification.create
data:
title: "Low power factor"
message: >
Power factor is {{ states('sensor.rbamp_ui1_mains_power_factor') }}.
Check for large inductive loads (motors, old lighting ballasts).
Alerta por exceso del presupuesto diario
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
automation:
- alias: "Daily energy budget — warning at 10 kWh"
trigger:
- platform: template
value_template: >
{{ states('sensor.energy_daily') | float(0) > 10000 }}
action:
- service: notify.mobile_app_your_phone
data:
message: "Daily energy usage exceeded 10 kWh."
14 · Tarjetas Lovelace
Medidor — potencia en vivo
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 3600
name: "Live Power"
segments:
- from: 0
color: green
- from: 1500
color: orange
- from: 2500
color: red
Apex Charts — potencia a lo largo del tiempo
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
type: custom:apexcharts-card
header:
title: "Power (W)"
show: true
graph_span: 4h
series:
- entity: sensor.rbamp_ui1_mains_power
name: Power
stroke_width: 2
curve: smooth
Apex Charts — comparación de energía entre tres canales
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
type: custom:apexcharts-card
header:
title: "Channel Energy (Wh)"
show: true
graph_span: 24h
series:
- entity: sensor.rbamp_ui3_ch0_energy
name: CH0
- entity: sensor.rbamp_ui3_ch1_energy
name: CH1
- entity: sensor.rbamp_ui3_ch2_energy
name: CH2
Minigráfico: tensión
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
type: custom:mini-graph-card
entities:
- sensor.rbamp_ui1_mains_voltage
name: "Mains Voltage"
hours_to_show: 12
points_per_hour: 4
line_width: 2
15 · Contador de servicio — agregación por día / semana / mes
ESPHome publica totales acumulados en Wh. La integración utility_meter de HA reinicia el contador en intervalos configurables y publica la diferencia como sensor aparte: útil para desgloses diarios o mensuales.
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
# configuration.yaml
utility_meter:
energy_daily:
source: sensor.rbamp_ui1_mains_energy
cycle: daily
name: "Daily Energy"
energy_monthly:
source: sensor.rbamp_ui1_mains_energy
cycle: monthly
name: "Monthly Energy"
energy_weekly:
source: sensor.rbamp_ui1_mains_energy
cycle: weekly
name: "Weekly Energy"
HA crea tres entidades: sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Cada una se pone a 0 al inicio de su periodo correspondiente y acumula la diferencia del sensor de origen total_increasing.
Sensor derivado de kWh/día
utility_meter emite Wh por defecto. Para mostrarlo en kWh, añada un sensor template:
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
template:
- sensor:
- name: "Daily Energy kWh"
unit_of_measurement: "kWh"
state_class: total_increasing
device_class: energy
state: >
{{ (states('sensor.energy_daily') | float(0) / 1000) | round(3) }}
Sensor de coste diario
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
template:
- sensor:
- name: "Daily Energy Cost"
unit_of_measurement: "EUR"
icon: mdi:currency-eur
state: >
{% set kwh = states('sensor.energy_daily') | float(0) / 1000 %}
{% set rate = 0.28 %} # EUR/kWh — set your own tariff
{{ (kwh * rate) | round(2) }}
16 · Submedición por carga (3 módulos en 0x50 / 0x51 / 0x52)
Instalar tres módulos rbAmp en un cuadro de distribución le permite medir la energía por circuito sin cuadro inteligente ni hardware adicional.
YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.
# Extending the multi-module example with per-circuit utility meters
utility_meter:
kitchen_daily:
source: sensor.rbamp_multi_house_energy
cycle: daily
name: "Kitchen Circuit Daily"
solar_monthly:
source: sensor.rbamp_multi_solar_energy
cycle: monthly
name: "Solar Production Monthly"
ev_daily:
source: sensor.rbamp_multi_ev_charger_energy
cycle: daily
name: "EV Charging Daily"
Combinado con el panel de energía de HA, obtiene extractos mensuales por circuito sin cálculos de kWh × tarifa.
17 · rbAmp + un relé — control en lazo cerrado
Una caldera con control por relé
# ESPHome YAML on the same ESP32 as rbAmp
switch:
- platform: gpio
pin: GPIO5
id: heater_relay
name: "Water Heater"
Con rbAmp y un relé en el mismo ESP32 puede construir un bucle cerrado dentro de ESPHome (mediante una Lambda o on_value), sin pasar por HA:
Supone que ya tiene una entrada switch: con el id usado abajo.
sensor:
- platform: rbamp
rbamp_id: meter1
power:
name: "House Power"
on_value:
then:
- if:
condition:
lambda: 'return x > 3000.0f;'
then:
- switch.turn_off: heater_relay
else:
- switch.turn_on: heater_relay
Qué demuestra: usar el callback on_value de un sensor rbAmp para controlar un relé sin intervención de HA. El callback se dispara en el ESP32 cada update_interval (60 s) y actualiza el estado del relé con la última lectura de potencia. Para un control más ajustado (un bucle < 60 s), reduzca update_interval a 10s: esto aumenta la carga del bus I²C en proporción. Un ejemplo de lazo cerrado más completo para una caldera está en 07_diy_integrations.md.
18 · Integración de DRDY
El pin DRDY de drenador abierto del módulo da un pulso LOW de ~10 µs cada ~100 ms tras actualizar los registros instantáneos. Puede conectarlo a un GPIO del ESP32. El componente registra el pin DRDY; las lecturas las dirige un temporizador (update_interval).
rbamp:
id: meter1
address: 0x50
update_interval: 60s # energy integration still happens every 60 s
drdy_pin:
number: GPIO15
mode:
input: true
pullup: true # DRDY is open-drain; it needs a pull-up
inverted: true # the DRDY pulse is LOW; inverted=true gives a rising edge
: en el firmware actual el componente registra drdy_pin en dump_config, pero no implementa lecturas RT dirigidas por interrupción: el update_interval sigue fijando la frecuencia de sondeo.
19 · Sensores con fases (variantes bifásicas / trifásicas)
Para los módulos con más de una entrada de tensión, el componente ofrece un grupo de sensores con fases (voltage_a/b/c, current_a/b/c, power_a/b/c, energy_a/b/c, power_factor_a/b/c, reactive_power_a/b/c, power_total, además de voltage_angle_b/c). Una ranura solo publica cuando el módulo conectado informa del canal correspondiente; en un módulo de una sola tensión, las ranuras con fases quedan sin valor. El esquema comprueba que los grupos individuales y con fases no se mezclen en un mismo bloque sensor:.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage_a:
name: "Phase A Voltage"
voltage_b:
name: "Phase B Voltage"
voltage_c:
name: "Phase C Voltage"
current_a:
name: "Phase A Current"
current_b:
name: "Phase B Current"
current_c:
name: "Phase C Current"
power_a:
name: "Phase A Power"
power_b:
name: "Phase B Power"
power_c:
name: "Phase C Power"
power_total:
name: "Total Power"
voltage_angle_b:
name: "Phase B Angle" # degrees vs phase A
voltage_angle_c:
name: "Phase C Angle"
phase_sequence:
name: "Phase Sequence" # 1 forward, 2 reverse, 3 abnormal
frequency:
name: "Grid Frequency"
Qué demuestra: el grupo de campos con fases. Mezclar campos individuales y con fases en un mismo bloque sensor: produce un error de compilación: elija el grupo que corresponde a su módulo. Los detalles están en 09 · Referencia de la API, §2.2.
20 · Migración desde otros componentes de medición de ESPHome
Desde pzem004t
La plataforma pzem004t exporta los mismos nombres de campo que rbamp para las magnitudes de CA habituales. El cambio es bloque por bloque, con nombres de sensor idénticos:
# Before (pzem004t, UART)
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
sensor:
- platform: pzem004t
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
Los campos name: idénticos dan entity IDs idénticos en HA. El historial del panel de energía se conserva tras el cambio: el sensor total_increasing continúa donde lo dejó. Elimine el bloque uart: si no se comparte con otro componente.
Desde cse7766 (Sonoff POW R2)
Mismo patrón. cse7766 proporciona voltage, current, power, energy, power_factor, apparent_power — todos presentes en rbamp. Sustituya platform: cse7766 por platform: rbamp, añada rbamp_id: meter1, elimine uart: y añada i2c: y el bloque rbamp:.
21 · Módulo STANDARD: totales de energía en el propio dispositivo
En un módulo STANDARD el componente acumula los contadores de energía del propio módulo. Los totales sobreviven a los reinicios tanto del ESP32 como del módulo y se mantienen monótonos. El mismo YAML funciona también con un módulo BASIC, salvo que las claves de total general nunca publican.
rbamp:
id: meter1
address: 0x50
update_interval: 30s
bidirectional: true # per-channel energy_exported
start_current_ua: 400 # no energy counted below 400 µA per channel
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy_total:
name: "Energy Imported" # all channels, total_increasing
energy_exported_total:
name: "Energy Exported" # all channels, total_increasing
energy_net:
name: "Energy Net" # import - export, may decrease
reactive_energy:
name: "Reactive Energy Imported" # varh
reactive_energy_exported:
name: "Reactive Energy Exported"
Qué demuestra: los sensores de total general, que no necesitan una declaración complementaria de current/voltage; start_current_ua: (0 = desactivado, en otro caso 10..2540 en pasos de 10) para que el ruido en vacío no se cuele en los contadores de importación y exportación (las lecturas instantáneas no se ven afectadas). Para el panel de energía de HA use energy_total como consumo de red y energy_exported_total como retorno a la red.
22 · Cambio de la potencia nominal de la SCT y anulación de servicio
rbamp:
id: meter1
ct_model: SCT_013_010 # module was delivered with the SCT-013-030
Las lecturas siguen siendo precisas tras el cambio: en firmware de módulo hasta la 1.4.19 el componente completa la escritura del modelo con el reinicio necesario del módulo (visible en el registro) y escala la corriente, la potencia y la energía al sensor seleccionado; los firmware más nuevos lo hacen en el módulo. Un valor que el módulo ya tiene no se vuelve a escribir, y en un módulo suministrado calibrado junto con su propio sensor integrado (sensor_class: WIRED_CT / BUILTIN_CT) el cambio se rechaza con una línea de registro. Solo para un reaplicado deliberado del preajuste:
rbamp:
id: meter1
ct_model: SCT_013_010
ct_model_force: true # one-off service option; remove both lines afterwards
Resumen de las reglas de validación del YAML
| Regla | Aplicado por |
|---|---|
power / energy / power_factor / reactive_power requieren current |
Validador del esquema (_SINGLE_SLOT_DEPS) |
P/Q/PF/E de cualquier canal requieren voltage |
Validador del esquema |
Los grupos individuales y con fases no se mezclan en un mismo sensor: |
_validate_topology_consistency |
new_address ≠ address |
_validate_new_address |
address en el rango 0x08..0x77 |
cv.i2c_address |
update_interval mínimo 1s, aplicado |
Validador del esquema |
latch_interval ≥ update_interval |
Validador del esquema |
ct_model: y ct_models: son mutuamente excluyentes |
Validador del esquema |
ct_models: tiene de 1 a 16 entradas |
Validador del esquema |
ct_model_force: true requiere ct_model: o ct_models: |
Validador del esquema |
start_current_ua es 0 o 10..2540 en pasos de 10 |
Validador del esquema |
El código de modelo de CT es válido para el sensor_class fijado |
Validador del esquema |
Los errores de validación se notifican en el tiempo de esphome compile con un mensaje legible que señala la clave infractora. No hace falta grabar el hardware para encontrar un error de configuración.
Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/06_examples.md (v1.9.1)