rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub [Edit on GitHub]

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)
Nota

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

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)

Versión de 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)

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)

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()

Versión de CPython (medidor de periodos, sin pantalla)

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")

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.

Instantánea coherente

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

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)}")

Versión de 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)))

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)

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 (mediante 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

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

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")

Versión de 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

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.)

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)

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.

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}")

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.

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}")

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.

Seguridad

⚠ 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.

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)

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)

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 (mediante 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())

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 con snap.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.

Nota

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.

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() 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):

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() 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:

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")

Y la unidad en 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

Para arrancarlo: sudo systemctl enable --now rbamp. Registros: journalctl -u rbamp -f.

Lo que viene después


← 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)