rbAmp
ES
Tienda
Docs
Actualizado

12 · Ejemplos de MicroPython y CircuitPython

Este capítulo es el equivalente en Python de arduino-examples.md: los mismos diez escenarios, portados a MicroPython en ESP32 / RP2040 / ESP8266 / Pyboard, con las diferencias de CircuitPython donde los dos dialectos difieren.

Nota

Estos ejemplos hablan directamente con rbAmp mediante la API de registros I²C en bruto. Están pensados para integraciones nativas, embebidas o con recursos limitados, donde hace falta control directo y cada byte del bus importa.

Para una interfaz más cómoda y estructurada, use la biblioteca MicroPython rbamp (véase la tabla de bibliotecas cliente del README). La biblioteca encapsula los detalles de registro en una clase RbAmp de alto nivel con métodos con nombre (dev.voltage, dev.latch_period(), dev.read_period_snapshot(), etc.), API síncrona y uasyncio, un acumulador de Wh por canal automático, auxiliares multimódulo y la disciplina de reintento + comprobación de cordura de la SPEC §B.5 para puertos ESP32 mediante MachineI2CBackend(retry_attempts=…). El mismo paquete se ejecuta sin cambios en CPython; véase la tabla de bibliotecas cliente del README. La mayoría de los proyectos de usuario deben partir de la biblioteca y recurrir a la API en bruto solo cuando haga falta.

MicroPython frente a CircuitPython: referencia rápida

El lenguaje Python es el mismo; cambian los módulos de acceso al dispositivo. La tabla siguiente asigna cada concepto usado en los ejemplos al módulo o clase equivalente en cada dialecto.

Concepto MicroPython CircuitPython
Bus I2C from machine import I2C, Pin
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
import board, busio
i2c = busio.I2C(board.SCL, board.SDA, frequency=50000)
Lectura de un byte i2c.readfrom_mem(addr, reg, 1)[0] with i2c_device: i2c_device.write_then_readinto(bytes([reg]), buf, in_end=1) (usando adafruit_bus_device.I2CDevice)
Escritura de un byte i2c.writeto_mem(addr, reg, bytes([val])) i2c_device.write(bytes([reg, val]))
Entrada GPIO + IRQ pin = Pin(15, Pin.IN, Pin.PULL_UP)
pin.irq(trigger=Pin.IRQ_FALLING, handler=fn)
import digitalio, countio
btn = countio.Counter(board.D15, edge=countio.Edge.FALL)
o keypad.Keys([board.D15], ...)
Suspensión (seg / ms) time.sleep(s) / time.sleep_ms(ms) time.sleep(s) (sin sleep_ms)
ms / µs monotónicos time.ticks_ms(), time.ticks_us(), time.ticks_diff(a, b) time.monotonic_ns() / time.monotonic() (sin ticks_diff)
WiFi import network
wlan = network.WLAN(network.STA_IF)
import wifi
wifi.radio.connect(ssid, pwd) (ESP32-S2/S3/C3 con CP nativo)
MQTT from umqtt.simple import MQTTClient import adafruit_minimqtt.adafruit_minimqtt as mqtt
NTP import ntptime; ntptime.settime() import adafruit_ntp; ntp = adafruit_ntp.NTP(socketpool, server="...")
Suspensión profunda import machine; machine.deepsleep(ms) import alarm; alarm.exit_and_deep_sleep_until_alarms(time_alarm)
Memoria retenida del RTC machine.RTC().memory(buf) import alarm; alarm.sleep_memory[...]
Asíncrono import uasyncio as asyncio import asyncio (CircuitPython 8+)

Cada ejemplo está escrito en MicroPython. Cuando el equivalente en CircuitPython difiere en más de una línea de importación, se incluye un bloque explícito «Delta de CircuitPython».

Índice de ejemplos

# Título Dificultad Salida MQTT DRDY Multimódulo Bidireccional Caso de uso
1 Lectura rápida mínimo REPL — — — — Prueba de humo
2 Medidor de energía de 60 segundos en OLED bajo SSD1306 — — — — Contador Wh encapsulado
3 Monitor multimódulo bajo REPL — — sí (3) — Monitorización de toda la vivienda
4 Medidor de energía por aparato (UI3) medio — sí — — — Submedición en HA
5 Bidireccional en el maestro con un módulo BASIC medio REPL — sí — sí (maestro) Vivienda solar en nivel BASIC
6 Balance energético de la vivienda alta — sí — sí (3) sí Balance energético de la vivienda
7 Detección de eventos de corriente medio REPL + SD — sí — — Registro de eventos de electrodomésticos
8 Publicador MQTT con auto-descubrimiento de HA medio — sí (+disco) — — opcional Integración de HA lista para usar
9 Registrador remoto alimentado por batería con sueño profundo medio — sí — — — Medidor exterior / autónomo
10 Tarifa por franjas horarias (TOU) con hora de pared por NTP medio REPL sí — — opcional Medición por tarifa punta / valle

Cabecera común para todos los ejemplos

Cada ejemplo supone que estos auxiliares están presentes en el mismo archivo .py (o importados desde un helpers.py). Para ahorrar espacio, el bloque no se repite en cada boceto.

Python
"""
rbAmp raw-I2C helpers for MicroPython.

For CircuitPython, replace the I2C bring-up:
    import board, busio
    from adafruit_bus_device.i2c_device import I2CDevice
    i2c_bus = busio.I2C(board.SCL, board.SDA, frequency=50000)
    # then use I2CDevice(i2c_bus, addr) for each rbAmp, see notes in each example.
"""

import struct
import time
from machine import I2C, Pin   # MicroPython


