rbAmp
IT
Negozio
Docs
Aggiornato il

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)

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

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

Text
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

  1. Regolare i canali tramite N_VOLTAGE/N_CURRENT, le funzioni tramite CAPABILITIES, il layout della mappa tramite VERSION.
  2. Identificare i moduli tramite UID, non tramite indirizzo sul bus.
  3. Riarmare lo stato in RAM (maschera eventi, soglie, orologio) dopo qualsiasi riavvio del modulo rilevato.
  4. Tollerare NACK/clock stretching durante i comandi che toccano la flash; rispettare i tempi di assestamento.
  5. Energia: differenze dei contatori con gestione di generazione/riavvio — mai P·dt lato host.
  6. Aggiornamenti firmware: inviare il file di rilascio preparato così com'è; verificare prima BOARD_ID.