rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub [Edit on GitHub]

Exemplos

Este capítulo percorre 11 cenários (10 na tabela abaixo mais o Cenário 11) — desde um "olá mundo" mínimo até uma implementação de produção. A maioria dos cenários tem implementações paralelas em MicroPython (em examples_upy/) e em CPython (em examples_cpython/). O código abaixo é uma destilação da lógica-chave, não um script completo; as versões completas estão nos ficheiros de exemplo correspondentes.

# Cenário MicroPython CPython
1 Leitura rápida 01_quick_read.py 01_quick_read.py
2 Contador por período + visor local 02_oled_period.py 02_period_meter.py
3 Monitorizar 3 módulos num barramento 03_multi_module.py 03_multi_module_broadcast.py
4 UI3 + MQTT por canal 04_mqtt.py 04_mqtt_publisher.py
5 Medição bidirecional do lado do mestre 07_bidirectional_energy.py 05_bidirectional_energy.py
6 Balanço energético da casa inteira (multi-módulo + MQTT) 08_home_energy_balance.py 07_home_energy_balance.py
7 Registo de deteção de eventos (EMA) 09_event_detection_logger.py sem ficheiro
8 Registador local rotativo sem ficheiro 08_rotating_file_logger.py
9 Registador de deep-sleep alimentado a bateria 06_deep_sleep.py (não aplicável)
10 Streaming assíncrono via stream_period 05_async_streaming.py sem ficheiro (código no Cenário 10)
Nota

Todos os cenários assumem que a classe do sensor e o modelo TC já estão configurados via dev.set_sensor_class() + dev.set_ct_model() (ver 05 · Início rápido, Passo 4). Isto faz-se uma vez na instalação — as definições ficam guardadas na flash do módulo e sobrevivem a um reinício.


Cenário 1 — Leitura rápida

Objetivo: imprimir U / I / P / PF / frequência uma vez por segundo. É o mesmo "olá mundo" que escreveu em 05 · Início rápido, mas usando dev.read_all() — uma leitura única de todo o bloco RT para uma só estrutura RbAmpSnapshot.

Versão do CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        line = f"U={s.voltage:.1f} V  f={s.frequency} Hz   "
        for ch in range(s.channels):
            line += f"I{ch}={s.current[ch]:.2f}A  P{ch}={s.power[ch]:.1f}W  "
        print(line)
        time.sleep(1)

Versão do MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        print("U={:.1f} V  f={} Hz".format(s.voltage, s.frequency))
        for ch in range(s.channels):
            print("  I{}={:.2f}A  P{}={:.1f}W".format(
                ch, s.current[ch], ch, s.power[ch]))
        time.sleep(1)

O que acontece no barramento: dev.read_all() num UI3 faz cerca de 53 transações de bytes (13 valores float × 4 bytes + 1 byte de frequência). A 50 kHz com margem para retries, isto anda na ordem dos 25–30 ms. Se não precisar de todos os valores, use os acessores por propriedade (dev.voltage, dev.read_current(ch)).


Cenário 2 — Contador por período + visor local

Objetivo: um contador Wh, atualizado uma vez por minuto, num visor local. Em MicroPython — um OLED SSD1306 no mesmo barramento I²C. Em CPython — saída de texto para stdout (pode ligar um LCD de caracteres via GPIO ou usar uma página web — ver Cenário 6).

Versão MicroPython (OLED SSD1306)

Python
import time
from machine import I2C, Pin
from ssd1306 import SSD1306_I2C
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
oled = SSD1306_I2C(128, 64, i2c)   # OLED on the same bus, addr 0x3C

