01 · Visão geral
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
- 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(ouI2/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çomains − Σ(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).
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 |
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.
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.
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)
// 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
float u_rms = dev.readVoltage();
Leitura do período — sem a biblioteca
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
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_VALIDantes 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
Diagramas de interação
O fluxo de begin()
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)
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
- 02 · Níveis dos módulos — qual o nível para cada tarefa
- 04 · Ligação — pull-ups, comprimento do barramento, configuração multimódulo
- 05 · Início rápido — o primeiro sketch funcional
- 06 · Exemplos — percurso pelos esboços prontos a usar
- 09 · Referência da API — todos os métodos públicos
- 10 · Resolução de problemas — quando algo não funciona
Fonte e problemas: rb-amp/rbamp-arduino · esta página no repositório: docs/01_overview.md (v1.6.2)