def rb_read_u8(i2c, addr, reg):
    """Read one byte from an rbAmp slave register.

    :param i2c:  machine.I2C instance.
    :param addr: 7-bit slave address (e.g. 0x50).
    :param reg:  register address inside the slave.
    :returns:    the byte stored in the register.
    """
    return i2c.readfrom_mem(addr, reg, 1)[0]


def rb_read_float_le(i2c, addr, reg):
    """Read a little-endian float32 from four consecutive registers.

    rbAmp supports READ auto-increment (a single burst-read is valid for
    atomicity). The per-byte form below is shown for clarity. WRITE
    transactions, by contrast, are byte-at-a-time only. See chapter 11.
    """
    b = bytes([rb_read_u8(i2c, addr, reg + i) for i in range(4)])
    return struct.unpack('> 8) & 0xFF]))
        return True
    except OSError:
        return False


def rb_wait_ready(i2c, addr, timeout_ms=2000):
    """Block until DATA_VALID bit 0 is 1, or raise OSError on timeout."""
    t0 = time.ticks_ms()
    while time.ticks_diff(time.ticks_ms(), t0) < timeout_ms:
        if rb_read_u8(i2c, addr, 0xCE) & 0x01:
            return
        time.sleep_ms(50)
    raise OSError("rbAmp at 0x{:02X} not ready".format(addr))

Delta de CircuitPython: encabezado común

CircuitPython usa adafruit_bus_device.i2c_device.I2CDevice (envoltorio por esclavo) y no tiene time.ticks_ms. Auxiliares equivalentes:

Python
import time
import struct
import board, busio
from adafruit_bus_device.i2c_device import I2CDevice

def cp_read_u8(dev, reg):
    """Read one byte from one register (CircuitPython)."""
    buf = bytearray(1)
    with dev:
        dev.write_then_readinto(bytes([reg]), buf)
    return buf[0]

def cp_read_float_le(dev, reg):
    b = bytes(cp_read_u8(dev, reg + i) for i in range(4))
    return struct.unpack('> 8) & 0xFF]))
            return True
        except OSError:
            return False
    finally:
        i2c_bus.unlock()

def cp_wait_ready(dev, timeout_s=2.0):
    t0 = time.monotonic()
    while time.monotonic() - t0 < timeout_s:
        if cp_read_u8(dev, 0xCE) & 0x01:
            return
        time.sleep(0.05)
    raise OSError("rbAmp not ready")

Ejemplo 1: lectura rápida (mínimo)

Objetivo: mostrar U, I, P, PF en un REPL una vez por segundo. Hardware: ESP32 / RP2040 / Pico W + un rbAmp UI1.

Python
from machine import I2C, Pin
import time

# I2C bus 0 on ESP32 default pins.
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)

RB_ADDR = 0x50

# Wait until the first RT window has been computed.
rb_wait_ready(i2c, RB_ADDR)
ver = rb_read_u8(i2c, RB_ADDR, 0x03)
print("rbAmp version: 0x{:02X}".format(ver))

while True:
    u  = rb_read_float_le(i2c, RB_ADDR, 0x86)   # RMS voltage, V
    i_ = rb_read_float_le(i2c, RB_ADDR, 0x8E)   # RMS current, A
    p  = rb_read_float_le(i2c, RB_ADDR, 0xA6)   # active power, W (signed)
    pf = rb_read_float_le(i2c, RB_ADDR, 0xB2)   # power factor, signed
    print("U={:.1f}V  I={:.3f}A  P={:+.1f}W  PF={:+.3f}".format(u, i_, p, pf))
    time.sleep(1)

Diferencias de CircuitPython

Python
import board, busio, time
from adafruit_bus_device.i2c_device import I2CDevice

i2c_bus = busio.I2C(board.SCL, board.SDA, frequency=50000)
dev = I2CDevice(i2c_bus, 0x50)

cp_wait_ready(dev)
print("rbAmp version: 0x{:02X}".format(cp_read_u8(dev, 0x03)))

while True:
    u  = cp_read_float_le(dev, 0x86)
    i_ = cp_read_float_le(dev, 0x8E)
    p  = cp_read_float_le(dev, 0xA6)
    pf = cp_read_float_le(dev, 0xB2)
    print("U={:.1f}V  I={:.3f}A  P={:+.1f}W  PF={:+.3f}".format(u, i_, p, pf))
    time.sleep(1)

Ejemplo 2: medidor de energía de 60 segundos en OLED

Objetivo: contador de Wh actualizado una vez por minuto, mostrado en un SSD1306 de 128×64. Hardware: ESP32 + rbAmp + OLED SSD1306 en el mismo bus. Contabilidad: unidireccional (nivel BASIC). Biblioteca: ssd1306.py de los ejemplos de MicroPython (un controlador estándar de un solo archivo).

Python
from machine import I2C, Pin
import time
import ssd1306

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50

oled = ssd1306.SSD1306_I2C(128, 64, i2c)        # OLED typically at 0x3C

rb_wait_ready(i2c, RB_ADDR)

# Primer snapshot — discard its result.
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_prev_ms = time.ticks_ms()
total_wh = 0.0

while True:
    time.sleep(60)

    # 1) Final snapshot — closes the period [t_prev_ms .. now].
    rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
    t_now_ms = time.ticks_ms()
    time.sleep_ms(50)                            # let firmware finalise the snapshot

    # 2) Verify the snapshot is fresh.
    if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
        print("WARN: stale snapshot")
        t_prev_ms = time.ticks_ms()
        continue

    # 3) Read time-averaged power, channel 0.
    avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)

    # 4) Energy uses the MASTER clock (authoritative).
    dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
    e_wh = avg_p * dt_s / 3600.0
    total_wh += e_wh
    t_prev_ms = t_now_ms

    # 5) Render on OLED.
    oled.fill(0)
    oled.text("P:  {:6.1f} W".format(avg_p), 0, 0)
    oled.text("dt: {:6.1f} s".format(dt_s),   0, 16)
    oled.text("E:  {:.2f} Wh".format(total_wh), 0, 32)
    oled.show()

    print("avg_P={:.1f}  E_period={:.3f}  total={:.3f}".format(avg_p, e_wh, total_wh))
