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

Esempi

Questo capitolo illustra 11 scenari (10 nella tabella sotto più lo Scenario 11) — da un minimo «hello world» fino a un deploy di produzione. La maggior parte degli scenari ha implementazioni parallele in MicroPython (in examples_upy/) e CPython (in examples_cpython/). Il codice sotto è una distillazione della logica chiave, non uno script completo; le versioni complete sono nei file di esempio corrispondenti.

# Scenario MicroPython CPython
1 Lettura rapida 01_quick_read.py 01_quick_read.py
2 Contatore di periodo + display locale 02_oled_period.py 02_period_meter.py
3 Monitoraggio di 3 moduli su un bus 03_multi_module.py 03_multi_module_broadcast.py
4 UI3 + MQTT per canale 04_mqtt.py 04_mqtt_publisher.py
5 Misura bidirezionale lato master 07_bidirectional_energy.py 05_bidirectional_energy.py
6 Bilancio energetico dell'intera casa (multi-modulo + MQTT) 08_home_energy_balance.py 07_home_energy_balance.py
7 Registrazione del rilevamento di eventi (EMA) 09_event_detection_logger.py nessun file
8 Logger locale a rotazione nessun file 08_rotating_file_logger.py
9 Logger a batteria con deep sleep 06_deep_sleep.py (non applicabile)
10 Streaming asincrono tramite stream_period 05_async_streaming.py nessun file (codice nello Scenario 10)
Nota

Tutti gli scenari presuppongono che la classe del sensore e il modello TA siano già configurati con dev.set_sensor_class() + dev.set_ct_model() (vedi 05 · Avvio rapido, Passo 4). Si fa una volta sola in fase di installazione — le impostazioni sono salvate in flash del modulo e sopravvivono a un reset.


Scenario 1 — Lettura rapida

Obiettivo: stampare U / I / P / PF / frequenza una volta al secondo. È lo stesso «hello world» scritto nell'05 · Avvio rapido, ma usando dev.read_all() — una lettura singola dell'intero blocco RT in una struttura RbAmpSnapshot.

CPython versione

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        line = f"U={s.voltage:.1f} V  f={s.frequency} Hz   "
        for ch in range(s.channels):
            line += f"I{ch}={s.current[ch]:.2f}A  P{ch}={s.power[ch]:.1f}W  "
        print(line)
        time.sleep(1)

Versione MicroPython

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        print("U={:.1f} V  f={} Hz".format(s.voltage, s.frequency))
        for ch in range(s.channels):
            print("  I{}={:.2f}A  P{}={:.1f}W".format(
                ch, s.current[ch], ch, s.power[ch]))
        time.sleep(1)

Che cosa succede sul bus: dev.read_all() su una UI3 esegue circa 53 transazioni di byte (13 valori float × 4 byte + 1 byte di frequenza). A 50 kHz con margine per i tentativi, si tratta dell'ordine di 25-30 ms. Se non le servono tutti i valori, usi gli accessori per singola proprietà (dev.voltage, dev.read_current(ch)).


Scenario 2 — Contatore di periodo + display locale

Obiettivo: un contatore Wh, aggiornato una volta al minuto, su un display locale. Su MicroPython — un OLED SSD1306 sullo stesso bus I²C. Su CPython — output di testo su stdout (si può collegare un LCD a caratteri via GPIO oppure usare una pagina web — vedi Scenario 6).

MicroPython versione (OLED SSD1306)

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
oled = SSD1306_I2C(128, 64, i2c)   # OLED on the same bus, addr 0x3C

