rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub

02 · Livelli dei moduli

Le due linee di moduli rbAmp, BASIC e STANDARD (STD), e dove viene calcolata l'energia su ciascuna.

rbAmp è disponibile in due linee di moduli: BASIC e STANDARD (STD). Ogni livello è una combinazione completa di revisione hardware e build firmware, non solo un flag nel firmware. Passare da un livello all'altro richiede la sostituzione fisica del modulo, non un aggiornamento del firmware.

Il componente ESPHome funziona con entrambe le linee di moduli da un unico YAML: lo schema è condiviso e il componente riconosce automaticamente la linea di modulo collegata (BASIC o STANDARD (STD)) all'avvio. Le differenze stanno nei dati che il modulo esporta davvero e nelle chiavi YAML che hanno senso su ciascuna linea.

Livelli

BASIC — livello di ingresso

Il firmware mantiene il conteggio unidirezionale del consumo: la potenza attiva media su un periodo non può mai essere negativa — i segmenti inversi nella finestra vengono azzerati prima dell'integrazione. In pratica si comporta come un contatore meccanico a disco classico.

  • L'energia è integrata sull'ESP32 dalla potenza media di periodo che il modulo restituisce dopo ogni snapshot, e salvata nella flash dell'ESP32 (NVS).
  • Il sensore energy_exported esiste nello schema YAML (per la compatibilità della configurazione), ma su BASIC pubblica sempre 0.
  • I sensori di energia totale complessiva (energy_total, energy_exported_total, energy_net, reactive_energy, reactive_energy_exported) vengono validati ma non pubblicano mai su BASIC.
  • Applicazioni tipiche: appartamenti senza generazione in loco, sotto-misura di carichi specifici (scaldabagni, motori, elettrodomestici, HVAC).

STANDARD (STD) — bidirezionale, energia integrata nel dispositivo

STANDARD (STD) è la linea di moduli attuale. Misura importazione ed esportazione separatamente e mantiene propri contatori cumulativi di energia all'interno del modulo.

  • Stesso YAML. Il componente riconosce un modulo STANDARD (STD) all'avvio e ricava dal modulo il numero di canali, la variante e le funzionalità disponibili. Non si imposta alcuna linea e non serve topology:.
  • Energia dai contatori del modulo. Il componente accumula i contatori del modulo invece di integrare la potenza da sé, quindi i totali sopravvivono ai riavvii sia dell'ESP32 sia del modulo, restano monotoni tra i riavvii del modulo e gli azzeramenti dei contatori e non derivano. I valori vengono inoltre salvati nella flash dell'ESP32 (NVS) ogni 5 minuti e allo spegnimento pulito (riavvio / OTA).
  • Nuovi sensori: energy_total, energy_exported_total, energy_net (importazione − esportazione, può diminuire), reactive_energy, reactive_energy_exported — totali generali su tutti i canali; sulle varianti a tre tensioni anche voltage_angle_b, voltage_angle_c e phase_sequence.
  • Energia energy ed energy_exported per canale (con bidirectional: true) provengono dagli stessi contatori.
  • start_current_ua: imposta una corrente di avvio sotto la quale un canale non conteggia energia, così il rumore a vuoto non si insinua nei contatori.
  • Applicazioni tipiche: case con produzione solare/eolica, accumuli a batteria, colonnine per auto elettriche, qualsiasi installazione in cui importazione ed esportazione vadano misurate separatamente e in cui i totali di energia debbano sopravvivere ai riavvii.

Su un modulo STD l'energia proviene dai contatori propri del modulo; latch_interval si applica solo a BASIC.

Le chiavi esistenti solo per la linea di moduli BASIC (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: per il percorso di energia lato master) vengono ignorate su un modulo STANDARD con una riga di log.

Contabilità dell'energia su BASIC (il master integra la potenza media del periodo) rispetto a STANDARD (il master legge i contatori cumulativi del modulo).

Matrice delle capacità

