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

05 · Avvio rapido

Un tutorial di cinque minuti: installi il pacchetto, colleghi il modulo, scelga un sensore e legga il primo valore RT e il primo snapshot per periodo (Wh). Questo tutorial copre in parallelo entrambi i runtime — MicroPython (su ESP32 / RP2040 / STM32 / Pyboard) e CPython (su Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).

Per i dettagli (pinout per uno specifico host, bus multi-modulo, scelta di un SCT-013 per intervallo), vedi i capitoli vicini:

Di cosa avrà bisogno

Sicurezza

⚠ Sicurezza di rete. La tensione di rete può essere letale. Scolleghi e blocchi il circuito prima di collegare i morsetti L/N o di montare la pinza; lasci il cablaggio di rete e ogni intervento dentro un quadro a una persona qualificata. Stringa un solo conduttore (L) — mai l'intero cavo (stringendo L e N si legge circa 0). La pinza stessa è senza contatto.

  • Un modulo rbAmp (qualsiasi linea di moduli, UI1 per semplicità)
  • Uno di questi host:
  • CPython: Raspberry Pi (qualsiasi modello) / Orange Pi 5 / Rock Pi 5 / x86 + dongle USB-I²C

  • MicroPython: ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)

  • Una pinza CT SCT-013 nominata per la sua corrente massima (5A / 10A / 30A / 50A / 100A)

  • Un'alimentazione a 5 V per il modulo (dal USB-5V dell'host o da alimentazione esterna)
  • Un circuito CA da misurare (una lampada, un bollitore o un elettrodomestico)

Quale percorso seguire?

Verificare dev.is_std (oppure l'etichetta SKU sul modulo — vedi 02 · Linee di moduli). Modulo STD: saltare i passi 4-5 e andare a 06 · Esempi, Scenario 11. Modulo BASIC: seguire tutti i passi. I passi 3 e 4 sono uguali per entrambi.

Il percorso verso una prima lettura: collegare il modulo, impostare il modello della pinza, poi leggere tensione, corrente e potenza.

Passaggio 1 — Installazione del pacchetto

CPython (su SBC Linux o x86)

Shell
pip install rbamp

(Su un sistema Debian/Ubuntu può usare l'alternativa di sistema smbus2, sudo apt install python3-smbus, ma si consiglia smbus2 da pip — supporta il gestore di contesto with SMBus(...).)

Verify:

Shell
rbamp --version          # rbamp 1.6.0
rbamp --bus 1 scan       # I²C scan, should show 0x50

MicroPython (su ESP32 e altri)

Shell
mpremote mip install github:rb-amp/rbamp-python

Oppure copi il pacchetto a mano:

Shell
mpremote cp -r path/to/rbamp/ :rbamp/

Il pacchetto viene installato in /lib/rbamp/ sul dispositivo.

Passo 2 — Cablaggio

Quattro fili più DRDY opzionale:

Pin rbAmp Host
VCC +5 V (intervallo 4.5..5.5 V)
GND GND
SDA SDA I²C (RPi pin 3, ESP32 GPIO21, RP2040 GPIO0/ecc.)
SCL SCL I²C (pin 5 del RPi, GPIO22 dell'ESP32, GPIO1/ecc. dell'RP2040)

L'alimentazione deve essere 5 V. Le linee I²C funzionano a logica 3.3 V ma tollerano 5 V. La scheda del modulo ha già resistenze di pull-up integrate da 4.7 kΩ — per un singolo modulo non servono resistenze esterne.

Il pinout completo per ogni host è in 04 · Cablaggio.

La pinza TA SCT-013 si inserisce attorno al solo conduttore di linea (L), con la freccia sul corpo della pinza che punta nella direzione della corrente verso il carico. Maggiori dettagli in 04 · Cablaggio.

Collegare la pinza sul filo L con la freccia verso il carico, e i morsetti di riferimento di rete.

Sicurezza

⚠ Sicurezza di rete. La tensione di rete può essere letale. Scolleghi e blocchi il circuito prima di collegare i morsetti L/N o di montare la pinza; lasci il cablaggio di rete e ogni intervento dentro un quadro a una persona qualificata. Stringa un solo conduttore (L) — mai l'intero cavo (stringendo L e N si legge circa 0). La pinza stessa è senza contatto.

Passaggio 3 — Primo script (lettura RT)

Uno script minimo: indicare al modulo quale pinza si usa (una volta), poi leggere U / I / P / PF. I codici modello sono elencati nel Passo 4; 3 qui sotto è SCT-013-030. La tabella linea/variante del modulo è in 02 · Linee di moduli.

CPython versione

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

with SMBus(1) as bus:
    with RbAmp(bus, 0x50) as dev:
        # the context manager's __enter__ automatically calls dev.begin()
        # the module variant is detected automatically
        variant = dev.read_variant()
        label = dev.read_label() or "(unset)"
        print(f"Module ready: variant={variant}  label={label!r}")
        # variant codes: see the table in 02 · Module lines
        # Once per installation (saved in the module's flash):
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)   # SCT-013-030, see Step 4
        while True:
            try:
                print(f"U={dev.voltage:.1f}V  "
                      f"I={dev.read_current(0):.3f}A  "
                      f"P={dev.read_power(0):.1f}W  "
                      f"PF={dev.read_power_factor(0):.3f}")
            except RbAmpError as e:
                print("read failed:", e)
            time.sleep(1)

Run:

Shell
python quick_read.py

Versione MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)   # ESP32 default
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)   # once per installation
    dev.set_ct_model(3)                              # SCT-013-030, see Step 4
    print("Module ready.")
    while True:
        try:
            print("U={:.1f}V  I={:.3f}A  P={:.1f}W  PF={:.3f}".format(
                dev.voltage, dev.read_current(0),
                dev.read_power(0), dev.read_power_factor(0)))
        except RbAmpError as e:
            print("read failed:", e)
        time.sleep(1)

