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 |
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Ω).
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)
[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_powerin 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)
# 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:
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:
[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.
🛑 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:
[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.
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:
[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:
[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 configrifiuta lo schema (cv.Invalid). Se il YAML sfugge al validatore (modifica manuale / build legacy), il firmware restituisceREG_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).
# 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)
[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 broadcastgroup=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.
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.
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:
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_iddi HA — per esempiosensor.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 bloccorbamp:. Se vuoi pubblicazioni più rade di singoli sensori, aggiungifilters: - 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 inkWhconmultiply: 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.
⚠ 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).
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).
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.
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:
⚠ 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.
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.
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:
-
Sondare
0x50. Se0x50è silenzioso e0x51risponde già, la modifica è stata applicata in un avvio precedente; il componente si adatta e registra un avviso che chiede di ripulire il YAML. -
Verificare che il modulo sia pronto ad accettare un'operazione di provisioning.
-
Scrivere il nuovo indirizzo in flash (~700 ms), un soft reset (~300 ms), e il ri-aggancio al ciclo CA.
-
Confermare al nuovo indirizzo. In caso di successo — il log
Address change confirmed at 0x51eIMPORTANT: 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):
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# AFTER (production — applied next flash):
rbamp:
id: meter1
address: 0x51 # ← replaced with the new address
# new_address: 0x51 # ← DELETE the line (do not comment it out)
update_interval: 60s
Esattamente tre modifiche:
- Cambiare il valore di
address:da quello vecchio a quello nuovo. - Elimina (non commentare) la riga
new_address:. - 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.
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):
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:
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.
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.
# 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:
- Impostazioni → Dashboard → Energia. [Settings → Dashboards → Energy]
-
Aggiungi consumo → scegli «Energia di rete» (o l'entità di misura dell'importazione che preferisci). [Add Consumption → "Mains Energy"]
-
Se hai il fotovoltaico — Aggiungi produzione → scegli Energia solare (da
meter_solarnell'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.
# 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.
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.
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.
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.
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.
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.
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.
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.
# 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.
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.
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.
# 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è
# 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.
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).
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
: 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:.
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:
# Before (pzem004t, UART)
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
sensor:
- platform: pzem004t
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
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.
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
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:
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)