02 · Níveis dos módulos
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)
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:
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()ereadPeriodSnapshot()usam os valores do próprio módulo (wh_net= importação − exportação), estdReadEnergy()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 comstdReadTotals(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.
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
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 …
: 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:
— isto não está disponível num módulo BASIC.
Ou, inversamente, comportamento específico do 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
-
03 · Seleção do sensor de corrente — qual SCT-013 para cada trabalho
-
04 · Ligação — detalhes de hardware
-
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-arduino · esta página no repositório: docs/02_tiers.md (v1.6.2)