rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub [Edit on GitHub]

06 · Ricettario YAML

Questo capitolo si apre con gli scenari di riferimento — i modelli di installazione reali per cui il componente è stato progettato nella v1.3 (rete + N carichi secondari su un bus con fleet_gc_enable per la sincronizzazione, flusso di provisioning, misto multi-canale con TA, sincronizzazione GC di flotta). Seguono gli scenari a modulo singolo, da una UI1 minima fino a una installazione di produzione con automazioni HA.

Ogni esempio è autonomo: copiarlo, inserire il nome della scheda e le credenziali Wi-Fi, compilare e flashare. Ove un esempio si discosta dal modello minimo, una spiegazione indica il motivo.

Cross-references:

  • Schema del componente, mappa dei registri, protocollo di misura per periodi, topologia multi-modulo, sincronizzazione GC di flotta e la regola di sanità permissiva per NACK: 09 · Riferimento API
# Scenario Topologia Quando usarlo
1 Rete + N sotto-carichi: il canone dell'80% UI1 + N× I2/I3 Misura dell'intera abitazione con suddivisione per sotto-derivazioni
2 Flusso di provisioning (vergine → flotta) singolo sequenziale Messa in servizio di un nuovo lotto di moduli
3 Misto multi-canale con TA diversi (UI3 con pinze diverse) UI3 Misura di carichi misti con ottimizzazione dell'accuratezza
4 Sincronizzazione GC di flotta (sincronia stretta) N× UI/I Cluster multi-inquilino e sotto-misura
5 UI1 — canale singolo (minimo) UI1 Hello-world a modulo singolo
6 UI1 con personalizzazione UI1 Tutte le opzioni standard di ESPHome
7 UI3 — tre canali con pinze miste UI3 Modulo singolo multi-canale
8 Bus multi-modulo (sincronizzazione GC) N× UI/I fleet_gc_enable + group_id su tre moduli
9 Cambio di indirizzo I²C una tantum singolo Provisioning di un singolo modulo
10..20 Integrazioni e automazioni HA misto Schemi di deployment in produzione
21 Modulo STANDARD (STD) — totali di energia integrati nel dispositivo qualsiasi Totali generali, energia reattiva, start_current_ua:
22 Cambio della portata SCT, ct_model_force qualsiasi Cambio del valore nominale senza perdere accuratezza
Nota

Gli scenari 1-4 sono quelli di punta, mirati al deployment canonico v1.3 del pacchetto. Il loro codice usa fleet_gc_enable + superficie di identità + lettura-confronto-scrittura ed è testato su un setup eterogeneo UI1+I2+I3. Gli scenari 5-22 sono schemi a modulo singolo e compatti. Lo scenario 8 è la breve configurazione a bus a tre moduli.


