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

01 · Visão geral

Cadeia de sinal do rbAmp: sensor → módulo → I²C → mestre → cloud / Home Assistant

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 RbAmpStaleError e 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

Um módulo na alimentação da rede e um módulo por sub-carga partilham um barramento I²C com o mestre, que os consulta a todos com uma única chamada à frota.

  • 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 (ou I2 / 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ço mains − Σ(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.

Segurança

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
Nota

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.

Nota

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)

Python
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

Python
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

Python
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

Python
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 valid antes de ler; num snapshot obsoleto levanta RbAmpStaleError.

  • 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 — float de 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

Onde se situa um script Python: script, pacote rbamp, backend I²C e o módulo rbAmp, com a velocidade I²C de cada host.

Text
┌─────────────────────────────────────────────────────┐
│  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.

Hierarquia de exceções do pacote rbamp: todo o erro deriva de RbAmpError, que deriva de OSError.

O padrão Python habitual:

Python
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()

Sequência de transações no barramento que begin() executa: lê a versão, deteta a linha do módulo, envia o snapshot de primer e depois devolve o controlo.

Text
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()

Sequência de read_period_snapshot(): tirar o snapshot do período, ler o bloco de snapshot e integrar a energia no mestre para BASIC ou ler os contadores do dispositivo para STD.

Text
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


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