with RbAmp(i2c, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            continue

        oled.fill(0)
        oled.text("rbAmp Energy Meter", 0, 0)
        oled.text("{:.1f} W".format(snap.avg_p[0]), 0, 16, 1)
        oled.text("Wh: {:.4f}".format(dev.energy.wh(0)), 0, 32)
        oled.text("ok={} bad={}".format(snapshots_ok, snapshots_bad), 0, 48)
        oled.show()

Versão do CPython (medidor de período, sem ecrã)

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpStaleError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            print("stale snapshot — skipping")
            continue

        print(f"P = {snap.avg_p[0]:.2f} W   "
              f"Wh = {dev.energy.wh(0):.4f}   "
              f"ok={snapshots_ok} bad={snapshots_bad}   "
              f"dt={snap.master_dt_ms} ms")

Tratamento de snapshots obsoletos. dev.read_period_snapshot() levanta RbAmpStaleError se o módulo não tiver conseguido preparar um snapshot novo até à leitura. O pacote mantém o timestamp anterior, para que o snapshot bem-sucedido seguinte cubra o intervalo completo e os Wh se mantenham exatos. Um padrão standard de try/except em Python.


Cenário 3 — Monitorizar 3 módulos num barramento

Objetivo: consultar 3 módulos nos endereços 0x50 / 0x51 / 0x52, com snapshot coerente para que as suas potências por canal somem no mesmo período da rede.

Snapshot coerente

um frame de General-Call (A5 27 ) faz com que cada módulo tire o seu snapshot, que tenha aderido com fleet.enable_gc_all() — desvio da frota < 10 µs, pelo que os totais se somam. fleet.gc_latch() envia o frame e devolve o tick de difusão; fleet.check_sync() lê de volta o tick testemunhado de cada módulo, para assinalar um que tenha falhado o frame. (Em firmware v1.0/v1.1 o General-Call não estava disponível e este cenário recorria a snapshots sequenciais por dispositivo.) Veja 09 · Referência da API para RbAmpFleet.

Versão do CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpFleet, RbAmpError, RbAmpStaleError

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    for addr in ADDRS:
        try:
            dev = RbAmp(bus, addr); dev.begin()
        except RbAmpError as exc:
            print(f"skip 0x{addr:02X}: {exc}"); continue
        fleet.add(dev)

    # one-time: persist the General-Call snapshot opt-in on every module
    fleet.enable_gc_all(group=GC_GROUP)

    while True:
        time.sleep(60)

        tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame snapshots the bus
        time.sleep(0.050)                         # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        for dev, s in zip(fleet, sync):
            if not s.in_sync:                     # this module missed the frame
                print(f"  0x{s.addr:02X}  MISSED tick 0x{tick:04X}")
                continue
            try:
                snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
            except RbAmpStaleError:
                continue
            print(f"  0x{dev.address:02X}  P={snap.avg_p[0]:.0f} W  "
                  f"Wh={dev.energy.wh(0):.3f}")
        print(f"  fleet ΣWh={fleet.total_energy_wh():.3f}  "
              f"in_sync={sum(s.in_sync for s in sync)}/{len(sync)}")

Versão do MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpFleet, RbAmpError, RbAmpStaleError

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)

fleet = RbAmpFleet(i2c)
for addr in ADDRS:
    try:
        dev = RbAmp(i2c, addr); dev.begin()
    except RbAmpError as exc:
        print("skip 0x{:02X}:".format(addr), exc); continue
    fleet.add(dev)

fleet.enable_gc_all(group=GC_GROUP)           # one-time, persisted

while True:
    time.sleep(60)

    tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame
    time.sleep_ms(50)                         # single shared settle
    sync = fleet.check_sync(expected_tick=tick)

    for dev, s in zip(fleet, sync):
        if not s.in_sync:
            print("  0x{:02X}  MISSED tick".format(s.addr))
            continue
        try:
            snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue
        print("  0x{:02X}  P={:.0f} W  Wh={:.3f}".format(
            dev.address, snap.avg_p[0], dev.energy.wh(0)))

Cenário 4 — UI3 + MQTT por canal

Objetivo: um módulo UI3 com 3 pinças CT em três linhas independentes. Contadores de Wh por canal, publicados em MQTT uma vez por minuto. Mostra que dev.energy.wh(ch) funciona em cada canal de forma independente — sem necessidade de um array manual total_wh[3] do lado do mestre.

CPython (via paho-mqtt; instalar com pip install paho-mqtt)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = ["main", "heatpump", "lights"]

mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "rbamp-ui3")
mqtt.connect("192.168.1.10", 1883, keepalive=60)
mqtt.loop_start()

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = json.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            mqtt.publish(f"rbamp/{CH_NAMES[ch]}/state",
                         payload, qos=1, retain=True)

MicroPython (via umqtt.simple)

Python
import time, ujson
from machine import I2C, Pin
from umqtt.simple import MQTTClient
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = [b"main", b"heatpump", b"lights"]

mqtt = MQTTClient(b"rbamp-ui3", b"192.168.1.10",
                  port=1883, keepalive=60)
mqtt.connect()

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = ujson.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            topic = b"rbamp/" + CH_NAMES[ch] + b"/state"
            mqtt.publish(topic, payload.encode(), qos=1, retain=True)
Nota