Diferencias de CircuitPython

: use adafruit_ssd1306 (variante displayio o variante framebuf). El constructor de la OLED cambia, pero el resto del bucle no: sustituya las llamadas rb_* por las funciones cp_* y use time.monotonic() para dt_s.


Ejemplo 3: monitor multimódulo

Objetivo: sondear tres módulos (alimentación principal, calentador de agua, AC) e imprimir el total. Hardware: ESP32 + 3 × rbAmp UI1 en 0x50, 0x51 y 0x52.

Python
from machine import I2C, Pin
import time

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
modules = ((0x50, "Mains "), (0x51, "Boiler"), (0x52, "AC    "))

# I2C scan — confirm every module is present.
present = i2c.scan()
for addr, label in modules:
    if addr not in present:
        raise RuntimeError("{} at 0x{:02X} not on bus".format(label, addr))
print("All modules OK:", [hex(a) for a in present])

while True:
    total_p = 0.0
    print("---")
    for addr, label in modules:
        u = rb_read_float_le(i2c, addr, 0x86)
        p = rb_read_float_le(i2c, addr, 0xA6)
        print("[{}] U={:.1f}  P={:+.1f} W".format(label, u, p))
        total_p += p
    print("TOTAL: {:.1f} W".format(total_p))
    time.sleep(2)

Ejemplo 4: medidor de energía por aparato (UI3)

Objetivo: un módulo UI3 con tres pinzas de corriente (CT) en tres cargas distintas de la misma fase. Contadores de Wh independientes por carga, publicados por MQTT cada minuto. Hardware: ESP32 + 1 × rbAmp UI3. Biblioteca: umqtt.simple (MicroPython) o umqtt.robust para reconexión automática.

Python
from machine import I2C, Pin
import network, time
from umqtt.simple import MQTTClient

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
CH_NAMES = ("main", "heatpump", "lights")

# --- Wi-Fi ---
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "password")
while not wlan.isconnected():
    time.sleep(0.5)

# --- MQTT ---
mqtt = MQTTClient(client_id="rbamp-ui3", server="192.168.1.10")
mqtt.connect()

def mqtt_publish(ch_name, avg_p, e_wh):
    """Publish one channel's state to MQTT.

    :param ch_name: short channel name (used in the topic).
    :param avg_p:   time-averaged power, W.
    :param e_wh:    accumulated channel energy, Wh.
    """
    topic = "rbamp/{}/state".format(ch_name).encode()
    payload = '{{"power":{:.1f},"energy":{:.4f}}}'.format(avg_p, e_wh).encode()
    mqtt.publish(topic, payload)

rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)            # primer snapshot
t_prev_ms = time.ticks_ms()
total_wh = [0.0, 0.0, 0.0]

while True:
    time.sleep(60)

    rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
    t_now_ms = time.ticks_ms()
    time.sleep_ms(50)

    if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
        t_prev_ms = time.ticks_ms()
        continue

    # PERIOD_AVG_P_W per channel: I0 at 0xDC, I1 at 0xC2, I2 at 0xC6.
    avg_p = (rb_read_float_le(i2c, RB_ADDR, 0xDC),
             rb_read_float_le(i2c, RB_ADDR, 0xC2),
             rb_read_float_le(i2c, RB_ADDR, 0xC6))

    dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
    t_prev_ms = t_now_ms

    for ch in range(3):
        e = avg_p[ch] * dt_s / 3600.0
        total_wh[ch] += e
        print("[{}] avg_P={:+.1f} W  E_total={:.3f} Wh".format(
            CH_NAMES[ch], avg_p[ch], total_wh[ch]))
        mqtt_publish(CH_NAMES[ch], avg_p[ch], total_wh[ch])
Diferencias de CircuitPython

: sustituya umqtt.simple.MQTTClient por adafruit_minimqtt.MQTT(...) (necesita un socket_pool y un ssl_context: véase la guía Wi-Fi de Adafruit). La lógica de medición no cambia.


Ejemplo 5: bidireccional en el maestro con un módulo BASIC

Objetivo: implementar contabilidad bidireccional en el maestro mientras el firmware del módulo es BASIC (el acumulador de periodo fija a cero las muestras negativas). Leer RT P_real en cada flanco de DRDY y separar consumo y exportación. Hardware: ESP32 + rbAmp UI1 en una carga con inversor solar + DRDY conectado a un GPIO.

Python
from machine import I2C, Pin
import time

i2c  = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
drdy = Pin(15, Pin.IN, Pin.PULL_UP)
RB_ADDR = 0x50

_data_ready = False
_e_consumed_wh = 0.0
_e_exported_wh = 0.0
_t_last_sample_ms = 0

def _drdy_isr(pin):
    """ISR for DRDY falling edge — only sets a flag (no I2C inside ISR)."""
    global _data_ready
    _data_ready = True

drdy.irq(trigger=Pin.IRQ_FALLING, handler=_drdy_isr)

rb_wait_ready(i2c, RB_ADDR)
_t_last_sample_ms = time.ticks_ms()
_last_print = time.ticks_ms()
print("Bidirectional accumulator started")

