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

01 · Visão geral

Cadeia de sinal do rbAmp: sensor → módulo → I²C → mestre → cloud / Home Assistant

O que é a rbAmp

O rbAmp é um módulo de hardware compacto para medição de precisão de parâmetros da rede CA. Do ponto de vista de quem integra, é um escravo I²C comum: aplica alimentação, lê um registo e obtém um valor pronto a usar em unidades físicas. Não é necessário processamento de sinal do lado do mestre. A calibração de fábrica é feita uma vez na produção e guardada na flash do módulo; ao utilizador resta apenas escolher o modelo de pinça de CT (ver 03_sensor_selection.md) e ligar o barramento.

Fluxo de dados (em uma linha)

Fluxo de dados do componente ESPHome: rede, pinça CT, módulo rbAmp, I²C, componente rbamp, publish_state() e Home Assistant.

O argumento-chave: as grandezas físicas chegam do módulo prontas a usar. Do lado do ESP32 não há processamento de sinal, tabelas de calibração nem cálculos de RMS/potência. O componente ESPHome é um cliente I²C leve + um acumulador de energia + uma camada de publicação para o HA. Não é necessário nenhum lambda: para o funcionamento básico.

rbAmp no ecossistema ESPHome

Se já usou os contadores de energia incorporados (pzemac por UART, atm90e32 por SPI, cse7766 por UART), isto segue exatamente a mesma estrutura. O componente rbamp é um "bom cidadão" do ESPHome: usa o transporte i2c: standard, a sintaxe sensor.platform: rbamp standard, slots de sensor standard com device_class / state_class / unit_of_measurement, e suporta o conjunto completo de filtros e propriedades de sensor.

Compare a anatomia (o modelo mental é idêntico):

YAML
# ATM90E32 (SPI meter) — shown for comparison only, not part of an rbAmp config:
spi:
  clk_pin: GPIO18
  miso_pin: GPIO19
  mosi_pin: GPIO23

sensor:
  - platform: atm90e32
    cs_pin: GPIO5
    voltage_a:
      name: "Mains Voltage"
    power_a:
      name: "Mains Power"
YAML
# rbAmp (I²C meter) — a separate file, do not paste both:
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz

rbamp:
  id: meter1
  address: 0x50

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:                       # power needs voltage AND current declared
      name: "Mains Current"
    power:
      name: "Mains Power"

As únicas diferenças são o transporte (i2c: em vez de spi:) e o facto de rbamp: ser declarado como bloco separado (precisa de um id: + address: para um barramento com vários módulos). Tudo o resto é ESPHome normal: os nomes dos slots (voltage, current, power, energy, frequency, power_factor) são reconhecíveis, e a personalização (name, update_interval, accuracy_decimals, filters:) funciona como de costume. Para um exemplo de personalização detalhado, veja 06_examples.md §1.1 "UI1 com personalização — todos os ajustes padrão do ESPHome".

Implementação canónica — uma frota multi-módulo

O principal caso de uso do rbAmp no ESPHome é monitorizar várias cargas a partir de um único mestre ESP32. Uma casa, uma oficina ou um quadro tem tipicamente uma alimentação principal e várias derivações: um termoacumulador, um ar condicionado, um VE, divisões individuais. Um rbAmp UI1 é colocado na alimentação e conta a potência total + energia; vários módulos rbAmp I2/I3 são colocados nas derivações e contam apenas as correntes de cada canal.

Todos os módulos vivem num único barramento I²C do ESP32 — cada um com o seu endereço da gama 0x50..0x77. O componente suporta MULTI_CONF = True, por isso um único ficheiro YAML pode declarar vários blocos rbamp: e publicá-los todos como conjuntos de entidades independentes no Home Assistant.

Um módulo rbAmp na alimentação da rede e um por sub-carga partilham um único barramento I²C até ao mestre, cada pinça no fio L da respetiva derivação.

Neste cenário o ESP32 é o único mestre: emite uma difusão partilhada de instantâneo General-Call quando fleet_gc_enable: true, e todos os módulos iniciam de forma atómica um novo período de acumulação num único instante do fio. Isto proporciona sincronização apertada entre subcontadores — as somas dos canais coincidem com as somas da alimentação dentro da duração de um único período.

Uma configuração de módulo único (UI1 na rede, sem sub-contadores) é o caso mínimo, não o canónico. Na v1.3 ambas são válidas; a configuração multi-módulo é recomendada logo no primeiro capítulo da documentação, porque 80% das implementações no terreno são exatamente essa.