Em MicroPython, umqtt.simple é um cliente síncrono e bloqueante. Para uma variante assíncrona, use mqtt_as (um cliente MQTT asyncio) — ver também o Cenário 10.

Para o auto-discovery completo do HA sobre este padrão, ver 07 · Integrações DIY.


Cenário 5 — Medição bidirecional do lado do mestre

Objetivo: separar a potência instantânea com sinal em consumo bruto e exportação bruta. Use este padrão na linha de módulos BASIC, onde o firmware corta os valores negativos em snap.avg_p[ch] (potência média do período) — amostre dev.read_power(0) (potência instantânea, com sinal em todas as linhas de módulos) a 10 Hz do lado do mestre e agrupe os valores você mesmo.

Versão do CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.monotonic()
    last_print = t_prev

    while True:
        time.sleep(0.1)   # 10 Hz, matches the RT cadence

        t_now = time.monotonic()
        dt_s  = t_now - t_prev
        t_prev = t_now

        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        dwh = p * dt_s / 3600.0
        if p >= 0:
            consume_wh += dwh
        else:
            export_wh  += -dwh

        # Print once per second
        if t_now - last_print >= 1.0:
            last_print = t_now
            print(f"P={p:.1f} W   "
                  f"cons={consume_wh:.4f} Wh  exp={export_wh:.4f} Wh  "
                  f"net={consume_wh - export_wh:.4f} Wh")

Versão do MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpIOError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.ticks_ms()

    while True:
        time.sleep_ms(100)

        t_now = time.ticks_ms()
        dt_s  = time.ticks_diff(t_now, t_prev) / 1000
        t_prev = t_now

        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        dwh = p * dt_s / 3600.0
        if p >= 0:
            consume_wh += dwh
        else:
            export_wh  += -dwh

Num módulo STANDARD (STD) as chamadas de período funcionam sem alterações e a energia é líquida (a exportação subtrai); os contadores de importação e exportação do próprio módulo estão em read_std_energy() (Cenário 11). Esta divisão do lado do mestre só é necessária em módulos BASIC, para relatórios separados de consumo bruto / exportação bruta.


Cenário 6 — Balanço energético da casa inteira

Objetivo: 3 módulos — rede (bidirecional), solar (apenas geração), cargas (UI3 por aparelho). Um painel combinado é publicado uma vez por minuto.

(Requer pip install paho-mqtt.)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import (RbAmp, RbAmpFleet, RbAmpError,
                   RbAmpStaleError, RbAmpSensorClass)

GC_GROUP = 0

with SMBus(1) as bus:
    mains = RbAmp(bus, 0x50)   # bidirectional mains
    solar = RbAmp(bus, 0x51)   # generation only
    loads = RbAmp(bus, 0x52)   # UI3 — per-appliance
    devs = [mains, solar, loads]
    for d in devs:
        d.begin()

    fleet = RbAmpFleet(bus)
    for d in devs:
        fleet.add(d)
    fleet.enable_gc_all(group=GC_GROUP)   # one-time, persisted

    mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "home-balance")
    mqtt.connect("192.168.1.10", 1883, keepalive=60)
    mqtt.loop_start()

    while True:
        time.sleep(60)

        # One coherent all-call snapshot for the whole bus (see Scenario 3)
        tick = fleet.gc_latch(group=GC_GROUP)
        time.sleep(0.050)                     # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        try:
            sm = mains.read_period_snapshot(settle_ms=0, skip_latch=True)
            ss = solar.read_period_snapshot(settle_ms=0, skip_latch=True)
            sl = loads.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue

        payload = {
            "mains":  round(mains.energy.wh(0), 3),
            "solar":  round(solar.energy.wh(0), 3),
            "hp":     round(loads.energy.wh(0), 3),
            "ac":     round(loads.energy.wh(1), 3),
            "ev":     round(loads.energy.wh(2), 3),
        }
        mqtt.publish("home/energy/balance",
                     json.dumps(payload), qos=1, retain=True)

        # let a dashboard alarm on a partial fleet (a module that missed the frame)
        in_sync = sum(s.in_sync for s in sync)
        mqtt.publish("home/energy/sync/in_sync",
                     f"{in_sync}/{len(sync)}", qos=1, retain=True)

Nos módulos BASIC a exportação não é contabilizada por energy.wh(), pelo que os valores de solar e mains acima são apenas consumo. Para uma separação explícita de consumo bruto / exportação bruta na rede, combine isto com o padrão do Cenário 5 (um ciclo separado a 10 Hz sobre mains.read_power(0) numa threading.Thread em segundo plano no CPython, ou uasyncio.create_task no MicroPython).