1 · Rete + N carichi secondari (il canone dell'80%) — sistema di misura integrato

Obiettivo: il deployment canonico del pacchetto — un sistema di misura coerente su una flotta eterogenea, chiuso in un unico avvio ESPHome (discovery → configurazione → abilitazione GC → loop[publish_state + tick GC auto-emesso]).

Hardware (setup di test UI1 + I2 + I3): UI1@0x50 + I2@0x51 + I3@0x52; carico di ~0.58 A; pull-up secondo la riga a 3 moduli della tabella di 04_hardware.md (tagliare tutti, una coppia esterna da 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;

Output di esempio (carico di ~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

Note per l'uso

  • Un unico ciclo sincronizzato — l'intero sistema. A ogni tick di update_interval, l'ESP32 emette un frame GC a 0x00 → tutti e 3 i moduli fanno uno snapshot dei loro accumulatori di periodo nello stesso momento sul filo (validato 3/3 in_sync sotto carico).

  • mains_power in un parco eterogeneo = la potenza attiva da UI1 (mains_meter). I sotto-contatori (I2/I3) misurano solo la corrente, senza una P canonica. Nel canone 80%, mains_power ≈ la potenza totale di tutti i carichi (mains_meter copre l'alimentazione).

  • I Wh sui moduli BASIC sono integrati sull'ESP32 rispetto al proprio clock (il tempo tra gli snapshot), quindi tutti i moduli della flotta condividono una sola base dei tempi. I moduli STANDARD mantengono propri contatori di energia, che il componente accumula.

  • Resiliente alla perdita. Se un modulo esce dal bus (provisioning / ciclo di alimentazione), gli altri continuano a funzionare; HA mostra "Unavailable" [Non disponibile] per le sue entità finché non si riprende.


2 · Flusso di provisioning (vergine → flotta)

Obiettivo: la procedura canonica di messa in servizio per i nuovi moduli, dall'indirizzo di fabbrica 0x50 agli indirizzi unici della flotta. Dimostra il commit dell'indirizzo in due fasi (v1.3 adatto alla produzione) e la disciplina richiesta di "un solo vergine sul bus alla volta".

Passo 2.1 — provisioning UI1 rete (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();'

Verifica: in HA dovrebbero comparire sensor.provision_ui1_variant == "UI1" + sensor.provision_ui1_capability con una bitmap esadecimale diversa da zero ("0x0000" indica firmware legacy). Registrare l'UID per il tracciamento dell'inventario.

Passo 2.2 — provisioning I2 (0x50 → 0x51 tramite commit in due fasi)

Scollega la UI1 dal bus (altrimenti ci sarà un conflitto di indirizzi). Collega il modulo I2. Flasha il YAML aggiornato:

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

Cosa succede all'avvio:

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

Dopo il successo: aggiorna il YAML con address: 0x51 e rimuovi new_address:. Il prossimo avvio non eseguirà il flusso di cambio.

Passo 2.3 — provisioning I3 (0x50 → 0x52) + ripetizione per gli altri

Stesso schema di 2.2: scollegare I2, collegare I3 vergine, flashare il YAML con new_address: 0x52, attendere la rienumerazione e aggiornare il YAML a address: 0x52.

Nota

🛑 DEVE: un solo modulo vergine sul bus alla volta. Se due moduli vergini sono entrambi su 0x50, entrambi risponderanno nella fase di indirizzo e pilateranno SDA l'uno contro l'altro → stato indeterminato, e nessuna procedura di provisioning funzionerà.

Passo 2.4 — assemblare la flotta

Una volta completato il provisioning di tutti i moduli, aggiorna il YAML alla configurazione di flotta finale (vedi scenario §1 sopra), disabilita i pull-up interni su tutti i moduli (3 moduli = tagliali tutti) e aggiungi una coppia esterna da 2.7–3.3 kΩ sull'ESP32 — vedi la tabella dei pull-up in 04_hardware.md. Flasha il YAML finale — tutti i moduli dovrebbero essere rilevati:

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

Modalità di errore (provisioning)

Sintomo Causa Ripristino
Probe failed at 0x50 dopo il flash Modulo non alimentato oppure contatto difettoso Verifica la connettività di VCC + GND + SDA + SCL
[W] cambio di indirizzo in due fasi non supportato Modulo con firmware legacy (v1.0-v1.2) Il fallback monofase richiede la modalità di provisioning di fabbrica (vedere 04_hardware.md)
[E] address change committed but re-probe at 0x51 failed Bus marginale o commit interrotto Ripetere l'avvio; se si ripete, il pull-up esterno è troppo debole oppure c'è un burst EMI
[W] WARN_FACTORY_MODE_REQUIRED Firmware legacy senza cambio indirizzo in due fasi Il fornitore abilita la modalità di fabbrica (fuori dallo scopo della libreria)

3 · Misto multi-canale con TA diversi (UI3 con pinze diverse)

Obiettivo: mostrare che il modello TA su canali diversi di un singolo modulo può essere misto secondo la caratteristica del carico. Il componente associa i canali uno per uno; l'ordine non conta.

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

Verifica del binding del modello TA all'avvio

Dopo flash + avvio, nel 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)

Con un avvio a caldo (i riflessi corrispondono), senza scrittura in 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)

Comportamento osservato

  • Binding TA misto: codici [1, 3, 6] su un modulo a tre canali a 0x52 vengono mantenuti ciascuno sul proprio canale.
  • Rifiuto di codici non validi: un tentativo con un codice fuori dall'insieme ammesso per la classe → esphome config rifiuta lo schema (cv.Invalid). Se il YAML sfugge al validatore (modifica manuale / build legacy), il firmware restituisce REG_ERROR = 0xFE DEV_ERR_PARAM, con lo specchio lasciato al valore precedente.

  • Tempi di installazione a freddo: ~2.1 s sulla UI3 (3 × ~700 ms di cancellazione flash).

  • Tempi di avvio a caldo: ~70 ms (la lettura-confronto-scrittura salta ogni cancellazione flash).
  • Misura della latenza: ~1.4 s dall'inizio di setup() alla prima pubblicazione (banco di prova).

4 · Sincronizzazione GC della flotta (sincronia stretta)

Obiettivo: dimostrare che la sincronizzazione del parco 3/3 non è accademica ma un requisito reale per distribuzioni multi-inquilino (sotto-misura di appartamenti su un quadro condiviso) e per una sotto-misura precisa (la rete di UI1 deve coincidere con la somma delle potenze dei sotto-contatori entro la durata di un singolo 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());'

Esempio di output (test di sincronizzazione con 10 iterazioni)

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

Come group_id aiuta nel multi-inquilino

Senza group_id non c'è separazione degli inquilini — tutti i moduli reagiscono a qualsiasi frame GC. Con group_id:

  • I moduli dell'inquilino 1 rispondono solo ai frame GC con group=1 (oppure al broadcast group=0)
  • I moduli dell'inquilino 2 rispondono solo ai frame GC con group=2

Questo permette al master di emettere frame GC separati per gli inquilini in momenti indipendenti — ad esempio, per periodo dell'inquilino:

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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

Validazione in produzione

  • Sensore template di HA"mains_minus_subsum" — un indicatore di discrepanza:
    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;
    

Uno scostamento < 1% di mains_power in banco = sincronizzazione corretta.

  • Integrazione sul tempo reale — anche con sincronizzazione GC 3/3, i moduli BASIC vengono integrati sul clock dell'ESP32, quindi un piccolo scarto tra i moduli non distorce i Wh.

5 · UI1 — canale singolo (minimo)

Fonte: ../example/ui1.yaml

La configurazione utile più semplice: un canale di tensione, un canale di corrente e sei grandezze derivate da essi. Un punto di partenza per qualsiasi nuovo deployment — estenderla con altri campi se necessario.

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"

Che cosa dimostra: la configurazione minima funzionante. I sei sensori coprono il caso base — misura dell'intera casa o di un singolo carico. Il sensore energy ha già device_class: energy + state_class: total_increasing impostati, quindi va direttamente nella dashboard Energia di HA senza configurazione aggiuntiva. Il protocollo di misura per periodi (snapshot / attesa di 50 ms / lettura della potenza media, integrata sul clock master) è documentato in 09 · Riferimento API.


6 · UI1 con personalizzazione — tutte le opzioni standard di ESPHome

rbAmp è un componente ESPHome «ben educato». Ogni slot (voltage, current, power, …) è un normale oggetto sensor: di ESPHome. Funzionano l'intero insieme standard di proprietà e filtri. Non servono né un lambda: né template personalizzati — tutto ciò che fai con pzemac / atm90e32 / cse7766 funziona qui esattamente allo stesso modo. L'esempio mostra le personalizzazioni più comuni in un unico blocco:

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;'

Cosa dimostra:

  • Nomi personalizzati (name:) diventano l'entity_id di HA — per esempio sensor.rbamp_ui1_tuned_mains_voltage. Nomi in qualsiasi lingua, incluso il cirillico, funzionano.

  • Precisione in uscita (accuracy_decimals:) è indipendente dal modulo; il modulo restituisce float32 con la massima precisione, e ESPHome la tronca per l'interfaccia.

  • update_interval: non va cambiato per singolo sensore — è una proprietà del componente (PollingComponent), impostata una volta nel blocco rbamp:. Se vuoi pubblicazioni più rade di singoli sensori, aggiungi filters: - throttle: .

  • filters: — l'insieme completo di ESPHome:

  • calibrate_linear — calibrazione su punto di riferimento (multimetro, amperometro di riferimento).

  • exponential_moving_average / sliding_window_moving_average — livellamento.

  • lambda — una trasformazione arbitraria (maschera della soglia di rumore, zero condizionale).
  • multiply / offset — aritmetica (per esempio, Wh → kWh).
  • throttle / delta — riduzione della frequenza di pubblicazione.
  • unit_of_measurement: può essere sovrascritto (ad esempio in kWh con multiply: 0.001). HA riconosce automaticamente la nuova unità.

  • Nessuna lambda: per il funzionamento di base — tutti i calcoli di RMS, potenza, frequenza e PF sono eseguiti dal modulo. L'ESP32 si limita a rinominare, formattare e filtrare.

Sicurezza

⚠ Non sovrascrivere device_class: per energy — la dashboard Energia di HA si aspetta rigorosamente device_class: energy + state_class: total_increasing. La conversione di unità tramite multiply + unit_of_measurement: mantiene la compatibilità, ma cambiare il device_class romperà la dashboard.

L'elenco completo delle proprietà standard dei sensori e dei filtri si trova nella documentazione ufficiale del Sensor Component di ESPHome. Tale documentazione è pienamente applicabile agli slot rbAmp — non ci sono deviazioni dallo standard.


7 · UI3 — tre canali con pinze miste

Fonte: ../example/ui3.yaml

Lo SKU UI3 ha un ingresso di tensione e tre canali di corrente indipendenti. Lo scenario canonico è applicare modelli di pinza diversi ai diversi canali: una pinza piccola sui consumatori a bassa corrente (per la massima risoluzione) e una grande sulla linea principale (per il margine sui picchi).

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"

Cosa dimostra: tutti e tre i canali dello SKU UI3 + modelli di pinza misti tramite ct_models:. Il validatore dello schema verifica che power_N ed energy_N (e power_factor_N, reactive_power_N) richiedano current_N e voltage — se si dichiara power_1 senza current_1, la compilazione fallisce con un messaggio chiaro. Ogni canale ha il proprio accumulatore energy_* indipendente persistito in NVS. Se tutti i canali usano lo stesso modello di pinza, usare il ct_model: globale invece di ct_models:.


8 · Bus multi-modulo (tre rbAmp agli indirizzi 0x50 / 0x51 / 0x52)

Fonte: ../example/multi_module.yaml

Tre moduli sullo stesso bus I²C — l'alimentazione principale della casa, l'uscita di generazione solare e la ricarica dell'auto elettrica. Ciascuno ha il proprio blocco rbamp: (nello schema 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"

Che cosa dimostra: il pattern MULTI_CONF = True — dichiari tanti blocchi rbamp: quanti moduli hai sul bus. Ciascuno mantiene il proprio accumulatore NVS, la cui chiave deriva dall'indirizzo I²C, così i tre contatori restano indipendenti tra i riavvii. Il flag internal: true sui sensori di tensione duplicati nasconde in HA le tre entità di tensione di rete quasi identiche, quando tutti i moduli misurano la stessa fase. Per la procedura di assegnazione degli indirizzi, vedi l'Esempio 2 qui sotto.

Nota

Significato di internal: true. Il flag non disabilita la lettura del registro dal modulo — il componente legge ancora la tensione da ogni modulo a ogni update_interval (necessario per il calcolo della potenza). Il flag nasconde solo il sensore dall'API di Home Assistant: non viene creata alcuna entità, non compare in Lovelace e non viene conteggiato nella dashboard Energia. Per ridurre il traffico I²C, non dichiarare affatto lo slot voltage: sotto sensor.platform: rbamp — il componente non interroga allora il registro. Se lo si dichiara, il flag internal: è puramente estetico.

Un secondo vincolo riguarda l'unicità degli indirizzi sul bus:

Sicurezza

⚠ Gli indirizzi unici sono responsabilità della configurazione. Lo schema del componente (MULTI_CONF = True) non verifica la sovrapposizione dei valori address: tra blocchi rbamp:. Se due blocchi indicano lo stesso address: 0x50, entrambe le dichiarazioni vengono accettate e sul bus entrambi i destinatari risponderanno insieme — attenderti conflitti I²C, risposte corrotte o sintomi simili a un modulo mancante. Prima di fare commit del YAML, verifica che tutti i valori address: siano unici (e non collidano con altri dispositivi I²C sul bus). Dopo ogni provisioning new_address:, aggiorna la sezione rbamp: al nuovo indirizzo — la vecchia voce non viene invalidata automaticamente.

Pull-up su un bus multi-modulo

Tutti e tre i moduli escono di fabbrica con pull-up da 4.7 kΩ. Su un bus di tre moduli la combinazione in parallelo è di ~1.6 kΩ — assorbimento di corrente più alto e integrità del segnale marginale a 50 kHz. Taglia i ponticelli di saldatura dei pull-up su tutti e tre i moduli e posiziona una coppia esterna da 2.7–3.3 kΩ vicino all'ESP32 (la riga dei 3 moduli nella tabella in 04_hardware.md).

Avanzato: cadenza di snapshot disaccoppiata per flotte multi-modulo (v1.4+)

Le installazioni a flotta sostengono il costo del ciclo di snapshot per modulo a ogni ciclo: su un bus a 3 moduli con polling a update_interval: 10s, sono 3× la scrittura dello snapshot + 3× la finestra di assestamento di 50 ms ogni 10 s — più le letture del blocco RT. Su host ESP8266 (single core; gli ISR del WiFi competono per la CPU durante le transazioni I²C) o su bus I²C condivisi con altri dispositivi, questo sovraccarico diventa visibile come glitch WiFi o letture obsolete su entità non rbAmp.

latch_interval: (disponibile dalla v1.4, moduli BASIC) separa le due cadenze: le letture del blocco RT (V/I/P/PF/Q) restano a update_interval: — chi legge vede sempre valori aggiornati sulla dashboard — mentre il passaggio snapshot → integrazione in Wh viene eseguito solo ogni latch_interval:. L'integrazione usa il tempo reale effettivo tra gli eventi di snapshot, quindi uno snapshot ogni 60 s produce semplicemente passi di integrazione larghi 60 s (e comunque corretti). latch_interval deve essere ≥ 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

Riduzione del carico sul bus rispetto allo stesso parco senza latch_interval:: con update_interval: 10s, ogni modulo contribuisce ~15 ms di lettura RT + ~65 ms di snapshot+assestamento per ciclo → ~80 ms per modulo per ciclo. Con latch_interval: 60s, lo snapshot+assestamento scatta solo una volta al minuto → le letture RT restano economiche ogni 10 s + una breve raffica di snapshot ogni 60 s, circa 3 volte un carico medio del bus inferiore. Parchi più grandi mostrano risparmi proporzionalmente maggiori.

Quando omettere latch_interval:: installazioni con un singolo modulo su host ESP32 in cui il carico di base non costa nulla — il valore predefinito a cadenza singola della v1.3 è più semplice e altrettanto corretto.


9 · Cambio una tantum dell'indirizzo I²C (0x50 → 0x51)

Fonte: ../example/address_change.yaml

Tutti i moduli rbAmp escono di fabbrica all'indirizzo 0x50. Per collegare più moduli su un bus, occorre riflashare ciascuno con un proprio indirizzo unico prima di collegarli in parallelo.

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

Che cosa dimostra: il flusso di cambio indirizzo una tantum. Il flash di questo YAML fa eseguire al componente la procedura una volta all'avvio:

  1. Sondare 0x50. Se 0x50 è silenzioso e 0x51 risponde già, la modifica è stata applicata in un avvio precedente; il componente si adatta e registra un avviso che chiede di ripulire il YAML.

  2. Verificare che il modulo sia pronto ad accettare un'operazione di provisioning.

  3. Scrivere il nuovo indirizzo in flash (~700 ms), un soft reset (~300 ms), e il ri-aggancio al ciclo CA.

  4. Confermare al nuovo indirizzo. In caso di successo — il log Address change confirmed at 0x51 e IMPORTANT: update YAML to address: 0x51 and remove new_address:.

Compatibilità firmware: sul firmware v1.3+ il cambio di indirizzo è adatto alla produzione — il componente usa il protocollo di commit in due fasi (stage → arm → commit → reboot) senza modalità speciali. Sul firmware legacy (v1.0-v1.2) il ripiego monofase richiede la modalità di provisioning di fabbrica; consultare la documentazione del modulo o il fornitore per la procedura di attivazione temporanea.

Dopo il successo: modifica il YAML con address: 0x51 e rimuovi la riga new_address: 0x51. Fai di nuovo il flash. Dal prossimo avvio il componente usa normalmente 0x51 e la procedura di cambio non viene più eseguita.

Checklist di ripristino dopo un provisioning riuscito

Per non lasciare nel repository una variante di provisioning «pendente» (due alternative, mai incollarle entrambe nello stesso file):

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

Esattamente tre modifiche:

  1. Cambiare il valore di address: da quello vecchio a quello nuovo.
  2. Elimina (non commentare) la riga new_address:.
  3. Riflashare via OTA o USB.

Dopo il passaggio 3, il log dovrebbe mostrare una normale riga dump_config senza l'avviso address change requested but current address matches new_address — il che significa che il ripristino è corretto. Vedi anche 10_troubleshooting §4 «L'OTA subito dopo il provisioning new_address: non si carica» se il primo OTA dopo il ripristino non parte.


10 · Configurazione di banco con secrets

Fonte: ../example/bench-ui1.yaml

Il pattern bench-*.yaml serve per le macchine di sviluppo in cui le credenziali Wi-Fi servono nella configurazione ma non devono finire in un commit. example/.gitignore esclude bench-*.yaml e secrets.yaml dal controllo di versione.

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"

Il secrets.yaml corrispondente (in example/, non tracciato):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Cosa dimostra: separare le credenziali in fase di compilazione dal YAML sotto controllo di versione tramite !secret di ESPHome. Elencare bench-*.yaml in .gitignore permette di tenere quante varianti di banco si vogliono senza rischio di fuga. Usare esphome run --device 192.168.0.173 example/bench-ui1.yaml per l'OTA dopo la prima connessione di rete, oppure esphome run --device COM6 example/bench-ui1.yaml per il primo flash USB.


11 · Brownout e perdita di rete

Quando l'alimentazione di rete viene interrotta, il front-end analogico isolato del modulo smette di ricevere un segnale. Il registro di tensione scende a 0.0 V — un float IEEE 754 finito valido che supera il filtro di integrità isfinite() del componente. La politica di filtraggio del componente è intenzionale:

Sicurezza

NESSUN limite fisico inferiore — brownout (U=0 V alla disconnessione della rete), abbassamento di tensione, test fuori rete / UPS e scatto dell'interruttore DEVONO passare a HA, così l'utente vede lo stato reale.

Nessun YAML speciale serve per rilevare la perdita di rete — il sensore voltage stesso legge 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"

Automazione HA: allarme alla perdita di rete

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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') }}.

Cosa dimostra: usare il comportamento di passaggio dello 0 V come fonte di un evento di "perdita di rete". Poiché il componente pubblica 0.0 V invece di saltare la pubblicazione, le automazioni di HA e la dashboard Energia vedono l'evento di brownout in tempo reale. La condizione for: 5 seconds blocca gli scatti falsi durante il riscaldamento di ~250 ms all'avvio (quando i registri leggono 0 prima della prima misura valida).


12 · Dashboard Energia di HA

Il sensore energy (e energy_1, energy_2, energy_exported, ecc.) è configurato automaticamente con device_class: energy e state_class: total_increasing — esattamente ciò che la dashboard Energia di HA si aspetta per i sensori di consumo cumulativo. Non serve YAML aggiuntivo.

Dopo il rilevamento:

  1. Impostazioni → Dashboard → Energia. [Settings → Dashboards → Energy]
  2. Aggiungi consumo → scegli «Energia di rete» (o l'entità di misura dell'importazione che preferisci). [Add Consumption → "Mains Energy"]

  3. Se hai il fotovoltaico — Aggiungi produzione → scegli Energia solare (da meter_solar nell'esempio multi-modulo). [Add Production → Solar Energy]

I valori di energia sono in Wh. HA li converte da sé in kWh per la visualizzazione. La persistenza NVS nel componente assicura che l'accumulatore sopravviva al riavvio dell'ESP32 senza un falso "azzeramento del contatore" nelle statistiche di 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 · Automazioni HA sui sensori rbAmp

Distacco dei carichi: un relè si spegne quando una soglia viene superata

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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

Promemoria sulla correzione del fattore di potenza

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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).

Avviso di superamento del budget giornaliero

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 · Schede Lovelace

Indicatore — potenza live

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 — potenza nel tempo

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 — confronto energia su tre canali

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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

Mini grafico — tensione

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 · Contatore di utenza — aggregazione per giorno / settimana / mese

ESPHome pubblica i totali cumulativi in Wh. L'integrazione utility_meter di HA azzera il contatore a intervalli configurabili e pubblica la differenza come sensore separato — utile per il dettaglio giornaliero o mensile.

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 tre entità: sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Ciascuna si azzera a 0 all'inizio del rispettivo periodo e accumula il delta dal sensore total_increasing di origine.

Sensore derivato kWh/giorno

utility_meter produce Wh per impostazione predefinita. Per visualizzare in kWh, aggiungere un sensore template:

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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) }}