while True:
    if not _data_ready:
        time.sleep_ms(10)
        continue
    _data_ready = False

    t_now = time.ticks_ms()
    # Signed instantaneous P_real: + consume, − export.
    p = rb_read_float_le(i2c, RB_ADDR, 0xA6)
    dt_s = time.ticks_diff(t_now, _t_last_sample_ms) / 1000.0
    _t_last_sample_ms = t_now

    if p > 0:
        _e_consumed_wh += p * dt_s / 3600.0
    else:
        _e_exported_wh += -p * dt_s / 3600.0

    # Summary print every 5 s — not on every RT window.
    if time.ticks_diff(t_now, _last_print) >= 5000:
        _last_print = t_now
        print("P={:+8.1f}W   consumed={:.4f} Wh  exported={:.4f} Wh  net={:+.4f} Wh"
              .format(p, _e_consumed_wh, _e_exported_wh,
                      _e_consumed_wh - _e_exported_wh))
Diferencias de CircuitPython

: CircuitPython generalmente desaconseja las IRQ de GPIO definidas por el usuario. Use countio.Counter(board.D15, edge=countio.Edge.FALL) y consulte su count desde el bucle principal, o keypad.Keys(...) para eventos de flanco. La lógica del acumulador es idéntica.


Ejemplo 6: balance energético del hogar

Objetivo: un panel de balance energético completo. Tres módulos:

  • rbAmp n.º 1 en la alimentación principal (STD: bidireccional)
  • rbAmp n.º 2 en la salida del inversor solar
  • rbAmp n.º 3, UI3, en tres cargas grandes (calefacción, AC, VE)

El maestro calcula total_consumed = solar_self_used + grid_consumed y solar_generated = solar_self_used + grid_exported. Hardware: ESP32 + 3 × rbAmp + WiFi + MQTT.

Python
from machine import I2C, Pin
import network, time, ujson as json
from umqtt.simple import MQTTClient

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
ADDR_MAINS = 0x50        # bidirectional (STD)
ADDR_SOLAR = 0x51        # generation only
ADDR_LOADS = 0x52        # UI3

# PERIOD_AVG_P_NEG address for the mains module — see the SKU datasheet
# of the STD product. Set to None on BASIC modules.
REG_PERIOD_AVG_P_NEG_MAINS = None

wlan = network.WLAN(network.STA_IF); wlan.active(True); wlan.connect("ssid", "password")
while not wlan.isconnected():
    time.sleep(0.5)
mqtt = MQTTClient("home-balance", "192.168.1.10"); mqtt.connect()

# Wait until all three modules report DATA_VALID.
for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
    rb_wait_ready(i2c, addr)

totals = {
    "mains_in_wh":    0.0,
    "mains_out_wh":   0.0,
    "solar_total_wh": 0.0,
    "loads_wh":       [0.0, 0.0, 0.0],
}

gc_tick = 0
if not rb_broadcast_latch(i2c, gc_tick):
    # GC NACK → fall back to per-module sequential snapshot.
    for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
        rb_write_u8(i2c, addr, 0x01, 0x27)
gc_tick += 1
t_prev_ms = time.ticks_ms()
print("Home balance started")

while True:
    time.sleep(60)

    if not rb_broadcast_latch(i2c, gc_tick):
        for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
            rb_write_u8(i2c, addr, 0x01, 0x27)
    gc_tick = (gc_tick + 1) & 0xFFFF
    t_now_ms = time.ticks_ms()
    time.sleep_ms(50)

    dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
    t_prev_ms = t_now_ms

    # --- MAINS (bidirectional, STD) ---
    if rb_read_u8(i2c, ADDR_MAINS, 0x07) & 0x01:
        avg_p_consume = rb_read_float_le(i2c, ADDR_MAINS, 0xDC)
        avg_p_export  = (rb_read_float_le(i2c, ADDR_MAINS, REG_PERIOD_AVG_P_NEG_MAINS)
                         if REG_PERIOD_AVG_P_NEG_MAINS is not None else 0.0)
        totals["mains_in_wh"]  += avg_p_consume * dt_s / 3600.0
        totals["mains_out_wh"] += avg_p_export  * dt_s / 3600.0

    # --- SOLAR (generation only) ---
    if rb_read_u8(i2c, ADDR_SOLAR, 0x07) & 0x01:
        avg_p = rb_read_float_le(i2c, ADDR_SOLAR, 0xDC)
        totals["solar_total_wh"] += avg_p * dt_s / 3600.0

    # --- LOADS (UI3, three channels) ---
    if rb_read_u8(i2c, ADDR_LOADS, 0x07) & 0x01:
        for i, reg in enumerate((0xDC, 0xC2, 0xC6)):     # I0, I1, I2
            p = rb_read_float_le(i2c, ADDR_LOADS, reg)
            totals["loads_wh"][i] += p * dt_s / 3600.0

    # --- Derived balance figures ---
    total_consumed  = (totals["mains_in_wh"] + totals["solar_total_wh"]
                      - totals["mains_out_wh"])
    solar_self_used = max(0.0, totals["solar_total_wh"] - totals["mains_out_wh"])

    print("MAINS  in={:.2f}  out={:.2f}".format(totals["mains_in_wh"],
                                                 totals["mains_out_wh"]))
    print("SOLAR  gen={:.2f}  self-used={:.2f}  exported={:.2f}".format(
          totals["solar_total_wh"], solar_self_used, totals["mains_out_wh"]))
    print("LOADS  HP={:.2f}  AC={:.2f}  EV={:.2f}".format(*totals["loads_wh"]))
    print("TOTAL  household consumed={:.2f} Wh".format(total_consumed))

    payload = json.dumps({
        "mains_in":       totals["mains_in_wh"],
        "mains_out":      totals["mains_out_wh"],
        "solar":          totals["solar_total_wh"],
        "self_used":      solar_self_used,
        "total_consumed": total_consumed,
        "hp":             totals["loads_wh"][0],
        "ac":             totals["loads_wh"][1],
        "ev":             totals["loads_wh"][2],
    })
    mqtt.publish(b"home/energy/balance", payload.encode(), retain=True)

