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

02 · Linhas de módulos

As linhas de módulos BASIC e STANDARD (STD) e o que cada uma oferece.

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)

O BASIC conta apenas o consumo no módulo, com a exportação tratada no mestre, enquanto o STD mantém contadores acumulados no dispositivo.

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:

Python
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_std para 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 levantam RbAmpNotSupportedError.

  • 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

Como saber em tempo de execução se o módulo ligado é BASIC ou STANDARD (STD).

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:

Python
# 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
Nota

: 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:

Apenas STD

— esta chamada não está disponível num módulo BASIC.

Ou, inversamente, comportamento específico do BASIC:

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


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