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

02 · Linee di moduli

Le linee di moduli BASIC e STANDARD (STD) e ciò che offre ciascuna.

Cos'è una linea di moduli

I moduli rbAmp sono disponibili in due linee: BASIC e STANDARD (STD). Una linea di moduli è un pacchetto completo di revisione hardware e firmware, non un flag software. Passare da una linea all'altra richiede un cambio fisico di SKU, non un aggiornamento firmware.

Dal punto di vista del pacchetto e del codice utente: una sola classe RbAmp serve ogni linea di moduli, e i lettori comuni (voltage, current, power, power_factor, frequency) funzionano su tutti. La linea del modulo viene rilevata automaticamente a begin(). I moduli STANDARD (STD) espongono inoltre le chiamate solo-STD (energia sul dispositivo e così via, vedi sotto); chiamarne una su un modulo BASIC solleva RbAmpNotSupportedError.

Stato attuale

I moduli BASIC e STANDARD sono supportati da questa libreria (STANDARD dalla 1.6.0).

Linea di moduli Spedizione
BASIC ✅ sì
STANDARD (STD) ✅ sì (supportato da questa libreria dalla 1.6.0)

BASIC — Linea di moduli di misura del consumo, livello base

Hardware

Un percorso analogico economico adatto ai carichi domestici tipici. Il modulo include un front-end analogico isolato, un regolatore di alimentazione di bordo e la calibrazione di fabbrica memorizzata in flash.

Comportamento del firmware

La logica di un classico contatore a disco meccanico — il conteggio va solo in avanti; l'export verso la rete non viene sottratto.

I tre "livelli" dei valori di potenza attiva si comportano in modo diverso:

Segnale Significato Comportamento su BASIC
dev.power[ch] / dev.read_power(ch) potenza attiva RT istantanea, aggiornamento ogni ~100 ms con segno — un valore negativo è visibile in tempo reale (esportazione)
snap.avg_p[ch] (da dev.read_period_snapshot()) potenza media sul periodo ciascuna finestra media-P di 100 ms viene limitata a max(P, 0) prima di essere aggiunta all'accumulatore di periodo
dev.energy.wh(ch) Wh accumulati dal pacchetto monotono — solo consumo; l'esportazione non viene conteggiata

In altre parole: l'utente vede l'export nella lettura RT, ma non è presente nel contatore dei Wh del pacchetto su BASIC.

Applicazioni tipiche

  • Famiglie senza produzione propria (senza pannelli solari, turbine eoliche, sistemi a batteria)

  • Sottocontabilizzazione di carichi puramente consumatori (scaldabagni, motori, elettrodomestici)

  • Monitoraggio dei consumi di un edificio dove la misura bidirezionale non è richiesta

Misura bidirezionale su BASIC (lato master)

BASIC conta solo il consumo sul modulo, con l'export gestito sul master, mentre STD mantiene i contatori cumulativi sul dispositivo.

Se deve tracciare separatamente l'export verso la rete su un modulo BASIC, lo faccia lato master. La potenza RT dev.power[0] ha il segno (oppure il metodo equivalente dev.read_power(0)), quindi:

Python
import time
from rbamp import RbAmp, RbAmpIOError

def bidirectional_loop(dev):
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.monotonic()

    while True:
        # Sample RT power at 10 Hz — matches the firmware-commit
        # cadence (100 ms per channel). Faster yields empty repeated
        # reads; slower loses resolution on sharp load transitions.
        time.sleep(0.1)

        t_now = time.monotonic()
        dt_s  = t_now - t_prev
        t_prev = t_now

        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        dwh = p * dt_s / 3600.0
        if p >= 0.0:
            consume_wh += dwh
        else:
            export_wh  += -dwh

Su MicroPython sostituisca time.monotonic() con time.ticks_ms() / time.ticks_diff() (più precisi e poco onerosi in RAM sulle piattaforme embedded) e time.sleep(0.1) con time.sleep_ms(100). Su CPython non serve alcuna modifica.

Un esempio completo funzionante dello schema è in 06_examples.md, nello scenario «Misura bidirezionale lato master», nonché nei file sorgente examples_upy/07_bidirectional_energy.py e examples_cpython/05_bidirectional_energy.py.

STANDARD (STD) — linea di moduli in produzione

