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

09 · Riferimento dello schema YAML

Mappa dei registri rbAmp — spazio di indirizzi della pagina 0 (0x00..0xFF)

Snapshot atomico del periodo — una scrittura chiude il periodo e ne apre il successivo

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:

  1. Blocco componente — rbamp:
  2. Piattaforma sensore — sensor.platform: rbamp
  3. Flusso dei dati e temporizzazione
  4. Impostazioni del bus I2C

1. Blocco componente — rbamp:

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.

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

YAML
rbamp:
  id: kitchen_meter

address

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

YAML
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

Attributo Valore
Tipo time (stringa di durata ESPHome)
Predefinito 60s
Obbligatorio No

Quanto spesso viene eseguito update(). Ogni chiamata:

  1. 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).
  2. 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.

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

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

YAML
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

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.

Nota

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.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

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.

YAML
rbamp:
  sensor_class: SCT_013   # default; may be omitted

Per scegliere la pinza e la famiglia, vedi 03_sensor_selection.md.


ct_model

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
Nota

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.

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

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

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

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

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

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

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

  1. Interrogare il address attuale. Se il modulo non risponde lì ma risponde a new_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.
  2. 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.
  3. 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.
  4. Percorso legacy (v1.0-v1.2): scrittura monofase, richiede la modalità di provisioning di fabbrica sul lato modulo.
  5. Il componente cambia il suo indirizzo I²C interno tramite i2c::I2CDevice::set_i2c_address() impostando new_address e verifica che il modulo risponda.
  6. 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.

Sicurezza

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

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

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:

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

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

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 impostare group_id: 1 come 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.

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

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

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

YAML
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

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

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.

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

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

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.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

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

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

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

YAML
reactive_power:
  name: "Reactive Power"
Nota

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.

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

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

Nota

La validazione della dipendenza per fase non è applicata ai campi a fasi (solo _SINGLE_SLOT_DEPS per il monofase).

Example:

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

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

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

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

Text
`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

Il flusso concettuale di un singolo ciclo update():

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

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:

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

Nota

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

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

YAML
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

YAML
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

C++
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:

Text
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

C++
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

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:

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

YAML
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

C++
// 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:

C++
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:

  1. Eliminare la causa (correggere il codice del modello TA nel YAML, correggere sensor_class).
  2. write_clear_error() — cancella REG_ERROR + EVENT_FLAGS bit3.
  3. 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)