with RbAmp(i2c, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            continue

        oled.fill(0)
        oled.text("rbAmp Energy Meter", 0, 0)
        oled.text("{:.1f} W".format(snap.avg_p[0]), 0, 16, 1)
        oled.text("Wh: {:.4f}".format(dev.energy.wh(0)), 0, 32)
        oled.text("ok={} bad={}".format(snapshots_ok, snapshots_bad), 0, 48)
        oled.show()

CPython versione (contatore di periodo, senza display)

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            print("stale snapshot — skipping")
            continue

        print(f"P = {snap.avg_p[0]:.2f} W   "
              f"Wh = {dev.energy.wh(0):.4f}   "
              f"ok={snapshots_ok} bad={snapshots_bad}   "
              f"dt={snap.master_dt_ms} ms")

Gestione delle istantanee non aggiornate. dev.read_period_snapshot() solleva RbAmpStaleError se il modulo non è riuscito a preparare una nuova istantanea al momento della lettura. Il pacchetto mantiene il timestamp precedente, quindi l'istantanea successiva valida copre l'intero intervallo e i Wh restano esatti. Uno schema standard try/except di Python.


Scenario 3 — Monitoraggio di 3 moduli su un bus

Obiettivo: interrogare 3 moduli agli indirizzi 0x50 / 0x51 / 0x52, con istantanea coerente in modo che le loro potenze per canale si sommino sullo stesso periodo di rete.

Istantanea coerente

un frame General-Call (A5 27 ) fa sì che ogni modulo che ha aderito con fleet.enable_gc_all() prenda il proprio snapshot — lo sfasamento della flotta è < 10 µs, quindi i totali si sommano. fleet.gc_latch() invia il frame e restituisce il tick di broadcast; fleet.check_sync() rilegge il tick registrato da ciascun modulo, così si può segnalare quello che ha perso il frame. (Sul firmware v1.0/v1.1 la General-Call non era disponibile e questo scenario ricadeva su snapshot sequenziali per dispositivo.) Vedi 09 · Riferimento API per RbAmpFleet.

CPython versione

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

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    for addr in ADDRS:
        try:
            dev = RbAmp(bus, addr); dev.begin()
        except RbAmpError as exc:
            print(f"skip 0x{addr:02X}: {exc}"); continue
        fleet.add(dev)

    # one-time: persist the General-Call snapshot opt-in on every module
    fleet.enable_gc_all(group=GC_GROUP)

    while True:
        time.sleep(60)

        tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame snapshots the bus
        time.sleep(0.050)                         # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        for dev, s in zip(fleet, sync):
            if not s.in_sync:                     # this module missed the frame
                print(f"  0x{s.addr:02X}  MISSED tick 0x{tick:04X}")
                continue
            try:
                snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
            except RbAmpStaleError:
                continue
            print(f"  0x{dev.address:02X}  P={snap.avg_p[0]:.0f} W  "
                  f"Wh={dev.energy.wh(0):.3f}")
        print(f"  fleet ΣWh={fleet.total_energy_wh():.3f}  "
              f"in_sync={sum(s.in_sync for s in sync)}/{len(sync)}")

Versione MicroPython

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

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)

fleet = RbAmpFleet(i2c)
for addr in ADDRS:
    try:
        dev = RbAmp(i2c, addr); dev.begin()
    except RbAmpError as exc:
        print("skip 0x{:02X}:".format(addr), exc); continue
    fleet.add(dev)

fleet.enable_gc_all(group=GC_GROUP)           # one-time, persisted

while True:
    time.sleep(60)

    tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame
    time.sleep_ms(50)                         # single shared settle
    sync = fleet.check_sync(expected_tick=tick)

    for dev, s in zip(fleet, sync):
        if not s.in_sync:
            print("  0x{:02X}  MISSED tick".format(s.addr))
            continue
        try:
            snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue
        print("  0x{:02X}  P={:.0f} W  Wh={:.3f}".format(
            dev.address, snap.avg_p[0], dev.energy.wh(0)))

Scenario 4 — UI3 + MQTT per canale

Obiettivo: un modulo UI3 con 3 pinze TA su tre linee indipendenti. Contatori Wh per canale, pubblicati su MQTT una volta al minuto. Mostra che dev.energy.wh(ch) funziona su ogni canale in modo indipendente — senza bisogno di un array manuale total_wh[3] sul master.

CPython (tramite paho-mqtt; installazione con pip install paho-mqtt)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = ["main", "heatpump", "lights"]

mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "rbamp-ui3")
mqtt.connect("192.168.1.10", 1883, keepalive=60)
mqtt.loop_start()

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = json.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            mqtt.publish(f"rbamp/{CH_NAMES[ch]}/state",
                         payload, qos=1, retain=True)

MicroPython (tramite umqtt.simple)

Python
import time, ujson
from machine import I2C, Pin
from umqtt.simple import MQTTClient
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = [b"main", b"heatpump", b"lights"]

mqtt = MQTTClient(b"rbamp-ui3", b"192.168.1.10",
                  port=1883, keepalive=60)
mqtt.connect()

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = ujson.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            topic = b"rbamp/" + CH_NAMES[ch] + b"/state"
            mqtt.publish(topic, payload.encode(), qos=1, retain=True)
Nota

Su MicroPython, umqtt.simple è un client sincrono e bloccante. Per una variante asincrona usi mqtt_as (un client MQTT asyncio) — vedere anche lo Scenario 10.

