09 · Riferimento dello schema YAML
Questo capitolo è il riferimento completo dello schema YAML del componente esterno rbamp per ESPHome. Se una chiave non è elencata qui, non esiste nello schema.
Un YAML per entrambe le linee di moduli. All'avvio il componente identifica quale linea di moduli è collegata (BASIC o STANDARD (STD)) e si adatta automaticamente: numero di canali, variante e funzionalità disponibili provengono dal modulo stesso, quindi nel YAML non servono la chiave topology: né un cambio di livello. Le chiavi che si applicano a una sola generazione sono indicate sotto; una chiave che il modulo collegato non può rispettare viene ignorata con una riga di log, mai con un errore bloccante.
Contents:
- Blocco componente —
rbamp: - Piattaforma sensore —
sensor.platform: rbamp - Flusso dei dati e temporizzazione
- Impostazioni del bus I2C
1. Blocco componente — rbamp:
Configurazione multi-modulo (initialization) · Polling multi-modulo — tre strategie (realtime-polling) · Problemi multi-modulo (troubleshooting)
Il blocco rbamp: di primo livello registra un'istanza di componente. Eredita da PollingComponent (che fornisce update_interval) e da i2c.I2CDevice (che fornisce address e l'handle del bus I²C). MULTI_CONF: True significa che un numero qualsiasi di blocchi rbamp: può coesistere in uno stesso YAML, ciascuno con il proprio slave I²C.
rbamp:
id: meter1
address: 0x50
update_interval: 60s
drdy_pin: GPIO4
sensor_class: SCT_013
ct_model: SCT_013_030
# or, for a UI3 with mixed clamps:
# ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
bidirectional: false
new_address: 0x51
fleet_gc_enable: false
group_id: 0
latch_interval: 60s
start_current_ua: 400 # STANDARD only, see below
# ct_model_force: true # service option, see below
Ogni chiave è facoltativa. topology: e broadcast_latch: sono ancora accettati per compatibilità con le versioni precedenti (vedere le loro voci).
id
| Attributo | Valore |
|---|---|
| Tipo | id (identificatore ESPHome) |
| Predefinito | Generato automaticamente |
| Obbligatorio | No |
Assegna un identificatore stabile all'istanza. I sensori lo referenziano tramite rbamp_id: meter1. Con più blocchi rbamp: serve un id esplicito.
rbamp:
id: kitchen_meter
address
02 · Inizializzazione e avvio (initialization) · 3.6 Algoritmo canonico di rilevamento (api-reference) · 6 · Sequenze di protocollo (api-reference)
| Attributo | Valore |
|---|---|
| Tipo | i2c_address (7 bit, 0x08..0x77) |
| Predefinito | 0x50 |
| Obbligatorio | No |
L'indirizzo I²C attuale del modulo rbAmp. L'indirizzo di fabbrica è 0x50. Dopo aver applicato un cambio di indirizzo (via new_address), aggiorna questa chiave con il nuovo valore e rimuovi new_address.
Intervallo valido: 0x08..0x77 (gli indirizzi I²C riservati a 7 bit sono esclusi).
rbamp:
address: 0x52 # three modules on the bus: 0x50, 0x51, 0x52
Riferimento incrociato: il protocollo del bus I²C nel riferimento API; cambio di indirizzo a runtime per cambiare l'indirizzo dopo l'avvio.
update_interval
04 · Misura per periodi e contabilità tariffaria (period-metering) · Ciclo di interrogazione continuo (consigliato) (period-metering) · Registri di snapshot del periodo (period-metering)
| Attributo | Valore |
|---|---|
| Tipo | time (stringa di durata ESPHome) |
| Predefinito | 60s |
| Obbligatorio | No |
Quanto spesso viene eseguito update(). Ogni chiamata:
- Invia il comando di snapshot e pianifica un timeout non bloccante di 50 ms per la lettura dello snapshot del periodo (moduli BASIC; sui moduli STANDARD l'energia arriva dai contatori integrati del modulo, vedi
energy_total). - Controlla il registro di stato; se il modulo è pronto, pubblica tutti i sensori istantanei collegati.
Il valore predefinito di 60 s è ragionevole: il modulo aggiorna internamente la potenza media del periodo circa ogni ~100 ms, ma integrare l'energia sul lato master richiede una finestra abbastanza lunga per essere corretta. Con 60 s e un carico medio di 60 W, uno snapshot mancato perde ≤ 1 Wh.
Il valore minimo ammesso è 1s: lo schema rifiuta valori inferiori, e esphome config segnala una diagnostica. Valori sotto 5-10 s non offrono vantaggi per una sincronizzazione stretta e riempiono solo il bus.
rbamp:
update_interval: 30s # more frequent dashboard updates, more traffic
latch_interval
Ciclo di interrogazione continuo (consigliato) (period-metering) · 4.11 Blocco periodo V03 (0xBE..0xCF) (api-reference) · 6.4 Sincronizzazione del periodo — due strategie (api-reference)
| Attributo | Valore |
|---|---|
| Tipo | time (stringa di durata ESPHome) |
| Predefinito | Come update_interval |
| Obbligatorio | No |
| Dalla | v1.4 |
Con quale frequenza il componente invia il comando di snapshot e integra un campione in Wh. Se impostato, separa il ciclo di snapshot dalla cadenza di lettura RT — update_interval: continua a controllare la frequenza di lettura e pubblicazione dei registri V/I/P/PF/Q, mentre latch_interval: controlla con quale frequenza l'accumulatore di periodo viene salvato come snapshot e i Wh vengono integrati.
L'integrazione dell'energia non aggiunge un errore proprio oltre alla precisione della potenza attiva del modulo, qualunque sia il rapporto: l'integrazione lato master usa il dt reale di orologio tra eventi di snapshot successivi, quindi snapshot più lunghi producono solo passi di integrazione più grossolani.
Deve essere >= update_interval (impostarlo più corto viene rifiutato alla validazione della configurazione — gli snapshot in più non produrrebbero dati osservabili).
Se non impostato, lo snapshot viene eseguito a ogni chiamata di update() (comportamento a cadenza singola della v1.3, compatibile con le versioni precedenti).
rbamp:
update_interval: 3s # RT V/I/P/PF refreshed every 3 s
latch_interval: 60s # snapshot + Wh integration once a minute
Utile quando contano il carico del bus o la competizione per la CPU lato master — flotte multi-modulo, host ESP8266 (single-core; gli ISR del WiFi competono per la CPU durante le transazioni I²C), o bus I²C condivisi con altri dispositivi.
drdy_pin
01 · Connessione hardware (hardware-connection) · 03 · Polling in tempo reale (realtime-polling)
| Attributo | Valore |
|---|---|
| Tipo | gpio_input_pin_schema |
| Predefinito | Nessuno (facoltativo) |
| Obbligatorio | No |
Collega l'uscita open-drain DRDY del modulo a un GPIO dell'ESP32. Quando specificato, il pin viene configurato in setup() all'avvio.
Il pin viene registrato in dump_config ma non è usato come trigger di lettura — i registri istantanei vengono interrogati ogni update_interval. Dichiarare il pin non cambia il comportamento.
rbamp:
drdy_pin: GPIO4
sensor_class
Impostazione della classe del sensore e del modello TA (inizializzazione) · 4.3 Sistema (0x20..0x25) (riferimento API) · 6.2 Associazione del modello TA — solo staging + CMD per canale (riferimento API)
| Attributo | Valore |
|---|---|
| Tipo | enum (SCT_013, WIRED_CT, BUILTIN_CT) |
| Predefinito | SCT_013 |
| Obbligatorio | No |
Fissa la famiglia del sensore di corrente sul lato modulo. Con firmware v1.2+ il valore viene scritto in flash e diventa una condizione preliminare per scrivere il modello TA: il modulo rifiuta di scrivere il modello se la classe non è impostata. Con firmware precedenti il valore viene accettato dallo schema e applicato automaticamente all'aggiornamento.
| Valore | Significato |
|---|---|
SCT_013 |
Pinze split-core SCT-013 — il valore predefinito |
WIRED_CT |
Modulo fornito calibrato insieme al proprio sensore montato |
BUILTIN_CT |
Modulo fornito calibrato insieme al proprio sensore integrato |
Controllo di scrittura. Il componente non scrive mai una classe che il modulo ha già (un riavvio ripetuto non scrive nulla). Su un modulo calibrato in coppia con il proprio sensore montato (WIRED_CT / BUILTIN_CT), una modifica di classe o modello dal YAML viene rifiutata con una riga di log esplicita — la scrittura sostituirebbe la calibrazione individuale con un'impostazione generica. Lasciare sensor_class: e ct_model: fuori dal YAML per tali moduli, oppure vedere ct_model_force.
rbamp:
sensor_class: SCT_013 # default; may be omitted
Per scegliere la pinza e la famiglia, vedi 03_sensor_selection.md.
ct_model
Impostazione della classe del sensore e del modello TA (initialization) · 6.2 Binding del modello TA — pura fase di staging + CMD per canale (api-reference) · 8.6 Provisioning dopo flash nuovo (api-reference)
| Attributo | Valore |
|---|---|
| Tipo | enum (SCT_013_005, _010, _020, _030, _050) |
| Predefinito | Nessuno (facoltativo) |
| Obbligatorio | No |
Scrive l'identificatore del modello della pinza TA nella flash del modulo. Con firmware v1.2+ questo carica automaticamente i coefficienti di fabbrica per il modello scelto — non serve alcun passaggio di calibrazione aggiuntivo. Un valore uguale a quello già presente nel modulo non viene scritto.
| Valore YAML | Codice | Corrente nominale | Stato v1.3 |
|---|---|---|---|
SCT_013_005 |
1 | 5 A | produzione |
SCT_013_010 |
2 | 10 A | produzione |
SCT_013_020 |
6 | 20 A | produzione (nuovo nella v1.3) |
SCT_013_030 |
3 | 30 A | produzione (SKU predefinito) |
SCT_013_050 |
4 | 50 A | produzione |
Il set di codici ammessi per classe per SCT_013 è {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 è il codice 5, SCT_013_060 è il codice 7; l'ordine dei codici non è l'ordine delle portate). I valori non corrispondenti vengono rifiutati in esphome config tramite cv.Invalid. Per saperne di più, vedi 03 · Scelta del sensore di corrente.
rbamp:
ct_model: SCT_013_030
Applicato una volta in setup(). Ogni scrittura è accompagnata da una scrittura flash di ~700 ms (il modulo invia NACK a tutte le operazioni I²C durante questo tempo — il componente alimenta il watchdog automaticamente).
Il cambio di portata SCT mantiene la precisione. Ogni modulo SCT è calibrato in fabbrica con l'SCT-013-030. Quando selezioni un'altra portata, corrente, potenza ed energia restano corrette: sul firmware fino alla 1.4.19 il componente completa la scrittura del modello con un riavvio del modulo (fa parte del flusso normale e compare nel log), poi scala le letture sul sensore selezionato; i firmware più recenti eseguono il cambio sul modulo e il componente lascia invariate le letture. Tensione e fattore di potenza non ne sono influenzati. Per questo non serve alcuna modifica al YAML.
Guardia di scrittura. Un valore uguale non viene mai scritto e, su un modulo accoppiato in fabbrica (sensor_class: WIRED_CT / BUILTIN_CT), la scrittura viene rifiutata con una riga di log — vedi sensor_class.
Mutuamente esclusivo con ct_models: — ne può essere usato uno solo per blocco rbamp:.
Per approfondire, vedere 03_sensor_selection.md. Riferimento incrociato: il riferimento ct_model.
ct_models
| Attributo | Valore |
|---|---|
| Tipo | elenco di da 1 a 16 valori enum |
| Predefinito | Nessuno (facoltativo) |
| Obbligatorio | No |
Modelli di pinza TA per canale — per moduli con pinze miste su canali diversi. Accetta gli stessi valori enum di ct_model:. Lo schema accetta da 1 a 16 voci; la posizione nell'elenco è l'indice del canale. Il componente applica tante voci quanti sono i canali del modulo (1 per UI1, 2 per UI2, 3 per UI3, e così via); le voci in eccesso vengono ignorate con un avviso.
rbamp:
id: ui3_meter
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby loads (maximum resolution),
# CH1=30A for main household loads,
# CH2=20A for a water heater / medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)
Con firmware v1.2+ ogni canale riceve un proprio insieme di coefficienti di fabbrica in modo indipendente. Il tempo di setup totale all'avvio è di ~2-3 secondi (~700 ms di scrittura in flash per canale).
Moduli STANDARD. I modelli per canale sono memorizzati solo dai moduli che dichiarano uno storage persistente per canale. Su un modulo che non lo dichiara, il componente rifiuta rumorosamente (un avviso che ct_models: non è supportato da questo dispositivo, chiavi ignorate) invece di scrivere un valore che si annullerebbe dopo un ciclo di alimentazione — usare lì la singola ct_model:.
Si applicano gli stessi controlli di scrittura di ct_model: (i valori uguali non vengono scritti; i moduli accoppiati in fabbrica rifiutano la modifica).
Si escludono a vicenda con ct_model:.
ct_model_force
| Attributo | Valore |
|---|---|
| Tipo | bool |
| Predefinito | false |
| Obbligatorio | No |
Opzione di servizio. Scavalca la guardia di scrittura: il componente applica il preset ct_model: / ct_models: anche quando il modulo è accoppiato in fabbrica o contiene già lo stesso valore. Questo sostituisce la calibrazione individuale del modulo con il preset generico per quel modello, quindi usala solo in modo deliberato, eseguila una volta e poi rimuovila.
Lo schema rifiuta ct_model_force: true a meno che non sia presente anche ct_model: o ct_models:, così il flag non può restare armato nel YAML in attesa di una linea di modelli successiva.
rbamp:
ct_model: SCT_013_030
ct_model_force: true # one-off; remove both lines after the operation
start_current_ua
| Attributo | Valore |
|---|---|
| Tipo | intero, microampere |
| Valori ammessi | 0 (disattivato) oppure 10..2540 a passi di 10 |
| Predefinito | Nessuno (si applica il valore predefinito del modulo) |
| Obbligatorio | No |
| Si applica a | Moduli STANDARD con contatori di energia integrati; ignorati con un avviso altrove |
Corrente di avvio per il conteggio dell'energia. Mentre la corrente di un canale è sotto questo valore, il modulo non conteggia energia su quel canale. Senza di essa, a vuoto la potenza misurata è rumore di segno variabile che si insinua lentamente sia nei contatori di importazione sia in quelli di esportazione. Le letture istantanee (corrente, potenza, ...) non sono influenzate — solo i contatori di energia.
I valori fuori dall'insieme ammesso (ad esempio 15 o 3000) vengono rifiutati dallo schema, quindi un valore non valido non arriva mai al bus. L'impostazione viene memorizzata sul modulo e verificata dopo la scrittura; un valore uguale a quello memorizzato non viene riscritto.
rbamp:
start_current_ua: 400
Il valore memorizzato si può rileggere da una lambda con id(meter1).read_start_current_ua() (restituisce 65535 quando non disponibile).
period_banks
| Attributo | Valore |
|---|---|
| Tipo | elenco di voci di banco |
| Voci per elenco | da 1 a 8, ciascun bank: (da 0 a 7) elencato una sola volta |
| Predefinito | Nessuno |
| Obbligatorio | No |
| Si applica a | Moduli STANDARD che pubblicizzano banchi di snapshot (immagine 0x7E e successive); su qualsiasi altro modulo le voci restano non disponibili e il log lo segnala una volta all'avvio |
Il modulo mantiene otto banchi di snapshot indipendenti. Ogni voce misura un periodo — il tempo tra due blocchi dello stesso banco, cronometrato con il clock dell'ESP32 — e pubblica medie, picchi ed energia del periodo. Usalo per «energia per ora», «picco di corrente dall'ultima pressione» e domande simili cui i totali correnti non rispondono.
| Chiave | Significato |
|---|---|
bank |
Numero di banco 0..7. Il banco 0 è libero sui moduli con contatori di energia integrati; su un modulo senza contatori il componente usa il banco 0 stesso e la voce viene ignorata con un avviso. |
interval |
Cadenza facoltativa e automatica dello snapshot, di almeno 1s. Senza di essa il banco viene bloccato solo dall'azione rbamp.latch_bank. |
power, reactive_power, apparent_power |
Media sul periodo. |
energy, energy_exported |
Wh importati / esportati nel periodo (non contatori — hanno state_class: measurement). |
max_power, max_current, max_voltage, min_voltage |
Estremi all'interno del periodo. |
period_length |
La durata del periodo in secondi, come misurata dall'ESP32. |
channels |
Elenco facoltativo, una voce per canale di corrente (prima voce = canale 0), ciascuna con power, energy, energy_exported. |
Il primo latch di un banco dopo l'avvio, o dopo il riavvio del modulo, avvia solo il periodo; i suoi valori vengono scartati e i sensori pubblicano dal latch successivo in poi. I latch di banchi diversi sono mantenuti distanti almeno 150 ms.
rbamp:
id: meter1
period_banks:
- bank: 1
interval: 1h
power: {name: "Hour average power"}
energy: {name: "Hour energy"}
max_current: {name: "Hour peak current"}
- bank: 2 # latched by hand
energy: {name: "Energy since last press"}
period_length: {name: "Since last press, s"}
button:
- platform: template
name: "Latch bank 2"
on_press:
- rbamp.latch_bank:
id: meter1
bank: 2
Un esempio completo è in example/std_banks.yaml.
bidirectional
| Attributo | Valore |
|---|---|
| Tipo | bool |
| Predefinito | false |
| Obbligatorio | No |
Abilita il percorso di energia esportata per canale (energy_exported, energy_exported_1, energy_exported_2). Con true, l'energia esportata viene accumulata separatamente da quella importata.
Su un modulo STANDARD l'energia esportata viene dai contatori del modulo, quindi sopravvive ai riavvii ed è monotona. Su un modulo BASIC la linea è unidirezionale: i sensori energy_exported_* sono accettati dallo schema ma pubblicano 0.
Dichiarare energy_exported (o _1 / _2) sotto sensor.platform: rbamp solo quando è impostato bidirectional: true. Le chiavi di totale generale energy_exported_total ed energy_net non richiedono questa chiave.
rbamp:
bidirectional: true # needed for the per-channel energy_exported* sensors
new_address
Cambio di indirizzo (inizializzazione) · 4.5 Indirizzo (0x30..0x31) (riferimento API) · 6.1 Cambio di indirizzo — commit in due fasi (adatto alla produzione) (riferimento API)
| Attributo | Valore |
|---|---|
| Tipo | i2c_address (0x08..0x77) |
| Predefinito | Nessuno (facoltativo) |
| Obbligatorio | No |
Attiva un cambio di indirizzo I²C una tantum all'avvio. Deve differire da address — il validatore segnala un errore se sono uguali.
Sul firmware v1.3 si usa un commit in due fasi — produzione-OK senza blocco del provisioning di fabbrica. Comportamento di compatibilità:
| Firmware | Comportamento |
|---|---|
| Dichiara il commit dell'indirizzo in due fasi (v1.3+) | Percorso di produzione — scrittura in fase di staging, conferma esplicita, commit, nuova enumerazione. |
| Non lo pubblicizza (legacy v1.0-v1.2) | Ripiego legacy — scrittura monofase, richiede la modalità di provisioning di fabbrica. Registra WARN_FACTORY_MODE_REQUIRED se non è in modalità di provisioning. |
I moduli STANDARD supportano anche new_address:; il componente lo applica e si ricollega al nuovo indirizzo nello stesso modo.
Il flusso completo gira una volta in setup():
- Interrogare il
addressattuale. Se il modulo non risponde lì ma risponde anew_address, il componente si adatta al nuovo indirizzo con un avviso (supponendo che un avvio precedente abbia già applicato la modifica) e salta la scrittura. - Verifica se il firmware dichiara il commit in due fasi. Sì → percorso di produzione (vedi sotto). No → percorso legacy con il controllo della modalità di provisioning.
- Percorso di produzione (v1.3): predisporre il nuovo indirizzo, confermare, eseguire il commit → attendere ~700 ms → ripetere la verifica di
new_address. Non è richiesta alcuna abilitazione della modalità di fabbrica. - Percorso legacy (v1.0-v1.2): scrittura monofase, richiede la modalità di provisioning di fabbrica sul lato modulo.
- Il componente cambia il suo indirizzo I²C interno tramite
i2c::I2CDevice::set_i2c_address()impostandonew_addresse verifica che il modulo risponda. - Se il modulo non risponde dopo la modifica, il componente chiama
mark_failed()e si ferma.
Dopo un cambio riuscito: modifica il YAML con address: e rimuovi new_address:. Se al successivo avvio il modulo è già sul nuovo indirizzo ma new_address: è ancora nel YAML, la sonda all'avvio sul vecchio indirizzo fallisce, quella sul nuovo riesce, il componente si adatta con un avviso e non avviene alcuna riscrittura.
⚠ Solo modalità di fabbrica sul firmware legacy (v1.0-v1.2).
I moduli di produzione standard con firmware legacy sono stati consegnati con la modalità di provisioning disabilitata. Scrivere new_address: su un modulo del genere senza modalità di fabbrica viene rifiutato (avviso WARN_FACTORY_MODE_REQUIRED). Con firmware v1.3 questa restrizione non c'è più — il componente rileva automaticamente il percorso di produzione.
⚠ Rienumerazione dopo il commit. Dopo un commit riuscito il modulo si resetta e si rienumera al nuovo indirizzo. Le chiamate successive nello stesso setup() vengono dirette al nuovo indirizzo in modo trasparente — ma qualsiasi altro master sul bus (uno strumento I²C grezzo, una sonda di debug, un altro ESP32) considera ancora il modulo all'indirizzo vecchio finché non aggiorna il proprio stato.
rbamp:
address: 0x50
new_address: 0x51 # remove this line after the first successful boot
Recupero: se il cambio di indirizzo è stato applicato ma il modulo non risponde, vedere 10_troubleshooting.md → "Address changed, but the module doesn't respond".
Riferimento incrociato: il riferimento sul cambio di indirizzo a runtime.
fleet_gc_enable (NUOVO in v1.3)
General Call (broadcast all'indirizzo 0x00) (initialization) · Multi-modulo — snapshot simultaneo (period-metering) · 4.4 Configurazione della flotta (0x27..0x2F) (api-reference)
| Attributo | Valore |
|---|---|
| Tipo | bool |
| Predefinito | false |
| Obbligatorio | No |
| Si applica a | Moduli BASIC con supporto allo snapshot general-call (firmware v1.3+); ignorato con una riga di log su STANDARD |
Opzionale: abilita la ricezione dello snapshot broadcast General-Call dal master. Quando l'ESP32 emette un frame GC di 5 byte all'indirizzo 0x00, tutti i moduli con fleet_gc_enable: true (e un group_id: corrispondente) acquisiscono atomicamente uno snapshot dei loro accumulatori di periodo in un unico momento sul filo. Questo garantisce una sincronizzazione stretta tra i sotto-contatori.
Comportamento della capacità: all'avvio il componente verifica se il firmware pubblicizza lo snapshot general-call. Se no → avviso + salto senza applicare:
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).
Persistenza: all'applicazione il componente scrive REG_FLEET_CONFIG.bit0, salva in flash tramite CMD_SAVE_USER_CONFIG e RESETTA il dispositivo — la modalità GC è configurata in fase di init, non commutabile a caldo. Con lettura-confronto-scrittura questo avviene una volta al primo avvio; i successivi avvii lo saltano.
rbamp:
- id: mains
fleet_gc_enable: true # opt-in, capability-gated
group_id: 1 # see below
- id: boiler
fleet_gc_enable: true
group_id: 1 # same group → synchronized
Riferimento incrociato: il riferimento Fleet Group-Commit, 04_hardware.md Multi-module fleet.
group_id (NUOVO in v1.3)
General Call (broadcast all'indirizzo 0x00) (initialization) · Multi-modulo — snapshot simultaneo (period-metering) · 4.4 Configurazione della flotta (0x27..0x2F) (api-reference)
| Attributo | Valore |
|---|---|
| Tipo | uint8_t (0..255) |
| Predefinito | 0 |
| Obbligatorio | No |
| Si applica a | Moduli BASIC; ignorato con una riga di log su STANDARD |
Un identificatore di cluster per lo snapshot GC selettivo. Il modulo accetta un frame GC solo se il campo di gruppo del frame corrisponde a questo group_id OPPURE è uguale a 0x00 (all-call).
Casi d'uso:
-
Multi-tenant: un ESP32 pilota più cluster indipendenti di moduli (ad es. 3 appartamenti in un unico quadro). Cluster 1 =
group_id: 1, cluster 2 =group_id: 2. Il master emette un frame GC con gruppo=1 → solo il cluster 1 esegue lo snapshot. -
Monotenant: lasciare
group_id: 0(chiamata generale) oppure impostaregroup_id: 1come etichetta — il comportamento è identico, tutti i moduli fanno uno snapshot.
Persistenza: scritto in REG_GROUP_ID e salvato in flash tramite lettura-confronto-scrittura. Per cambiarlo serve un avvio.
rbamp:
- id: apt1_mains
group_id: 1
- id: apt2_mains
group_id: 2
broadcast_latch (deprecato, legacy v0.4.0)
| Attributo | Valore |
|---|---|
| Tipo | bool |
| Predefinito | false |
| Obbligatorio | No |
| Stato | Deprecato — sostituito da fleet_gc_enable: (v1.3+). |
Un alias legacy per lo snapshot broadcast General-Call. Nella v1.3 questa chiave è accettata dallo schema come no-op (per una migrazione senza rotture dallo YAML v0.4.0), ma non ha effetto. Per il nuovo codice usa fleet_gc_enable: — è condizionata dalle capacità e funziona con il firmware v1.3.
Sarà rimosso in una futura release minore; nel log compare un avviso di deprecazione:
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.
Riferimento incrociato: il riferimento Fleet Group-Commit.
topology
| Attributo | Valore |
|---|---|
| Tipo | enum (SINGLE, SPLIT_PHASE, THREE_PHASE) |
| Predefinito | SINGLE |
| Obbligatorio | No |
Suggerimento facoltativo, mantenuto per compatibilità con le versioni precedenti. Non è necessario sui moduli STANDARD: il componente legge dal modulo stesso il numero di canali, la variante e le funzionalità, e dimensiona da lì l'insieme delle entità. Sui moduli BASIC il numero di canali deriva dagli slot current[_1/_2] dichiarati, mentre topology: modifica solo la riga stampata da dump_config.
rbamp:
topology: SINGLE # cosmetic; may be omitted
2. Piattaforma sensore — sensor.platform: rbamp
Ogni blocco sensor: dichiara un insieme di sensori con nome legati al componente padre rbamp:. L'unica chiave obbligatoria nel blocco è rbamp_id.
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"
Tutti i campi sotto il blocco sensor: sono facoltativi, con una regola: power, energy, power_factor, reactive_power e apparent_power richiedono voltage E current dichiarati nello stesso blocco (i sensori di canale numerati power_N, energy_N, power_factor_N, reactive_power_N richiedono current_N e voltage); altrimenti esphome config fallisce con "power requires current to also be declared". Aggiungere internal: true a un sensore richiesto che non si vuole come entità di Home Assistant. Dichiarare solo le grandezze che lo scenario richiede — il componente legge solo i registri corrispondenti ai sensori dichiarati.
rbamp_id
| Attributo | Valore |
|---|---|
| Tipo | use_id(RbAmpComponent) |
| Obbligatorio | Sì |
Fa riferimento al blocco rbamp: a cui è legato questo gruppo di sensori.
2.1 Campi singoli
Corrente multi-canale (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Finestra di accesso ai canali (0x32 + 0x3C..0x3F) (api-reference)
Usato per moduli a tensione singola (UI1, UI2, UI3, I1, I2, I3 e varianti con più canali). Tutti i campi sono facoltativi. Mescolarli con i campi a fasi (voltage_a, voltage_angle_b, ecc.) genera un errore di validazione.
Ci sono slot per fino a sette canali di corrente: current e current_1 ... current_6, e analogamente power, energy e power_factor con gli stessi suffissi (power_3, energy_5, ...). energy_exported esiste per i canali da 0 a 2 (energy_exported, energy_exported_1, energy_exported_2). Uno slot oltre il numero di canali riportato dal modulo non pubblica mai. reactive_power esiste solo per i canali da 0 a 2 (reactive_power, reactive_power_1, reactive_power_2); reactive_power_3 ... reactive_power_6 sono accettati dallo schema ma non pubblicano mai.
Ogni campo accetta le sottochiavi standard di sensor.sensor_schema di ESPHome: name, id, filters, unit_of_measurement, accuracy_decimals, icon, e così via.
voltage
Riferimento dei registri RT (realtime-polling) · 4.10 Blocco in tempo reale V03 (0x86..0xBD) (api-reference)
| Attributo | Valore |
|---|---|
| Unità | V |
device_class |
voltage |
state_class |
measurement |
accuracy_decimals |
1 |
| Fonte | Tensione di rete RMS (registro istantaneo del modulo) |
Tensione di rete RMS. Letta a ogni update() una volta che il modulo è pronto. Il float a 4 byte viene letto con ripetizione per byte (3 tentativi × 5 ms) e supera il controllo std::isfinite() più |val| < 10000.
Zero è un valore valido da pubblicare: un evento di interruzione di rete o di brownout produce U ≈ 0 V e passa a HA senza filtri — il filtro di integrità scarta solo NaN/Inf, non gli zeri legittimi.
voltage:
name: "Mains Voltage"
filters:
- sliding_window_moving_average:
window_size: 3
send_every: 1
current / current_1 ... current_6
| Attributo | Valore |
|---|---|
| Unità | A |
device_class |
current |
state_class |
measurement |
accuracy_decimals |
3 |
Corrente RMS per i canali 0, 1, 2, ... Il canale 0 è la pinza TA principale; i canali 1 e 2 sono presenti sulle varianti UI2 / UI3 e I2 / I3, i canali da 3 a 6 sulle varianti con più canali.
Su un modulo BASIC il numero di canali attivi deriva dal numero di slot dichiarati: se è dichiarato solo current, il componente usa 1 canale; con current e current_1, 2; aggiungendo current_2 si hanno 3. Su un modulo STANDARD il numero di canali proviene dal modulo stesso; gli slot dichiarati oltre tale numero semplicemente non vengono mai pubblicati.
current:
name: "Phase Current"
current_1:
name: "Load 1 Current"
current_2:
name: "Load 2 Current"
power / power_1 ... power_6
Riferimento dei registri RT (realtime-polling) · 4.10 Blocco in tempo reale V03 (0x86..0xBD) (api-reference)
| Attributo | Valore |
|---|---|
| Unità | W |
device_class |
power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dipendenze | power richiede current + voltage; power_N richiede current_N + voltage |
Potenza attiva in watt, con segno. Valori negativi = flusso inverso (immissione in rete) sui moduli STANDARD. Su BASIC, i valori istantanei negativi all'interno della finestra del periodo vengono portati a 0 a livello firmware — la media del periodo è ≥ 0. La potenza attiva istantanea può ancora leggere negativa nel momento della generazione.
Dichiarare power senza current + voltage genera un errore di validazione: power requires current to also be declared.
power:
name: "Active Power"
energy / energy_1 ... energy_6
Algoritmo lato master (period-metering) · 7 · Semantica (riferimento API)
| Attributo | Valore |
|---|---|
| Unità | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dipendenze | energy richiede current + voltage; energy_N richiede current_N + voltage |
Energia consumata (importata) accumulata in Wh per il canale.
- Moduli STANDARD — il componente accumula i contatori di energia propri del modulo. I totali sopravvivono ai riavvii sia dell'ESP32 sia del modulo e sono monotoni (non tornano indietro quando il modulo si riavvia o un contatore viene azzerato).
- Moduli BASIC — calcolato sull'ESP32 dalla potenza media di periodo restituita dal modulo dopo ogni snapshot:
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600
In entrambi i casi il valore viene salvato nella flash dell'ESP32 (NVS) ogni 5 minuti e allo spegnimento pulito (riavvio / OTA), e ripristinato prima del primo publish_state all'avvio — ciò impedisce alla dashboard Energia di HA di interpretare uno 0 istantaneo come un azzeramento del contatore. Su BASIC, una interruzione improvvisa di corrente fa perdere al massimo gli ultimi 5 minuti di energia (≈ 5 Wh con una media di 60 W). Quando il layout NVS cambia (incremento di versione), il contatore riparte da 0.
state_class: total_increasing è richiesto per la dashboard Energia di HA. Il valore cresce in modo monotono; in funzionamento normale non diminuisce.
energy:
name: "Mains Energy"
energy_exported / energy_exported_1 / energy_exported_2
| Attributo | Valore |
|---|---|
| Unità | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dipendenze | Richiede current + voltage + bidirectional: true |
Energia di esportazione (generazione) in Wh per i canali da 0 a 2, accumulata separatamente da energy. Impostare bidirectional: true nel blocco rbamp: quando si dichiarano questi sensori. Sui moduli STANDARD i valori provengono dai contatori del modulo (persistenti, monotoni). Sui moduli BASIC i sensori sono accettati ma pubblicano 0.
power_factor / power_factor_1 ... power_factor_6
| Attributo | Valore |
|---|---|
| Unità | (dimensionless) |
device_class |
power_factor |
state_class |
measurement |
accuracy_decimals |
3 |
| Dipendenze | Richiede current + voltage per lo slot corrispondente |
Fattore di potenza nell'intervallo da −1 a +1. Un PF negativo indica un carico anticipato o ritardato; la convenzione sui segni è definita dal firmware. Il filtro di integrità (§B.5) scarta i valori fuori da |pf| > 10000; non c'è un limite inferiore.
power_factor:
name: "Power Factor"
reactive_power / reactive_power_1 / reactive_power_2
| Attributo | Valore |
|---|---|
| Unità | VAr |
device_class |
reactive_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dipendenze | Richiede current + voltage per lo slot corrispondente |
Potenza reattiva in var. Senza segno (≥ 0), calcolata come √(S² − P²), include la distorsione; nessuna precisione dichiarata. I carichi induttivi e capacitivi non vengono distinti. Letta dal modulo a ogni ciclo update(); pubblicata solo per i canali 0..2 (reactive_power_3 ... reactive_power_6 sono accettati dallo schema ma non pubblicano mai). Non è dichiarata alcuna precisione per la potenza reattiva.
reactive_power:
name: "Reactive Power"
Nota su device_class: reactive_power — ESPHome lo accetta (la costante DEVICE_CLASS_REACTIVE_POWER) e il valore passa a Home Assistant. Tuttavia l'elenco ufficiale di Home Assistant per device_class è cambiato nel tempo: in alcune versioni reactive_power è disponibile nell'interfaccia e funziona con unit_of_measurement VAr, in altre viene mostrato come sensore generico senza icona né conversione di unità specifiche. I dati vengono sempre pubblicati (sono solo uno state); la sola questione è come HA visualizza il sensore in Lovelace. Se il sensore risulta sconosciuto nella versione di HA in uso, è un fatto estetico, non una regressione funzionale. Rimuovere la chiave reactive_power: dal YAML se il sensore non viene usato.
apparent_power
| Attributo | Valore |
|---|---|
| Unità | VA |
device_class |
apparent_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Fonte | Calcolata sul master: S = V_rms × I_rms[0] |
| Dipendenze | Richiede current + voltage |
Potenza apparente in VA. Calcolata dal componente a partire dai valori U_rms e I0_rms letti nello stesso ciclo update() — non viene letto alcun registro separato. Entrambe le letture devono riuscire nello stesso ciclo; se anche una sola fallisce (tentativi esauriti), in quel ciclo non viene pubblicato alcuno stato e in HA resta l'ultimo valore.
apparent_power è in SHARED_FIELDS e funziona con qualsiasi topologia, ma dipende da voltage e current per il calcolo V × I.
apparent_power:
name: "Apparent Power"
2.2 Campi per fase (varianti a tensione multipla)
Per i moduli con più di un ingresso di tensione (varianti split-phase e trifase) i sensori sono dichiarati per fase. Lo schema accetta il gruppo per fase su qualsiasi modulo; uno slot pubblica solo quando il modulo collegato segnala effettivamente il canale corrispondente, altrimenti resta senza valore.
I campi singoli e per fase si escludono a vicenda all'interno di un blocco sensor:. Il validatore segnala un errore:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).
Tutti i campi per fase condividono gli stessi valori predefiniti di sensor_schema dei rispettivi campi monofase (stesse unità, device_class, state_class, accuracy_decimals).
| Campo | Unità | device_class |
|---|---|---|
voltage_a / _b / _c |
V | voltage |
current_a / _b / _c |
A | corrente |
power_a / _b / _c |
W | potenza |
power_total |
W | potenza |
energy_a / _b / _c |
Wh | energia |
energy_exported_a / _b / _c |
Wh | energia |
power_factor_a / _b / _c |
— | power_factor |
reactive_power_a / _b / _c |
VAr | reactive_power |
voltage_angle_b / _c |
° | — |
voltage_angle_b e voltage_angle_c pubblicano l'angolo di fase delle tensioni B e C in gradi, rispetto alla fase A (la fase A è il riferimento di 0°, quindi non esiste voltage_angle_a). Richiedono un firmware del modulo che fornisca gli angoli; sui firmware più vecchi il componente registra un avviso all'avvio e i sensori non pubblicano mai. Finché l'angolo non può essere determinato, il valore è «sconosciuto».
La validazione della dipendenza per fase non è applicata ai campi a fasi (solo _SINGLE_SLOT_DEPS per il monofase).
Example:
rbamp:
id: panel_meter
address: 0x50
sensor:
- platform: rbamp
rbamp_id: panel_meter
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_total:
name: "Total Active Power"
voltage_angle_b:
name: "Phase B Angle"
voltage_angle_c:
name: "Phase C Angle"
2.3 Campi condivisi (indipendenti dalla topologia)
Questi campi funzionano in qualsiasi gruppo di topologia, incluso il caso in cui non sia dichiarato alcun sensore di corrente monofase o per fase (un'installazione solo tensione o solo frequenza).
frequency
| Attributo | Valore |
|---|---|
| Unità | Hz |
device_class |
frequency |
state_class |
measurement |
accuracy_decimals |
0 |
Frequenza di rete. I valori non plausibili (il modulo segnala «non ancora misurato») vengono scartati senza pubblicazione, evitando una transizione «Sconosciuto» → 0 Hz → 50 Hz nell'entità HA durante il riscaldamento.
frequency:
name: "Mains Frequency"
apparent_power
Vedere la voce sotto i campi singoli sopra. apparent_power richiede current e voltage, quindi va inserito in un blocco sensore monofase.
energy_total / energy_exported_total / energy_net
| Sensore | Unità | state_class |
Significato |
|---|---|---|---|
energy_total |
Wh | total_increasing |
Energia importata, tutti i canali del modulo |
energy_exported_total |
Wh | total_increasing |
Energia esportata, tutti i canali del modulo |
energy_net |
Wh | total |
Importazione meno esportazione. Può diminuire. |
Totali generali su tutti i canali del modulo, presi dai contatori di energia propri del modulo (moduli STANDARD). Sopravvivono ai riavvii dell'ESP32 e del modulo, sono monotoni tra i riavvii del modulo e i reset dei contatori (eccetto energy_net, che è la differenza di due valori monotoni), e sono anche salvati in NVS ogni 5 minuti e allo spegnimento pulito. Non richiedono la chiave bidirectional: né una dichiarazione companion di current/voltage.
Su un modulo senza contatori di energia integrati (BASIC) queste chiavi vengono validate ma non pubblicano mai; il componente registra un avviso all'avvio. Usa lì i sensori energy per canale.
sensor:
- platform: rbamp
rbamp_id: meter1
energy_total:
name: "Energy Imported"
energy_exported_total:
name: "Energy Exported"
energy_net:
name: "Energy Net"
reactive_energy / reactive_energy_exported
| Attributo | Valore |
|---|---|
| Unità | varh |
state_class |
total_increasing |
accuracy_decimals |
3 |
Energia reattiva (importazione / esportazione) su tutti i canali, dagli stessi contatori on-device e con la stessa persistenza di energy_total. Solo moduli STANDARD; sugli altri le chiavi vengono validate ma non pubblicano mai.
phase_sequence
| Attributo | Valore |
|---|---|
| Unità | — |
accuracy_decimals |
0 |
Rotazione di fase di un modulo a tre tensioni: 1 = diretta, 2 = inversa, 3 = anomala. "Unknown" [Sconosciuto] finché non può essere determinata (meno di tre ingressi di tensione attivi). Richiede un firmware del modulo che la fornisca; altrimenti il componente registra un avviso all'avvio e il sensore non pubblica mai. In una lambda, id(meter1).get_phase_sequence_str() restituisce "forward", "reverse", "abnormal", "n/a" o "unavailable".
2.4 Regole di validazione dello schema
Il validatore Python _validate_topology_consistency applica due classi di regole durante esphome config / la compilazione — prima che giri qualsiasi codice C++.
Mutua esclusione delle topologie
I campi monofase (voltage, current, current_1, ecc.) e i campi per fase (voltage_a, voltage_b, ecc.) non possono coesistere in un unico blocco sensor:. Un tentativo di mescolarli:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.
Il gruppo per fase include voltage_angle_b / voltage_angle_c.
Requisiti di companion per slot (solo monofase)
Ogni grandezza derivata richiede i campi di ingresso che il modulo usa per calcolarla:
| Campo dichiarato | Companion richiesti |
|---|---|
power / _1 ... _6 |
current (o _1 ... _6, stesso suffisso) + voltage |
energy / _1 ... _6 |
current (o _1 ... _6, stesso suffisso) + voltage |
power_factor / _1 ... _6 |
current (o _1 ... _6, stesso suffisso) + voltage |
reactive_power / _1 / _2 |
current (o _1 ... _6, stesso suffisso) + voltage |
apparent_power |
current + voltage |
energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* e phase_sequence non hanno requisiti di companion nello schema.
Un companion mancante genera:
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.
Altre regole a livello del blocco rbamp:
| Regola | Descrizione |
|---|---|
ct_model: ↔ ct_models: si escludono a vicenda |
Ne può essere usato solo uno dei due per blocco rbamp: — altrimenti un errore di validazione. |
new_address ≠ address |
Se coincidono — cv.Invalid. |
address nell'intervallo 0x08..0x77 |
Viene applicato cv.i2c_address. |
update_interval ≥ 1s |
Intervalli più brevi vengono rifiutati. |
latch_interval ≥ update_interval |
Una cadenza di snapshot più breve viene rifiutata. |
ct_models: ha da 1 a 16 voci |
Gli elenchi più lunghi vengono rifiutati. |
group_id va da 0 a 255 |
I valori fuori intervallo vengono rifiutati. |
start_current_ua è 0 oppure da 10 a 2540 a passi di 10 |
Qualsiasi altro valore viene rifiutato. |
ct_model_force: true richiede ct_model: o ct_models: |
Rifiutato da solo. |
period_banks: — ogni bank una volta, interval ≥ 1s |
Un banco duplicato, un banco fuori da 0..7 o un intervallo più breve viene rifiutato. |
Codice modello TA valido per la sensor_class fissata |
Un codice non ammesso per la classe viene rifiutato, con l'elenco dei valori consentiti. |
Tutti gli errori di validazione vengono segnalati durante esphome compile con un messaggio leggibile che indica la chiave colpevole. Non serve flashare l'hardware per trovare un errore di configurazione.
3. Flusso dei dati e tempistica
Polling — modulo singolo (realtime-polling) · 3. DATA_VALID (0xCE) non diventa mai 1 (troubleshooting) · 4 · Mappa dei registri (produzione v1.3) (api-reference)
Il flusso concettuale di un singolo ciclo update():
Module (autonomous) ESP32 (ESPHome component)
───────────────────────────────── ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
↓ (~100 ms per cycle)
Atomically publishes the block update() fires every update_interval (60 s)
of instantaneous registers ↓
↓ phase 1 — snapshot:
write the snapshot command
Closes the period accumulator, 50 ms timeout (non-blocking)
opens a new one ↓ (main loop keeps running)
↓
wait 50 ms phase 2 — period snapshot:
read the valid flag
read per-channel average powers
E_Wh[ch] += avg_P × dt_s / 3600
save to NVS if 5 minutes elapsed
↓
phase 3 — instantaneous values:
read the status register
read U_rms, I[0..n]_rms, P[0..n],
PF[0..n], Q[0..n], frequency
publish all bound sensors
↓
Push state to HA over the native API
Il diagramma mostra il flusso BASIC basato sugli snapshot. Un modulo STANDARD mantiene i propri contatori di energia: a ogni update() il componente legge i valori istantanei e lo snapshot del contatore (una transazione coerente) e somma la differenza ai totali correnti, quindi il passaggio di snapshot non viene usato per l'energia.
Tempi caratteristici:
| Evento | Cadenza |
|---|---|
| Commit interno del blocco istantaneo da parte del modulo | ~100 ms |
Chiamata update() |
update_interval (60 s di default) |
| Timeout di assestamento dopo il comando di snapshot | 50 ms (non bloccante) |
| Salva in NVS | Ogni 5 minuti |
| Pausa tra i tentativi di ripetizione per byte | 5 ms, fino a 3 tentativi |
| Finestra di scrittura in flash durante la scrittura del modello | ~700 ms (il modulo risponde con NACK per tutto il tempo) |
Il timeout di assestamento dello snapshot non è bloccante — lo scheduler cooperativo di ESPHome continua a servire Wi-Fi, API e gli altri componenti durante l'attesa di 50 ms. Le fasi restanti di update() (lettura dei registri istantanei) vengono eseguite subito dopo il ritorno dalla fase di snapshot.
L'avviso [W][component:522]: rbamp took a long time for an operation (XXX ms) è previsto e innocuo quando compare. Con firmware v1.3 il componente legge il blocco dei valori istantanei con una singola lettura a raffica (auto-incremento READ), quindi un ciclo sano resta ben sotto i 30 ms. L'avviso compare quando il percorso a raffica ricade su letture per singolo registro (4 transazioni per float, fino a 36 transazioni a 50 kHz, più i tentativi) — di solito a causa di un bus marginale o di un firmware legacy senza la capacità di lettura a raffica.
4. Impostazioni del bus I2C
Il componente rbamp eredita il bus I²C configurato nel blocco di primo livello i2c:. Impostazioni consigliate sul firmware attuale:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
scan: true # optional: logs the addresses found at boot
Velocità del bus: usare 50kHz sui master basati su ESP-IDF (ESP32 con ESPHome o Arduino). Il modulo invia periodicamente NACK a 100 kHz (una quota sensibile delle transazioni) a causa di una nota interazione con il driver ESP-IDF i2c_master (confermata in esp-idf issue #9426, marcata "Won't Do" da Espressif). Il firmware v1.1/v1.3 ha irrobustito il lato modulo, ma l'interazione con il driver persiste — 50 kHz è la raccomandazione permanente. La mitigazione a tre livelli del componente (ritentativo + controllo di integrità + 50 kHz) porta il tasso di letture errate sotto l'1%.
Resistori di pull-up: si consigliano 4.7 kΩ verso 3.3 V su SDA e SCL. Valori più alti (10 kΩ) aumentano il tempo di salita e il tasso di NACK a 100 kHz.
Più dispositivi: il bus I²C dell'ESP32 supporta fino a 112 dispositivi a indirizzi distinti a 7 bit. Usare address: e new_address: per assegnare un indirizzo unico a ciascun modulo. scan: true nel blocco i2c: registra all'avvio ogni indirizzo che risponde — verificare che ogni modulo sia rilevato prima di abilitare la misura per periodo.
La mappa completa dei registri a livello di filo e l'insieme dei comandi del modulo sono nella pagina pubblica di riferimento dell'API. Per l'utente tipico dello schema YAML questo capitolo basta — ogni registro è nascosto dietro l'interfaccia dichiarativa del componente.
5. Superficie di identità (NUOVO in v1.3) — metodi C++ pubblici
Rilevamento automatico della variante del modulo (initialization) · 3. DATA_VALID (0xCE) non diventa mai 1 (troubleshooting) · Codici di errore (REG_ERROR = 0x02) (troubleshooting)
Il componente v1.3 espone getter di identità / diagnostica accessibili da una lambda: YAML e tramite la piattaforma template. Tutti i metodi restituiscono una std::string (per compatibilità con text_sensor) o tipi primitivi — nessuna eccezione, tutto tramite stato in cache.
| Metodo | Tipo di ritorno | Fonte | Descrizione |
|---|---|---|---|
get_variant_str() |
std::string |
REG_HW_VARIANT (0x55) |
"UI1"/"UI2"/"UI3"/"I1"/"I2"/"I3"/"UNK" — la variante del modulo |
get_capability_hex() |
std::string |
registro di capacità | "0xNNNN" — la bitmap delle capacità a 16 bit, per la diagnostica |
get_uid_hex() |
std::string |
REG_UID (0x5C × 12 byte) |
Esadecimale a 24 caratteri (UID del chip a 96 bit) |
get_last_error_str() |
std::string |
REG_ERROR (0x02) |
"OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC" |
get_event_flags() |
uint8_t |
REG_EVENT_FLAGS (0x03) |
bit persistenti: bit3=ERR_LATCH, bit5=ADDR_CHANGED, ecc. |
get_firmware_version() |
uint8_t |
REG_VERSION (0x01) |
il byte di versione del modulo (ad esempio 0x04 sul firmware BASIC v1.3) |
get_std_image_version() |
uint32_t |
Solo STANDARD | Versione dell'immagine del modulo in esecuzione; 0 = sconosciuta o BASIC |
get_phase_sequence_str() |
std::string |
Solo STANDARD | "forward"/"reverse"/"abnormal"/"n/a"/"unavailable" |
read_start_current_ua() |
uint16_t |
Solo STANDARD | Lettura aggiornata della corrente di avvio memorizzata in µA; 65535 = non disponibile |
read_gc_tick_received() |
uint16_t |
REG_GC_LAST_TICK (0x58) |
ultimo valore del tick catturato dal frame GC |
get_capability_cached() |
uint16_t |
bitmap delle capacità in cache | la mappa di bit letta all'avvio, senza transazione sul bus |
Cache: variant / capability / uid / firmware_version vengono letti una volta in setup() e messi in cache — le chiamate successive non vanno sul bus. last_error_str() / event_flags() / gc_tick vengono letti a ogni chiamata per avere dati aggiornati.
Uso tramite un text_sensor template
text_sensor:
- platform: template
name: "Mains variant"
update_interval: 30s
lambda: 'return id(mains_meter).get_variant_str();'
# → entity_id: sensor.mains_variant, value: "UI1"
- platform: template
name: "Mains capability"
update_interval: 30s
lambda: 'return id(mains_meter).get_capability_hex();'
# → the capability bitmap as hex, "0xNNNN" (diagnostics only)
- platform: template
name: "Mains UID"
update_interval: 30s
lambda: 'return id(mains_meter).get_uid_hex();'
- platform: template
name: "Mains last error"
update_interval: 30s
lambda: 'return id(mains_meter).get_last_error_str();'
- platform: template
name: "Mains firmware version"
update_interval: 30s
lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'
Questi text_sensor compaiono in HA come sensor.mains_variant e simili — utili per le dashboard di inventario, gli scenari di tracciamento degli asset e la verifica post-flash.
Usa tramite lambda: nelle automazioni
sensor:
- platform: rbamp
rbamp_id: mains
energy: { name: "Mains Energy" }
# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
on_boot:
then:
- lambda: |-
ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());
6. Flotta e sincronizzazione GC (v1.3 NUOVO)
transmit_gc_frame() — emissione GC programmatica
bool transmit_gc_frame();
Emette un frame General-Call di snapshot di 5 byte verso l'indirizzo di bus 0x00. Il byte di gruppo è il group_id: dell'istanza e il tick è un contatore auto-incrementante; il metodo restituisce true quando la scrittura sul bus riesce. Solo moduli BASIC — su un modulo STANDARD registra un avviso e non fa nulla:
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP
Tutti i moduli con fleet_gc_enable: true + un group_id: corrispondente (oppure group_id: 0) fanno uno snapshot dei propri accumulatori di periodo in modo sincrono in un unico istante sul filo. Il valore del tick viene memorizzato da ciascun modulo per la verifica della sincronia (read_gc_tick_received()).
Emissione automatica: il componente emette automaticamente un frame GC in update() se fleet_gc_enable: true e il firmware pubblicizza lo snapshot general-call. Un'emissione manuale serve solo per una sincronizzazione extra (ad esempio, su un trigger di evento lato HA).
Verifica delle capacità: se il firmware non dichiara lo snapshot general-call — avviso, nessun invio.
fleet_apply_now() — forza la riapplicazione lettura-confronto-scrittura
bool fleet_apply_now();
Ripete per forza la lettura-confronto-scrittura per le impostazioni di flotta: rilegge la configurazione di flotta del modulo e l'id del gruppo, li confronta con fleet_gc_enable: / group_id: dal YAML e scrive la differenza. Restituisce false (senza fare nulla) su un modulo STANDARD.
Caso d'uso: dopo aver riportato un modulo ai valori predefiniti con uno strumento di debug, oppure per la verifica post-OTA che la configurazione di flotta sia stata applicata.
7. Servizi API nativi (v1.3 NUOVO) — automazioni di ripristino
Codici di errore (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recupero dallo stato di errore — albero decisionale (api-reference)
Il componente v1.3 non registra i servizi automaticamente — lo fa il YAML. Ma i metodi pubblici write_clear_error() / write_reset() / transmit_gc_frame() sono pensati per essere usati tramite il pattern api: services:. Ricette canoniche:
api:
port: 6053
services:
# Recovery: clear REG_ERROR + EVENT_FLAGS bit3
- service: mains_clear_error
then:
- lambda: 'id(mains).write_clear_error();'
# Maintenance: soft reset (preserves flash)
- service: mains_reset
then:
- lambda: 'id(mains).write_reset();'
# Fleet: manual GC snapshot (beyond the auto-emit in update())
- service: fleet_latch_now
then:
- lambda: 'id(mains).transmit_gc_frame();' # group = this instance's group_id, tick auto-increments
# Maintenance: force fleet-config re-apply (post-OTA verify)
- service: mains_fleet_apply
then:
- lambda: 'id(mains).fleet_apply_now();'
Dopodiché HA può richiamare i servizi dalle automazioni:
automation:
- alias: "Auto-clear meter error on detection"
trigger:
platform: state
entity_id: sensor.mains_last_error
from: "OK"
action:
- delay: 60s # wait one update_interval to confirm a persistent error
- service: esphome._mains_clear_error
- condition: state
entity_id: sensor.mains_last_error
state: "ERR_PARAM"
- service: persistent_notification.create
data:
title: "Meter parameter error"
message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."
8. Errore e recupero (v1.3) — REG_ERROR contro EVENT_FLAGS bit3
Nella v1.3 il modulo ha due canali di errore indipendenti:
| Canale | Registro | Semantica del latch | Cancellazione |
|---|---|---|---|
| Sincronizzazione (ultima scrittura) | REG_ERROR (0x02) |
vince l'ultima scrittura, sovrascritta dall'operazione successiva | write_clear_error() o la successiva operazione riuscita |
| Asincrono durevole | REG_EVENT_FLAGS bit3 (0x03) |
persistente, riattiva per alcune centinaia di millisecondi se la causa non viene risolta | write_clear_error() (una sola operazione cancella entrambi) |
Schema di lettura
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str(); // "ERR_PARAM" / "OK" / ...
// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;
Semantica del ripristino
Azzerare solo REG_ERROR non basta se il firmware riattiva bit3:
id(mains).write_clear_error(); // clears REG_ERROR + EVENT bit3
delay(300); // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
// Root cause not resolved — firmware re-latched bit3
ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}
Per un ripristino completo:
- Eliminare la causa (correggere il codice del modello TA nel YAML, correggere sensor_class).
write_clear_error()— cancella REG_ERROR + EVENT_FLAGS bit3.- Verifica tramite
get_event_flags()dopo ~300 ms che bit3 non sia riattivato.
Vedi 10_troubleshooting.md §6 Errore e ripristino.
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/09_api_reference.md (v1.9.1)