02 · Livelli dei moduli
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_exportedesiste nello schema YAML (per la compatibilità della configurazione), ma su BASIC pubblica sempre0. - 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 anchevoltage_angle_b,voltage_angle_cephase_sequence. - Energia
energyedenergy_exportedper canale (conbidirectional: 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.
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 |
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).
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
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:
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
Oppure un profilo per canale (per UI3 con pinze miste):
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 act_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) — usarect_model:.
Per approfondire la scelta del modello, vedere 03_sensor_selection.md.
new_address: — assegnazione una tantum dell'indirizzo I²C
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
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
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
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
- 03_sensor_selection.md — scelta di una pinza TA e comportamento di
ct_model:/ct_models: - 04_hardware.md — cablaggio fisico, selezione dei GPIO
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/02_tiers.md (v1.9.1)