O que mede

Grandeza Slot YAML Gama Precisão típica
Tensão RMS voltage 0..300 V ±0.5%
Corrente RMS (por canal) current / current_1 / current_2 0..100 A (depende do SKU) ±0.5..1% (módulo)
Potência ativa (com sinal) power / power_1 / power_2 ±23 kW ±1% (módulo)
Fator de potência (com sinal) power_factor / power_factor_1 / power_factor_2 −1..+1 ±0.01 com PF ≈ 1 (carga resistiva) com sensores SCT-013 de calibre 10 A e superiores; o desfasamento próprio do sensor de 5 A acrescenta até ~0.015 de erro de leitura — uma carga puramente resistiva lê ~0.985–0.993
Potência reativa (sem sinal, √(S² − P²), inclui distorção; sem precisão declarada) reactive_power / reactive_power_1 / reactive_power_2 igual a P —
Potência aparente apparent_power (apenas CH0; para CH1/CH2 use um sensor de modelo do HA, ver Integrações DIY §6) igual a P ±2%
Frequência da rede frequency 50 / 60 Hz (detetado no BASIC) —
Energia acumulada (Wh) energy / energy_1 / ... (por canal); energy_total / energy_exported_total / energy_net (STANDARD (STD), todos os canais) 64-bit depende da precisão de P
Energia reativa (varh) reactive_energy / reactive_energy_exported (STANDARD) 64-bit —
Nota

Estes são os números do próprio módulo. O que lê é o módulo mais o sensor que instala, pelo que o total depende do sensor e do seu calibre: os limites mínimos detetáveis, os limites legíveis e as classes de precisão por calibre para a família SCT-013 estão publicados na tabela de precisão BASIC. Módulos com um sensor CT fornecido em par de fábrica, e módulos STD, são especificados separadamente nessa tabela.

Existem slots para até sete canais de corrente (current_3 ... current_6 e os power_N, energy_N, power_factor_N correspondentes nas variantes de mais canais).

Todas as grandezas instantâneas são atualizadas autonomamente pelo módulo, com um passo de ~100 ms. Nos módulos BASIC a acumulação em Wh é feita pelo ESP32 com base na potência média devolvida pelo módulo no intervalo entre duas chamadas update(); nos módulos STANDARD o componente acumula os contadores de energia do próprio módulo. O componente ESPHome oculta estes protocolos — o utilizador vê apenas entidades de sensores prontas a usar no Home Assistant.

