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.
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, Pini2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000) |
import board, busioi2c = 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, countiobtn = 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 networkwlan = network.WLAN(network.STA_IF) |
import wifiwifi.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.
"""
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:
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.
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
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).
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))
: 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.
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.
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])
: 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.
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))
: 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.
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).
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
: 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.
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)
: 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.
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.
: 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.
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
timede MicroPython usa UTC en la mayoría de los puertos; conviértalo contime.gmtime(time.time() + offset_seconds). Para un manejo completo del horario de verano, una pequeña tabla TZ o la bibliotecautimezonepueden sustituir aTZ_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.
: 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 registro0xCE) tras el arranque, yPERIOD_VALID(bit 0 de0x07) tras cadaCMD_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 aCMD_LATCH_PERIODsecuencial 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.Counterokeypad.Keyspara 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.