Per l'auto-discovery completo di HA sopra questo schema, vedi 07 · Integrazioni fai-da-te.


Scenario 5 — Misura bidirezionale lato master

Obiettivo: separare la potenza istantanea con segno in consumo lordo e esportazione lorda. Usare questo schema sulla linea di moduli BASIC, dove il firmware azzera i valori negativi in snap.avg_p[ch] (potenza media per periodo) — campionare dev.read_power(0) (potenza istantanea, con segno su tutte le linee di moduli) a 10 Hz lato master e raggruppare i valori da sé.

CPython versione

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.monotonic()
    last_print = t_prev

    while True:
        time.sleep(0.1)   # 10 Hz, matches the RT cadence

        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:
            consume_wh += dwh
        else:
            export_wh  += -dwh

        # Print once per second
        if t_now - last_print >= 1.0:
            last_print = t_now
            print(f"P={p:.1f} W   "
                  f"cons={consume_wh:.4f} Wh  exp={export_wh:.4f} Wh  "
                  f"net={consume_wh - export_wh:.4f} Wh")

Versione MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpIOError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.ticks_ms()

    while True:
        time.sleep_ms(100)

        t_now = time.ticks_ms()
        dt_s  = time.ticks_diff(t_now, t_prev) / 1000
        t_prev = t_now

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

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

Su un modulo STANDARD (STD) le chiamate di periodo funzionano senza modifiche e l'energia è netta (l'export sottrae); i contatori di import ed export del modulo stesso sono in read_std_energy() (Scenario 11). Questa suddivisione lato master serve solo sui moduli BASIC, per la rendicontazione separata di consumo lordo ed export lordo.


Scenario 6 — Bilancio energetico dell'intera casa

Obiettivo: 3 moduli — rete (bidirezionale), solare (solo generazione), carichi (UI3 per singolo apparecchio). Un cruscotto combinato viene pubblicato una volta al minuto.

(Richiede pip install paho-mqtt.)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import (RbAmp, RbAmpFleet, RbAmpError,
                   RbAmpStaleError, RbAmpSensorClass)

GC_GROUP = 0

with SMBus(1) as bus:
    mains = RbAmp(bus, 0x50)   # bidirectional mains
    solar = RbAmp(bus, 0x51)   # generation only
    loads = RbAmp(bus, 0x52)   # UI3 — per-appliance
    devs = [mains, solar, loads]
    for d in devs:
        d.begin()

    fleet = RbAmpFleet(bus)
    for d in devs:
        fleet.add(d)
    fleet.enable_gc_all(group=GC_GROUP)   # one-time, persisted

    mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "home-balance")
    mqtt.connect("192.168.1.10", 1883, keepalive=60)
    mqtt.loop_start()

    while True:
        time.sleep(60)

        # One coherent all-call snapshot for the whole bus (see Scenario 3)
        tick = fleet.gc_latch(group=GC_GROUP)
        time.sleep(0.050)                     # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        try:
            sm = mains.read_period_snapshot(settle_ms=0, skip_latch=True)
            ss = solar.read_period_snapshot(settle_ms=0, skip_latch=True)
            sl = loads.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue

        payload = {
            "mains":  round(mains.energy.wh(0), 3),
            "solar":  round(solar.energy.wh(0), 3),
            "hp":     round(loads.energy.wh(0), 3),
            "ac":     round(loads.energy.wh(1), 3),
            "ev":     round(loads.energy.wh(2), 3),
        }
        mqtt.publish("home/energy/balance",
                     json.dumps(payload), qos=1, retain=True)

        # let a dashboard alarm on a partial fleet (a module that missed the frame)
        in_sync = sum(s.in_sync for s in sync)
        mqtt.publish("home/energy/sync/in_sync",
                     f"{in_sync}/{len(sync)}", qos=1, retain=True)

Sui moduli BASIC l'esportazione non viene conteggiata da energy.wh(), quindi i valori solar e mains sopra sono solo consumo. Per una separazione esplicita consumo lordo / esportazione lorda sulla rete, combinare con lo schema dello Scenario 5 (un ciclo separato a 10 Hz su mains.read_power(0) in un threading.Thread in background su CPython, oppure uasyncio.create_task su MicroPython).


Scenario 7 — Registrazione degli eventi di rilevamento (EMA)