Notes:

  • rb_broadcast_latch(i2c, tick) garantiza que los tres módulos tomen la instantánea en el mismo instante, lo que es crítico para un saldo preciso. La recepción GC (General Call) es opcional (FLEET_CONFIG.bit0, por defecto desactivada; vea el capítulo 02). Ante un NACK, recurra a instantáneas secuenciales por módulo (desfase ~1 ms/módulo a 50 kHz).
  • solar_self_used = solar_total − grid_exported; limítelo a cero para absorber el ruido de medición.

Ejemplo 7: detección de eventos de corriente

Objetivo: en cada flanco de DRDY, comparar la P instantánea con una EMA y registrar en una tarjeta SD las desviaciones significativas. Hardware: ESP32 + rbAmp + tarjeta SD (por SPI, p. ej. mediante el controlador MicroPython sdcard.py). Caso de uso: detección automática de eventos de cargas grandes (microondas, aire acondicionado, hervidor).

Python
from machine import I2C, Pin, SPI
import time, os, sdcard

i2c  = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
drdy = Pin(15, Pin.IN, Pin.PULL_UP)
RB_ADDR = 0x50

# Mount the SD card on /sd (SPI bus 1, CS = GPIO 5).
spi = SPI(1, baudrate=1_000_000, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
sd  = sdcard.SDCard(spi, Pin(5))
os.mount(sd, "/sd")

EMA_ALPHA = 0.05                                  # ~2 s time constant at 10 Hz
EVENT_THRESHOLD_W = 200.0

_data_ready = False
def _drdy_isr(pin):
    global _data_ready
    _data_ready = True
drdy.irq(trigger=Pin.IRQ_FALLING, handler=_drdy_isr)

rb_wait_ready(i2c, RB_ADDR)
# Seed the EMA with the current power so we do not log a spurious startup event.
p_ema = rb_read_float_le(i2c, RB_ADDR, 0xA6)
print("Event detector started")

logfile = open("/sd/events.log", "a")

while True:
    if not _data_ready:
        time.sleep_ms(10)
        continue
    _data_ready = False

    p = rb_read_float_le(i2c, RB_ADDR, 0xA6)
    delta = p - p_ema
    p_ema = (1 - EMA_ALPHA) * p_ema + EMA_ALPHA * p

    if abs(delta) > EVENT_THRESHOLD_W:
        event = "TURN_ON" if delta > 0 else "TURN_OFF"
        line = "{}  {}  delta={:+.1f} W  P={:.1f} W  EMA={:.1f} W\n".format(
            time.ticks_ms(), event, delta, p, p_ema)
        print(line, end="")
        logfile.write(line)
        logfile.flush()                          # ensure the line hits the card
Diferencias de CircuitPython

: use adafruit_sdcard.SDCard + storage.mount(VfsFat(sdcard), "/sd"). Sustituya la IRQ por countio.Counter(board.D15, edge=countio.Edge.FALL) consultado desde el bucle principal.


Ejemplo 8: publicador MQTT con descubrimiento automático de Home Assistant

Objetivo: una integración directa con HA. El ESP32 se conecta a Wi-Fi y a un broker MQTT, publica configuraciones de auto-descubrimiento de HA (así las entidades aparecen sin YAML) y emite un estado en JSON cada minuto. Hardware: ESP32 + un rbAmp UI1 + red Wi-Fi con un broker MQTT. Contabilidad: unidireccional.

Python
from machine import I2C, Pin
import network, time, ujson as json
from umqtt.simple import MQTTClient

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50

WIFI_SSID  = "ssid"
WIFI_PASS  = "password"
MQTT_HOST  = "192.168.1.10"
MQTT_USER  = "ha"
MQTT_PASS  = "secret"
DEVICE_ID  = "rbamp_main"
DEVICE_NAME = "Mains rbAmp"

# Bring up WiFi.
wlan = network.WLAN(network.STA_IF); wlan.active(True); wlan.connect(WIFI_SSID, WIFI_PASS)
while not wlan.isconnected():
    time.sleep(0.5)
print("WiFi up:", wlan.ifconfig()[0])

mqtt = MQTTClient(DEVICE_ID, MQTT_HOST, user=MQTT_USER, password=MQTT_PASS)
mqtt.connect()

DEVICE = {
    "identifiers": [DEVICE_ID],
    "name":        DEVICE_NAME,
    "manufacturer": "rbAmp",
    "model":       "rbAmp UI*",
}

def publish_discovery_sensor(key, friendly, unit, dev_class, state_class):
    """Publish one HA discovery config (retained).

    :param key:         short id used in the topic and value_template.
    :param friendly:    HA friendly-name suffix.
    :param unit:        unit_of_measurement, or None.
    :param dev_class:   HA device_class string, or None.
    :param state_class: 'measurement' or 'total_increasing'.
    """
    cfg = {
        "name":            "{} {}".format(DEVICE_NAME, friendly),
        "unique_id":       "{}_{}".format(DEVICE_ID, key),
        "state_topic":     "rbamp/{}/state".format(DEVICE_ID),
        "value_template":  "{{{{ value_json.{} }}}}".format(key),
        "state_class":     state_class,
        "device":          DEVICE,
    }
    if unit:      cfg["unit_of_measurement"] = unit
    if dev_class: cfg["device_class"] = dev_class
    topic = "homeassistant/sensor/{}/{}/config".format(DEVICE_ID, key).encode()
    mqtt.publish(topic, json.dumps(cfg).encode(), retain=True)

def publish_discovery_all():
    """Publish the full set of HA discovery configs for one rbAmp module."""
    publish_discovery_sensor("voltage",        "Voltage",        "V",   "voltage",        "measurement")
    publish_discovery_sensor("current",        "Current",        "A",   "current",        "measurement")
    publish_discovery_sensor("power",          "Power",          "W",   "power",          "measurement")
    publish_discovery_sensor("energy",         "Energy",         "Wh",  "energy",         "total_increasing")
    publish_discovery_sensor("frequency",      "Frequency",      "Hz",  "frequency",      "measurement")
    publish_discovery_sensor("power_factor",   "Power Factor",   None,  "power_factor",   "measurement")
    publish_discovery_sensor("apparent_power", "Apparent Power", "VA",  "apparent_power", "measurement")
    publish_discovery_sensor("reactive_power", "Reactive Power", "var", "reactive_power", "measurement")

publish_discovery_all()

rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)            # primer snapshot
t_prev_ms = time.ticks_ms()
total_wh = 0.0

