02 · Linhas de módulos
O que é uma linha de módulos
Os módulos rbAmp vêm em duas linhas: BASIC e STANDARD (STD). Uma linha de módulos é um pacote completo de revisão de hardware e firmware, não uma flag de software. Passar entre linhas de módulos exige uma mudança física de SKU, não uma atualização de firmware.
Do ponto de vista do pacote e do código do utilizador: uma só classe RbAmp serve todas as linhas de módulos, e as leituras comuns (voltage, current, power, power_factor, frequency) funcionam em todos. A linha do módulo é detetada automaticamente em begin(). Os módulos STANDARD (STD) expõem ainda as chamadas exclusivas de STD (energia no dispositivo e outras, ver abaixo); chamar uma delas num módulo BASIC lança RbAmpNotSupportedError.
Estado atual
Os módulos BASIC e STANDARD são suportados por esta biblioteca (STANDARD desde a 1.6.0).
| Linha de módulos | Comercialização |
|---|---|
| BASIC | ✅ sim |
| STANDARD (STD) | ✅ sim (suportado por esta biblioteca desde a 1.6.0) |
BASIC — Linha de módulos de medição de consumo, nível de entrada
Hardware
Um caminho analógico de custo otimizado, adequado a cargas domésticas típicas. O módulo inclui um front-end analógico isolado, um regulador de potência incorporado e calibração de fábrica guardada na memória flash.
Comportamento do firmware
A lógica de um contador de disco mecânico clássico — a contagem só avança; a exportação para a rede não é subtraída.
Os três «níveis» dos valores de potência ativa comportam-se de forma diferente:
| Sinal | Significado | Comportamento no BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
potência RT instantânea, atualização a cada ~100 ms | com sinal — um valor negativo é visível em tempo real (exportação) |
snap.avg_p[ch] (de dev.read_period_snapshot()) |
potência média ao longo do período | cada janela de potência média de 100 ms é limitada a max(P, 0) antes de ser somada ao acumulador do período |
dev.energy.wh(ch) |
Wh acumulados pelo pacote | monotónico — só consumo; a exportação não é contada |
Dito de outra forma: o utilizador vê a exportação na leitura RT, mas ela não está presente no contador de Wh do pacote em BASIC.
Aplicações típicas
-
Casas sem produção própria (sem painéis solares, turbinas eólicas, sistemas de bateria)
-
Submedição de cargas puramente consumidoras (termoacumuladores, motores, eletrodomésticos)
-
Monitorização do consumo em edifícios onde a medição bidirecional não é necessária
Medição bidirecional em BASIC (do lado do mestre)
Se precisar de acompanhar a exportação para a rede em separado num módulo BASIC, faça-o do lado do mestre. A potência RT dev.power[0] tem sinal (ou o método equivalente dev.read_power(0)), portanto:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
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.0:
consume_wh += dwh
else:
export_wh += -dwh
Em MicroPython, substitua time.monotonic() por time.ticks_ms() / time.ticks_diff() (mais preciso e barato em RAM em plataformas embutidas) e time.sleep(0.1) por time.sleep_ms(100). Em CPython, sem alterações.
Um exemplo completo e funcional do padrão está em 06_examples.md, no cenário "Medição bidirecional do lado do mestre", bem como nos ficheiros examples_upy/07_bidirectional_energy.py e examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — Linha de módulos em fornecimento
Os módulos STANDARD são uma linha de módulos em produção que esta biblioteca suporta desde a versão 1.6.0. Usam um mapa de registos diferente (16 bits) do BASIC; a biblioteca esconde a diferença — a mesma classe RbAmp, a mesma ligação I²C e endereço, e os mesmos leitores comuns.
O que a biblioteca acrescenta num módulo STD:
-
Energia no dispositivo:
dev.read_std_energy()devolve os contadores vitalícios do próprio módulo — energia ativa importada / exportada / líquida e reativa, em resoluções Wh, mWh e µWh, com valores por canal.RbAmp.std_energy_delta(prev, now)dá a energia consumida entre duas leituras e é segura num corte de energia. Não integra a potência no mestre para estes contadores. -
Medição por período:
read_period_snapshot()e as outras chamadas de período funcionam como em BASIC.begin()escolhe a fonte — os contadores de energia do módulo (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. A energia é líquida (a exportação subtrai). -
Bancos de latch (módulos que os reportam):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Auxiliares multifásicos:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(apenas STD; em BASIC a potência reativa não é exposta por esta biblioteca),dev.read_apparent(ch). -
Corrente de arranque:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Blocos completos:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Algumas chamadas STD precisam de uma imagem de módulo suficientemente recente (contadores de energia em micro-unidades, ângulos de tensão, corrente de arranque). Se o módulo não fornecer uma, a chamada lança
RbAmpNotSupportedError("not available"). -
Use
dev.is_stdpara ramificar no código da aplicação. -
A configuração de classe de sensor e de modelo de CT, o reset e a alteração de endereço, os registos de identidade, o canal de erros / eventos, os auxiliares da frota e
wait_ready()são exclusivos do BASIC; num módulo STD levantamRbAmpNotSupportedError. -
As funcionalidades de energia no dispositivo, ângulo e corrente de arranque são validadas em CPython (
smbus2). O caminho de 16 bits do MicroPython está implementado mas ainda não validado em hardware — prefira CPython para estas funcionalidades até uma nota de versão dizer o contrário.
Assinaturas completas: 09 · Referência da API.
Como detetar a linha do módulo em tempo de execução
No firmware atual não existe um registo explícito de "linha de módulo". Há indicadores indiretos disponíveis através das propriedades do handle:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std indica a linha de módulos (STD vs BASIC). Os outros indicadores (versão do firmware, número de canais, presença de sensor de tensão, variante) descrevem o módulo mas não identificam a linha. dev.read_variant() é o byte de variante BASIC; use a etiqueta SKU na caixa do módulo como fonte de verdade para o produto.
Onde são assinalados os pontos dependentes da linha de módulos na documentação
No texto do pacote e na documentação canónica, as funcionalidades dependentes da linha de módulos são assinaladas explicitamente, por exemplo:
— esta chamada não está disponível num módulo BASIC.
Ou, inversamente, comportamento específico do BASIC:
: o contador dev.energy.wh(ch) é monotónico — a exportação para a rede não é contabilizada. Para medição bidirecional, ver o cenário "Medição bidirecional do lado do mestre" em 06_examples.md, ou use um módulo STANDARD, em que a energia do período é líquida e dev.read_std_energy() tem contadores separados de importação e exportação.
Próximos passos
-
03 · Seleção do sensor de corrente — qual SCT-013 para qual tarefa
-
04 · Ligação — especificidades de hardware para cada host (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Exemplos — cenários para BASIC, incluindo medição bidirecional do lado do mestre
-
09 · Referência da API — a API pública completa
Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/02_tiers.md (v1.6.1)