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

05 · Arranque rápido

Um hello-world de cinco minutos: instale o pacote, ligue o módulo, selecione um sensor e leia o seu primeiro valor RT e o seu primeiro snapshot por período (Wh). Este tutorial cobre os dois runtimes em paralelo — MicroPython (em ESP32 / RP2040 / STM32 / Pyboard) e CPython (em Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).

Para os detalhes (pinagem para um anfitrião específico, barramento com vários módulos, escolha de um SCT-013 por gama), veja os capítulos vizinhos:

O que vai precisar

Segurança

⚠ Segurança elétrica. A tensão da rede pode matar. Desligue e bloqueie o circuito antes de ligar os terminais L/N ou de colocar a pinça; deixe o trabalho de ligação à rede e qualquer trabalho dentro de um quadro a cargo de uma pessoa qualificada. Coloque a pinça em um condutor apenas (L) — nunca no cabo inteiro (com L e N na pinça lê ~0). A própria pinça é sem contacto.

  • Um módulo rbAmp (qualquer linha de módulos; UI1 por simplicidade)
  • Um destes hosts:
  • CPython: Raspberry Pi (qualquer modelo) / Orange Pi 5 / Rock Pi 5 / x86 + dongle USB-I²C

  • MicroPython: ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)

  • Uma pinça de CT SCT-013 com calibre para a sua corrente máxima (5A / 10A / 30A / 50A / 100A)

  • Uma alimentação de 5 V para o módulo (da USB-5V do host ou externa)
  • Um circuito CA a medir (uma lâmpada, uma chaleira ou um eletrodoméstico)

Que caminho sigo?

Verifique dev.is_std (ou o rótulo de SKU no módulo — ver 02 · Linhas de módulos). Módulo STD: salte os Passos 4-5 e vá para 06 · Exemplos, Cenário 11. Módulo BASIC: siga todos os passos. Os Passos 3 e 4 são iguais para ambos.

O caminho até à primeira leitura: ligue o módulo, defina o modelo da pinça e depois leia tensão, corrente e potência.

Passo 1 — Instalar o pacote

CPython (num SBC Linux ou x86)

Shell
pip install rbamp

(Num sistema Debian/Ubuntu pode usar a alternativa do sistema smbus2, sudo apt install python3-smbus, mas recomenda-se o smbus2 do pip — suporta o gestor de contexto with SMBus(...).)

Verify:

Shell
rbamp --version          # rbamp 1.6.0
rbamp --bus 1 scan       # I²C scan, should show 0x50

MicroPython (no ESP32 e noutros)

Shell
mpremote mip install github:rb-amp/rbamp-python

Ou copie o pacote manualmente:

Shell
mpremote cp -r path/to/rbamp/ :rbamp/

O pacote instala-se em /lib/rbamp/ no dispositivo.

Passo 2 — Ligação

Quatro fios mais DRDY opcional:

pino rbAmp Anfitrião
VCC +5 V (intervalo 4.5..5.5 V)
GND GND
SDA I²C SDA (RPi pino 3, ESP32 GPIO21, RP2040 GPIO0/etc.)
SCL SCL I²C (RPi pino 5, ESP32 GPIO22, RP2040 GPIO1/etc.)

A alimentação tem de ser de 5 V. As linhas I²C funcionam a lógica de 3.3 V mas toleram 5 V. A placa do módulo já tem resistências de pull-up de 4.7 kΩ integradas — para um módulo único não são necessárias externas.

A tabela completa de pinos de cada anfitrião está em 04 · Cablagem.

A pinça SCT-013 envolve apenas o condutor de linha (L), com a seta no corpo da pinça a apontar no sentido da corrente para a carga. Ver mais em 04 · Ligação.

Ligue a pinça ao fio L com a seta virada para a carga, e os terminais de referência da rede.

Segurança

⚠ Segurança elétrica. A tensão da rede pode matar. Desligue e bloqueie o circuito antes de ligar os terminais L/N ou de colocar a pinça; deixe o trabalho de ligação à rede e qualquer trabalho dentro de um quadro a cargo de uma pessoa qualificada. Coloque a pinça em um condutor apenas (L) — nunca no cabo inteiro (com L e N na pinça lê ~0). A própria pinça é sem contacto.

Passo 3 — Primeiro script (leitura RT)

Um script mínimo: indique ao módulo qual a pinça que usa (uma vez) e depois leia U / I / P / PF. Os códigos de modelo estão listados no Passo 4; o 3 abaixo é o SCT-013-030. A tabela de linhas/variantes de módulos está em 02 · Linhas de módulos.