Sensore del costo giornaliero

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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 · Sotto-misurazione per carico (3 moduli agli indirizzi 0x50 / 0x51 / 0x52)

Installare tre moduli rbAmp in un quadro di distribuzione permette la misura di energia per singolo circuito senza quadro intelligente né hardware aggiuntivo.

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel 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"

Combinata con la dashboard Energia di HA, ottieni estratti mensili per circuito senza calcoli kWh×tariffa aggiuntivi.


17 · rbAmp + un relè — controllo ad anello chiuso

Uno scaldabagno con controllo a relè

YAML
# ESPHome YAML on the same ESP32 as rbAmp
switch:
  - platform: gpio
    pin: GPIO5
    id: heater_relay
    name: "Water Heater"

Con rbAmp e un relè sullo stesso ESP32 puoi costruire un anello chiuso direttamente in ESPHome (tramite un Lambda o on_value), senza passare da HA:

Presuppone che esista già una voce switch: con l'id usato sotto.

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

Cosa dimostra: usare il callback on_value di un sensore rbAmp per controllare un relè senza intervento di HA. Il callback scatta sull'ESP32 a ogni update_interval (60 s) e aggiorna lo stato del relè dall'ultima lettura di potenza. Per un controllo più stretto (un ciclo < 60 s), ridurre update_interval a 10s — questo aumenta in proporzione il carico sul bus I²C. Un esempio di anello chiuso più completo per una caldaia è in 07_diy_integrations.md.


