01 · Visão geral
O que é a rbAmp
rbAmp é um módulo de hardware compacto para medição de precisão de parâmetros da rede AC através da interface I²C. Assenta num microcontrolador com um front-end analógico isolado integrado e calibração de fábrica guardada na flash.
Do ponto de vista de quem integra, o módulo comporta-se como um escravo I²C padrão: cria-se RbAmp(bus, 0x50), chama-se dev.begin() e obtêm-se valores prontos a usar através de propriedades e métodos. O mesmo código corre em MicroPython (com machine.I2C) e em CPython (com smbus2) — o backend é selecionado automaticamente a partir do tipo do objeto de barramento.
Termos usados nesta documentação
- Linha de módulos — BASIC ou STANDARD (STD): a linha de produto do módulo (ver 02).
- Variante — UI1, UI2, UI3, I1, I2, I3 (e UI5/UI7): quantos canais de corrente tem e se o módulo tem entrada de tensão.
- Versão do firmware / versão da imagem do módulo — o software dentro do módulo; algumas chamadas STD precisam de uma imagem suficientemente recente.
- Leitura RT — uma leitura instantânea (tensão, corrente, potência), atualizada pelo módulo a cada 100 ms.
- Período / snapshot — um snapshot congela os totais do período decorrido e inicia o seguinte; um snapshot de período é o resultado congelado (potência média por canal).
- Snapshot obsoleto — o módulo não tinha um snapshot novo pronto; a biblioteca levanta
RbAmpStaleErrore o snapshot bom seguinte cobre o intervalo inteiro. - Primer — o primeiro snapshot tirado por
begin(); descarta o que se acumulou desde o arranque. - GC (General Call) — uma trama I²C de difusão que faz com que vários módulos tirem o seu snapshot exatamente no mesmo instante.
- DRDY — pino opcional que pulsa a cada ~100 ms quando há novos dados RT prontos.
Um módulo ou vários
Um módulo ou vários: comece com um RbAmp; use RbAmpFleet para vários. O pacote Python rbamp funciona com um único módulo e também com um grupo de módulos num único barramento I²C. O cenário canónico multi-módulo é um módulo mestre na alimentação da rede mais N módulos em cargas individuais, todos num barramento, comandados por um único ESP32 / RPi / SBC. A biblioteca fornece a classe RbAmpFleet — um objeto único através do qual faz scan ao barramento, consulta todos os módulos numa só chamada, obtém a potência total e o balanço "alimentação − Σ(consumidores)", apanha erros em cada módulo e, quando necessário, sincroniza snapshots de período com um comando de broadcast.
Os módulos multicanal também são suportados — os apenas de corrente I2 / I3 (dois ou três TC) e os equipados com tensão UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 canais de corrente, com potência, PF e Wh por canal). Cada canal tem o seu próprio modelo de sensor. É típico num subquadro, onde um único ponto de instalação monitoriza vários alimentadores.
Trabalhar com um único módulo é o caso mínimo da mesma biblioteca: a classe RbAmp é o bloco de construção sobre o qual assenta o RbAmpFleet. Se tiver um módulo no barramento, usa esse mesmo handle diretamente — a API da frota não é necessária.
O cenário dos 80% — alimentação principal + N subcargas
- 1 módulo na alimentação (rede) — consumo total e qualidade da rede.
- N módulos em cargas individuais — medição por canal.
- Os módulos multicanal também servem este caso: um único
UI2/UI3/UI5/UI7(ouI2/I3) pode medir várias cargas, cada uma no seu canal — N módulos não têm de significar N cargas. -
Um único
fleet.poll_all()consulta tudo; o balançomains − Σ(sub_loads)mostra "o resto" (consumo de fundo, cargas não medidas, fugas). -
Um timestamp mestre partilhado → contabilização correta de Wh sem desvio entre módulos.
Detalhe arquitetónico importante. As variantes I (I1/I2/I3) medem apenas corrente — não têm tensão, potência ativa nem PF. A energia ativa (Wh) e a potência são calculadas apenas nas variantes UI (que têm um front-end de tensão). Na implementação canónica, o papel de "contador da rede" (medir energia) é desempenhado por um único UI1 na alimentação da rede; o papel de sub-contador (detalhe de corrente por carga) é desempenhado pelos módulos I2/I3 (ou por UI2 / UI3 / UI5 / UI7 quando se precisa de potência e Wh por carga).
Para detalhes, veja o capítulo 06 · Exemplos, cenário 1 ("Rede + N sub-cargas — o cânone dos 80 %"). Para a API, veja o capítulo 09 · Referência da API, secção "Gestor da frota".
O que a rbAmp mede
| Grandeza | Tipo Python | Gama |
|---|---|---|
| Tensão eficaz U_rms | float, V |
0…300 V |
| Tensão de pico U_peak | float, V |
0…450 V |
| Corrente RMS I_rms | float, A |
depende do sensor escolhido — ver 03_sensor_selection.md |
| Corrente de pico I_peak | float, A |
depende do sensor selecionado |
| Potência ativa P (com sinal em RT) | float, W |
depende do sensor selecionado |
| Fator de potência PF | float |
−1…+1 |
| Frequência da rede | int, Hz |
50 / 60 Hz (detetado) |
| P média do período | float, W |
igual a P |
O valor RT da potência ativa P é sempre com sinal em qualquer linha de módulos (negativo significa exportação para a rede). O comportamento do valor médio por período (snap.avg_p[ch] em RbAmpPeriodSnapshot) depende da linha do módulo — ver a secção "Linhas de módulos" abaixo e 02_tiers.md.
Ligação
O módulo liga ao anfitrião com quatro fios no lado de baixa tensão; tudo o que toca na rede fica dentro do invólucro.
| Fio | Finalidade |
|---|---|
VCC |
+5 V (4.5..5.5 V), corrente ~15 mA, pico ~25 mA |
GND |
comum com o host (obrigatório) |
SDA, SCL |
I²C, lógica de 3.3 V, tolerante a 5 V. Pull-ups incorporados 4.7 kΩ |
DRDY |
opcional, dreno aberto em BAIXO ~10 µs a cada ~100 ms |
O endereço predefinido é 0x50 (7 bits, intervalo de alteração 0x08..0x77). A velocidade recomendada para MicroPython no ESP32 é 50 kHz; para CPython através do I²C do kernel é normalmente 100 kHz (o padrão de NACK não aparece pela API do kernel Linux).
As regras completas (comprimento do barramento, recomendações de pull-up num barramento com vários módulos, diagramas de cablagem para RPi / ESP32 / RP2040 / STM32) estão no capítulo 04 · Cablagem.
Linhas de módulos (folha de consulta rápida)
Os módulos BASIC e STANDARD (STD) estão em fornecimento; o STANDARD é suportado por esta biblioteca desde a 1.6.0.
O BASIC é uma medição unidirecional (apenas consumo), seguindo a lógica de um contador mecânico clássico:
| Linha de módulos | Potência RT dev.power[ch] |
Acumulador do período snap.avg_p[ch] |
Contador Wh do pacote |
|---|---|---|---|
| BASIC | com sinal (negativo = exportação para a rede, visível em tempo real) | cada janela de 100 ms da potência ativa média é limitada a max(P, 0) antes de ser somada ao acumulador do período |
monotónico — medição apenas de consumo |
| STANDARD (STD) | com sinal | as mesmas chamadas que BASIC; a fonte são os contadores de energia do módulo ou o banco de latch 0, escolhido em begin(); a energia é líquida (a exportação subtrai) |
dev.energy integra o período; os totais do próprio módulo: read_std_energy() (ver capítulo 02) |
Para mais detalhes, consulte o capítulo 02 · Linhas de módulos. Ao nível do pacote usa-se a mesma classe RbAmp independentemente da linha de módulos; as diferenças aparecem nos valores que o módulo devolve.
Medição bidirecional em BASIC: dev.energy.wh(ch) na linha de módulos BASIC dá apenas consumo. Se precisar de contabilizar a exportação em separado, amostre a potência RT dev.power[0] (ou dev.read_power(0)) a ~10 Hz e separe as amostras positivas e negativas em duas variáveis acumuladoras. Para um exemplo, veja 06_examples.md, cenário "Medição bidirecional do lado do mestre".
O que este pacote faz
A função principal é esconder a troca de protocolo e poupar o código do utilizador à rotina de trabalhar com registos, ordem dos bytes e tempos de estabilização depois dos comandos. Além disso, o pacote calcula a energia (Wh) — o módulo devolve apenas a potência média do período, e o mestre faz a integração usando time.monotonic() / time.ticks_us().
Sem o pacote (acesso direto aos registos via smbus2)
import struct
from smbus2 import SMBus, i2c_msg
# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("
Com o pacote
from smbus2 import SMBus
from rbamp import RbAmp
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
u_rms = dev.voltage # property (one call = one transaction)
# or: u_rms = dev.read_voltage()
Ler um período — sem o pacote
import time, struct
with SMBus(1) as bus:
# Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
bus.write_byte_data(0x50, 0x01, 0x27) # REG_COMMAND, CMD_LATCH_PERIOD
t_latch = time.monotonic()
time.sleep(0.050) # settle
bus.write_byte(0x50, 0x07)
if bus.read_byte(0x50) & 0x01 == 0:
# snapshot is stale — keep the previous t_prev_latch, so the next
# good snapshot covers the full interval
raise SystemExit("stale snapshot")
# ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
# dt_s = time.monotonic() - t_prev_latch
# E_Wh += avg_p * dt_s / 3600
Ler um período — com o pacote
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
snap = dev.read_period_snapshot() # snapshot + settle + valid + read + Wh tick
print(snap.avg_p[0], "W")
print(dev.energy.wh(0), "Wh")
Internamente o pacote garante:
- Uma estabilização de 50 ms após
CMD_LATCH_PERIOD, e uma leitura correta do snapshot. -
Uma verificação da flag
validantes de ler; num snapshot obsoleto levantaRbAmpStaleError. -
Manter o carimbo temporal anterior num snapshot obsoleto, para que o snapshot bom seguinte cubra o intervalo completo e o Wh fique exato.
-
Acumulação de Wh por canal em dupla precisão (CPython —
floatde 64 bits; MicroPython — depende da build, ver 04 · Cablagem). -
Carregamento automático dos coeficientes de calibração quando o sensor de corrente é selecionado via
dev.set_sensor_class(cls)+dev.set_ct_model(code)— o utilizador não precisa de conhecer os registos internos de calibração.
Quando usar o pacote e quando usar acesso direto ao barramento
| Tarefa | Pacote | Acesso direto via smbus2 / machine.I2C |
|---|---|---|
| Leitura de U / I / P / PF / frequência | ✅ | apenas para depuração com um analisador lógico |
| Medição de energia por período | ✅ | só se os Wh forem guardados fora do pacote (por exemplo, numa base de dados do lado do mestre) |
| Vários módulos num mesmo barramento | ✅ (via snapshot sequencial + estabilização partilhada) | — |
| Medição bidirecional no BASIC | ✅ (via leituras RT — ver 06_examples.md) | alternativa — o seu próprio ciclo de leitura em tempo real |
| Streaming assíncrono via asyncio / uasyncio | ✅ (async for snap in dev.stream_period()) |
difícil — sem wrapper assíncrono incorporado |
| Adaptação a outra plataforma | n/a | ✅ — ver rbamp-docs (mapa de registos e protocolo) |
Para todas as tarefas típicas das primeiras linhas, o pacote é o caminho a seguir.
Arquitetura
┌─────────────────────────────────────────────────────┐
│ User code (.py) │
│ from smbus2 import SMBus │
│ from rbamp import RbAmp, RbAmpSensorClass │
│ with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: │
│ # __enter__ calls dev.begin() itself; │
│ # explicit begin() shown for transparency │
│ dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│ dev.set_ct_model(3) │
│ snap = dev.read_period_snapshot() │
│ dev.energy.wh(0) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Public API of the RbAmp class (rbamp/__init__.py) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Lifecycle: begin / probe / wait_ready │ │
│ │ RT properties: .voltage / .power[ch] / │ │
│ │ .current[ch] / .frequency │ │
│ │ RT methods: read_voltage / read_power / │ │
│ │ read_all │ │
│ │ Period: latch_period / │ │
│ │ read_period_snapshot │ │
│ │ Async: stream_period │ │
│ │ Configuration: set_sensor_class / │ │
│ │ set_ct_model │ │
│ │ Diagnostics: retry_exhaustion_count / │ │
│ │ sanity_reject_count │ │
│ │ Exceptions: RbAmpError → IOError / │ │
│ │ TimeoutError / StaleError / │ │
│ │ ParamError / ModeError / │ │
│ │ VersionError │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Backend selection (inside __init__): │ │
│ │ bus.readfrom_mem → MachineI2CBackend │ │
│ │ bus.read_byte_data → SMBusBackend │ │
│ │ duck-typed → custom (FTDI / mocks) │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Instance state: │ │
│ │ • RbAmpEnergy — Wh accumulator │ │
│ │ • RbAmpSnapshot / RbAmpPeriodSnapshot │ │
│ │ • Time of last snapshot (monotonic) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Backend — native I²C on the host platform: │
│ smbus2 (CPython) / machine.I2C (MicroPython) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ rbAmp module at address 0x50 │
│ • U / I / P / PF measurement pipeline (~100 ms) │
│ • Period accumulator (atomic CMD_LATCH_PERIOD) │
└─────────────────────────────────────────────────────┘
Hierarquia de exceções
Ao contrário da biblioteca Arduino (onde os erros são reportados via lastError() + um código de retorno) e do componente ESP-IDF (onde são reportados via esp_err_t), o pacote Python usa o padrão clássico do Python — uma hierarquia de exceções.
O padrão Python habitual:
from rbamp import RbAmp, RbAmpStaleError, RbAmpError
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
# Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
continue
except RbAmpError as e:
log.warning("rbAmp failure: %s", e)
Diagramas de interação
O fluxo de dev.begin()
code RbAmp Backend rbAmp module
│ │ │ │
├─dev.begin()► │ │
│ ├─read_u8(REG_VERSION)► │
│ │ ├──[0x50, 0x03]────────►│
│ │ │◄────────────────ACK───┤
│ │ ├──[read 1 byte]───────►│
│ │ │◄──────────────[0x04]──┤
│ │◄─────── version_byte ─────┤ │
│ │ │ │
│ ├─read_float_le(U_RMS)►(4 single-byte reads) │
│ │ → 226.3 V │ │
│ │ → has_voltage_hw = True │
│ │ │ │
│ ├─write_cmd(LATCH)──►│ │
│ │ ├──[0x50, 0x01, 0x27]──►│
│ │ sleep(50ms) │ │
│ │ │ │
│◄────self────┤ (or raises RbAmpIOError on failure) │
O primeiro snapshot é um primer (o módulo devolve o que acumulou desde a ligação, o que não serve para a medição tarifária). O pacote regista por si que este snapshot tem de ser descartado — o código do utilizador nunca o vê.
O fluxo de dev.read_period_snapshot()
code RbAmp Backend rbAmp module
│ │ │ │
├─read_period_snapshot()► │ │
│ ├─write_cmd(LATCH)──►│ t_now = time.monotonic()
│ │ │ │
│ │ sleep(50ms) │ │
│ │ │ │
│ ├─is_period_valid()─►│ │
│ │ → True │ │
│ │ │ │
│ ├─read_float_le(AVG_P0)►(4 reads) │
│ ├─read_float_le(MAX_P0)►(4 reads) │
│ ├─read_u32_le(LATCH_MS)►(4 reads) │
│ │ │ │
│ │ dt = t_now − last_latch │
│ │ energy.wh[ch] += avg_p[ch] × dt / 3600 │
│ │ last_latch = t_now │
│ │ │ │
│◄─snap──────┤ │ │
O snapshot atómico do lado do módulo garante que cada medição dentro de um período cai exatamente num snapshot — sem duplicação, sem perdas na fronteira do período.
Correspondência com a API de registos direta
Uma tabela para quem migra a partir do seu próprio trabalho de acesso direto:
API direta (smbus2 / machine.I2C) |
Equivalente do pacote |
|---|---|
Leitura manual de 4 bytes + struct.unpack |
dev.voltage (propriedade) ou dev.read_voltage() |
read_byte por canal × 4 |
dev.power[ch] (_ChannelProxy) ou dev.read_power(ch) |
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) |
dev.latch_period(); time.sleep(0.05) (ou diretamente dev.read_period_snapshot()) |
Verificar read_byte(0x07) & 1 |
dev.is_period_valid() ou o campo snap.valid |
Fórmula manual E_Wh += avg_p × dt / 3600 |
dev.energy.wh(0) — atualizado automaticamente |
| Configuração manual do sensor de corrente através da API de registos direta | dev.set_sensor_class(cls) + dev.set_ct_model(code) — as predefinições de fábrica são carregadas automaticamente |
O que vem a seguir
- 02 · Linhas de módulos — que linha de módulos para que tarefa
-
04 · Cablagem — pull-ups, comprimento do barramento, cablagem por anfitrião (RPi / ESP32 / RP2040 / STM32)
-
05 · Início rápido — o primeiro script para ambos os backends
-
06 · Exemplos — um percurso pelos cenários prontos a usar
-
09 · Referência da API — todas as classes, métodos, propriedades e exceções públicas
-
10 · Resolução de problemas — quando algo não funciona
Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/01_overview.md (v1.6.1)