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) |
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
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
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)
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)
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.
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
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
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)
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)
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)
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
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
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.)
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.
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.
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.
⚠ 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.
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)
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)
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 consnap.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.
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.
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):
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:
#!/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é:
# /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
-
07 · Integrazioni fai-da-te — Home Assistant / Node-RED / OpenHAB costruiti su questi scenari
-
08 · Integrazioni cloud — AWS IoT / Azure / GCP / InfluxDB Cloud / webhook generico
-
09 · Riferimento API — ogni classe pubblica + metodo + proprietà + eccezione
-
10 · Risoluzione dei problemi — quando gli scenari non funzionano sul suo banco di prova
← 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)