Versão do CPython

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

with SMBus(1) as bus:
    with RbAmp(bus, 0x50) as dev:
        # the context manager's __enter__ automatically calls dev.begin()
        # the module variant is detected automatically
        variant = dev.read_variant()
        label = dev.read_label() or "(unset)"
        print(f"Module ready: variant={variant}  label={label!r}")
        # variant codes: see the table in 02 · Module lines
        # Once per installation (saved in the module's flash):
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)   # SCT-013-030, see Step 4
        while True:
            try:
                print(f"U={dev.voltage:.1f}V  "
                      f"I={dev.read_current(0):.3f}A  "
                      f"P={dev.read_power(0):.1f}W  "
                      f"PF={dev.read_power_factor(0):.3f}")
            except RbAmpError as e:
                print("read failed:", e)
            time.sleep(1)

Run:

Shell
python quick_read.py

Versão do MicroPython

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)   # ESP32 default
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)   # once per installation
    dev.set_ct_model(3)                              # SCT-013-030, see Step 4
    print("Module ready.")
    while True:
        try:
            print("U={:.1f}V  I={:.3f}A  P={:.1f}W  PF={:.3f}".format(
                dev.voltage, dev.read_current(0),
                dev.read_power(0), dev.read_power_factor(0)))
        except RbAmpError as e:
            print("read failed:", e)
        time.sleep(1)

(Em MicroPython usa-se .format() em vez de f-strings — por desempenho e compatibilidade com portas mais antigas; em portas mais recentes as f-strings também funcionam.)

Run:

Shell
mpremote run quick_read.py

Saída esperada com uma carga ligada (os valores dependem da sua carga):

Text
Module ready.
U=230.4V  I=0.523A  P=119.8W  PF=0.987
Segurança

U mostra aproximadamente a tensão da rede (220-240 V para redes de 230 V). Sem carga, I é ~0 e PF é indefinido (pode mostrar nan, 0 ou um valor de substituição) — a forma exata não importa enquanto a corrente for zero. Se I ficar em 0.000 A com a carga ligada, verifique a pinça (um só condutor, direção correta) e o código de modelo, e depois veja 10 · Resolução de problemas.

Passo 4 — Configuração do sensor de corrente

Tem de indicar ao módulo a classe e o modelo do sensor (feito no script do Passo 3). Sem isto, os coeficientes de calibração não são carregados e as leituras de corrente ficam a zero. Chame sempre set_sensor_class() primeiro, depois set_ct_model(code).

Escolha o código que corresponde à sua pinça:

code Modelo Gama Utilização típica
1 SCT-013-005 0..5 A Cargas pequenas, uma só tomada
2 SCT-013-010 0..10 A Frigorífico, máquina de lavar roupa
3 SCT-013-030 0..30 A Alimentação doméstica até ~7 kW
4 SCT-013-050 0..50 A Carregador de VE, aquecimento elétrico
6 SCT-013-020 0..20 A Alimentação média, eletrodomésticos de 3–4 kW

Mais sobre a seleção — 03 · Seleção do sensor de corrente.

Nota

Estas duas chamadas são feitas uma vez na primeira instalação — a escolha fica guardada na flash do módulo e sobrevive a um reset. O tempo total é cerca de 1.4 segundos (duas escritas na flash × ~700 ms cada).

Nas execuções seguintes do script não precisa de chamar set_sensor_class() e set_ct_model() (o módulo lembra-se). Chamá-los de novo com o valor que o módulo já tem é um no-op.

Passo 5 — Contabilização de energia (Wh)

O módulo devolve apenas as grandezas instantâneas e a potência média num período. Os próprios Wh são calculados pelo pacote usando o relógio do mestre (time.monotonic() em CPython, time.ticks_ms() em MicroPython):

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

onde master_dt_s são os segundos entre duas chamadas bem-sucedidas a dev.read_period_snapshot().

Nota

Espere um período completo antes do primeiro read_period_snapshot(). begin() já inicia um período, por isso um snapshot tirado logo a seguir cobre apenas uma fração de segundo e o Wh lerá ~0. Os ciclos abaixo esperam 60 s primeiro por esta razão.

O contador Wh fica em memória. Reinicia em 0 após um reinício do script ou do sistema. Para um total absoluto, guarde você mesmo dev.energy.wh(0). Nos módulos BASIC a exportação não é contabilizada (ver 02 · Linhas de módulos). Num módulo STD as mesmas chamadas funcionam e o valor é energia líquida (a exportação subtrai); begin() escolhe a fonte — os contadores de energia do módulo ou o banco de latch 0 — e o primeiro período começa em begin(). Os totais de vida do próprio módulo estão em read_std_energy() (Cenário 11 em 06 · Exemplos).

