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

01 · Visão geral

Cadeia de sinal desde a pinça de corrente, passando pelo módulo rbAmp e pelo I²C, até ao mestre e depois à cloud ou ao Home Assistant.

O que é a rbAmp

rbAmp é um módulo compacto de hardware para medição de precisão de parâmetros da rede CA através da interface I²C. Tem uma frente analógica isolada integrada 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: ligue a alimentação, leia os registos e obtém valores prontos em unidades físicas. Não é necessário qualquer processamento de sinal do lado do mestre.

A finalidade principal da biblioteca — monitorizar várias cargas

A biblioteca RbAmp para Arduino foi concebida para trabalhar com um grupo de módulos em simultâneo num único barramento I²C, e não para comandar um só dispositivo. O cenário canónico é um módulo principal na alimentação da rede mais N módulos em cargas individuais, todos num barramento, comandados por um único Arduino/ESP32. A biblioteca disponibiliza a classe RbAmpFleet — um único objeto através do qual pesquisa o barramento, consulta todos os módulos com uma só chamada, obtém a potência consumida total e o balanço "alimentação − Σ(cargas)", deteta erros em cada módulo e, quando necessário, sincroniza os instantâneos de período com um comando de difusão.

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 desta mesma biblioteca: a classe RbAmp é o bloco de construção sobre o qual se assenta o RbAmpFleet. Se tiver um módulo no barramento, usa diretamente esse mesmo handle — a API de frota não é necessária.

O cenário dos 80% — alimentação principal + N subcargas

Um módulo na alimentação principal e um módulo por subcarga, todos num barramento I²C partilhado lido por um único mestre.

  • 1 módulo na alimentação da rede — consumo global 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.
  • Uma única chamada fleet.pollAll() consulta tudo; o balanço mains − Σ(sub_loads) revela "o resto" (consumo de fundo, cargas não medidas, fugas).

  • Um carimbo temporal comum do master → medição de Wh correta sem deriva entre módulos (ver 02_tiers.md e a secção sobre o relógio de parede do master em 09_api_reference.md).

Segurança

Detalhe arquitetural importante. As variantes I (I1/I2/I3) medem apenas corrente — não têm tensão, nem potência ativa, nem PF. A energia ativa (Wh) e a potência são calculadas apenas nas variantes UI (que têm uma entrada de tensão). Na implementação canónica, o papel de «contador da rede» (medição tarifária / por período) é desempenhado por uma única UI1 na alimentação da rede; o papel de sub-contador (detalhe de corrente por carga) é desempenhado pelos módulos I2/I3 (ou pelas UI2 / UI3 / UI5 / UI7 quando são precisas potência e Wh por carga).

Para mais detalhes, ver o capítulo 06 · Exemplos, cenário 1 («Rede + N cargas secundárias — o cânone dos 80 %»). Para a API, ver o capítulo 09 · Referência da API, secção «Gestor de frota».

O que a rbAmp mede

Grandeza Tipo Gama
Tensão eficaz U_rms float32, V 0…300 V
Tensão de pico U_peak float32, V 0…450 V
Corrente RMS I_rms float32, A depende do sensor selecionado — ver 03_sensor_selection.md
Corrente de pico I_peak float32, A depende do sensor selecionado
Potência ativa P (com sinal em RT) float32, W depende do sensor selecionado
Fator de potência PF float32 −1…+1
Frequência da rede uint8, Hz 50 / 60 Hz (detetado)
P média do período float32, W igual a P
Nota

O valor RT da potência ativa P é sempre com sinal em qualquer nível de módulo (negativo significa exportação para a rede). O comportamento do valor médio por período (PERIOD_AVG_P_W) depende do nível do módulo — ver a secção "Níveis dos módulos" abaixo e 02_tiers.md.

Ligação

O módulo liga-se ao master com quatro fios no lado de baixa tensão; tudo o que toca na rede elétrica fica dentro da caixa.

Fio Finalidade
VCC +5 V (4.5..5.5 V), corrente ~15 mA, pico ~25 mA. Regulador de bordo e filtragem
GND comum com o mestre (obrigatório)
SDA, SCL I²C, lógica de 3.3 V, tolerante a 5 V. Resistências de pull-up integradas de 4.7 kΩ para 3.3 V
DRDY opcional, LOW em dreno aberto durante ~10 µs a cada ~100 ms

O endereço predefinido é 0x50 (7 bits, intervalo de alteração 0x08..0x77), a 100 kHz (UNO / Mega / STM32 / RP2040) ou 50 kHz (ESP32 / ESP8266); não use 400 kHz. Arranque a frio até à primeira medição válida ~250 ms.

As regras completas (comprimento do barramento, recomendações de pull-up num barramento com vários módulos, esquemas de cablagem com diferentes hosts) estão no capítulo 04 · Ligação.

Níveis dos módulos (resumo rápido)

O nível BASIC implementa uma medição unidirecional (apenas consumo), seguindo a lógica de um contador mecânico clássico; a linha STANDARD (STD) é uma segunda linha de módulos comercializada com energia bidirecional com sinal (importação / exportação):

Nível Potência RT P Acumulador por período PERIOD_AVG_P_W Contador Wh da biblioteca
BASIC com sinal (negativo = exportação para a rede, visível em tempo real) cada janela de 100 ms de P médio é limitada a max(P, 0) antes de ser somada ao acumulador do período monotónico — regista apenas consumo
STANDARD (STD) com sinal importação e exportação contadas em separado (bancos de instantâneos, ou os contadores de vida útil persistidos do módulo) energia líquida = importação − exportação (wh_net, stdReadEnergy())