Cenário 7 — Registo de deteção de eventos (EMA)

Objetivo: a cada janela RT de 100 ms, comparar a potência instantânea com uma média móvel exponencial. Registar desvios significativos — cargas como um micro-ondas, uma chaleira ou um secador "aparecem" no registo como eventos de ligar / desligar.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

EMA_ALPHA = 0.05
EVENT_THRESHOLD_W = 200.0

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    try:
        p_ema = dev.read_power(0)   # seed so the first read isn't an event
    except RbAmpIOError:
        p_ema = 0.0

    while True:
        time.sleep(0.1)
        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        delta = p - p_ema
        p_ema = (1 - EMA_ALPHA) * p_ema + EMA_ALPHA * p

        if abs(delta) > EVENT_THRESHOLD_W:
            action = "TURN_ON" if delta > 0 else "TURN_OFF"
            print(f"{time.time():.0f}  {action}  delta={delta:.0f} W  "
                  f"P={p:.0f} W  EMA={p_ema:.0f}")

Em MicroPython, aplique as mesmas substituições: time.sleep → time.sleep_ms, e time.time() → time.time() (disponível na maioria das portas) ou time.ticks_ms().

Combine isto com a publicação MQTT do Cenário 4 para automatizações do lado do HA.


Cenário 8 — Registador local rotativo (CPython)

Objetivo: escrever um snapshot de período num ficheiro CSV rotativo uma vez por minuto, através do logging.handlers.RotatingFileHandler standard. Útil para implementações autónomas sem WiFi / MQTT, ou como buffer para sincronização diferida na nuvem.

Python
import time, logging
from logging.handlers import RotatingFileHandler
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpStaleError

log = logging.getLogger("rbamp.csv")
log.setLevel(logging.INFO)
handler = RotatingFileHandler("rbamp.csv", maxBytes=1_000_000, backupCount=5)
handler.setFormatter(logging.Formatter("%(asctime)s,%(message)s",
                                       datefmt="%Y-%m-%dT%H:%M:%S"))
log.addHandler(handler)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            log.warning("stale")
            continue
        log.info(f"{snap.avg_p[0]:.1f},{dev.energy.wh(0):.4f},"
                 f"{snap.master_dt_ms}")

Em MicroPython o módulo padrão logging.handlers não está disponível — para um registo local, use um simples with open("log.csv", "a") mais rotação manual via os.stat() + os.rename(). Veja o exemplo completo em examples_upy/09_event_detection_logger.py.

Para sincronização na nuvem diferida (registar localmente, enviar uma vez por hora), veja a secção "Híbrido: armazenamento local + sincronização" em 08 · Integrações na nuvem.


Cenário 9 — Registador de deep-sleep alimentado por bateria (apenas MicroPython)

Objetivo: um ESP32 (MicroPython) acorda uma vez a cada 10 minutos, tira um único snapshot de período, publica por Wi-Fi+MQTT e volta ao deep sleep. A energia é preservada entre ciclos de sono através da memória RTC.

Segurança

⚠ Nota importante sobre deep-sleep e firmware v1.0/v1.1. No firmware atual, dev.begin() emite um primer CMD_LATCH_PERIOD que repõe o acumulador de período do firmware. Isto significa que, após acordar do deep-sleep, não pode simplesmente chamar read_period_snapshot() por predefinição — essa chamada tiraria outro snapshot e devolveria dados quase nulos, cobrindo apenas os ~50 ms desde o primer. O padrão correto abaixo usa skip_latch=True para ler os dados acumulados durante o intervalo de sono, e a duração conhecida do sono (machine.deepsleep(SLEEP_MS)) como dt — time.ticks_ms() após acordar pode ser uma fonte pouco fiável.

Python
import time, machine
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass

# Publishing stub. Replace with real WiFi+MQTT logic —
# see Scenario 4 (mqtt_publisher) for a template. In a deep-sleep
# scenario, the WiFi stack is brought up/torn down on every wake,
# which eats up the bulk of the energy budget.
def publish_via_wifi(power_w, total_wh, dt_s):
    print("P=%.1f W  Wh=%.4f  dt=%.1f s" % (power_w, total_wh, dt_s))

SLEEP_MS = 10 * 60 * 1000             # 10 minutes — fixed interval
RTC_MAGIC = b"\xCA\xFE\xFE\xED"

# RTC slow memory: persisted across deep-sleep wakes
rtc = machine.RTC()
state = rtc.memory()                  # bytes; empty on cold boot