I moduli STANDARD sono una linea di moduli in commercio che questa libreria supporta dalla versione 1.6.0. Usano una mappa dei registri diversa (a 16 bit) rispetto a BASIC; la libreria nasconde la differenza — stessa classe RbAmp, stesso cablaggio I²C e stesso indirizzo, e gli stessi lettori comuni.

Cosa aggiunge la libreria su un modulo STD:

  • Energia sul dispositivo: dev.read_std_energy() restituisce i contatori a vita del modulo stesso — energia attiva di import / export / netta e reattiva, in risoluzione Wh, mWh e µWh, con valori per canale. RbAmp.std_energy_delta(prev, now) dà l'energia usata tra due letture ed è sicura in caso di interruzione di alimentazione. Per questi contatori non integra la potenza sul master.

  • Misura per periodo: read_period_snapshot() e le altre chiamate di periodo funzionano come su BASIC. begin() sceglie la sorgente — i contatori di energia del modulo (il periodo è la differenza di due letture; non viene inviato alcun comando di latch) oppure, su un modulo con soli banchi di latch, il banco di latch 0. L'energia è netta (l'export sottrae).

  • Banchi latch (moduli che li riportano): dev.std_arm_banks(mask), dev.std_latch(bank), dev.std_read_latch(bank), RbAmp.std_latch_wh(snap, dt_ms).

  • Funzioni multifase: dev.read_voltage_angle(phase), dev.read_phase_sequence(), dev.read_reactive(ch) (solo STD; su BASIC la potenza reattiva non è esposta da questa libreria), dev.read_apparent(ch).

  • Corrente di avviamento: dev.get_start_current() / dev.set_start_current(µA) + dev.save_config().

  • Blocchi completi: dev.read_std_voltage(), read_std_channel(), read_std_totals(), read_std_config(), read_std_health(), dev.set_time().

Notes:

  • Alcune chiamate STD richiedono un'immagine del modulo abbastanza recente (contatori di energia in micro-unità, angoli di tensione, corrente di avviamento). Se il modulo non ne fornisce una, la chiamata solleva RbAmpNotSupportedError («non disponibile»).

  • Usare dev.is_std per ramificare nel codice applicativo.

  • La configurazione della classe del sensore e del modello TA, reset e cambio di indirizzo, i registri di identità, il canale di errori/eventi, le funzioni di supporto del fleet e wait_ready() sono riservati ai BASIC; su un modulo STD sollevano RbAmpNotSupportedError.

  • Le funzioni di energia sul dispositivo, angolo e corrente di avviamento sono validate su CPython (smbus2). Il percorso MicroPython a 16 bit è implementato ma non ancora validato su hardware — preferire CPython per queste funzioni finché una nota di rilascio non dica diversamente.

Firme complete: 09 · Riferimento API.

Come rilevare la linea del modulo a runtime

Come capire a runtime se il modulo collegato è BASIC o STANDARD (STD).

Nel firmware attuale non c'è un registro esplicito della «linea del modulo». Indicatori indiretti sono disponibili tramite le proprietà dell'handle:

Python
# Firmware version — opaque byte
fw = dev.firmware_version

# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw

# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels

# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()

# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
Nota

: dev.is_std indica la linea del modulo (STD o BASIC). Gli altri indicatori (versione del firmware, numero di canali, presenza di un sensore di tensione, variante) descrivono il modulo ma non identificano la linea. dev.read_variant() è il byte di variante BASIC; usi l'etichetta SKU sull'involucro del modulo come fonte di riferimento per il prodotto.

Come sono contrassegnati nella documentazione i punti che dipendono dalla linea del modulo

Nel testo del pacchetto e nella documentazione canonica le funzioni che dipendono dalla linea del modulo sono contrassegnate esplicitamente, per esempio:

Solo STD

— questa chiamata non è disponibile su un modulo BASIC.

Oppure, al contrario, comportamento specifico del BASIC:

BASIC

: il contatore dev.energy.wh(ch) è monotono — l'export verso la rete non viene conteggiato. Per la misura bidirezionale, vedere lo scenario "Misura bidirezionale lato master" in 06_examples.md, oppure usi un modulo STANDARD, dove l'energia per periodo è netta e dev.read_std_energy() ha contatori separati di import ed export.

Cosa segue


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repo: docs/02_tiers.md (v1.6.1)