while True:
    time.sleep(60)

    # Snapshot + read period snapshot.
    rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
    t_now_ms = time.ticks_ms()
    time.sleep_ms(50)
    if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
        t_prev_ms = time.ticks_ms()
        continue
    avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
    dt_s  = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
    total_wh += avg_p * dt_s / 3600.0
    t_prev_ms = t_now_ms

    # Live RT values.
    u  = rb_read_float_le(i2c, RB_ADDR, 0x86)
    i_ = rb_read_float_le(i2c, RB_ADDR, 0x8E)
    pf = rb_read_float_le(i2c, RB_ADDR, 0xB2)
    q  = rb_read_float_le(i2c, RB_ADDR, 0xD0)
    freq = rb_read_u8(i2c, RB_ADDR, 0x20)

    payload = json.dumps({
        "voltage":        u,
        "current":        i_,
        "power":          avg_p,
        "energy":         total_wh,
        "frequency":      freq,
        "power_factor":   pf,
        "apparent_power": u * i_,
        "reactive_power": q,
    })
    mqtt.publish("rbamp/{}/state".format(DEVICE_ID).encode(), payload.encode())
    print("Published:", payload)
Diferencias de CircuitPython

: use adafruit_minimqtt.MQTT con un socket pool de wifi.radio. Los payloads de descubrimiento se construyen igual. Consulte la guía de MQTT + descubrimiento de HA de Adafruit para el código base del socket.


Ejemplo 9: registrador remoto alimentado por batería con sueño profundo

Objetivo: un registrador exterior / autónomo que se despierta cada 10 minutos, toma una instantánea de un periodo, publica por MQTT y vuelve al sueño profundo. Consumo medio de unos mA: una celda de Li-ion dura meses. Hardware: ESP32 (o ESP32-S3) + un rbAmp UI1 + Li-ion pequeña + Wi-Fi. Contabilidad: unidireccional. La energía sobrevive al sueño profundo mediante la memoria RTC.

Python
from machine import I2C, Pin, RTC, deepsleep
import network, time, struct, ujson as json
from umqtt.simple import MQTTClient

SLEEP_MS = 10 * 60 * 1000                        # 10-minute wake interval
RB_ADDR  = 0x50

# RTC retained memory layout (with a magic-marker sentinel so garbage RTC RAM
# after a brown-out or watchdog reset is NOT mistaken for valid state):
#   uint32  magic == 0xCAFEFEED     (4 bytes)
#   double  total_wh                (8 bytes)
#   uint32  wake_count              (4 bytes)
#   uint8   primer_done             (1 byte) + 3 bytes pad
#
# NOTE on dt: we do NOT persist a microsecond counter because time.ticks_us()
# is monotonic SINCE BOOT — it resets to 0 on every deep-sleep wake, so
# carrying the previous value across sleep is meaningless. dt is approximated
# by the configured SLEEP_MS interval; for tighter accuracy use machine.RTC()
# .datetime() which DOES survive deep sleep.
_MAGIC = 0xCAFEFEED
_FMT   = " timeout_s * 1000:
            return None
        time.sleep_ms(100)
    return wlan

def publish_measurement(wake_count, dt_s, avg_p, total_e):
    """Publish one period sample via MQTT, retained."""
    mqtt = MQTTClient("rbamp-remote", "192.168.1.10")
    mqtt.connect()
    payload = json.dumps({
        "wake":      wake_count,
        "dt_s":      round(dt_s, 1),
        "avg_p":     round(avg_p, 1),
        "energy_wh": round(total_e, 3),
    })
    mqtt.publish(b"rbamp/remote/state", payload.encode(), retain=True)
    mqtt.disconnect()
    print("Published:", payload)

# ===== Main wake-handler — runs on every wake-up =====

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
total_wh, wake_count, primer_done = _rtc_load()
wake_count += 1

rb_wait_ready(i2c, RB_ADDR)

# First wake-up after a cold boot: primer snapshot only.
if not primer_done:
    rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
    _rtc_save(total_wh, wake_count, 1)
    print("Primer done — sleeping until first real period")
    deepsleep(SLEEP_MS)

# Subsequent wake-ups: close the period and read its average power.
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
time.sleep_ms(50)

if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
    print("WARN: stale snapshot — skipping this cycle")
    _rtc_save(total_wh, wake_count, 1)
    deepsleep(SLEEP_MS)

avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
# dt approximation: deep sleep + boot ≈ SLEEP_MS. time.ticks_us() resets
# every wake so a stored "previous" value would be meaningless; the
# configured interval is accurate to single-digit-% on the ESP32 RTC.
dt_s = SLEEP_MS / 1000.0
total_wh += avg_p * dt_s / 3600.0
_rtc_save(total_wh, wake_count, 1)

# Publish; fall back gracefully if WiFi is unreachable.
if wifi_connect(timeout_s=8):
    try:
        publish_measurement(wake_count, dt_s, avg_p, total_wh)
    except Exception as e:
        print("MQTT failed, value buffered in RTC:", e)
else:
    print("WiFi failed — value buffered in RTC, retry next wake")

print("Deep sleep")
deepsleep(SLEEP_MS)

Presupuesto de energía (típico, ESP32-WROOM):

  • Tiempo despierto por despertar: ~3 s.
  • Corriente en vigilia: ~80 mA de media → ~0.07 mAh por despertar.
  • Corriente en reposo: ~10 µA (dominios RTC retenidos).
  • Un despertar cada 10 min → unos 10 mAh/día → una sola batería Li-ion de 2000 mAh dura unos 6 meses.
Diferencias de CircuitPython

: use alarm.time.TimeAlarm(monotonic_time=...) + alarm.exit_and_deep_sleep_until_alarms(alarm) en lugar de machine.deepsleep. Guarde total_wh en alarm.sleep_memory (un bytearray sobrevive a la suspensión profunda). La NVM (microcontroller.nvm) sobrevive incluso a un corte de alimentación, pero tiene un desgaste limitado.


Ejemplo 10: tarifa por franjas horarias (TOU) con hora de pared por NTP

Objetivo: facturar la energía según un horario de tarifa por franjas horarias (tarifas distintas para horas punta y valle). El ESP32 mantiene una hora de pared real mediante NTP, asigna cada periodo cerrado al tramo tarifario correspondiente, reinicia los totales diarios a medianoche y publica las cargas útiles con marcas de tiempo ISO. Hardware: ESP32 + un rbAmp UI1 + WiFi. Contabilidad: unidireccional. La lógica de tramos funciona en STD: basta con pasar por ella los dos acumuladores.

Python
from machine import I2C, Pin
import network, ntptime, time, ujson as json
from umqtt.simple import MQTTClient

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50

WIFI_SSID  = "ssid"
WIFI_PASS  = "password"
MQTT_HOST  = "192.168.1.10"

# Local UTC offset in hours. For DST, recompute on roll-over or use a TZ library.
# Example: Central European Summer Time = UTC+2.
TZ_OFFSET_HOURS = 2

# Time-of-use schedule: peak hours [PEAK_START_HOUR .. PEAK_END_HOUR), local time.
PEAK_START_HOUR = 8
PEAK_END_HOUR   = 22

def wifi_connect():
    wlan = network.WLAN(network.STA_IF); wlan.active(True)
    wlan.connect(WIFI_SSID, WIFI_PASS)
    while not wlan.isconnected():
        time.sleep(0.5)
    print("WiFi up:", wlan.ifconfig()[0])

def ntp_sync():
    """Synchronise the on-board RTC with NTP (UTC).

    Returns True on success, False on persistent failure. DOES NOT raise —
    a TOU meter that crashes when NTP is unreachable is worse than one that
    skips bucketing for the current period and retries later.
    """
    ntptime.host = "pool.ntp.org"
    for _ in range(5):
        try:
            ntptime.settime()
            t = time.gmtime()
            print("NTP sync: {:04d}-{:02d}-{:02d} {:02d}:{:02d}:{:02d} UTC".format(*t[:6]))
            return True
        except Exception as e:
            print("NTP retry:", e)
            time.sleep(2)
    print("WARN: NTP sync failed — tariff bucketing paused until next sync")
    return False

def local_time():
    """Return current local time as a 9-tuple struct_time (year, mon, ..., wday, yday)."""
    return time.gmtime(time.time() + TZ_OFFSET_HOURS * 3600)

def is_peak_hour(hour):
    """True if `hour` (0..23 local) is inside the peak tariff window.

    For schedules that cross midnight (peak 22..6), change to
        return hour >= PEAK_START_HOUR or hour < PEAK_END_HOUR
    """
    return PEAK_START_HOUR <= hour < PEAK_END_HOUR

def iso_now():
    """Return the current local time as an ISO 8601 string with offset."""
    t = local_time()
    sign = "+" if TZ_OFFSET_HOURS >= 0 else "-"
    return "{:04d}-{:02d}-{:02d}T{:02d}:{:02d}:{:02d}{}{:02d}00".format(
        t[0], t[1], t[2], t[3], t[4], t[5], sign, abs(TZ_OFFSET_HOURS))

wifi_connect()
ntp_sync()

mqtt = MQTTClient("rbamp-tou", MQTT_HOST); mqtt.connect()

rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)            # primer snapshot
t_prev_ms = time.ticks_ms()
print("TOU started: peak {:02d}:00..{:02d}:00 local".format(PEAK_START_HOUR, PEAK_END_HOUR))

# Tariff buckets.
today = {"peak_wh": 0.0, "off_peak_wh": 0.0, "yday": -1}
lifetime = {"peak_wh": 0.0, "off_peak_wh": 0.0}