O que o componente ESPHome acrescenta

  • Sensores HA prontos a usar — cada slot já tem o seu device_class, state_class e unidades definidos. O sensor energy aparece de imediato no painel de Energia, sem configuração manual.
  • Um YAML para ambas as linhas de módulos — no arranque o componente identifica se está ligado um módulo BASIC ou STANDARD e obtém o número de canais, a variante e as funcionalidades do próprio módulo. topology: não é necessário. As chaves que só se aplicam a uma geração são ignoradas, com uma linha de registo, na outra.
  • Energia no próprio dispositivo (STANDARD) — o módulo mantém os seus próprios contadores acumulados; o componente acumula-os, pelo que os totais sobrevivem a reinícios do ESP32 e do módulo e se mantêm monotónicos. Sensores de totais gerais: energy_total, energy_exported_total, energy_net, reactive_energy, reactive_energy_exported. start_current_ua: define a corrente abaixo da qual um canal não conta energia.
  • Persistência de Wh na NVS — a energia total é escrita na flash do ESP32 a cada 5 minutos (e no encerramento limpo, para que um reinício ou OTA não perca o último intervalo) e restaurada antes do primeiro publish_state. O Home Assistant nunca vê um zero momentâneo após um reinício e nunca o interpreta como reposição de contador.
  • Configuração declarativa de sensores — duas linhas YAML (sensor_class: + ct_models: para UI3, ou ct_model: para UI1) fixam a família e o modelo de CT para cada canal. Os coeficientes de fábrica são carregados automaticamente pelo módulo — sem passos de calibração na sequência de arranque.
  • Calendarização de consultas através de PollingComponent::update() com um update_interval configurável (60 s por predefinição).
  • Cadências de leitura RT e de instantâneo desacopladas (v1.4+) — a chave opcional latch_interval: permite que o ciclo instantâneo → integração de Wh corra na sua própria cadência, enquanto update_interval: continua a controlar a frequência com que o componente ESPHome lê o bloco em tempo real V/I/P/PF/Q. Uso típico: update_interval: 3s + latch_interval: 60s — valores frescos no painel a cada 3 s, carga de instantâneo no barramento apenas uma vez por minuto. A integração de energia não adiciona erro próprio além da precisão de potência ativa do módulo (a integração do lado do mestre usa o dt de relógio de parede real entre eventos de instantâneo).
  • Resiliência a NACK — uma disciplina em três camadas está implementada: 50 kHz por predefinição, repetição por byte e um filtro de sanidade para NaN/Inf. Detalhes abaixo.
  • Atribuição de endereço numa única passagem — a chave new_address: altera o endereço I²C do módulo num único ciclo de arranque. Na firmware v1.3 funciona em modo de produção, sem controlo de provisionamento de fábrica (commit de endereço em duas fases, detetado automaticamente). Útil para configuração em lote de um conjunto de dispositivos depois de instalados num quadro.
  • Barramento com vários módulos — MULTI_CONF = True permite declarar vários blocos rbamp: num único ESP32 e fazer polling a todos por turnos.
  • Sincronização GC da frota (v1.3) — a chave fleet_gc_enable: true ativa a receção da difusão de instantâneo GC do ESP32. Todos os módulos com esta flag e um group_id: correspondente iniciam um novo período em simultâneo. Condicionado por capacidade; no firmware legado regista um aviso e salta sem aplicar. Apenas módulos BASIC.
  • Superfície de identidade (v1.3) — os métodos públicos get_variant_str() / get_capability_hex() / get_uid_hex() / get_firmware_version() / get_last_error_str() são acessíveis a partir de lambda: e através de um text_sensor.platform: template. Permitem apresentar no HA a variante atual do módulo (UI1/UI3/I2…), o bitmap de capacidades, o UID e a versão do firmware.
  • Arranque de ler-comparar-escrever (v1.3) — sensor_class: / ct_model: / ct_models: só são escritos na flash se o valor pedido for diferente do guardado. A reescrita de configuração no arranque desce de ~2.8 s (instalação a frio do UI3) para ~0 ms numa configuração estável. O antigo conselho de "remover ct_model: do YAML depois de verificar" está obsoleto — a configuração é idempotente.
  • Proteção da calibração de fábrica (v1.8.1+) — num módulo calibrado em par com o seu próprio sensor incorporado (WIRED_CT / BUILTIN_CT), uma alteração de classe ou de modelo a partir do YAML é recusada com uma linha de registo. A opção de serviço ct_model_force: true sobrepõe-se deliberadamente.
  • A comutação de calibre SCT mantém a precisão (v1.9) — selecionar outro calibre SCT-013 via ct_model: mantém a calibração de fábrica por unidade: na firmware até 1.4.19 o componente conclui a comutação com o reinício necessário do módulo e escala as leituras; firmware mais recente faz isto no módulo.

Arquitetura

A cadeia rbamp-esphome, desde a rede elétrica e a pinça de CT, passando pelo módulo rbAmp e pelo componente ESPHome no ESP32, até ao Home Assistant.

O motor de medição vive no módulo; o ESP32 atua como ponte para o HA. Nos módulos BASIC, as Wh são integradas no ESP32 com o seu próprio relógio, o que mantém a acumulação consistente entre vários módulos. Os módulos STANDARD mantêm eles próprios contadores de energia acumulada e o ESP32 acumula-os.

Fluxo de dados dentro de um único update()

A descrição abaixo é o fluxo BASIC. Num módulo STANDARD o ramo instantâneo é o mesmo; o ramo de período é substituído por uma leitura coerente dos contadores de energia do módulo, cuja diferença face ao snapshot anterior é somada aos totais acumulados (sem passo de snapshot).

Cada chamada update() num módulo BASIC executa dois ramos em paralelo:

Janelas de medição do módulo a correr no seu próprio relógio, e os passos update() do ESP32: comando de instantâneo, aguardar 50 ms, ler o instantâneo, leitura RT, publicar.

Ramo 1 — valores instantâneos (bloco RT)

  1. Verifique o registo de estado. Se o módulo estiver ocupado (arranque, janela de escrita em flash), salte sem escrever.
  2. Para cada sensor RT declarado, lê um float32 do registo correspondente.
  3. Filtro de sanidade std::isfinite() — descarta NaN/Inf, que podem surgir de rasgos ao ler registos não atómicos.
  4. sensor->publish_state(val).

