rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub (Edit on GitHub)

02 · Níveis dos módulos

As linhas de módulos BASIC e STANDARD (STD) lado a lado: energia no mestre para o BASIC, no módulo para o STD.

O que é uma linha de módulos

Verifique a etiqueta do seu módulo; dev.line() indica a linha após begin().

A rbAmp existe em linhas de módulos: BASIC e STANDARD (STD). Uma linha de módulos é um emparelhamento completo de revisão de hardware e firmware, não uma flag de software. Passar de uma linha para outra exige uma troca física de SKU, não uma atualização de firmware.

Do ponto de vista da biblioteca e do seu código: uma só classe RbAmp serve ambas as linhas comercializadas. begin() deteta se um módulo é BASIC ou STANDARD (STD) e encaminha internamente cada chamada; os métodos comuns (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) funcionam em ambos. A linha STD acrescenta chamadas próprias — potência reativa e aparente, leituras de blocos por canal, contadores de energia de vida com sinal — ver 09 · Referência da API.

Estado atual

Os níveis BASIC e a linha STANDARD (STD) são linhas de módulos comercializadas; esta biblioteca suporta ambas (STANDARD (STD) a partir da biblioteca 1.6.0, ver o README).

Nível Comercialização
BASIC ✅ sim
STANDARD (STD) ✅ sim (biblioteca 1.6.0+)

BASIC — nível de entrada para a medição de consumo doméstico

Hardware

Um caminho analógico de custo otimizado, adequado a cargas domésticas típicas. O módulo inclui uma frente analógica isolada, um regulador de alimentação de bordo e calibração de fábrica guardada na flash.

Comportamento do firmware

A lógica de um contador mecânico clássico de disco — 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.readPower(ch) potência RT instantânea, atualizada a cada ~100 ms com sinal — um valor negativo é visível em tempo real (exportação)
PERIOD_AVG_P_W (dentro de readPeriodSnapshot) potência média ao longo do período a média de P de cada janela de 100 ms é limitada a max(P, 0) antes de ser somada ao acumulador do período
dev.energy().wh(ch) Wh acumulados pela biblioteca 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 está ausente do contador Wh da biblioteca no BASIC.

Casos de utilização típicos

  • Habitações sem geração no local (sem painéis solares, turbinas eólicas ou sistemas de baterias)

  • Subcontadores para cargas que apenas consomem (esquentadores, motores, eletrodomésticos)

  • Monitorização do consumo em edifícios onde a medição bidirecional não é necessária

Medição bidirecional no BASIC (lado do mestre)

Contabilidade de energia no BASIC (consumo no módulo, exportação integrada no mestre) e no STANDARD (STD) (contadores de importação, exportação e líquido no módulo).

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.readPower(0) é com sinal, portanto:

C++
double consume_wh = 0.0;
double export_wh  = 0.0;
uint32_t t_prev_ms = millis();

void loop() {
    // Sample RT power at 10 Hz — matches the firmware-commit cadence
    // (100 ms per channel). Faster gives empty repeat reads; slower
    // loses resolution on abrupt load transitions.
    //
    // delay() blocks the loop — incompatible with concurrent work
    // (LCD refresh, MQTT, networking). For sketches with other tasks,
    // replace it with a non-blocking millis() / scheduler pattern.
    delay(100);
    uint32_t t_now_ms = millis();
    float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    float p = dev.readPower(0);
    if (isnan(p)) return;

    double dwh = (double)p * dt_s / 3600.0;
    if (p >= 0) consume_wh += dwh;
    else        export_wh  += -dwh;
}

Um exemplo completo funcional está em 06_examples.md (o cenário BidirectionalEnergy) e em examples/06_BidirectionalEnergy/.

STANDARD (STD) — linha bidirecional

Os módulos STANDARD (STD) são uma linha de módulos comercializada. A biblioteca deteta-os em begin() (dev.line() == RbAmpLine::Std) e usa a mesma ligação e a mesma API comum que o BASIC (ver 04 · Ligação).

O que a linha STD acrescenta

Num módulo STD com contadores de energia persistidos, a API de período/instantâneo e a energia vêm dos próprios contadores do módulo (as imagens STD mais antigas usam os bancos de instantâneos do módulo); o modelo de TC no STD é apenas uma etiqueta e não define qualquer ganho.

  • Energia com sinal: a importação e a exportação são contabilizadas em separado. Nos módulos que mantêm contadores de vida persistidos, dev.energy() e readPeriodSnapshot() usam os valores do próprio módulo (wh_net = importação − exportação), e stdReadEnergy() dá os contadores em bruto (Wh, mWh e, nas imagens que os disponibilizam, µWh / µvarh).

  • Mais grandezas (no BASIC, esta biblioteca não expõe a potência reativa): readReactivePower(ch), readApparentPower(ch), stdReadChannel(ch) (I / P / Q / S / PF / pico numa só rajada) e, quando ativados, valores baseados em harmónicos (THD, fator de potência de deslocamento).

  • Módulos multicanal / multitensão: o número de canais vem do módulo; stdReadVoltage(v), totais por fase com stdReadTotals(k).

  • Diagnóstico e assistência: stdReadHealth(), relógio do módulo, histórico e registo de eventos, identificação por UID, atualização de firmware por I²C.

Tudo isto está descrito chamada a chamada em 09 · Referência da API § API da linha STD.

Dependência da imagem.

Algumas funcionalidades STD dependem da versão da imagem do módulo: contadores de energia de micro-resolução, a corrente de arranque para a energia, os ângulos de fase de tensão e a sequência de fases precisam de uma versão de imagem do módulo de pelo menos 0x0001007B (dev.stdReadImageVersion()); numa imagem mais antiga são reportadas como «não disponível». Chamadas apenas-STD num módulo BASIC devolvem RB_ERR_NOT_IMPLEMENTED.

Casos de utilização típicos

  • Casas com produção solar em telhado
  • Casas com turbinas eólicas
  • Sistemas de armazenamento por bateria
  • Cargas regenerativas
  • Carregamento de VE vehicle-to-grid (V2G)

Como detetar a linha em tempo de execução

Como saber qual a linha de módulos que possui: leia a etiqueta ou chame line() após begin().

C++
if (!dev.begin()) { /* see dev.errorString() */ }

// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line();          // RbAmpLine::Basic / RbAmpLine::Std

// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();

// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();

// Number of current channels
uint8_t channels = dev.channels();

// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant();   // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
Nota

: line() indica se é BASIC ou STANDARD (STD). Os outros indicadores (versão do firmware, número de canais, sensor de tensão, SKU) descrevem o hardware. A etiqueta de SKU na caixa do módulo continua a ser a fonte de verdade para o produto.

Onde os itens dependentes do nível estão assinalados na documentação

Ao longo do texto da biblioteca e da documentação canónica, as funcionalidades dependentes do nível são assinaladas explicitamente, por exemplo:

apenas STANDARD (STD)

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

Ou, inversamente, comportamento específico do BASIC:

BASIC

: o contador dev.energy().wh(ch) é monótono — a exportação para a rede não é contada. Para medição bidirecional veja o exemplo BidirectionalEnergy ou use um módulo STANDARD (STD).

O que vem a seguir


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