rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub [Edit on GitHub]

01 · Visão geral

rbAmp é um módulo de hardware compacto para medição de precisão de parâmetros da rede AC através da interface I²C. Assenta num microcontrolador com um front-end analógico isolado integrado e calibração de fábrica guardada na flash.

O que é a rbAmp

Visão geral de como a aplicação, a biblioteca, o barramento I²C e os módulos rbAmp se encaixam uns nos outros.

A finalidade principal da biblioteca — monitorizar várias cargas

O components/rbamp foi concebido para funcionar com um grupo de módulos num único barramento I²C em simultâneo, e não para controlar um só dispositivo. O cenário canónico é um módulo principal na entrada da rede mais N módulos em cargas individuais, todos no mesmo barramento, comandados por um só ESP32. A biblioteca fornece um handle de frota: um único objeto através do qual pode procurar no barramento, consultar todos os módulos numa só chamada, obter a potência total consumida e o balanço "entrada − Σ(cargas)", apanhar erros por módulo e — quando necessário — sincronizar instantâneos de período com um comando de difusão.

Os módulos multicanal também são suportados — os I2 / I3 só de corrente (2 / 3 canais de corrente) e os UI2 / UI3 / UI5 / UI7 com tensão (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 CT. É típico de um subquadro em que um único ponto de instalação monitoriza vários circuitos: um módulo dá uma repartição por canal sem um módulo separado em cada um.

Segurança

Detalhe arquitetural importante. Potência e Wh exigem uma variante UI; uma "rede menos soma das cargas" exige um módulo UI em cada carga. As variantes I (I1/I2/I3) medem apenas corrente — não têm tensão, 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" (energia total) é preenchido por um único UI1 na entrada da rede, enquanto o papel de sub-medidor (detalhe de corrente por carga) é preenchido por módulos I2/I3 (ou por UI2 / UI3 / UI5 / UI7 quando for preciso potência e Wh por carga).

Trabalhar com um único módulo é o caso mínimo desta mesma biblioteca: rbamp_handle_t é o bloco de construção sobre o qual a frota assenta. Se tem um módulo no barramento, usa esse mesmo handle diretamente — sem API de frota.

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

Um mestre num barramento I²C partilhado, com um módulo de rede na entrada e módulos de carga secundária em derivações individuais, uma pinça por módulo.

  • 1 módulo na entrada (rede) — consumo total e qualidade da rede.
  • N módulos em cargas individuais — contabilização por canal.
  • Os módulos multicanal também se encaixam neste caso: um 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 da frota rbamp_fleet_poll_all() sondagem tudo; o saldo mains − Σ(sub_loads) revela o "resto" (consumo de fundo, cargas não contabilizadas, fugas).

  • Uma base de tempo mestre partilhada → contabilização de Wh correta, sem desvio entre módulos (ver 02_tiers.md e a secção sobre o relógio de parede do master em 09_api_reference.md).

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 float, V 0…300 V
Tensão de pico U_peak float, V 0…450 V
Corrente RMS I_rms float, A depende do sensor selecionado — ver 03_sensor_selection.md
Corrente de pico I_peak float, A depende do sensor selecionado
Potência ativa P (com sinal em RT) float, W depende do sensor selecionado
Fator de potência PF float −1…+1
Frequência da rede uint8, Hz 50 / 60 Hz (detetado)
P médio sobre um período float, W igual a P
Nota

A potência ativa RT P é sempre com sinal em qualquer linha de módulo (negativo = exportação para a rede). O comportamento do valor médio por período (avg_p[ch] em rbamp_period_snapshot_t) depende da linha do módulo — veja a secção "Linhas de módulos" abaixo e 02_tiers.md.

Ligação

O módulo liga-se ao mestre com quatro fios no lado de BT. A referência de rede única (a entrada de tensão L/N nas variantes UI*) fica atrás de um divisor galvanicamente isolado, e a pinça de CT acopla magneticamente sem contacto elétrico; ver 04 · Cablagem, "Ligação à rede e às pinças de CT" (a tensão da rede pode matar — leia primeiro o aviso aí indicado).

Fio Finalidade
VCC +5 V (4.5..5.5 V), ~15 mA, pico ~25 mA. Regulador e filtragem de bordo
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, dreno aberto em BAIXO ~10 µs a cada ~100 ms

O endereço por omissão é 0x50 (7 bits, intervalo configurável 0x08..0x77); a velocidade recomendada é 50 kHz no ESP32 (ver a secção sobre a disciplina de repetição + sanidade abaixo). Arranque a frio até à primeira medição válida ~250 ms.

As regras completas (comprimento do barramento, recomendações de pull-up num barramento multimódulo, diagramas de ligação para os vários alvos ESP32) estão no capítulo 04 · Ligação.

Linhas de módulos (folha de consulta rápida)

Os módulos BASIC e STANDARD (STD) estão a ser fornecidos. O BASIC segue a lógica de um contador mecânico clássico — contabilização unidirecional (apenas consumo); o STD mantém contadores de energia com sinal:

Nível Potência RT P Acumulador por período avg_p[ch] Contador de Wh do componente
BASIC com sinal (negativo = exportação para a rede, visível em tempo real) cada janela de 100 ms da potência ativa média é limitada a max(P, 0) antes de ser somada ao acumulador do período monotónica — contabilização apenas de consumo
STANDARD (STD) com sinal; também potência reativa e aparente bancos de instantâneos, ou diferenças de contadores — a exportação é mantida (importação e exportação contadas separadamente) valor líquido com sinal (negativo = exportação líquida)

Para detalhes, veja o capítulo 02 · Linhas de módulos. Ao nível do componente usa-se o mesmo handle rbamp_handle_t independentemente do nível — rbamp_begin() deteta a linha do módulo (rbamp_line()); as diferenças aparecem nos valores que o módulo devolve e nas chamadas rbamp_std_* extra que um módulo STD oferece.

Nota

Contabilização bidirecional no BASIC: rbamp_energy_wh(dev, ch) no nível BASIC dá apenas o consumo. Se precisar de contabilizar a exportação em separado, amostre a potência RT rbamp_read_power(dev, 0, &p) a ~10 Hz e separe você mesmo as amostras positivas e negativas em duas variáveis acumuladoras. Veja o exemplo em 06_examples.md (Cenário 9, "Medição bidirecional do lado do master").

O que faz este componente

Linha temporal de janelas de medição de 100 ms consecutivas, dos pulsos opcionais de pronto dos dados e de um instantâneo de período disparado pelo master.
A sua principal função é ocultar a troca de protocolo e poupar a aplicação do trabalho de lidar com registos, ordem dos bytes e tempos de estabilização pós-comando. Além disso, o componentecalcula a energia (Wh)— o módulo devolve apenas a potência média por período, e a integração é feita pelo mestre através deesp_timer_get_time().

O componente também trata da contabilização do período: tira um instantâneo, aguarda que o módulo estabilize, verifica que o instantâneo é válido e integra Wh contra o relógio mestre (rbamp_read_period_snapshot() e rbamp_energy_wh(), ver 05 · Arranque rápido Passo 5). A comparação ao nível dos registos ("sem o componente"), o diagrama de arquitetura, os diagramas de interação e a tabela de mapeamento estão em 09 · Referência da API, apêndice "Por baixo do capô".

Registo e Kconfig

Ao contrário da biblioteca Arduino, onde o fluxo de log é configurado em tempo de execução (setLogStream(&Serial)), aqui usa-se o padrão habitual do ESP-IDF: o componente regista sob a etiqueta "rbamp" via esp_log. O nível de log é compilado através da escolha Kconfig CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, INFO por omissão). Com NONE as strings de log são removidas por completo do binário.

O filtro em tempo de execução também funciona (através de esp_log_level_set("rbamp", ...)), mas está limitado superiormente pelo nível de compilação.

Seis símbolos CONFIG_RBAMP_* estão disponíveis em idf.py menuconfig → Configuração do componente [Component config] → rbAmp client:

Símbolo Finalidade Predefinido
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ Frequência SCL para o barramento partilhado 50000 (50 kHz)
CONFIG_RBAMP_I2C_TIMEOUT_MS timeout de envio/receção 100 ms
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS tentativas de repetição por leitura de um byte 3
CONFIG_RBAMP_NACK_RETRY_GAP_MS intervalo entre tentativas de retentativa 5 ms
CONFIG_RBAMP_DISABLE_ENERGY remover o acumulador de Wh da compilação n
CONFIG_RBAMP_LOG_LEVEL_* nível de compilação das strings de log INFO

Para mais detalhes, veja 09 · Referência da API, secção "Configuração em tempo de compilação".

O que vem a seguir


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