Integrazione host
Come far funzionare un modulo STD dal proprio codice — con le nostre librerie o con il solo master I²C/Modbus.
Con le librerie rbAmp
Una libreria client per piattaforma copre tutta la linea; numero di canali e funzioni vengono rilevati a runtime:
- Arduino (rbamp-arduino) — supporto STD: rilevamento, tempo reale, configurazione, eventi/DRDY, OTA, storico, energia a risoluzione micro, corrente di avviamento, angolo di fase e sequenza. Su un modulo con banchi di snapshot e contatori di energia usare la v1.6.2 o successiva (le versioni precedenti prendono il periodo dal banco 0 invece che dai contatori; sorgente dell'energia e versione minima).
- ESP-IDF (rbamp-esp-idf) — componente con supporto STD, incluso energia a risoluzione micro e corrente di avviamento. Su un modulo con banchi di snapshot e contatori di energia usare la v1.7.3 o successiva (le versioni precedenti prendono il periodo dal banco 0 invece che dai contatori; versione minima).
- ESPHome / Home Assistant (rbamp-esphome) — componente esterno: contatori di energia on-device, corrente di avviamento e diagnostica di fase. Usare la v1.9.0 o successiva; i banchi di istantanee (
period_banks:) dalla v1.9.1. - Python (rbamp-python) — supporto STD: una sola classe client, la linea del modulo viene rilevata alla connessione. Usare la v1.6.0 o successiva; le chiamate ai banchi di istantanee dalla v1.6.1. Verificato su Python Linux standard (smbus2).
Le librerie coprono questi flussi (controllo di discovery, interrogazione busy/err, OTA con immagine preparata, contabilità dei delta di energia), quindi preferirle dove la piattaforma lo consente.
Le funzioni di energia a risoluzione micro e di corrente di avviamento in sintesi — ogni chiamata degrada con garbo sui moduli che non pubblicano la funzione (nessun traffico sul bus, o valori derivati dai contatori grossolani):
| Caratteristica | Arduino | ESP-IDF | ESPHome (YAML) | Python |
|---|---|---|---|---|
Energia a risoluzione micro (i campi µWh / µvarh sono sempre utilizzabili; un flag fine indica se sono i contatori propri del modulo) |
stdReadEnergy() → campi *_uwh / *_uvarh di RbAmpStdEnergy, stdEnergyDelta() |
campi rbamp_std_energy_t *_uwh / *_uvarh, rbamp_std_energy_delta() |
energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported |
read_std_energy() → campi RbAmpStdEnergy *_uwh / *_uvarh, RbAmp.std_energy_delta() |
| Corrente di avviamento per l'energia | stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() |
rbamp_std_set_start_current() / rbamp_std_get_start_current() |
start_current_ua: |
set_start_current() / get_start_current() |
| Angolo di fase della tensione | stdReadVoltage(v) → angle_deg / angle_valid |
rbamp_std_voltage_t.angle_deg / angle_valid |
voltage_angle_b / voltage_angle_c |
read_std_voltage(phase) → angle_deg / angle_valid |
| Sequenza di fase | stdReadPhaseSequence() |
rbamp_std_read_phase_seq() |
phase_sequence |
read_phase_sequence() |
Se l'applicazione conserva uno snapshot dell'energia della libreria (NVS, EEPROM, file), memorizzare i singoli campi necessari nel proprio formato fisso, non la struct come blob grezzo — le strutture dello snapshot acquisiscono campi tra una versione della libreria e l'altra.
Senza le nostre librerie
Tutto ciò che fanno le librerie è semplice I/O sui registri. Il protocollo è documentato e stabile; le modifiche alla mappa sono versionate (VERSION) e condizionate dalle funzioni (CAPABILITIES). I flussi canonici passo passo (inizializzazione, comando, configurazione, modifica dell'indirizzo, energia, storia, OTA, sblocco) sono in Sequenze — di seguito i modelli di lavoro più brevi.
Avvio minimo I²C (pseudocodice)
# discovery (once)
id = read(0x0000, 2) # expect 'S','T'
ver = read(0x0003, 1) # map version, expect >= 0x36
caps = read_u16(0x0004)
nv = read(0x0007, 1); ni = read(0x0008, 1)
uid = read(0x00F4, 12) # device identity for your database
fwv = read_u32(0x0114) # firmware version: high word . low word (1.126)
# clock (after every module reset: STATUS bit4 == 0)
write_u32(0x08C0, unix_epoch) # TIME_SET
write(0x0060, 0x06) # SET_TIME; then poll CMD_STATE 0x006A bit0 -> 0, check ERROR == 0
# realtime poll (every 0.2..1 s, or on the DRDY edge)
u_mv = read_i32(0x0200 + v*0x20) # per voltage channel
i_ua = read_i32(0x1000 + c*0x40) # per current channel
p_mw = read_i32(0x1000 + c*0x40 + 0x04) # signed
pf = read_i16(0x1000 + c*0x40 + 0x10) # /1024
freq = read_u16(0x0010) # /100 Hz
tot_p = read_i32(0x0300 + 0x04) # grand active power
Schema di contabilità dell'energia
# at each interval boundary (your clock):
blk = read(0x0800, 0x44) # ONE transaction <= 128 B: Wh + mWh counters + LT_GEN — coherent
e_imp = i64(blk, 0x28); e_exp = i64(blk, 0x30) # grand import/export, mWh
gen = u32(blk, 0x40) # LT_GEN (0x0840)
up = read_u32(0x08A0) # UPTIME
interval_import = e_imp - last_imp # delta of cumulative counters
if gen != last_gen: re-anchor, no delta # counter was reset/adopted (event-logged)
if up < last_up: delta = max(0, delta) # restart: ~last second of energy may be missing; re-feed time
Leggere il blocco energia in una transazione di ≤ 128 byte — i campi i64 letti in transazioni separate possono spezzarsi tra una pubblicazione e l'altra (trasporto I²C).
Non integrare mai la potenza nel tempo sull'host — i contatori del modulo sono compensati per le lacune e persistenti; il vostro integrale non è né l'uno né l'altro. Dettagli: Misura ed energia.
Lettura dei record orari
write(0x0C00, 1) # HIST_PERIOD = hourly
write_u16(0x0C04, n) # n records back from newest
write(0x0060, 0x08) # HIST_READ
poll CMD_STATE (0x006A) bit0 -> 0
err = read(0x0002, 1) # 0xFC = no such record
flags = read(0x0C02, 1) # bit0 = record valid
rec = read(0x0C20, 80) # one transaction; see record layout
I record riportano l'Wh assoluto a vita alla fine del periodo più l'energia del periodo per fase (struttura).
Interrogazione di salute
Vedere la checklist diagnostica — sei letture coprono disponibilità, salute dell'archivio, riavvii e generazioni dei contatori.
Integrazione Modbus senza librerie
-
Profilo float32: i punti che il modulo pubblica — V/I/P per fase, P totale, frequenza, energia di importazione/esportazione in kWh — agli indirizzi di input float32 (elenco). Gli altri indirizzi del profilo leggono 0.
-
Profilo nativo: le FC04 leggono a 0x6000 (discovery), 0x6100/0x6200 (canali), 0x6B00+ (energia), 0x6C00 (totali); configurazione e comandi tramite FC16 a 0x8000+ con UNLOCK per i comandi che modificano lo stato. Mappa completa: mappa dei registri; regole: Trasporto Modbus.
-
I master solo FC03 leggono i dati nativi tramite lo specchio 0xA000+ (input + 0x4000).
Regole di integrazione da ribadire
- Regolare i canali tramite
N_VOLTAGE/N_CURRENT, le funzioni tramiteCAPABILITIES, il layout della mappa tramiteVERSION. - Identificare i moduli tramite UID, non tramite indirizzo sul bus.
- Riarmare lo stato in RAM (maschera eventi, soglie, orologio) dopo qualsiasi riavvio del modulo rilevato.
- Tollerare NACK/clock stretching durante i comandi che toccano la flash; rispettare i tempi di assestamento.
- Energia: differenze dei contatori con gestione di generazione/riavvio — mai P·dt lato host.
- Aggiornamenti firmware: inviare il file di rilascio preparato così com'è; verificare prima
BOARD_ID.