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
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.
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
- 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 saldomains − Σ(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 |
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.
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
esp_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
- 02 · Linhas de módulos — que nível para que tarefa
- 04 · Ligação — pull-ups, comprimento do barramento, pinagem da família ESP32
- 05 · Arranque rápido — o seu primeiro projeto a funcionar
- 06 · Exemplos — tutoriais de projetos IDF prontos
- 09 · Referência da API — cada função pública
- 10 · Resolução de problemas — quando algo não funciona
Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/01_overview.md (v1.7.3)