Obiettivo: a ogni finestra RT di 100 ms, confrontare la potenza istantanea con una media mobile esponenziale. Registrare le deviazioni significative — carichi come un forno a microonde, un bollitore o un asciugacapelli "compaiono" nel log come eventi di accensione / spegnimento.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

EMA_ALPHA = 0.05
EVENT_THRESHOLD_W = 200.0

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    try:
        p_ema = dev.read_power(0)   # seed so the first read isn't an event
    except RbAmpIOError:
        p_ema = 0.0

    while True:
        time.sleep(0.1)
        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        delta = p - p_ema
        p_ema = (1 - EMA_ALPHA) * p_ema + EMA_ALPHA * p

        if abs(delta) > EVENT_THRESHOLD_W:
            action = "TURN_ON" if delta > 0 else "TURN_OFF"
            print(f"{time.time():.0f}  {action}  delta={delta:.0f} W  "
                  f"P={p:.0f} W  EMA={p_ema:.0f}")

Su MicroPython applicare le stesse sostituzioni: time.sleep → time.sleep_ms, e time.time() → time.time() (disponibile sulla maggior parte delle porte) oppure time.ticks_ms().

Lo combini con la pubblicazione MQTT dello Scenario 4 per le automazioni lato HA.


Scenario 8 — Logger locale a rotazione (CPython)

Obiettivo: scrivere uno snapshot di periodo su un file CSV a rotazione una volta al minuto tramite il modulo standard logging.handlers.RotatingFileHandler. Utile per installazioni autonome senza WiFi / MQTT, oppure come buffer per la sincronizzazione differita con il cloud.

Python
import time, logging
from logging.handlers import RotatingFileHandler
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpStaleError

log = logging.getLogger("rbamp.csv")
log.setLevel(logging.INFO)
handler = RotatingFileHandler("rbamp.csv", maxBytes=1_000_000, backupCount=5)
handler.setFormatter(logging.Formatter("%(asctime)s,%(message)s",
                                       datefmt="%Y-%m-%dT%H:%M:%S"))
log.addHandler(handler)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            log.warning("stale")
            continue
        log.info(f"{snap.avg_p[0]:.1f},{dev.energy.wh(0):.4f},"
                 f"{snap.master_dt_ms}")

Su MicroPython il modulo standard logging.handlers non è disponibile — per un log locale usare un semplice with open("log.csv", "a") più una rotazione manuale tramite os.stat() + os.rename(). Vedi l'esempio completo in examples_upy/09_event_detection_logger.py.

Per la sincronizzazione differita con il cloud (registrare localmente, inviare una volta l'ora), vedi la sezione «Ibrido: archiviazione locale + sincronizzazione» in 08 · Integrazioni cloud.


Scenario 9 — Logger a batteria in deep sleep (solo MicroPython)

Obiettivo: un ESP32 (MicroPython) si risveglia ogni 10 minuti, prende un singolo snapshot di periodo, pubblica via Wi-Fi+MQTT e torna in deep sleep. L'energia viene conservata tra i cicli di sleep tramite la memoria RTC.

Sicurezza

⚠ Nota importante su deep-sleep e firmware v1.0/v1.1. Sul firmware attuale, dev.begin() emette un primer CMD_LATCH_PERIOD che azzera l'accumulatore di periodo del firmware. Quindi, dopo un risveglio da deep-sleep, non può semplicemente chiamare read_period_snapshot() per default: quella chiamata prenderebbe un'altra istantanea e restituirebbe dati quasi nulli, relativi ai soli circa 50 ms dal primer. Lo schema corretto qui sotto usa skip_latch=True per leggere i dati accumulati durante l'intervallo di sospensione, e la durata nota del sonno (machine.deepsleep(SLEEP_MS)) come dt — time.ticks_ms() dopo il risveglio può essere una fonte non affidabile.

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

# Publishing stub. Replace with real WiFi+MQTT logic —
# see Scenario 4 (mqtt_publisher) for a template. In a deep-sleep
# scenario, the WiFi stack is brought up/torn down on every wake,
# which eats up the bulk of the energy budget.
def publish_via_wifi(power_w, total_wh, dt_s):
    print("P=%.1f W  Wh=%.4f  dt=%.1f s" % (power_w, total_wh, dt_s))

SLEEP_MS = 10 * 60 * 1000             # 10 minutes — fixed interval
RTC_MAGIC = b"\xCA\xFE\xFE\xED"

# RTC slow memory: persisted across deep-sleep wakes
rtc = machine.RTC()
state = rtc.memory()                  # bytes; empty on cold boot

def save_state(magic, wh_total, primer_done):
    # Simple layout: 4 bytes magic + 8 bytes float wh + 1 byte primer_done
    import struct
    rtc.memory(magic + struct.pack("dB", wh_total, 1 if primer_done else 0))

def load_state():
    import struct
    if len(state) < 4 + 8 + 1 or state[:4] != RTC_MAGIC:
        return False, 0.0, False
    wh_total, primer_done_byte = struct.unpack("dB", state[4:4+9])
    return True, wh_total, bool(primer_done_byte)

valid, rtc_total_wh, primer_done = load_state()
if not valid:
    rtc_total_wh = 0.0
    primer_done = False

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:    # __enter__ automatically calls begin() — the snapshot primer
    dev.energy.disable()         # the master owns Wh persistence itself

    if not primer_done:
        # First wake: the primer snapshot just discarded the "dirty" data.
        # Save the flag and go straight back to sleep — the next wake,
        # SLEEP_MS later, will get a full accumulator for the interval.
        save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)
        machine.deepsleep(SLEEP_MS)

    # skip_latch=True reads what the begin() primer snapshot captured —
    # i.e. the accumulator for the elapsed sleep interval.
    snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)

    # Use the KNOWN sleep duration as dt
    dt_s = SLEEP_MS / 1000
    rtc_total_wh += snap.avg_p[0] * dt_s / 3600.0

    publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s)  # stub

    save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)

