rbAmp
PT
Loja
Docs
Atualizado

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.

Nota

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, Pin
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
import board, busio
i2c = 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, countio
btn = 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 network
wlan = network.WLAN(network.STA_IF)
import wifi
wifi.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.

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

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

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.

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)

Diferença do 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)

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

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))
Diferença do CircuitPython

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

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)

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.

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])
Diferença do CircuitPython

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

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))
Diferença do CircuitPython

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

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

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
Diferença do CircuitPython

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

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)
Diferença do CircuitPython

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

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)

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.
Diferença do CircuitPython

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

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:

  • O módulo time do MicroPython é baseado em UTC na maioria das portas — converta com time.gmtime(time.time() + offset_seconds). Para o tratamento completo do horário de verão, uma pequena tabela TZ ou a biblioteca utimezone podem substituir o TZ_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.
Diferença do CircuitPython

: 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 registo 0xCE) após o arranque e PERIOD_VALID (bit 0 de 0x07) após cada CMD_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 o CMD_LATCH_PERIOD sequencial 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.Counter ou keypad.Keys para 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.