rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub (Edit on GitHub)

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
Nota

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Ω).

YAML
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)

Text
[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_power en 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)

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)

YAML
# 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:

YAML
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:

Text
[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.

Nota

🛑 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:

Text
[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.

YAML
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:

Text
[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:

Text
[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 config rechaza el esquema (cv.Invalid). Si el YAML se cuela por el validador (edición manual / compilación heredada), el firmware devuelve REG_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).

YAML
# 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)

Text
[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 general group=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.

YAML
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.

YAML
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:

YAML
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 el entity_id de 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 bloque rbamp:. Si quiere publicaciones menos frecuentes de sensores concretos, añada filters: - 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, por kWh con multiply: 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.

Seguridad

⚠ 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).

YAML
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).

YAML
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.

Nota

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:

Seguridad

⚠ 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.

YAML
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.

YAML
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:

  1. Sondee 0x50. Si 0x50 está en silencio y 0x51 ya responde, el cambio se aplicó en un arranque anterior; el componente se adapta y registra una advertencia pidiendo que limpie el YAML.

  2. Compruebe que el módulo está listo para aceptar una operación de aprovisionamiento.

  3. Escriba la nueva dirección en flash (~700 ms), un reinicio blando (~300 ms) y vuelva a sincronizarse con el ciclo de CA.

  4. Confirme en la nueva dirección. Si tiene éxito — el log Address change confirmed at 0x51 y IMPORTANTE: 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):

YAML
# BEFORE (provisioning):
rbamp:
  id: meter1
  address: 0x50               # the module's current address
  new_address: 0x51           # the provisioning target
  update_interval: 60s
YAML
# 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:

  1. Cambie el valor de address: del antiguo al nuevo.
  2. Elimine (no comente) la línea new_address:.
  3. 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.

YAML
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):

YAML
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:

Seguridad

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.

YAML
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.

YAML
# 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:

  1. Ajustes → Paneles → Energía (Settings → Dashboards → Energy).
  2. Añadir consumo → elija «Mains Energy» (o la entidad de medición de importación que desee).

  3. Si tiene solar: Añadir producción → elija Solar Energy (desde meter_solar en 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.

YAML
# 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

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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
# 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.

YAML
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.

YAML
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.

YAML
# 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é

YAML
# 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.

YAML
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).

YAML
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
Nota

: 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:.

YAML
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:

YAML
# 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"
YAML
# 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.

YAML
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

YAML
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:

YAML
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)