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:
-
04 · Cablagem — detalhes de hardware e tabelas de pinos por anfitrião
-
03 · Seleção do sensor de corrente — qual o modelo SCT-013 a usar e porquê
O que vai precisar
⚠ 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.
Passo 1 — Instalar o pacote
CPython (num SBC Linux ou x86)
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:
rbamp --version # rbamp 1.6.0
rbamp --bus 1 scan # I²C scan, should show 0x50
MicroPython (no ESP32 e noutros)
mpremote mip install github:rb-amp/rbamp-python
Ou copie o pacote manualmente:
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.
⚠ 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
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:
python quick_read.py
Versão do MicroPython
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:
mpremote run quick_read.py
Saída esperada com uma carga ligada (os valores dependem da sua carga):
Module ready.
U=230.4V I=0.523A P=119.8W PF=0.987
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.
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):
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().
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)
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)
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))
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:
- Envia ao módulo o comando de instantâneo de período (
CMD_LATCH_PERIOD). - Aguarda 50 ms enquanto o módulo prepara o instantâneo.
-
Verifica a flag de pronto (
snap.valid); lê a potência média/de pico. -
Atualiza o contador interno de Wh:
dev.energy.wh(ch) += avg_p[ch] × dt / 3600. - Num snapshot obsoleto lança
RbAmpStaleErrore 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:
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=...):
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):
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)