No firmware v1.3, o bloco de valores instantâneos (U / I / P / PF / Q para todos os canais declarados) é obtido numa única leitura em rajada com auto-incremento de leitura — uma fase de endereço seguida dos bytes do bloco. Se a rajada falhar ou o firmware não suportar a capacidade, o componente recorre a leituras por registo (4 transações por float, cada uma com a sua própria fase de endereço). A escrita com auto-incremento não é suportada; as escritas por registo são sempre byte a byte.

Ramo 2 — medição por período (acumulação de energia)

  1. Registe t_latch = millis().
  2. Envie o comando de snapshot — fecha o período de acumulação atual e abre imediatamente o seguinte. Uma única transação fecha e abre; nenhuma amostra se perde na fronteira.
  3. Após 50 ms (um timeout não bloqueante), leia o indicador de validade. Se o módulo ainda não tiver terminado a integração (consulta mais rápida do que o período de integração, ou um snapshot obsoleto), salte — o ciclo seguinte apanha a janela perdida.
  4. Leia a potência ativa média do período para cada canal.
  5. E_Wh[ch] += avg_p_W[ch] × (t_latch − last_latch_ms_) / 3_600_000.
  6. Atualize last_latch_ms_ apenas após êxito em todos os canais.
  7. Guardar na NVS se tiverem passado mais de 5 minutos desde a última gravação.

O primeiro instantâneo após o arranque repõe o acumulador do módulo e calibra o relógio mestre; o seu resultado é descartado através da flag primed_.

Persistência de energia na NVS

Os valores acumulados são guardados na estrutura RbAmpPrefData (total por canal para até sete canais + exportação por canal para os canais 0..2):

C++
struct RbAmpPrefData {
  double energy_total_wh[7];
  double energy_export_wh[3];
} __attribute__((packed));

Nos módulos STANDARD os acumuladores de total geral e reativos (energy_total, energy_exported_total, reactive_energy*) vivem num segundo slot NVS separado, pelo que os valores por canal não são afetados por uma atualização. Ambos os slots são escritos a cada 5 minutos e no encerramento limpo (reinício / OTA).

A chave NVS deriva do ID do componente em XOR com RBAMP_PREF_VERSION (0x52424D31 = "RBM1"). Se a estrutura alguma vez mudar, incrementar a constante de versão descarta silenciosamente os dados obsoletos, em vez de os interpretar mal.

No arranque, o setup() restaura os totais antes do primeiro update(). Se o componente publicasse primeiro 0 Wh e depois saltasse para o valor guardado, o Home Assistant interpretaria o salto como uma reposição do contador e iniciaria um novo segmento de histórico. Restaurar antes da primeira publicação evita isto.

A frequência de gravação é regida por duas condições:

  • Por tempo — a cada 5 minutos (SAVE_INTERVAL_MS = 300000).
  • Por evento — após cada ciclo de integração completo bem-sucedido (todos os canais lidos sem NACK) e num encerramento limpo.

A pior perda de dados numa falha súbita de energia do ESP32 são os 5 minutos de energia acumulada. Com uma carga média de 60 W, isso são 5 Wh — abaixo da resolução da barra diária do painel de Energia.

Desgaste da NVS — a flash pode "gastar-se"?

Cada gravação escreve ~16 bytes na secção NVS do ESP32. A camada NVS do ESP-IDF agrupa as pequenas escritas num único bloco e apaga uma página (4 KB) apenas quando o bloco está cheio. Num ciclo de 5 minutos:

Métrica Valor
Poupa por dia 288
Gravações por ano ~105120
Tamanho de escrita ~16 bytes
Tamanho de página NVS 4096 bytes
Apagamentos de página por ano ~411 (≈ 105120 × 16 ÷ 4096)
Limite de ciclos de apagamento (datasheet da flash NOR do ESP32) 100000 ciclos
Tempo até falha (TTF) ~240 anos por página NVS

A NVS do ESP-IDF executa ainda nivelamento de desgaste entre as páginas NVS disponíveis (a partição predefinida tem 4 páginas), o que multiplica o TTF por ~4×. Conclusão prática: o desgaste da NVS com um ciclo de gravação de 5 minutos não é um fator limitante — o hardware ficará obsoleto primeiro.