18 · Integrazione DRDY

Il pin DRDY open-drain del modulo fornisce un impulso LOW di ~10 µs ogni ~100 ms dopo l'aggiornamento dei registri istantanei. Può essere collegato a un GPIO dell'ESP32. Il componente registra il pin DRDY; le letture sono guidate dal timer (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

: sul firmware attuale il componente registra drdy_pin in dump_config ma non implementa letture RT guidate da interrupt — update_interval continua a fissare la frequenza di polling.


19 · Sensori per fase (varianti split-phase / trifase)

Per i moduli con più di un ingresso di tensione il componente offre un gruppo di sensori per fase (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, più voltage_angle_b/c). Uno slot pubblica solo quando il modulo collegato segnala il canale corrispondente; su un modulo a tensione singola gli slot per fase restano senza valore. Lo schema verifica che i gruppi singoli e per fase non siano mescolati in un unico blocco 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"

Che cosa dimostra: il gruppo di campi per fase. Mescolare campi singoli e per fase nello stesso blocco sensor: produce un errore in fase di compilazione — scegli il gruppo che corrisponde al tuo modulo. I dettagli sono in 09 · Riferimento API §2.2.


20 · Migrazione da altri componenti di misura ESPHome

Da pzem004t

La piattaforma pzem004t espone gli stessi nomi di campo di rbamp per le grandezze CA più comuni. La sostituzione è blocco per blocco, con nomi di sensori identici:

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"

Campi name: identici danno ID entità identici in HA. La cronologia della dashboard Energia viene conservata durante la sostituzione: il sensore total_increasing riprende da dove era rimasto. Rimuovi il blocco uart: se non è condiviso con un altro componente.

Da cse7766 (Sonoff POW R2)

Stesso schema. cse7766 fornisce voltage, current, power, energy, power_factor, apparent_power — tutti presenti in rbamp. Sostituire platform: cse7766 con platform: rbamp, aggiungere rbamp_id: meter1, rimuovere uart: e aggiungere i2c: e il blocco rbamp:.


21 · Modulo STANDARD — totali di energia integrati nel dispositivo

Su un modulo STANDARD il componente accumula i contatori di energia integrati del modulo. I totali sopravvivono ai riavvii sia dell'ESP32 sia del modulo e restano monotoni. Lo stesso YAML funziona anche su un modulo BASIC, tranne che le chiavi del totale complessivo non pubblicano mai.

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"

Che cosa dimostra: i sensori del totale complessivo, che non richiedono una dichiarazione current/voltage associata; start_current_ua: (0 = disattivato, altrimenti 10..2540 a passi di 10) così il rumore a vuoto non si insinua nei contatori di importazione ed esportazione (le letture istantanee non ne sono influenzate). Per la dashboard Energia di HA usa energy_total come consumo di rete e energy_exported_total come ritorno in rete.


22 · Cambio del valore nominale SCT e override di servizio

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010      # module was delivered with the SCT-013-030

Le letture restano accurate dopo il cambio: sul firmware del modulo fino alla 1.4.19 il componente completa la scrittura del modello con il riavvio richiesto del modulo (visibile nel log) e scala corrente, potenza ed energia sul sensore selezionato; i firmware più recenti lo fanno sul modulo. Un valore già presente nel modulo non viene mai riscritto, e su un modulo fornito calibrato insieme al proprio sensore montato (sensor_class: WIRED_CT / BUILTIN_CT) il cambio viene rifiutato con una riga di log. Solo per una riapplicazione deliberata del preset:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010
  ct_model_force: true       # one-off service option; remove both lines afterwards

Riepilogo delle regole di validazione YAML

Regola Applicato da
power / energy / power_factor / reactive_power richiedono current Validatore dello schema (_SINGLE_SLOT_DEPS)
P/Q/PF/E per qualsiasi canale richiedono voltage Validatore dello schema
I gruppi singoli e per fase non vengono mescolati in un unico sensor: _validate_topology_consistency
new_address ≠ address _validate_new_address
address nell'intervallo 0x08..0x77 cv.i2c_address
update_interval minimo 1s, applicato Validatore dello schema
latch_interval ≥ update_interval Validatore dello schema
ct_model: e ct_models: si escludono a vicenda Validatore dello schema
ct_models: ha da 1 a 16 voci Validatore dello schema
ct_model_force: true richiede ct_model: o ct_models: Validatore dello schema
start_current_ua è 0 oppure da 10 a 2540 a passi di 10 Validatore dello schema
Il codice del modello TA è valido per la sensor_class fissata Validatore dello schema

Gli errori di validazione vengono segnalati in fase di esphome compile con un messaggio leggibile che indica la chiave colpevole. Non serve flashare l'hardware per trovare un errore di configurazione.


Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/06_examples.md (v1.9.1)