def save_state(magic, wh_total, primer_done):
    # Simple layout: 4 bytes magic + 8 bytes float wh + 1 byte primer_done
    import struct
    rtc.memory(magic + struct.pack("dB", wh_total, 1 if primer_done else 0))

def load_state():
    import struct
    if len(state) < 4 + 8 + 1 or state[:4] != RTC_MAGIC:
        return False, 0.0, False
    wh_total, primer_done_byte = struct.unpack("dB", state[4:4+9])
    return True, wh_total, bool(primer_done_byte)

valid, rtc_total_wh, primer_done = load_state()
if not valid:
    rtc_total_wh = 0.0
    primer_done = False

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:    # __enter__ automatically calls begin() — the snapshot primer
    dev.energy.disable()         # the master owns Wh persistence itself

    if not primer_done:
        # First wake: the primer snapshot just discarded the "dirty" data.
        # Save the flag and go straight back to sleep — the next wake,
        # SLEEP_MS later, will get a full accumulator for the interval.
        save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)
        machine.deepsleep(SLEEP_MS)

    # skip_latch=True reads what the begin() primer snapshot captured —
    # i.e. the accumulator for the elapsed sleep interval.
    snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)

    # Use the KNOWN sleep duration as dt
    dt_s = SLEEP_MS / 1000
    rtc_total_wh += snap.avg_p[0] * dt_s / 3600.0

    publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s)  # stub

    save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)

machine.deepsleep(SLEEP_MS)

O esboço completo (com configuração do WiFi, publicação MQTT, guardas de marcador RTC) está em examples_upy/06_deep_sleep.py.

Orçamento de energia (ESP32-WROOM numa bateria Li-ion de 2000 mAh, intervalo de 10 minutos):

  • Ciclo ativo: ~3 s (WiFi + MQTT + I²C) a ~80 mA → ~0.07 mAh por despertar
  • Sono: ~10 µA (RTC + domínios retidos)
  • ~10 mAh por dia → 2000 mAh duram ~6 meses

Hosts CPython (Raspberry Pi etc.) costumam funcionar com alimentação 24/7 — o deep sleep não se aplica. Para funcionamento a bateria em CPython, ver a secção sobre consumo de energia e suspensão do systemd em 08 · Integrações cloud.


Cenário 10 — Streaming assíncrono via stream_period (funcionalidade apenas Python)

Objetivo: integrar num loop de eventos asyncio / uasyncio existente. O pacote fornece um gerador assíncrono dev.stream_period(interval_s=...) que encapsula o snapshot periódico mais o tratamento automático de leituras obsoletas.

CPython (via asyncio + paho-mqtt-asyncio, ou simples)

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        # Once per minute, skip_stale=True (default) — stale snapshots are
        # automatically skipped without raising RbAmpStaleError
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"P={snap.avg_p[0]:.2f} W,  Wh={dev.energy.wh(0):.4f}")

asyncio.run(main())

MicroPython (via uasyncio)

Python
import uasyncio as asyncio
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass

async def reader(dev):
    async for snap in dev.stream_period(interval_s=60.0):
        print("P={:.2f} W,  Wh={:.4f}".format(snap.avg_p[0], dev.energy.wh(0)))

async def main():
    i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
    with RbAmp(i2c, 0x50) as dev:
        # Run reader + other async tasks in parallel
        await asyncio.gather(
            reader(dev),
            # other_async_task(),
        )

asyncio.run(main())

Parâmetros de stream_period(interval_s=, skip_stale=):

  • interval_s — o período entre snapshots (recomendado ≥ 30 s)
  • skip_stale=True (predefinido) — os snapshots obsoletos são ignorados automaticamente; o gerador avança simplesmente para o intervalo seguinte

  • skip_stale=False — os snapshots obsoletos são produzidos com snap.valid=False, e o chamador decide o que fazer com eles

Exemplos completos — examples_upy/05_async_streaming.py (MicroPython) e o equivalente asyncio nos exemplos CPython.


Cenário 11 — Energia no dispositivo STD (CPython)

Objetivo: num módulo STANDARD (STD), ler os contadores de energia vitalícios do próprio módulo e registar o que foi consumido em cada intervalo. Não existe um ficheiro de exemplo separado para este cenário; o código abaixo está completo.

Nota