def accumulate(e_wh, tm):
    """Add one period's energy to the right bucket; roll over the day at midnight.

    :param e_wh: Wh in this period.
    :param tm:   local struct_time at the snapshot instant.
    """
    yday = tm[7]                                  # struct_time.tm_yday is index 7
    if today["yday"] != yday:
        if today["yday"] >= 0:
            payload = json.dumps({
                "yday":        today["yday"],
                "peak_wh":     today["peak_wh"],
                "off_peak_wh": today["off_peak_wh"],
                "total_wh":    today["peak_wh"] + today["off_peak_wh"],
            })
            mqtt.publish(b"rbamp/tou/day_close", payload.encode(), retain=True)
            print("Day closed:", payload)
        today["peak_wh"] = 0.0
        today["off_peak_wh"] = 0.0
        today["yday"] = yday

    hour = tm[3]                                  # struct_time.tm_hour is index 3
    if is_peak_hour(hour):
        today["peak_wh"]    += e_wh
        lifetime["peak_wh"] += e_wh
    else:
        today["off_peak_wh"]    += e_wh
        lifetime["off_peak_wh"] += e_wh

while True:
    time.sleep(60)

    rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
    t_now_ms = time.ticks_ms()
    time.sleep_ms(50)
    if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
        t_prev_ms = time.ticks_ms()
        continue
    avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
    dt_s  = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
    e_wh  = avg_p * dt_s / 3600.0
    t_prev_ms = t_now_ms

    tm = local_time()
    accumulate(e_wh, tm)
    peak = is_peak_hour(tm[3])

    payload = json.dumps({
        "ts":                iso_now(),
        "tariff":            "peak" if peak else "off_peak",
        "avg_p":             round(avg_p, 1),
        "period_wh":         round(e_wh, 4),
        "today_peak_wh":     round(today["peak_wh"], 3),
        "today_off_peak_wh": round(today["off_peak_wh"], 3),
        "life_peak_wh":      round(lifetime["peak_wh"], 3),
        "life_off_peak_wh":  round(lifetime["off_peak_wh"], 3),
    })
    mqtt.publish(b"rbamp/tou/state", payload.encode())
    print(payload)

Notes:

  • El módulo time de MicroPython usa UTC en la mayoría de los puertos; conviértalo con time.gmtime(time.time() + offset_seconds). Para un manejo completo del horario de verano, una pequeña tabla TZ o la biblioteca utimezone pueden sustituir a TZ_OFFSET_HOURS.
  • Error de frontera: un periodo de 60 s que cruza las 22:00 se atribuye por completo a fuera de punta (la marca de tiempo corresponde al instante de la instantánea). Como máximo ~30 s de atribución errónea al día: despreciable para la contabilidad tarifaria residencial.
  • Para la medición bidireccional STD, llame a accumulate() dos veces, una para el lado del consumo y otra para el lado de la exportación, y publique ambos conjuntos de totales de punta y fuera de punta.
Diferencias de CircuitPython

: use adafruit_ntp.NTP(socketpool, server="pool.ntp.org", tz_offset=2) + rtc.RTC().datetime = ntp.datetime para fijar el reloj del sistema y leerlo después con time.localtime(). La lógica de tramos es idéntica.


Comparación de ejemplos

# Complejidad Salida MQTT DRDY Multimódulo Bidireccional Persistencia Caso de uso
1 mínimo REPL — — — — — prueba de humo
2 bajo OLED — — — — RAM medidor en caja
3 bajo REPL — — sí (3) — — monitorización doméstica
4 medio — sí — — — RAM por electrodoméstico en HA
5 medio REPL — sí — sí (maestro) RAM vivienda solar en nivel BASIC
6 alta — sí — sí (3) sí RAM balance energético de toda la casa
7 medio REPL + SD — sí — — Tarjeta SD detección de eventos
8 medio — sí (+disco) — — opcional RAM + MQTT Auto-descubrimiento de HA
9 medio — sí — — — Memoria RTC registrador exterior / autónomo
10 medio REPL sí — — opcional RAM + MQTT Tarifa punta/valle con NTP

Buenas prácticas

  • Compruebe siempre DATA_VALID (bit 0 del registro 0xCE) tras el arranque, y PERIOD_VALID (bit 0 de 0x07) tras cada CMD_LATCH_PERIOD.
  • Espere al menos 50 ms tras una instantánea antes de leerla.
  • El reloj maestro es la referencia para los Wh: no use PERIOD_LATCH_MS (0xEC) para calcular la energía.
  • Para configuraciones con varios módulos, rb_broadcast_latch(i2c, tick) mediante llamada general ofrece una sincronización precisa. La recepción GC es opcional por módulo (FLEET_CONFIG.bit0, por defecto desactivada). Si hay NACK, recurra a CMD_LATCH_PERIOD secuencial por módulo.
  • La persistencia en el maestro es obligatoria para la contabilidad a largo plazo: rbAmp no guarda los Wh internamente. Use la memoria RTC (ejemplo 9), la tarjeta SD (ejemplo 7) o las cargas MQTT retenidas (ejemplo 6).
  • Los manejadores de IRQ de MicroPython deben ser mínimos (activar un indicador, sin I²C). Haga todo el trabajo I²C en el bucle principal.
  • En CircuitPython, prefiera countio.Counter o keypad.Keys para los eventos de flanco en lugar de IRQ definidas por el usuario.

Lo siguiente

Tras repasar estos diez ejemplos:

  • Para el paquete de alto nivel rbamp, consulte la tabla de bibliotecas cliente del README.
  • Para la integración con ESPHome (YAML declarativo), consulte tools/esphome-rbamp/docs/en/.
  • Para un entorno SBC más completo (Raspberry Pi, CPython completo), consulte la tabla de bibliotecas cliente del README.
  • Driver Berry de Tasmota: aplazado (no se incluye biblioteca).
  • La especificación formal de registros I²C que se usa aquí está en api-reference.md.