machine.deepsleep(SLEEP_MS)

Lo sketch completo (con configurazione WiFi, pubblicazione MQTT, guardie con marcatore magico RTC) è in examples_upy/06_deep_sleep.py.

Bilancio energetico (ESP32-WROOM su Li-ion da 2000 mAh, intervallo di 10 minuti):

  • Ciclo attivo: ~3 s (WiFi + MQTT + I²C) a ~80 mA → ~0.07 mAh per risveglio
  • Sleep: ~10 µA (RTC + domini conservati)
  • ~10 mAh al giorno → 2000 mAh durano ~6 mesi

Gli host CPython (Raspberry Pi e simili) funzionano di norma 24/7 con un alimentatore — il deep sleep non si applica. Per il funzionamento a batteria su CPython, vedere la sezione sul consumo energetico e la sospensione systemd in 08 · Integrazioni cloud.


Scenario 10 — Streaming asincrono tramite stream_period (funzione solo Python)

Obiettivo: integrarsi in un loop di eventi asyncio / uasyncio esistente. Il pacchetto fornisce un generatore asincrono dev.stream_period(interval_s=...) che incapsula lo snapshot periodico più la gestione automatica delle letture non aggiornate.

CPython (tramite asyncio + paho-mqtt-asyncio, oppure piatto)

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:
        # Once per minute, skip_stale=True (default) — stale snapshots are
        # automatically skipped without raising RbAmpStaleError
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"P={snap.avg_p[0]:.2f} W,  Wh={dev.energy.wh(0):.4f}")

asyncio.run(main())

MicroPython (tramite uasyncio)

Python
import uasyncio as asyncio
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass

async def reader(dev):
    async for snap in dev.stream_period(interval_s=60.0):
        print("P={:.2f} W,  Wh={:.4f}".format(snap.avg_p[0], dev.energy.wh(0)))

async def main():
    i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
    with RbAmp(i2c, 0x50) as dev:
        # Run reader + other async tasks in parallel
        await asyncio.gather(
            reader(dev),
            # other_async_task(),
        )

asyncio.run(main())

Parametri di stream_period(interval_s=, skip_stale=):

  • interval_s — il periodo tra due istantanee (consigliato ≥ 30 s)
  • skip_stale=True (predefinito) — le istantanee non aggiornate vengono saltate automaticamente; il generatore passa semplicemente all'intervallo successivo

  • skip_stale=False — gli snapshot non aggiornati vengono prodotti con snap.valid=False, e spetta al chiamante decidere cosa farne

Esempi completi — examples_upy/05_async_streaming.py (MicroPython) e l'equivalente asyncio negli esempi CPython.


Scenario 11 — Energia STD sul dispositivo (CPython)

Obiettivo: su un modulo STANDARD (STD), leggere i contatori di energia a vita del modulo stesso e riportare quanto è stato consumato in ciascun intervallo. Per questo scenario non c'è un file di esempio separato; il codice seguente è completo.

Nota