A energia no dispositivo é validada em CPython (smbus2). O caminho de 16 bits do MicroPython está implementado mas ainda não validado em hardware — prefira CPython para este cenário.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpNotSupportedError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    if not dev.is_std:
        raise SystemExit("not an STD module")

    try:
        prev = dev.read_std_energy()
    except RbAmpNotSupportedError:
        raise SystemExit("this module does not provide on-device energy")

    while True:
        time.sleep(60)
        now = dev.read_std_energy()
        delta, restarted = RbAmp.std_energy_delta(prev, now)
        if delta is None:
            print("energy generation changed - readings not comparable")
        else:
            print("import %d Wh, export %d Wh, net %d Wh%s" % (
                delta.act_import_wh, delta.act_export_wh, delta.act_net_wh,
                " (module restarted)" if restarted else ""))
        prev = now

std_energy_delta() é segura num corte de energia: um contador que volta ligeiramente abaixo é tratado como aumento zero. Os valores por canal estão em now.ch_import_uwh[ch] / ch_export_uwh[ch] para ch < now.channels.

As chamadas de período num módulo STD

As chamadas de período do Cenário 2 funcionam num módulo STD como num BASIC; a energia é líquida (a exportação subtrai):

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpStaleError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue    # nothing to report for this period; the next one covers it
        print("avg %.1f W, net %.4f Wh, total %.4f Wh%s" % (
            snap.avg_p_total, snap.wh_net, dev.energy.wh(0),
            " (module restarted)" if snap.module_restarted else ""))

begin() escolhe a fonte do período a partir do que o módulo reporta: os seus contadores de energia (o período é a diferença de duas leituras; não é enviado nenhum comando de latch) ou, num módulo só com bancos de latch, o banco de latch 0. Os bancos de latch também estão disponíveis diretamente — ver "Latch banks" em 09 · Referência da API.


Tabela-resumo dos cenários

# LOC Runtime barramento I²C Período? DRDY? MQTT? Persistência
1 ~25 ambos dedicado não não não não
2 ~35 ambos (OLED em uPy) partilhado com OLED (uPy) sim não não RAM
3 ~50 ambos partilhado, 3 módulos sim não não RAM
4 ~50 ambos dedicado sim não sim MQTT retained
5 ~40 ambos dedicado não (RT) não não RAM (propriedade do master)
6 ~60 ambos partilhado, 3 módulos sim não sim MQTT retained
7 ~40 ambos dedicado não (RT) não não RAM
8 ~30 CPython dedicado sim não não ficheiro de log rotativo
9 ~50 Apenas MicroPython dedicado sim não sim Memória RTC + MQTT
10 ~25 ambos (asyncio/uasyncio) dedicado sim não (optional) RAM
11 ~20 CPython (módulo STD) dedicado não (no dispositivo) não não contadores de vida útil do módulo

Implementação em produção (apenas CPython)

Para uma implementação de longa duração 24/7 num SBC Linux, recomenda-se um serviço systemd. O exemplo completo está em examples_cpython/10_systemd_service.py (inclui um auxiliar --install que gera o ficheiro de unidade /etc/systemd/system/rbamp.service).

Estrutura básica:

Python
#!/usr/bin/env python3
# /usr/local/bin/rbamp_daemon.py  (make it executable: sudo chmod +x /usr/local/bin/rbamp_daemon.py)
import sys, signal, time, logging
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

logging.basicConfig(level=logging.INFO,
                    format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("rbamp")

shutdown = False
def on_signal(sig, frame):
    global shutdown
    log.info("Received signal %d, shutting down gracefully", sig)
    shutdown = True

signal.signal(signal.SIGTERM, on_signal)
signal.signal(signal.SIGINT,  on_signal)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    log.info("rbAmp daemon started")
    while not shutdown:
        try:
            snap = dev.read_period_snapshot()
            log.info("P=%.1f W, Wh=%.4f", snap.avg_p[0], dev.energy.wh(0))
        except Exception as e:
            log.warning("snapshot failed: %s", e)
        time.sleep(60)

log.info("rbAmp daemon stopped")

E a própria unidade:

INI
# /etc/systemd/system/rbamp.service
[Unit]
Description=rbAmp I2C AC sensor daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/rbamp_daemon.py
Restart=on-failure
RestartSec=5
# the user must be in the i2c group: sudo usermod -aG i2c pi
User=pi

[Install]
WantedBy=multi-user.target

Para arrancar: sudo systemctl enable --now rbamp. Registos: journalctl -u rbamp -f.

O que vem a seguir


← Início rápido | Índice | Integrações DIY →


Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/06_examples.md


Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/06_examples.md (v1.6.1)