Ejemplos
Este capítulo recorre 11 escenarios (10 en la tabla de abajo más el Escenario 11), desde un «hola mundo» mínimo hasta un despliegue de producción. La mayoría tiene implementaciones paralelas en MicroPython (en examples_upy/) y en CPython (en examples_cpython/). El código de abajo es una destilación de la lógica clave, no un script completo; las versiones completas están en los archivos de ejemplo correspondientes.
| # | Escenario | MicroPython | CPython |
|---|---|---|---|
| 1 | Lectura rápida | 01_quick_read.py |
01_quick_read.py |
| 2 | Contador por periodos + pantalla local | 02_oled_period.py |
02_period_meter.py |
| 3 | Monitorización de 3 módulos en un bus | 03_multi_module.py |
03_multi_module_broadcast.py |
| 4 | UI3 + MQTT por canal | 04_mqtt.py |
04_mqtt_publisher.py |
| 5 | Medición bidireccional en el lado del maestro | 07_bidirectional_energy.py |
05_bidirectional_energy.py |
| 6 | Balance energético de toda la casa (varios módulos + MQTT) | 08_home_energy_balance.py |
07_home_energy_balance.py |
| 7 | Registro de detección de eventos (EMA) | 09_event_detection_logger.py |
sin archivo |
| 8 | Registrador local rotativo | sin archivo | 08_rotating_file_logger.py |
| 9 | Registrador de sueño profundo alimentado por batería | 06_deep_sleep.py |
(no aplica) |
| 10 | Transmisión asíncrona mediante stream_period |
05_async_streaming.py |
sin archivo (código en el Escenario 10) |
Todos los escenarios asumen que la clase de sensor y el modelo de CT ya están configurados mediante dev.set_sensor_class() + dev.set_ct_model() (véase 05 · Inicio rápido, Paso 4). Esto se hace una vez en la instalación: los ajustes se guardan en la flash del módulo y sobreviven a un reinicio.
Escenario 1: lectura rápida
Objetivo: imprimir U / I / P / PF / frecuencia una vez por segundo. Es el mismo «hola mundo» que escribió en 05 · Inicio rápido, pero usando dev.read_all(): una lectura puntual del bloque RT completo en una única estructura RbAmpSnapshot.
Versión de CPython
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)
Versión de 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)
Qué ocurre en el bus: dev.read_all() en un UI3 realiza unas 53 transacciones de bytes (13 valores en coma flotante × 4 bytes + 1 byte de frecuencia). A 50 kHz con margen de reintentos, son del orden de 25–30 ms. Si no necesita todos los valores, use los accesores por propiedad (dev.voltage, dev.read_current(ch)).
Escenario 2: contador por periodos + pantalla local
Objetivo: un contador de Wh, actualizado una vez por minuto, en una pantalla local. En MicroPython, una OLED SSD1306 en el mismo bus I²C. En CPython, salida de texto por stdout (puede conectar una LCD de caracteres por GPIO o usar una página web: véase el Escenario 6).
Versión de MicroPython (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()
Versión de CPython (medidor de periodos, sin pantalla)
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")
Gestión de instantáneas obsoletas. dev.read_period_snapshot() lanza RbAmpStaleError si el módulo no ha conseguido preparar una instantánea nueva en el momento de la lectura. El paquete conserva la marca de tiempo anterior, así que la siguiente instantánea correcta cubre el intervalo completo y los Wh siguen siendo exactos. Un patrón estándar de try/except de Python.
Escenario 3 — Monitorización de 3 módulos en un bus
Objetivo: sondear 3 módulos en las direcciones 0x50 / 0x51 / 0x52, con instantáneas coherentes para que sus potencias por canal sumen en el mismo periodo de red.
una trama de llamada general (A5 27 ) hace que cada módulo que haya optado con fleet.enable_gc_all() tome su instantánea: desfase de la flota < 10 µs, para que los totales cuadren. fleet.gc_latch() envía la trama y devuelve el tick de difusión; fleet.check_sync() lee de vuelta el tick que registra cada módulo, para señalar el que se perdió la trama. (En el firmware v1.0/v1.1 la llamada general no estaba disponible y este escenario recurría a instantáneas secuenciales por dispositivo.) Véase 09 · Referencia de la API para RbAmpFleet.
Versión de CPython
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)}")
Versión de 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)))
Escenario 4 — UI3 + MQTT por canal
Objetivo: un módulo UI3 con 3 pinzas CT en tres líneas independientes. Contadores de Wh por canal, publicados en MQTT una vez por minuto. Muestra que dev.energy.wh(ch) funciona en cada canal de forma independiente, sin necesidad de un array manual total_wh[3] en el maestro.
CPython (mediante paho-mqtt; instale 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 (mediante 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)
En MicroPython, umqtt.simple es un cliente síncrono y bloqueante. Para una variante asíncrona use mqtt_as (un cliente MQTT asyncio); véase también el Escenario 10.
Para el autodescubrimiento completo de HA sobre este patrón, véase 07 · Integraciones DIY.
Escenario 5: medición bidireccional en el lado del maestro
Objetivo: separar la potencia instantánea con signo en consumo bruto y exportación bruta. Use este patrón en la línea de módulos BASIC, donde el firmware recorta los valores negativos en snap.avg_p[ch] (potencia promediada por periodo): muestree dev.read_power(0) (potencia instantánea, con signo en todas las líneas de módulos) a 10 Hz en el lado del maestro y agrupe los valores usted mismo.
Versión de CPython
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")
Versión de 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
En un módulo STANDARD (STD) las llamadas de periodo funcionan sin cambios y la energía es neta (la exportación resta); los contadores de importación y exportación del propio módulo están en read_std_energy() (Escenario 11). Esta separación en el maestro solo hace falta en módulos BASIC, para informar por separado del consumo bruto y de la exportación bruta.
Escenario 6: balance energético de toda la casa
Objetivo: 3 módulos: red (bidireccional), solar (solo generación), cargas (UI3 por aparato). Un panel combinado se publica una vez por minuto.
(Requiere 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)
En módulos BASIC la exportación no la cuenta energy.wh(), así que las cifras de solar y mains de arriba son solo consumo. Para una separación explícita entre consumo bruto y exportación bruta en la red, combine esto con el patrón del Escenario 5 (un bucle aparte a 10 Hz sobre mains.read_power(0) en un threading.Thread en segundo plano en CPython, o uasyncio.create_task en MicroPython).
Escenario 7 — Registro de detección de eventos (EMA)
Objetivo: en cada ventana de tiempo real de 100 ms, comparar la potencia instantánea con una media móvil exponencial. Registrar las desviaciones significativas: cargas como un microondas, un hervidor o un secador de pelo "aparecen" en el registro como eventos de encendido / apagado.
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}")
En MicroPython, aplique las mismas sustituciones: time.sleep → time.sleep_ms, y time.time() → time.time() (disponible en la mayoría de puertos) o time.ticks_ms().
Combínelo con la publicación MQTT del Escenario 4 para las automatizaciones en HA.
Escenario 8: registrador local con rotación (CPython)
Objetivo: escribir una instantánea de periodo en un archivo CSV con rotación una vez por minuto mediante el logging.handlers.RotatingFileHandler estándar. Útil para despliegues autónomos sin WiFi / MQTT, o como búfer para la sincronización diferida con la nube.
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}")
En MicroPython el módulo estándar logging.handlers no está disponible; para un registro local, use un simple with open("log.csv", "a") más rotación manual mediante os.stat() + os.rename(). Véase el ejemplo completo en examples_upy/09_event_detection_logger.py.
Para la sincronización diferida con la nube (registro local, envío una vez por hora), véase la sección «Híbrido: almacenamiento local + sincronización» en 08 · Integraciones en la nube.
Escenario 9: registrador con batería y deep sleep (solo MicroPython)
Objetivo: un ESP32 (MicroPython) despierta cada 10 minutos, toma una única instantánea de periodo, publica por WiFi+MQTT y vuelve al deep sleep. La energía se conserva entre ciclos de sueño mediante la memoria RTC.
⚠ Nota importante sobre el sueño profundo y el firmware v1.0/v1.1. En el firmware actual, dev.begin() emite un cebado CMD_LATCH_PERIOD que reinicia el acumulador de periodo del firmware. Esto significa que, tras despertar de un sueño profundo, no puede simplemente llamar a read_period_snapshot() por defecto: esa llamada tomaría otra instantánea y devolvería datos casi nulos que cubren solo los ~50 ms desde el cebado. El patrón correcto de abajo usa skip_latch=True para leer los datos acumulados durante el intervalo de sueño, y la duración conocida del sueño (machine.deepsleep(SLEEP_MS)) como dt: time.ticks_ms() tras despertar puede no ser una fuente fiable.
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)
El boceto completo (con configuración de WiFi, publicación MQTT y guardas de marcador magic en RTC) está en examples_upy/06_deep_sleep.py.
Presupuesto energético (ESP32-WROOM con Li-ion de 2000 mAh, intervalo de 10 minutos):
- Ciclo activo: ~3 s (WiFi + MQTT + I²C) a ~80 mA → ~0.07 mAh por despertar
- Reposo: ~10 µA (RTC + dominios retenidos)
- ~10 mAh al día → 2000 mAh duran ~6 meses
Los hosts CPython (Raspberry Pi, etc.) normalmente funcionan con fuente de alimentación 24/7: el sueño profundo no aplica. Para el funcionamiento con batería en CPython, véase la sección de consumo de energía y la suspensión de systemd en 08 · Integraciones en la nube.
Escenario 10: transmisión asíncrona mediante stream_period (función solo de Python)
Objetivo: integrarse en un bucle de eventos asyncio / uasyncio existente. El paquete ofrece un generador asíncrono dev.stream_period(interval_s=...) que encapsula la instantánea periódica y el tratamiento automático de obsolescencia.
CPython (mediante asyncio + paho-mqtt-asyncio, o plano)
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 (mediante 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())
Parámetros de stream_period(interval_s=, skip_stale=):
interval_s— el periodo entre instantáneas (recomendado ≥ 30 s)-
skip_stale=True(por defecto): las instantáneas obsoletas se omiten automáticamente; el generador avanza simplemente al siguiente intervalo -
skip_stale=False: las instantáneas obsoletas se entregan consnap.valid=False, y el llamador decide qué hacer con ellas
Ejemplos completos: examples_upy/05_async_streaming.py (MicroPython) y el equivalente asyncio en los ejemplos de CPython.
Escenario 11 — Energía en el propio dispositivo STD (CPython)
Objetivo: en un módulo STANDARD (STD), leer los contadores de energía de vida útil del propio módulo e informar de lo consumido en cada intervalo. Para este escenario no hay un archivo de ejemplo aparte; el código siguiente es completo.
La energía en el dispositivo se valida en CPython (smbus2). La ruta de 16 bits de MicroPython está implementada pero aún no validada en hardware; para este escenario, use 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() es seguro ante cortes de alimentación: un contador que vuelve ligeramente más bajo se trata como incremento cero. Las cifras por canal están en now.ch_import_uwh[ch] / ch_export_uwh[ch] para ch < now.channels.
Las llamadas de periodo en un módulo STD
Las llamadas de periodo del Escenario 2 funcionan en un módulo STD igual que en BASIC; la energía es neta (la exportación resta):
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() elige la fuente del periodo según lo que informa el módulo: sus contadores de energía (el periodo es la diferencia de dos lecturas; no se envía ningún comando de latch) o, en un módulo solo con bancos de latch, el banco de latch 0. Los bancos de latch también están disponibles directamente; véase "Bancos de latch" en 09 · Referencia de la API.
Tabla resumen de escenarios
| # | LOC | Ejecución | bus I²C | ¿Período? | DRDY? | MQTT? | Persistencia |
|---|---|---|---|---|---|---|---|
| 1 | ~25 | ambos | dedicado | no | no | no | no |
| 2 | ~35 | ambos (OLED en uPy) | compartido con OLED (uPy) | sí | no | no | RAM |
| 3 | ~50 | ambos | compartido, 3 módulos | sí | no | no | RAM |
| 4 | ~50 | ambos | dedicado | sí | no | sí | MQTT retenido |
| 5 | ~40 | ambos | dedicado | no (RT) | no | no | RAM (propiedad del maestro) |
| 6 | ~60 | ambos | compartido, 3 módulos | sí | no | sí | MQTT retenido |
| 7 | ~40 | ambos | dedicado | no (RT) | no | no | RAM |
| 8 | ~30 | CPython | dedicado | sí | no | no | archivo de registro rotativo |
| 9 | ~50 | Solo MicroPython | dedicado | sí | no | sí | Memoria RTC + MQTT |
| 10 | ~25 | ambos (asyncio/uasyncio) | dedicado | sí | no | (optional) | RAM |
| 11 | ~20 | CPython (módulo STD) | dedicado | no (en el dispositivo) | no | no | contadores de vida útil del módulo |
Despliegue en producción (solo CPython)
Para un despliegue de 24/7 de larga duración en un SBC Linux se recomienda un servicio systemd. El ejemplo completo está en examples_cpython/10_systemd_service.py (incluye un ayudante --install que genera el archivo de unidad /etc/systemd/system/rbamp.service).
Estructura básica:
#!/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")
Y la unidad en 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
Para arrancarlo: sudo systemctl enable --now rbamp. Registros: journalctl -u rbamp -f.
Lo que viene después
-
07 · Integraciones DIY: Home Assistant / Node-RED / OpenHAB, construidos sobre estos escenarios
-
08 · Integraciones en la nube: AWS IoT / Azure / GCP / InfluxDB Cloud / webhook genérico
-
09 · Referencia de la API — cada clase, método, propiedad y excepción pública
-
10 · Solución de problemas — cuando los escenarios no funcionan en su banco de pruebas
← Inicio rápido | Índice | Integraciones DIY →
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/06_examples.md
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/06_examples.md (v1.6.1)