Um modelo mínimo de contabilidade periódica (uma vez por minuto):

Versão CPython (medidor de período)

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)   # SCT-013-030

    while True:
        time.sleep(60)   # 60-second period

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print(f"avg P over period: {snap.avg_p[0]:.2f} W   "
              f"accumulated: {dev.energy.wh(0):.4f} Wh   "
              f"dt={snap.master_dt_ms} ms")

Versão do MicroPython (medidor de período)

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)

    while True:
        time.sleep_ms(60_000)

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print("avg P over period: {:.2f} W   accumulated: {:.4f} Wh   dt={} ms".format(
            snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Nota

Após o Passo 4, as chamadas set_sensor_class() e set_ct_model() já correram uma vez e ficaram guardadas na flash do módulo; no modelo acima estão lá para reexecuções do script — o módulo ignora uma chamada repetida com o mesmo valor.

O que read_period_snapshot() faz por dentro:

  1. Envia ao módulo o comando de instantâneo de período (CMD_LATCH_PERIOD).
  2. Aguarda 50 ms enquanto o módulo prepara o instantâneo.
  3. Verifica a flag de pronto (snap.valid); lê a potência média/de pico.

  4. Atualiza o contador interno de Wh: dev.energy.wh(ch) += avg_p[ch] × dt / 3600.

  5. Num snapshot obsoleto lança RbAmpStaleError e mantém o carimbo temporal anterior, pelo que o snapshot bem-sucedido seguinte cobre o intervalo completo e o Wh fica exato.

dev.begin() inicia ele próprio o primeiro período (um primer) e descarta o que o módulo acumulou desde a ligação, pelo que o código do utilizador nunca vê esses dados.

Saída esperada:

Text
avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Variante de streaming assíncrono (opcional)

Para aplicações com asyncio (CPython) ou uasyncio (MicroPython), existe um gerador assíncrono dev.stream_period(interval_s=...):

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:
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)

        # Once a minute, with built-in stale handling (skip_stale=True)
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"{snap.avg_p[0]:.2f} W,  {dev.energy.wh(0):.4f} Wh")

asyncio.run(main())

Funciona da mesma forma em MicroPython (import uasyncio as asyncio).

Mais sobre cenários assíncronos — 06 · Exemplos, o cenário "Streaming assíncrono de períodos".

Passo 6 — Arranque rápido para uma frota de N módulos

Este início rápido mostra o trabalho com um único módulo. O cenário canónico real do pacote são vários módulos num só barramento via RbAmpFleet (rede + N cargas secundárias). Para o exemplo completo, veja o capítulo 06 · Exemplos, cenário 1 "Rede + N cargas secundárias — o cânone 80%". Um esqueleto mínimo de frota (CPython):

Python
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    added = fleet.scan()
    print(f"fleet: {added} modules; excluded: {fleet.excluded}")

    while True:
        snaps = fleet.poll_all()
        total_w = fleet.total_power()
        n_ok = sum(1 for snap, info in snaps if info.ok)
        print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
        time.sleep(0.2)

A versão MicroPython é idêntica — substitua SMBus(1) por I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).

No cenário canónico dos 80 %, um dos módulos é um UI1 na alimentação da rede (fornece total_power() e total_energy_wh()), e os restantes, I2/I3, são contadores de corrente secundários. Os detalhes e os cenários avançados (desagregação rede + sub-cargas, sincronização GC para snapshots fortemente sincronizados, fluxo de aprovisionamento) estão no capítulo 06.

O que vem a seguir

  • 01 · Visão geral — o que é o rbAmp e o que o pacote faz
  • 02 · Linhas de módulos — que linha de módulos para que tarefa
  • 06 · Exemplos — cenários de trabalho: rede + N sub-cargas (o cânone dos 80 %), fluxo de aprovisionamento, CT misto multicanal, sincronização GC da frota, MQTT, deep-sleep, streaming assíncrono

  • 07 · Integrações DIY — Home Assistant / Node-RED / OpenHAB

  • 08 · Integrações cloud — AWS IoT / Azure / GCP / InfluxDB

  • 09 · Referência da API — a API pública completa (incluindo RbAmpFleet + multicanal + modelo de erros v1.3 + identidade e aprovisionamento)

  • 10 · Resolução de problemas — se algo não funcionar (o three-layer de i2c-hang no MicroPython@ESP32, latch_ms é um temporizador de diagnóstico, RbAmpStaleError âncora-de-retenção-do-master)


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