02 · Linhas de módulos
Os módulos rbAmp vêm em linhas de módulos: BASIC e STANDARD (STD). Uma linha de módulos é um pacote completo de revisão de hardware e firmware, não um sinalizador de software. Passar de uma linha para outra exige uma troca física de SKU, não uma atualização de firmware.
O que é uma linha de módulos
Do ponto de vista do componente e do código do utilizador: um handle e uma API rbamp_* servem as duas linhas de módulos comercializadas. rbamp_begin() deteta se o módulo por trás do handle é BASIC ou STD (rbamp_line()), e as chamadas que só existem numa delas devolvem ESP_ERR_NOT_SUPPORTED na outra. As diferenças aparecem nos valores que o módulo devolve, nas grandezas extra que o módulo STD mede e na forma como o firmware trata os dados (em particular — a exportação para a rede).
Estado atual
Os módulos BASIC e STANDARD (STD) estão a ser fornecidos e são ambos suportados por este componente (versão 1.7.3).
| Linha de módulos | Estado neste componente |
|---|---|
| BASIC | ✅ em distribuição — RBAMP_LINE_BASIC |
| STANDARD (STD) | ✅ em distribuição — RBAMP_LINE_STD |
BASIC — linha de módulos de medição de consumo de gama de entrada
Hardware
Um caminho analógico de custo otimizado, adequado a cargas domésticas típicas. O módulo inclui uma frente analógica isolada, um regulador de alimentação de bordo e calibração de fábrica guardada na flash.
Comportamento do firmware
A lógica de um contador de disco mecânico clássico — a contagem só avança, e a exportação para a rede não é subtraída.
Os três «níveis» dos valores de potência ativa comportam-se de forma diferente:
| Sinal | Significado | Comportamento no BASIC |
|---|---|---|
rbamp_read_power(dev, ch, &p) |
potência RT instantânea, atualizada a cada ~100 ms | com sinal — um valor negativo é visível em tempo real (exportação) |
snap.avg_p[ch] (dentro de rbamp_read_period_snapshot) |
potência média ao longo do período | cada janela de potência média de 100 ms é limitada a max(P, 0) antes de ser somada ao acumulador do período |
rbamp_energy_wh(dev, ch) |
Wh acumulados pelo componente | monotónico — apenas consumo; a exportação não é contada |
Por outras palavras: o utilizador vê a exportação na leitura RT, mas o contador de Wh do componente no BASIC não a inclui.
Aplicações típicas
-
Casas sem produção própria (sem painéis solares, turbinas eólicas, sistemas de bateria)
-
Submedidores para cargas puramente consumidoras (esquentadores, motores, aparelhos domésticos)
-
Monitorização do consumo em edifícios onde a medição bidirecional não é necessária
Medição bidirecional no BASIC (lado do mestre)
rbamp_read_power(dev, 0, &p)é assinado, portanto:
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static double consume_wh = 0.0;
static double export_wh = 0.0;
void bidirectional_loop(rbamp_handle_t dev) {
int64_t t_prev_us = esp_timer_get_time();
while (1) {
/* Sample RT power at 10 Hz. Slower polling loses resolution
* on sharp load transitions; faster adds little for typical
* mixed loads with an inverter. */
vTaskDelay(pdMS_TO_TICKS(100));
int64_t t_now_us = esp_timer_get_time();
double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
}
}
Um exemplo completo do padrão está em 06_examples.md, no cenário "Medição bidirecional do lado do master".
STANDARD (STD) — a linha de módulos de medição alargada
Os módulos STD são suportados pela mesma API rbamp_*; rbamp_begin() deteta-os. Para além do que o BASIC oferece, um módulo STD fornece:
-
Energia com sinal. Importação e exportação são grandezas separadas, e o módulo mantém contadores de vida persistidos (Wh / varh, com resoluções mais finas em firmware mais recente). A exportação não é descontada: a energia de um período é a diferença entre duas leituras de contador (
rbamp_std_read_energy()/rbamp_std_energy_delta()), erbamp_energy_wh()transporta um valor líquido com sinal nesses módulos. -
Mais grandezas: potência reativa e potência aparente por canal (
rbamp_read_reactive_power(),rbamp_read_apparent_power(),rbamp_std_read_channel()), totais por fase e globais e — quando a extração de harmónicos estiver ativa — THD e fator de potência de deslocamento. Os módulos trifásicos também reportam os ângulos de fase de tensão e a sequência de fases. -
Mecanismos de período: bancos de instantâneos (oito períodos independentes, temporizados pelo master) nos módulos que os têm, ou diferenças de contadores nos módulos que mantêm a energia no dispositivo. O mecanismo é escolhido em
rbamp_begin()(rbamp_std_info_t.period_source). -
O modelo de CT é apenas uma etiqueta. Num módulo STD o modelo de CT é apenas uma etiqueta e não define qualquer ganho.
- Relógio do módulo, histórico no dispositivo e registo de eventos, estado de saúde e diagnóstico, atualização de firmware por I²C, certificado do dispositivo e atestação.
Tudo isto está documentado em 09 · Referência da API, capítulo "Linha STD". Um exemplo funcional é examples/std_meter/ (ver 06 · Exemplos, Cenário 18).
Comportamento que difere do BASIC
| Tema | BASIC | STD |
|---|---|---|
Exportação em rbamp_energy_wh() |
não contabilizada (monotónica, apenas consumo) | com sinal — líquido de importação e exportação |
| Potência reativa / aparente, THD | não disponível — no BASIC, a potência reativa não é exposta por esta biblioteca (ESP_ERR_NOT_SUPPORTED) |
disponível |
| Fonte do período | instantâneo do acumulador do período | bancos de instantâneos ou diferenças de contadores |
| Relógio do módulo | nenhum | defina-a com rbamp_std_set_time() após cada reposição do módulo |
rbamp_factory_reset() |
suportado | ESP_ERR_NOT_SUPPORTED |
Digest (rbamp_read_digest()) |
suportado no firmware com a capacidade | ESP_ERR_NOT_SUPPORTED |
| Chamadas de período num módulo sem bancos de instantâneos nem contadores | — | ESP_ERR_NOT_SUPPORTED |
Aplicações típicas
- Casas com produção solar em telhado, turbinas eólicas ou baterias
- Cargas regenerativas, carregamento de veículos elétricos V2G
- Instalações que precisam de potência reativa, fator de potência e harmónicos além da potência ativa
Como detetar a linha do módulo em tempo de execução
rbamp_begin():
/* BASIC or STD — available after rbamp_begin() */
rbamp_line_t line = rbamp_line(dev); /* RBAMP_LINE_BASIC / RBAMP_LINE_STD */
/* Full SKU — cached by rbamp_begin(), no bus traffic */
rbamp_variant_t variant = rbamp_variant(dev); /* UI1 / UI2 / ... / I3 / UI5 / UI7 */
/* Voltage-sensing presence (UI* variants vs I*-only) */
bool voltage_hw = rbamp_has_voltage_hw(dev);
/* Number of current channels (1 / 2 / 3 / 5 / 7) */
uint8_t channels = rbamp_channels(dev);
/* Firmware: BASIC — REG_VERSION byte; STD — register-map version */
uint8_t fw = rbamp_firmware_version(dev);
/* STD only: identity, capabilities and the period mechanism */
rbamp_std_info_t info;
if (rbamp_line(dev) == RBAMP_LINE_STD && rbamp_std_info(dev, &info) == ESP_OK) {
/* info.capabilities, info.n_voltage, info.n_current, info.period_source */
}
: rbamp_line() distingue BASIC de STD. Use a etiqueta do SKU no invólucro do módulo como fonte de verdade para o produto exato.
Onde os detalhes dependentes da linha estão assinalados na documentação
No texto do componente e na documentação canónica, as funcionalidades dependentes da linha são assinaladas explicitamente, por exemplo:
— esta função não está disponível no módulo BASIC (ESP_ERR_NOT_SUPPORTED).
Ou, inversamente, comportamento específico do BASIC:
: o contador rbamp_energy_wh(dev, ch) é monotónico — a exportação para a rede não é contabilizada. Para medição bidirecional, veja o cenário "Medição bidirecional do lado do master" em 06_examples.md, ou use um módulo STD.
O que vem a seguir
-
03 · Seleção do sensor de corrente — qual SCT-013 para cada tarefa
-
04 · Cablagem — particularidades de hardware
-
06 · Exemplos — cenários para BASIC, incluindo a medição bidirecional do lado do mestre
-
09 · Referência da API — a API pública completa
Código-fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/02_tiers.md (v1.7.3)