L'energia sul dispositivo è validata su CPython (smbus2). Il percorso MicroPython a 16 bit è implementato ma non ancora validato su hardware — per questo scenario preferire CPython.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpNotSupportedError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    if not dev.is_std:
        raise SystemExit("not an STD module")

    try:
        prev = dev.read_std_energy()
    except RbAmpNotSupportedError:
        raise SystemExit("this module does not provide on-device energy")

    while True:
        time.sleep(60)
        now = dev.read_std_energy()
        delta, restarted = RbAmp.std_energy_delta(prev, now)
        if delta is None:
            print("energy generation changed - readings not comparable")
        else:
            print("import %d Wh, export %d Wh, net %d Wh%s" % (
                delta.act_import_wh, delta.act_export_wh, delta.act_net_wh,
                " (module restarted)" if restarted else ""))
        prev = now

std_energy_delta() è sicura in caso di interruzione di alimentazione: un contatore che torna leggermente più basso viene trattato come incremento zero. I valori per canale sono in now.ch_import_uwh[ch] / ch_export_uwh[ch] per ch < now.channels.

Le chiamate di periodo su un modulo STD

Le chiamate di periodo dello Scenario 2 funzionano su un modulo STD come su BASIC; l'energia è netta (l'export sottrae):

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue    # nothing to report for this period; the next one covers it
        print("avg %.1f W, net %.4f Wh, total %.4f Wh%s" % (
            snap.avg_p_total, snap.wh_net, dev.energy.wh(0),
            " (module restarted)" if snap.module_restarted else ""))

begin() sceglie la sorgente del periodo in base a ciò che il modulo riporta: i suoi contatori di energia (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. I banchi di latch sono disponibili anche direttamente — vedere "Banchi di latch" in 09 · Riferimento API.


Tabella riassuntiva degli scenari

# LOC Runtime bus I²C Periodo? DRDY? MQTT? Persistenza
1 ~25 entrambi dedicato no no no no
2 ~35 entrambi (OLED su uPy) condiviso con OLED (uPy) sì no no RAM
3 ~50 entrambi condiviso, 3 moduli sì no no RAM
4 ~50 entrambi dedicato sì no sì MQTT retained
5 ~40 entrambi dedicato no (RT) no no RAM (di proprietà del master)
6 ~60 entrambi condiviso, 3 moduli sì no sì MQTT retained
7 ~40 entrambi dedicato no (RT) no no RAM
8 ~30 CPython dedicato sì no no file di log a rotazione
9 ~50 Solo MicroPython dedicato sì no sì Memoria RTC + MQTT
10 ~25 entrambi (asyncio/uasyncio) dedicato sì no (optional) RAM
11 ~20 CPython (modulo STD) dedicato no (sul dispositivo) no no contatori di vita del modulo

Deployment in produzione (solo CPython)

Per un deploy 24/7 di lunga durata su un SBC Linux si consiglia un servizio systemd. L'esempio completo è in examples_cpython/10_systemd_service.py (include un helper --install che genera il file unit /etc/systemd/system/rbamp.service).

Struttura di base:

Python
#!/usr/bin/env python3
# /usr/local/bin/rbamp_daemon.py  (make it executable: sudo chmod +x /usr/local/bin/rbamp_daemon.py)
import sys, signal, time, logging
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

logging.basicConfig(level=logging.INFO,
                    format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("rbamp")

shutdown = False
def on_signal(sig, frame):
    global shutdown
    log.info("Received signal %d, shutting down gracefully", sig)
    shutdown = True

signal.signal(signal.SIGTERM, on_signal)
signal.signal(signal.SIGINT,  on_signal)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    log.info("rbAmp daemon started")
    while not shutdown:
        try:
            snap = dev.read_period_snapshot()
            log.info("P=%.1f W, Wh=%.4f", snap.avg_p[0], dev.energy.wh(0))
        except Exception as e:
            log.warning("snapshot failed: %s", e)
        time.sleep(60)

log.info("rbAmp daemon stopped")

E l'unità in sé:

INI
# /etc/systemd/system/rbamp.service
[Unit]
Description=rbAmp I2C AC sensor daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/rbamp_daemon.py
Restart=on-failure
RestartSec=5
# the user must be in the i2c group: sudo usermod -aG i2c pi
User=pi

[Install]
WantedBy=multi-user.target

Per avviare: sudo systemctl enable --now rbamp. Log: journalctl -u rbamp -f.

Cosa c'è dopo


← Avvio rapido | Indice | Integrazioni fai-da-te →


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/06_examples.md


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/06_examples.md (v1.6.1)