Quando vale a pena reduzir a frequência: se um utilizador forçar um SAVE_INTERVAL_MS abaixo do predefinido (por exemplo 30 s) através de código próprio, recalcule o TTF com a mesma fórmula. Um limite inferior seguro para 10 anos de funcionamento é ~30 s.

Disciplina de NACK

As placas ESP32 com o driver i2c_master do ESP-IDF v5 (que o ESPHome, o arduino-esp32 v3.x e o MicroPython em ESP32 usam todos) fazem periodicamente NACK às leituras do módulo a 100 kHz — em cerca de 20% das transações. O mesmo módulo, mas com outro mestre (por exemplo outro MCU de 32 bits ou um Raspberry Pi), dá 0% de NACK. Logo o problema está do lado do mestre, não do módulo. Os detalhes estão na referência da API em "Disciplina elétrica I²C".

Há uma segunda complicação: quando i2c_master_transmit_receive() devolve ESP_FAIL devido a um NACK, o driver IDF v5 não põe a zero o buffer do utilizador. Os dados da transação anterior permanecem. Alguns destes padrões obsoletos parecem floats plausíveis (por exemplo 0x3C 0x2F 0xFB 0x3F → 1.962 V) e passam uma verificação ingénua de isfinite().

O componente implementa três camadas de mitigação:

Camada Implementação Efeito
Barramento a 50 kHz por predefinição frequency: 50kHz no bloco YAML i2c: Reduz a taxa de NACK em ~5× empiricamente
Repetição por byte 3 tentativas, pausa de 5 ms, em cada byte de cada float32 Limpa um NACK transitório antes de os dados serem usados
Filtro de sanidade permissivo std::isfinite() sem limites físicos rígidos Apanha NaN/Inf/denormais do buffer obsoleto; deixa passar valores-limite válidos (quebra de tensão, desligamento)

Com as três camadas ativas, o componente atinge > 99% de leituras válidas na bancada a 50 kHz, o valor recomendado. As firmwares v1.1 e v1.3 reforçaram a janela de recuperação I²C do módulo, mas 50 kHz continua a ser a definição recomendada em mestres baseados em ESP-IDF, porque a interação de temporização do driver persiste a 100 kHz.

A família de bibliotecas rbAmp

Este componente é um membro da família multiplataforma de bibliotecas cliente rbAmp. Todas implementam o mesmo protocolo de fio (referência da API).

Plataforma Repositório
ESPHome (este componente) rb-amp/rbamp-esphome
Arduino / arduino-esp32 rb-amp/rbamp-arduino
ESP-IDF rb-amp/rbamp-esp-idf
Python (CPython + MicroPython) rb-amp/rbamp-python

Todas as bibliotecas usam as mesmas convenções de fio — escritas byte a byte com leitura em rajada opcional, a mesma máquina de estados de instantâneo de medição por período, a mesma deteção de variante SKU no arranque e os mesmos códigos REG_ERROR. O código de qualquer uma destas plataformas pode ser portado para outra por tradução sintática mecânica — a lógica do protocolo é idêntica. Ver 09 · Referência da API para o mapa de registos canónico.

SKUs suportados

Variante Canal de tensão Canais de corrente Potência Slots ESPHome disponíveis
UI1 sim 1 sim voltage, current, power, energy, frequency, power_factor, reactive_power, apparent_power
UI2 sim 2 sim + current_1, power_1, energy_1, power_factor_1, reactive_power_1
UI3 sim 3 sim + current_2, power_2, energy_2, power_factor_2, reactive_power_2
I1 não 1 não current, frequency
I2 não 2 não + current_1
I3 não 3 não + current_2

Os módulos com mais de uma entrada de tensão usam os slots faseados (voltage_a/b/c, current_a/b/c, ...) — ver 09 §2.2; os dois grupos não podem ser misturados num mesmo bloco sensor:.

Nas variantes apenas de corrente, os slots power, energy e power_factor exigem um slot voltage declarado (verificado pelo validador do esquema) — declare-os apenas nos SKUs UI*.

O que vem a seguir

  • 02_tiers.md — as linhas de módulos BASIC / STANDARD (STD) e quais as chaves YAML disponíveis em cada uma
  • 03_sensor_selection.md — escolher a pinça CT e o comportamento das chaves ct_model: / ct_models:
  • 04_hardware.md — pinout GPIO, pull-ups, o barramento multi-módulo

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