Capacità BASIC STANDARD
Tensione RMS sì sì
Corrente RMS (da 1 a 3 canali, più sulle varianti con più canali) sì sì
Potenza attiva (float con segno) sì sì
Fattore di potenza sì sì
Potenza reattiva (letta dal modulo, canali 0..2; senza segno, calcolata come √(S² − P²), include la distorsione; nessuna precisione dichiarata) sì sì
Potenza apparente (solo CH0) sì (U × I[0], calcolata sull'ESP32) sì (dal modulo)
Frequenza di linea sì sì
Sensore energy (energia importata in Wh), salvato in NVS sì (integrato sull'ESP32) sì (dai contatori integrati)
Sensore energy_exported (richiede bidirectional: true) sempre 0 sì
L'energia sopravvive ai riavvii dell'ESP32 e del modulo Solo ESP32 sì
Totali generali: energy_total, energy_exported_total, energy_net no sì
Energia reattiva: reactive_energy, reactive_energy_exported no sì
start_current_ua: no sì
voltage_angle_b/_c, phase_sequence (varianti a tre tensioni) no sì
ct_models: per canale sì solo se il modulo memorizza i modelli per canale; altrimenti rifiutato con una riga di log
fleet_gc_enable: / group_id: sincronizzazione general-call sì (firmware v1.3+) ignorato
Nota

Il componente legge solo ciò per cui sono dichiarati dei sensori — un registro non dichiarato non viene mai richiesto.

Chiavi YAML per livello

bidirectional: (predefinito false)

Abilita i sensori di energia esportata per canale (energy_exported, energy_exported_1, energy_exported_2).

YAML
rbamp:
  id: solar_meter
  address: 0x51
  bidirectional: true   # meaningful on STANDARD; on BASIC the export sensors read 0

Su STANDARD l'energia esportata proviene dai contatori del modulo. Su BASIC la chiave è accettata dallo schema senza errori, ma energy_exported restituisce sempre 0. I sensori di totale generale energy_exported_total ed energy_net non richiedono questa chiave.

sensor_class: — fissa la famiglia del sensore

YAML
rbamp:
  id: meter1
  sensor_class: SCT_013   # default SCT_013

Accettato su entrambe le linee di moduli. 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. Un valore che il modulo ha già non viene riscritto.

Valori enum: SCT_013 (pinze SCT-013 a nucleo apribile, predefinito), WIRED_CT e BUILTIN_CT (moduli forniti calibrati insieme al proprio sensore montato). Su un modulo di questo tipo accoppiato in fabbrica, un cambio di classe o di modello dal YAML viene rifiutato con una riga di log, per proteggere la calibrazione individuale.

ct_model: / ct_models: — modello di pinza TA

Un unico profilo globale per tutti i canali:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Oppure un profilo per canale (per UI3 con pinze miste):

YAML
rbamp:
  id: meter_ui3
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]

Accettato su entrambe le linee di moduli, mutuamente esclusivo. Sul firmware v1.2+ il modulo carica automaticamente i coefficienti di fabbrica per il modello selezionato — non servono passaggi di calibrazione aggiuntivi. Sul firmware precedente il valore viene memorizzato come marcatore di modello.

  • Il cambio del valore nominale SCT mantiene l'accuratezza di fabbrica: il componente completa il cambio (un riavvio del modulo nel flusso è normale sul firmware fino a 1.4.19; il firmware più recente corregge sul modulo) e scala le letture al sensore selezionato.
  • Controlli di scrittura: un valore uguale non viene scritto; su un modulo accoppiato in fabbrica la modifica viene rifiutata con una riga di log. ct_model_force: true (opzione di servizio, valida solo insieme a ct_model: / ct_models:) lo sovrascrive deliberatamente.
  • ct_models: per canale su un modulo STANDARD richiede che il modulo memorizzi i modelli per canale; altrimenti il componente rifiuta rumorosamente (avviso, chiavi ignorate) — usare ct_model:.

Per approfondire la scelta del modello, vedere 03_sensor_selection.md.

new_address: — assegnazione una tantum dell'indirizzo I²C

YAML
rbamp:
  id: meter1
  address: 0x50
  new_address: 0x51   # one-shot; remove after a successful boot

Accettato su entrambe le linee di moduli. Con firmware v1.3+ il cambio di indirizzo è produzione-OK — il componente usa un protocollo di commit in due fasi (staging → armamento → commit → riavvio) senza modalità speciale. Sul firmware legacy (v1.0-v1.2) il ripiego monofase richiede la modalità di provisioning di fabbrica; per la procedura di attivazione consulta la documentazione del modulo o il fornitore. La modalità di provisioning di fabbrica resta richiesta su tutte le versioni del firmware per le operazioni di calibrazione (saveGains) e ripristino di fabbrica.

Flusso di esecuzione su un unico avvio: il componente interroga l'indirizzo attuale, scrive il nuovo indirizzo e lo salva in flash, riavvia il modulo e verifica la risposta al nuovo indirizzo. Dopo il successo, aggiorna il YAML a address: 0x51 e rimuovi new_address:. Se il componente constata che il vecchio indirizzo è muto mentre il nuovo risponde, si adatta automaticamente con un avviso nel log (nel caso un avvio precedente avesse già applicato la modifica).

fleet_gc_enable: / group_id: — snapshot sincrono per un bus multi-modulo

YAML
rbamp:
  - id: meter1
    fleet_gc_enable: true   # v1.3 production path — recommended
    group_id: 1             # cluster id (modules in the same group snapshot together)

Se abilitato, il componente invia un frame General-call di 5 byte all'indirizzo I²C di broadcast — sincronizzando lo snapshot del periodo su tutti i moduli dello stesso group_id con una sola transazione.

Sul firmware BASIC v1.3 lo snapshot general-call è opt-in e condizionato dalla capacità. Il componente verifica all'avvio se il firmware lo pubblicizza e abilita automaticamente il percorso quando la chiave YAML e il firmware concordano. Sul firmware legacy (v1.0..v1.2) non viene pubblicizzato; il componente ricade su uno snapshot sequenziale per ciascun modulo e registra una riga informativa. Su un modulo STANDARD queste chiavi vengono ignorate con una riga di log.

La chiave legacy broadcast_latch: è ancora accettata dallo schema per compatibilità all'indietro, ma non ha effetto. Usa fleet_gc_enable: + group_id:.

Lo scarto tra moduli su un bus a 50 kHz è dell'ordine di ~540 µs × N, meno dello 0.003% di un periodo di 60 secondi. Sui totali giornalieri di HA questa irregolarità è impercettibile.

topology: — suggerimento di topologia

YAML
rbamp:
  id: meter1
  topology: SINGLE      # SINGLE / SPLIT_PHASE / THREE_PHASE

Facoltativo e non necessario sui moduli STANDARD, dove il numero di canali e la variante provengono dal modulo stesso. Sui moduli BASIC il componente ricava il numero di canali dagli slot sensore dichiarati (se è dichiarato current_1, ci sono almeno 2 canali). La chiave è estetica e finisce nella riga di log di dump_config.

drdy_pin: — interrupt opzionale di data-ready

YAML
rbamp:
  id: meter1
  drdy_pin: GPIO15

Accettato su entrambe le linee di moduli. Si collega all'uscita DRDY open-drain facoltativa del modulo. Il pin viene configurato e registrato, ma i registri istantanei vengono interrogati comunque ogni update_interval. Con un tipico update_interval: 60s la chiave si può omettere.

Richiede una resistenza di pull-up da 10 kΩ sul GPIO master verso 3.3 V (l'uscita è open-drain; non c'è pull-up interno sul lato modulo). Vedi 04_hardware.md.

Tabella riepilogativa — chiave YAML × linea di modulo

Chiave YAML BASIC STANDARD Note
address: sì sì —
update_interval: sì sì Minimo 1s
latch_interval: sì n/a Separa la cadenza di snapshot/energia dalla cadenza di lettura; STANDARD legge i propri contatori a ogni update()
drdy_pin: sì sì Facoltativo, richiede un pull-up da 10 kΩ; non usato come trigger di lettura
topology: sì non necessario Suggerimento informativo
sensor_class: sì sì Non riscritto se uguale; rifiutato sui moduli accoppiati in fabbrica
ct_model: / ct_models: sì sì Mutuamente esclusivi; l'elenco per canale su STANDARD richiede un modulo che lo memorizza
ct_model_force: sì sì Opzione di servizio; lo schema richiede una chiave di modello
bidirectional: accettato (l'esportazione legge 0) funziona Necessario per i sensori per canale energy_exported*
start_current_ua: ignorato con un avviso funziona 0 oppure da 10 a 2540 a passi di 10
new_address: sì sì Produzione-OK sul firmware BASIC v1.3+; una tantum
fleet_gc_enable: / group_id: / broadcast_latch: sì ignorato La sincronizzazione General-call è una funzione della linea BASIC
Sensore energy_exported sempre 0 funziona Richiede bidirectional: true
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] non pubblicare mai funziona Totali generali dai contatori on-device
voltage_angle_b/_c, phase_sequence non pubblicare mai funziona su varianti a tre tensioni con firmware che le fornisce Vedi 09 §2.2–2.3
Sensori a fasi (voltage_a/b/c, current_a/b/c, …) nessun valore pubblica per i canali che il modulo segnala Dettagli in 09 §2.2

Cosa segue


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