Os detalhes estão no capítulo 02 · Níveis dos módulos. Ao nível da biblioteca usa-se a mesma classe RbAmp independentemente do nível; as diferenças aparecem nos valores que o módulo devolve.

Nota

Medição bidirecional no BASIC: o dev.energy().wh(ch) do nível BASIC dá apenas o consumo. Se precisar de contabilizar a exportação em separado, amostre a potência RT dev.readPower(0) a ~10 Hz e separe as amostras positivas e negativas em duas variáveis de acumulação por conta própria. Há um exemplo em 06_examples.md (o cenário BidirectionalEnergy).

O que esta biblioteca faz

A função principal é ocultar a troca de protocolo e poupar o esboço do utilizador à rotina de trabalhar com registos, ordem dos bytes e tempos de estabilização após comandos. Além disso, a biblioteca calcula a energia (Wh) — o módulo devolve apenas a potência média do período, e a integração é feita pelo master com o seu próprio relógio.

Nota

A criar para o ESPHome? Use o componente externo em vez desta biblioteca diretamente — integra o protocolo rbAmp nativamente no pipeline YAML do ESPHome.

Sem a biblioteca (acesso direto aos registos)

C++
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);

Com a biblioteca

C++
float u_rms = dev.readVoltage();

Leitura do período — sem a biblioteca

C++
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27);   // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50);                            // settling time after the command

Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
    // snapshot is stale — t_latch_ms must STILL be recorded,
    // otherwise the next snapshot will count Wh over two periods
    t_prev_latch_ms = t_latch_ms;   // <-- this line is easy to forget
    return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
//   float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
//   E_Wh += avg_p × dt_s / 3600.0f;

Leitura do período — com a biblioteca

C++
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
    // snap.avg_p[0] is filled,
    // dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
    // master_dt_ms is accounted for and saved for the next cycle.
}

Internamente, a biblioteca garante:

  • Um tempo de estabilização de 50 ms após CMD_LATCH_PERIOD, e uma leitura correta do instantâneo (instantâneo atómico do lado do módulo).

  • Verificação da flag PERIOD_VALID antes de ler.

  • Registar a hora pelo relógio do master mesmo num instantâneo desatualizado (protege contra a dupla contagem de Wh no período seguinte).

  • Acumulação de Wh por canal em dupla precisão.

  • Carregamento automático dos coeficientes de calibração quando um sensor de corrente é selecionado via setSensorClass(class) + setCTModel(code) — o utilizador não precisa de conhecer os registos NF/GAIN.

Quando usar a biblioteca e quando usar o acesso direto aos registos

Tarefa Biblioteca Acesso direto aos registos
Leitura de U / I / P / PF / frequência ✅ apenas para depuração com um analisador lógico
Medição de energia por período ✅ apenas se os Wh forem guardados fora da biblioteca (por exemplo, numa base de dados do lado do mestre)
Vários módulos num mesmo barramento ✅ —
Medição bidirecional no BASIC ✅ (através de leituras RT — ver 06_examples.md) alternativa — ciclo próprio de leituras RT + integração manual
Adaptação a uma plataforma não-Arduino n/a ✅ — ver 09 · Referência da API, a secção «Detalhes do protocolo de fio»
Limite rígido de RAM (AVR Uno) ~42 B por instância RbAmp + 63 B por instantâneo; viável, mas apertado em multimódulo (3 módulos × ~42 B + 3 × 63 B ≈ 315 B já ocupam uma parte notável do orçamento de RAM da aplicação) ✅ se a instância da biblioteca não couber

Para todas as tarefas típicas das primeiras linhas a biblioteca é a escolha certa.

Arquitetura

Onde se situa o seu esboço: esboço, biblioteca RbAmp, Wire (I²C) e o módulo rbAmp no endereço predefinido 0x50.

Diagramas de interação

O fluxo de begin()

Sequência do begin(): leitura da versão, deteção da linha, instantâneo de preparação (descartado), depois pronto.

O primeiro instantâneo é uma preparação (o módulo devolve o que acumulou desde o arranque, o que não serve para a medição tarifária). A biblioteca regista por conta própria que este instantâneo deve ser descartado — o código do utilizador nunca o vê.

O fluxo de readPeriodSnapshot(snap)

Sequência de readPeriodSnapshot(): a biblioteca fecha o período no módulo, lê o instantâneo, integra a energia no relógio do master e devolve o resultado ao esboço.

O instantâneo atómico do lado do módulo garante que cada medição dentro do período cai em exatamente um instantâneo — sem duplicação, sem perdas na fronteira do período.

Correspondência com a API de registos direta

Uma tabela para quem migra do seu próprio trabalho construído sobre acesso direto:

API direta Equivalente via a biblioteca
Leitura manual de 4 bytes + memcpy dev.readVoltage() / dev.readPower(ch)
Wire.write(0x01); Wire.write(0x27); delay(50) dev.latchPeriod(); delay(50) (ou simplesmente dev.readPeriodSnapshot())
Verificar Wire.read(0x07) & 1 dev.isPeriodValid()
A fórmula manual E_Wh += avg_p × dt_s / 3600 dev.energy().wh(0) — atualizado automaticamente
Configuração manual do sensor de corrente através da API de registos direta dev.setSensorClass(class) + dev.setCTModel(code) — as predefinições de fábrica são carregadas automaticamente

O que vem a seguir


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