(Su MicroPython si usa .format() al posto delle f-string — per prestazioni e compatibilità con porte più vecchie; sulle porte più recenti le f-string funzionano comunque.)

Run:

Shell
mpremote run quick_read.py

Output atteso con un carico acceso (i valori dipendono dal carico):

Text
Module ready.
U=230.4V  I=0.523A  P=119.8W  PF=0.987
Sicurezza

U mostra circa la tensione di rete (220-240 V per reti a 230 V). Senza carico I è ~0 e PF non è definito (può stampare nan, 0 oppure un segnaposto) — la forma esatta non conta finché la corrente è zero. Se I resta a 0.000 A con il carico acceso, controllare la pinza (un solo conduttore, direzione corretta) e il codice modello, poi vedere 10 · Risoluzione dei problemi.

Passaggio 4 — Configurazione del sensore di corrente

Bisogna dire al modulo la classe e il modello del sensore (fatto nello script del Passo 3). Senza questo, i coefficienti di taratura non vengono caricati e le letture di corrente restano a zero. Chiamare sempre prima set_sensor_class(), poi set_ct_model(code).

Scegliere il codice corrispondente alla propria pinza:

code Modello Intervallo Uso tipico
1 SCT-013-005 0..5 A Piccoli carichi, una sola presa
2 SCT-013-010 0..10 A Frigorifero, lavatrice
3 SCT-013-030 0..30 A Alimentazione domestica fino a ~7 kW
4 SCT-013-050 0..50 A Caricatore EV, riscaldamento elettrico
6 SCT-013-020 0..20 A Alimentazione intermedia, apparecchi da 3–4 kW

Per saperne di più sulla scelta — 03 · Selezione del sensore di corrente.

Nota

Queste due chiamate si fanno una sola volta alla prima installazione — la scelta viene salvata nella flash del modulo e sopravvive a un reset. Il tempo totale è circa 1.4 secondi (due scritture in flash × ~700 ms ciascuna).

Alle esecuzioni successive dello script non serve richiamare set_sensor_class() e set_ct_model() (il modulo le ricorda). Richiamarle con il valore che il modulo già possiede è un no-op.

Passo 5 — Contabilità dell'energia (Wh)

Il modulo restituisce solo le grandezze istantanee più la potenza media su un periodo. I Wh stessi sono calcolati dal pacchetto usando l'orologio del master (time.monotonic() su CPython, time.ticks_ms() su MicroPython):

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

dove master_dt_s sono i secondi tra due chiamate riuscite a dev.read_period_snapshot().

Nota

Attendere un periodo completo prima del primo read_period_snapshot(). begin() avvia già un periodo, quindi uno snapshot preso subito dopo copre solo una frazione di secondo e i Wh risulteranno ~0. I cicli sotto attendono 60 s per questo motivo.

Il contatore Wh è mantenuto in memoria. Riparte da 0 dopo un riavvio dello script o del dispositivo. Per un totale assoluto, memorizzarlo in autonomia dev.energy.wh(0). Sui moduli BASIC l'esportazione non viene conteggiata (vedi 02 · Linee di moduli). Su un modulo STD le stesse chiamate funzionano e il valore è energia netta (l'esportazione sottrae); begin() sceglie la sorgente — i contatori di energia del modulo, oppure il banco latch 0 — e il primo periodo parte da begin(). I totali di vita del modulo sono in read_std_energy() (Scenario 11 in 06 · Esempi).

