12 · Exemplos MicroPython e CircuitPython
Este capítulo é o equivalente em Python de arduino-examples.md: os mesmos dez cenários, portados para MicroPython em ESP32 / RP2040 / ESP8266 / Pyboard, com as diferenças do CircuitPython onde os dois dialetos divergem.
Estes exemplos falam diretamente com o rbAmp através da API de registos I²C em bruto. Destinam-se a integrações nativas, embebidas ou de outro modo com recursos limitados, onde é necessário controlo direto e cada byte no barramento conta.
Para uma interface mais cómoda e estruturada — use a biblioteca MicroPython rbamp (veja a tabela de bibliotecas cliente no README). A biblioteca envolve os pormenores ao nível dos registos numa classe RbAmp de alto nível com métodos com nome (dev.voltage, dev.latch_period(), dev.read_period_snapshot(), etc.), APIs síncronas e uasyncio, um acumulador Wh automático por canal, auxiliares multi-módulo, e a disciplina de repetição + verificação de sanidade da SPEC §B.5 para portes ESP32 via MachineI2CBackend(retry_attempts=…). O mesmo pacote corre sem alterações em CPython — veja a tabela de bibliotecas cliente no README. A maioria dos projetos deve começar pela biblioteca e recorrer à API de baixo nível apenas quando necessário.
MicroPython vs CircuitPython — referência rápida
A linguagem Python é a mesma; os módulos de acesso ao dispositivo diferem. A tabela abaixo associa cada conceito usado nos exemplos ao módulo / classe equivalente em cada dialeto.
| Conceito | MicroPython | CircuitPython |
|---|---|---|
| Barramento 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) |
| Leitura de um 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) |
| Escrita de um 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)ou keypad.Keys([board.D15], ...) |
| Suspensão (seg / ms) | time.sleep(s) / time.sleep_ms(ms) |
time.sleep(s) (sem sleep_ms) |
| ms / µs monotónicos | time.ticks_ms(), time.ticks_us(), time.ticks_diff(a, b) |
time.monotonic_ns() / time.monotonic() (sem ticks_diff) |
| WiFi | import networkwlan = network.WLAN(network.STA_IF) |
import wifiwifi.radio.connect(ssid, pwd) (ESP32-S2/S3/C3 com 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="...") |
| Deep sleep | import machine; machine.deepsleep(ms) |
import alarm; alarm.exit_and_deep_sleep_until_alarms(time_alarm) |
| Memória retida RTC | machine.RTC().memory(buf) |
import alarm; alarm.sleep_memory[...] |
| Assíncrono | import uasyncio as asyncio |
import asyncio (CircuitPython 8+) |
Cada exemplo abaixo está escrito em MicroPython. Quando a equivalência em CircuitPython difere mais do que uma única linha de importação, é apresentado um bloco explícito "delta CircuitPython".
Índice dos exemplos
| # | Título | Dificuldade | Saída | MQTT | DRDY | Multi-módulo | Bidirecional | Caso de utilização |
|---|---|---|---|---|---|---|---|---|
| 1 | Leitura rápida | mínimo | REPL | — | — | — | — | Teste de funcionamento |
| 2 | Contador de energia de 60 segundos no OLED | baixo | SSD1306 | — | — | — | — | Contador Wh em caixa |
| 3 | Monitor multi-módulo | baixo | REPL | — | — | sim (3) | — | Monitorização de toda a casa |
| 4 | Medidor de energia por aparelho (UI3) | médio | — | sim | — | — | — | Sub-medição no HA |
| 5 | Bidirecional no mestre num módulo BASIC | médio | REPL | — | sim | — | sim (mestre) | Casa solar em nível BASIC |
| 6 | Balanço energético doméstico | alta | — | sim | — | sim (3) | sim | Balanço energético doméstico completo |
| 7 | Deteção de eventos de energia | médio | REPL + SD | — | sim | — | — | Registo de eventos de eletrodomésticos |
| 8 | Publicador MQTT com auto-discovery do HA | médio | — | sim (+disco) | — | — | opcional | Integração HA pronta a usar |
| 9 | Registador remoto com bateria e sono profundo | médio | — | sim | — | — | — | Medidor para exterior / fora da rede |
| 10 | Tarifa por horário (TOU) com relógio de parede NTP | médio | REPL | sim | — | — | opcional | Medição de tarifa de ponta / fora de ponta |
Cabeçalho comum a todos os exemplos
Todos os exemplos assumem que estes auxiliares estão presentes no mesmo ficheiro .py (ou importados de um helpers.py). Para poupar espaço, o bloco não é repetido em cada sketch.
"""
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 CircuitPython — cabeçalho comum
O CircuitPython usa adafruit_bus_device.i2c_device.I2CDevice (invólucro por escravo) e não tem 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")
Exemplo 1 — Leitura rápida (mínima)
Objetivo: mostrar U, I, P, PF numa REPL uma vez por segundo. Hardware: ESP32 / RP2040 / Pico W + um 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)
Diferença do 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)
Exemplo 2 — medidor de energia de 60 segundos no OLED
Objetivo: contador de Wh atualizado uma vez por minuto, mostrado num SSD1306 de 128×64. Hardware: ESP32 + rbAmp + OLED SSD1306 no mesmo barramento. Contabilização: unidirecional (nível BASIC). Biblioteca: ssd1306.py dos exemplos MicroPython (um driver padrão de um só ficheiro).
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 ou variante framebuf). O construtor do OLED difere, mas o resto do ciclo mantém-se — substitua as chamadas rb_* pelos auxiliares cp_* e use time.monotonic() para dt_s.
Exemplo 3 — Monitor multi-módulo
Objetivo: consultar três módulos (alimentação principal, esquentador, AC) e imprimir o total. Hardware: ESP32 + 3 × rbAmp UI1 em 0x50, 0x51, 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)
Exemplo 4 — medidor de energia por aparelho (UI3)
Objetivo: um módulo UI3 com três pinças de corrente (CT) em três cargas diferentes na mesma fase. Contadores Wh independentes por carga, publicados via MQTT a cada minuto. Hardware: ESP32 + 1 × rbAmp UI3. Biblioteca: umqtt.simple (MicroPython) ou umqtt.robust para reconexão 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])
: substitua umqtt.simple.MQTTClient por adafruit_minimqtt.MQTT(...) (requer um socket_pool e um ssl_context — veja o guia Wi-Fi da Adafruit). A lógica de medição mantém-se.
Exemplo 5 — bidirecional no mestre num módulo BASIC
Objetivo: implementar contabilização bidirecional no mestre enquanto o firmware do módulo é BASIC (o acumulador de período limita a zero as amostras negativas). Ler o P_real RT em cada flanco DRDY e separar consumo / exportação. Hardware: ESP32 + rbAmp UI1 numa carga com um inversor solar + DRDY ligado a um 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))
: o CircuitPython desaconselha, em geral, IRQs de GPIO definidas pelo utilizador. Use countio.Counter(board.D15, edge=countio.Edge.FALL) e consulte o seu count a partir do ciclo principal, ou keypad.Keys(...) para eventos de flanco. A lógica do acumulador é idêntica.
Exemplo 6 — balanço energético doméstico
Objetivo: um painel completo de balanço energético. Três módulos:
- rbAmp #1 na alimentação principal (STD — bidirecional)
- rbAmp #2 na saída do inversor solar
- rbAmp #3 UI3 em três grandes cargas (bomba de calor HP, AC, VE)
O mestre calcula total_consumed = solar_self_used + grid_consumed e 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)garante que os três módulos fazem o instantâneo no mesmo instante — essencial para um saldo preciso. A receção GC é opcional (FLEET_CONFIG.bit0, por defeito DESLIGADO, veja o capítulo 02). Em caso de NACK, recorra a um instantâneo sequencial por módulo (desvio de ~1 ms por módulo a 50 kHz).solar_self_used = solar_total − grid_exported; limite a zero para absorver o ruído de medição.
Exemplo 7 — deteção de eventos de energia
Objetivo: em cada flanco de DRDY, comparar a potência ativa instantânea P com uma EMA e registar os desvios significativos num cartão SD. Hardware: ESP32 + rbAmp + cartão SD (por SPI, p. ex. através do driver MicroPython sdcard.py). Caso de utilização: deteção automática de eventos de cargas grandes (micro-ondas, ar condicionado, chaleira).
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"). Substitua a IRQ por countio.Counter(board.D15, edge=countio.Edge.FALL) consultado a partir do ciclo principal.
Exemplo 8 — Publicador MQTT com descoberta automática do Home Assistant [Auto-discovery]
Objetivo: uma integração HA imediata. O ESP32 liga-se à rede WiFi e a um broker MQTT, publica as configurações de Auto-discovery do HA (para que as entidades apareçam sem YAML) e emite um estado JSON a cada minuto. Hardware: ESP32 + um rbAmp UI1 + rede WiFi com um broker MQTT. Contabilização: unidirecional.
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 com um pool de sockets de wifi.radio. As cargas de discovery são construídas da mesma forma. Veja o guia da Adafruit sobre MQTT + discovery do HA para o código repetitivo dos sockets.
Exemplo 9 — Registador remoto com bateria e sono profundo
Objetivo: um registador para exterior / fora da rede que acorda a cada 10 minutos, captura um período, publica via MQTT e volta ao sono profundo. Corrente média de alguns mA — uma célula de iões de lítio dura meses. Hardware: ESP32 (ou ESP32-S3) + um rbAmp UI1 + uma pequena bateria de iões de lítio + Wi-Fi. Contabilização: unidirecional. A energia sobrevive ao sono profundo através da memória 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)
Orçamento de energia (típico, ESP32-WROOM):
- Tempo de atividade por despertar: ~3 s.
- Corrente de despertar: ~80 mA em média → ~0.07 mAh por despertar.
- Corrente em sono: ~10 µA (domínios retidos RTC).
- Um despertar a cada 10 min → ~10 mAh por dia → uma única bateria Li-ion de 2000 mAh dura ~6 meses.
: use alarm.time.TimeAlarm(monotonic_time=...) + alarm.exit_and_deep_sleep_until_alarms(alarm) em vez de machine.deepsleep. Persista o total_wh em alarm.sleep_memory (um bytearray sobrevive ao deep sleep). A NVM (microcontroller.nvm) sobrevive mesmo a uma perda de energia, mas tem desgaste limitado.
Exemplo 10 — tarifa por horário (TOU) com relógio de parede NTP
Objetivo: faturar a energia segundo um horário de tarifa por período (tarifas diferentes para as horas de ponta e de fora de ponta). O ESP32 mantém um relógio de parede real através de NTP, atribui cada período fechado ao escalão tarifário correto, repõe os totais diários à meia-noite e publica as mensagens com carimbos ISO. Hardware: ESP32 + um rbAmp UI1 + WiFi. Contabilização: unidirecional. A lógica dos escalões funciona no STD — basta fazer passar por ela os dois 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:
- O módulo
timedo MicroPython é baseado em UTC na maioria das portas — converta comtime.gmtime(time.time() + offset_seconds). Para o tratamento completo do horário de verão, uma pequena tabela TZ ou a bibliotecautimezonepodem substituir oTZ_OFFSET_HOURS. - Erro de fronteira: um período de 60 s que atravessa as 22:00 é atribuído inteiramente a fora de pico (carimbo temporal no instante da captura). No máximo ~30 s de atribuição errada por dia — desprezável para a contabilização tarifária residencial.
- Para medição bidirecional STD, chame
accumulate()duas vezes — uma do lado do consumo e outra do lado da exportação — e publique ambos os conjuntos de totais de pico / fora de pico.
: use adafruit_ntp.NTP(socketpool, server="pool.ntp.org", tz_offset=2) + rtc.RTC().datetime = ntp.datetime para definir o relógio do sistema e depois lê-lo com time.localtime(). A lógica dos escalões é idêntica.
Comparação de exemplos
| # | Complexidade | Saída | MQTT | DRDY | Multi-módulo | Bidirecional | Persistência | Caso de utilização |
|---|---|---|---|---|---|---|---|---|
| 1 | mínimo | REPL | — | — | — | — | — | teste de funcionamento |
| 2 | baixo | OLED | — | — | — | — | RAM | contador em caixa |
| 3 | baixo | REPL | — | — | sim (3) | — | — | monitorização doméstica |
| 4 | médio | — | sim | — | — | — | RAM | por eletrodoméstico no HA |
| 5 | médio | REPL | — | sim | — | sim (mestre) | RAM | casa solar em nível BASIC |
| 6 | alta | — | sim | — | sim (3) | sim | RAM | balanço energético doméstico completo |
| 7 | médio | REPL + SD | — | sim | — | — | Cartão SD | deteção de eventos |
| 8 | médio | — | sim (+disco) | — | — | opcional | RAM + MQTT | Auto-discovery do HA |
| 9 | médio | — | sim | — | — | — | Memória RTC | registador para exterior / fora da rede |
| 10 | médio | REPL | sim | — | — | opcional | RAM + MQTT | Ponta/fora de ponta com NTP |
Boas práticas
- Verifique sempre
DATA_VALID(bit 0 do registo0xCE) após o arranque ePERIOD_VALID(bit 0 de0x07) após cadaCMD_LATCH_PERIOD. - Aguarde pelo menos 50 ms após uma captura antes de a ler.
- O relógio mestre é a referência para os Wh — não use
PERIOD_LATCH_MS(0xEC) para calcular a energia. - Para configurações com vários módulos,
rb_broadcast_latch(i2c, tick)via chamada geral garante uma sincronização precisa. A receção de chamada geral é opt-in por módulo (FLEET_CONFIG.bit0, por defeito DESLIGADO). Em caso de NACK, recue para oCMD_LATCH_PERIODsequencial por módulo. - A persistência no mestre é obrigatória para a contabilização a longo prazo — o rbAmp não guarda os Wh internamente. Use a memória RTC (Exemplo 9), o cartão SD (Exemplo 7) ou as mensagens MQTT retidas (Exemplo 6).
- Os manipuladores de IRQ do MicroPython têm de ser mínimos (definir um sinalizador, sem I²C). Faça todo o trabalho I²C no ciclo principal.
- Em CircuitPython, prefira
countio.Counteroukeypad.Keyspara eventos de flanco em vez de IRQs definidas pelo utilizador.
O que se segue
Depois de percorrer estes dez exemplos:
- Para o pacote de alto nível
rbamp, veja a tabela de bibliotecas cliente no README. - Para a integração ESPHome (YAML declarativo), veja
tools/esphome-rbamp/docs/en/. - Para um ambiente SBC mais rico (Raspberry Pi, CPython completo), veja a tabela de bibliotecas cliente no README.
- Driver Tasmota Berry — adiado (nenhuma biblioteca fornecida).
- A especificação formal dos registos I²C usada aqui está em api-reference.md.