Un modello minimo di contabilità periodica (una volta al minuto):

Versione CPython (misuratore di periodo)

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)   # SCT-013-030

    while True:
        time.sleep(60)   # 60-second period

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print(f"avg P over period: {snap.avg_p[0]:.2f} W   "
              f"accumulated: {dev.energy.wh(0):.4f} Wh   "
              f"dt={snap.master_dt_ms} ms")

MicroPython versione (contatore di periodo)

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)

    while True:
        time.sleep_ms(60_000)

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print("avg P over period: {:.2f} W   accumulated: {:.4f} Wh   dt={} ms".format(
            snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Nota

Dopo il Passaggio 4, le chiamate set_sensor_class() e set_ct_model() sono già state eseguite una volta e salvate nella flash del modulo; nello schema sopra restano per le riesecuzioni dello script — il modulo ignora una chiamata ripetuta con lo stesso valore.

Cosa fa read_period_snapshot() sotto il cofano:

  1. Invia al modulo il comando di snapshot di periodo (CMD_LATCH_PERIOD).
  2. Attende 50 ms mentre il modulo prepara lo snapshot.
  3. Controlla il flag di pronto (snap.valid); legge la potenza media e di picco.

  4. Aggiorna il contatore interno dei Wh: dev.energy.wh(ch) += avg_p[ch] × dt / 3600.

  5. Su uno snapshot non aggiornato solleva RbAmpStaleError e mantiene il timestamp precedente, così lo snapshot valido successivo copre l'intero intervallo e i Wh restano esatti.

dev.begin() avvia da sé il primo periodo (un primer) e scarta quanto il modulo ha accumulato dall'accensione, così il codice utente non vede mai quei dati.

Output atteso:

Text
avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Variante con streaming asincrono (facoltativa)

Per le applicazioni che usano asyncio (CPython) o uasyncio (MicroPython) è disponibile un generatore asincrono dev.stream_period(interval_s=...):

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)

        # Once a minute, with built-in stale handling (skip_stale=True)
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"{snap.avg_p[0]:.2f} W,  {dev.energy.wh(0):.4f} Wh")

asyncio.run(main())

Funziona allo stesso modo su MicroPython (import uasyncio as asyncio).

Altri dettagli sugli scenari asincroni — 06 · Esempi, lo scenario «Streaming periodico asincrono».

Passo 6 — Guida rapida per una flotta di N moduli

Questo avvio rapido mostra come lavorare con un singolo modulo. Lo scenario canonico per il pacchetto è invece quello con più moduli sullo stesso bus tramite RbAmpFleet (rete + N carichi secondari). Per l'esempio completo, vedi il capitolo 06 · Esempi, scenario 1 «Rete + N carichi secondari — il canone 80%». Uno scheletro minimo di flotta (CPython):

Python
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    added = fleet.scan()
    print(f"fleet: {added} modules; excluded: {fleet.excluded}")

    while True:
        snaps = fleet.poll_all()
        total_w = fleet.total_power()
        n_ok = sum(1 for snap, info in snaps if info.ok)
        print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
        time.sleep(0.2)

La versione MicroPython è identica — sostituisca SMBus(1) con I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).

Nello scenario canonico all'80% uno dei moduli è un UI1 sull'alimentazione di rete (fornisce total_power() e total_energy_wh()), e gli altri, I2/I3, sono contatori di corrente secondari. I dettagli e gli scenari avanzati (disaggregazione rete + sotto-carichi, sincronizzazione GC per istantanee strettamente sincrone, flusso di provisioning) sono nel capitolo 06.

Cosa c'è dopo

  • 01 · Panoramica — cos'è rbAmp e cosa fa il pacchetto
  • 02 · Linee di moduli — quale linea di moduli per quale attività
  • 06 · Esempi — scenari funzionanti: rete + N sotto-carichi (il canone dell'80%), flusso di provisioning, TA multi-canale misti, sincronizzazione GC del fleet, MQTT, deep-sleep, streaming asincrono

  • 07 · Integrazioni fai-da-te — Home Assistant / Node-RED / OpenHAB

  • 08 · Integrazioni cloud — AWS IoT / Azure / GCP / InfluxDB

  • 09 · Riferimento API — l'API pubblica completa (incluso RbAmpFleet + Multi-canale + modello degli errori v1.3 + Identità e provisioning)

  • 10 · Risoluzione dei problemi — se qualcosa non funziona (blocco i2c su MicroPython@ESP32 a tre livelli, latch_ms è un timer diagnostico, RbAmpStaleError con ancora di hold del master)


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