06 · Exemplos
Este capítulo abre com os cenários emblemáticos — os padrões de implementação reais para os quais a biblioteca foi concebida (rede + N cargas secundárias num único barramento, instantâneos sincronizados por GC). Seguem-se os cenários de módulo único — desde um "hello world" mínimo até um registador de deep-sleep alimentado por bateria.
A maioria dos cenários vem como projeto IDF pronto a compilar em examples/, que pode compilar com idf.py -C examples/. O código deste capítulo é uma destilação da lógica-chave, não o projeto completo (bus_cfg / arranque do WiFi / Kconfig são omitidos por brevidade).
| # | Cenário | Dificuldade | Fonte |
|---|---|---|---|
| 1 | Rede + N subcargas: o cânone dos 80 % | médio | examples/fleet_sync/ |
| 2 | Fluxo de provisionamento (virgem → frota) | baixo | (composition) |
| 3 | CT misto multicanal (I3, modelos diferentes) | médio | (composition) |
| 4 | Sincronização GC da frota — sincronismo do período tarifário | médio | examples/fleet_sync/ |
| 5 | Leitura rápida (módulo único) | mínimo | examples/quick_read/ |
| 6 | Contador de Wh num LCD de 16×2 | baixo | examples/lcd_period/ |
| 7 | Monitorização de 3 módulos (sequencial legado) | baixo | examples/multi_module/ |
| 8 | MQTT por canal | médio | examples/mqtt_publisher/ |
| 9 | Medição bidirecional do lado do mestre | médio | (composition) |
| 10 | Balanço energético da casa inteira (3 módulos) | alta | (composition) |
| 11 | Registo por eventos (EMA) | médio | (composition) |
| 12 | Registador CSV local em SPIFFS | médio | examples/spiffs_logger/ |
| 13 | Registador a bateria com deep-sleep | médio | examples/deep_sleep_logger/ |
| 14 | I3 com TC diferente por canal (análise aprofundada de cargas mistas) | médio | (composition) |
| 15 | Submedição: 5×UI1 num barramento partilhado | alta | (composition) |
| 16 | Instantâneo broadcast GC para >8 módulos | alta | (composition) |
| 17 | Filtragem por grupo GC (medição multi-inquilino) | alta | (composition) |
| 18 | Módulo STD: potência reativa / aparente, THD, energia cronometrada pelo mestre | médio | examples/std_meter/ |
O cenário 18 mostra a linha de módulos STD. Os cenários 1–4 são os principais, construídos em torno da implementação canónica da biblioteca. O seu código usa a API de frota e está validado em bancada de testes (uma frota heterogénea UI1+I2+I3). Os cenários 5–13 são de módulo único e padrões de composição; os 14–17 são cenários de frota alargada (aprofundamento das capacidades introduzidas em 1–4). O cenário 7 é o instantâneo sequencial legado por módulo, sem API de frota, mantido para comparação e como caminho de migração.
Todos os cenários assumem que a classe do sensor e o modelo de TC já foram configurados via rbamp_set_sensor_class() + rbamp_set_ct_model() (ver 05 · Arranque rápido, Passo 3). Isto é feito uma vez na instalação — as definições ficam guardadas na flash do módulo e sobrevivem a um reinício.
REQUIRES extra para main/CMakeLists.txt
O componente base puxa esp_driver_i2c, esp_timer, log. Alguns cenários usam componentes ESP-IDF adicionais — acrescente-os ao REQUIRES da sua pasta main/:
| Cenário | REQUIRES extra |
|---|---|
| 1 — Rede principal + N cargas secundárias (frota) | — (apenas rbamp) |
| 2 — Fluxo de provisionamento | — |
| 3 — I3 multicanal com TC mistas | — |
| 4 — Sincronização GC da frota | — |
| 5 — Leitura rápida | — |
| 6 — Contador de Wh no LCD | rbamp (o driver de LCD é um componente separado à sua escolha) |
| 7 — Multimódulo (sequencial legado) | — |
| 8 — MQTT por canal | rbamp mqtt esp_wifi esp_event esp_netif nvs_flash |
| 9 — Medição bidirecional | — |
| 10 — Balanço de energia | — |
| 11 — Registo por eventos | — |
| 12 — Registador SPIFFS | rbamp spiffs |
| 13 — Registador de deep-sleep | rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (se publicar) |
| 18 — Contador STD | — (apenas rbamp) |
Os componentes de rede também exigem nvs_flash_init() em app_main e o arranque do WiFi. Por brevidade, tudo isto é omitido nos excertos abaixo; o projeto completo está sempre em examples/.
Nota importante sobre os excertos abaixo. Cada excerto é uma destilação da lógica-chave, não uma app_main completa. Num código de trabalho, a linha rbamp_handle_t dev é sempre precedida de i2c_master_bus_config_t bus_cfg = {...}; i2c_new_master_bus(&bus_cfg, &bus); rbamp_new(bus, 0x50, &dev); rbamp_begin(dev); (para módulo único) ou rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (para a frota). Quando o trabalho termina — rbamp_del(dev) / rbamp_fleet_destroy(fleet) (omitidos onde a app_main entra num ciclo infinito — o handle vive até o chip reiniciar).
Cenário 1 — Rede + N cargas secundárias (o cânone dos 80%): sistema de medição integrado
Objetivo: a implementação canónica da biblioteca — um sistema de medição coerente sobre uma frota heterogénea, fechado num único ciclo:
-
Descobrir —
rbamp_fleet_scanencontra todos os módulos, verifica a identidade de cada um e elimina endereços em conflito. -
Configurar —
rbamp_configure_channelsdefine a classe do sensor + os modelos de CT por canal + um únicoSAVE_USER_CONFIGfinal, numa só chamada por módulo multicanal. -
Armar GC —
rbamp_fleet_enable_gc_allativa a receção de instantâneos General-Call em todos os módulos da frota. -
Ciclo — a cada tick o master executa um
_gclatchatómico (um instantâneo síncrono em toda a frota), verifica com_check_sync, lê com_poll_all, integra a energia pormaster_dte calcula_total_power+_total_energy_wh.
Este é o exemplo principal do capítulo — mostra a biblioteca completa em funcionamento na configuração canónica. Cada um dos outros cenários (2-17) divide este fluxo em blocos individuais ou acrescenta-lhe integrações de terceiros (LCD, MQTT, SD).
Hardware (validado em HW): uma frota heterogénea de 3 módulos num único barramento, com uma pull-up externa de 4.7 kΩ em SDA/SCL (ver 04 · Ligação, secção "Barramento multimódulo — a topologia principal"):
@0x50— UI1, contador da rede na entrada de serviço (um canal de corrente + tensão).@0x51— I2, um sub-medidor de corrente de dois canais (sem tensão).@0x52— I3, um submedidor de corrente de três canais (sem tensão).
A carga de referência na linha é de ~0.57 A.
Código — ciclo integrado
#include "rbamp.h"
#include "rbamp_fleet.h"
#include "esp_timer.h"
static const char *TAG = "metering";
/* The per-module Wh accumulator lives in the handle (the component
* already integrates by master_dt in rbamp_read_period_snapshot —
* here we only read it). */
static void configure_one(rbamp_handle_t dev) {
if (!dev) return;
uint8_t n = rbamp_channels(dev);
if (n == 1) { /* UI1 mains */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
} else if (n == 2) { /* I2 sub-meter */
const uint8_t models[2] = { 1, 3 }; /* 5A, 30A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 2);
} else if (n == 3) { /* I3 sub-meter */
const uint8_t models[3] = { 1, 3, 6 }; /* 5A, 30A, 20A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 3);
}
}
void app_main(void) {
/* 1) bus + fleet_create — omitted for brevity */
rbamp_fleet_t fleet;
ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));
/* 2) discover */
size_t n_added = 0;
if (rbamp_fleet_scan(fleet, true, &n_added) == ESP_ERR_INVALID_STATE) {
ESP_LOGE(TAG, "bus wedged — see ch.10");
return;
}
ESP_LOGI(TAG, "fleet_scan: %u module(s), %u excluded",
(unsigned)n_added,
(unsigned)rbamp_fleet_excluded_count(fleet));
/* 3) configure per-module (mixed-CT on the sub-meters) */
for (size_t i = 0; i < rbamp_fleet_count(fleet); ++i) {
configure_one(rbamp_fleet_get(fleet, i));
}
/* 4) arm GC across the whole fleet */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "enable_gc_all → %u/%u modules armed",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
/* 5) loop: gclatch → check_sync → poll_all → energy + totals */
rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
while (1) {
rbamp_fleet_gclatch(fleet, /*group=*/0, tick, /*settle_ms=*/50);
size_t n_missed = SIZE_MAX;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_ok = 0;
rbamp_fleet_poll_all(fleet, snaps, status,
RBAMP_FLEET_MAX_MODULES, &n_ok);
/* Energy is accumulated per-handle by the component on each
* period-snapshot read. Here we read the fleet-wide aggregates. */
float p_total = 0.0f;
double e_total = 0.0;
rbamp_fleet_total_power(fleet, &p_total);
rbamp_fleet_total_energy_wh(fleet, &e_total);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "ITER %3u: GC %u/%u in_sync | poll n_ok=%u/%u | "
"P_total=%.1f W E_total=%.3f Wh",
(unsigned)tick,
(unsigned)(n_total - n_missed), (unsigned)n_total,
(unsigned)n_ok, (unsigned)n_total,
p_total, e_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(1000)); /* 1 Hz for a compact summary */
}
}
Saída de bancada (validada em hardware em toda a frota)
INTEGRATED METERING SYSTEM — fleet_scan: 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (mains meter: voltage + 1 current)
module[1] @0x51 channels=2 voltage=no (2-channel current sub-meter)
module[2] @0x52 channels=3 voltage=no (3-channel current sub-meter)
configure_channels(2ch) → mirrors [1 2 -]
configure_channels(3ch) → mirrors [1 2 3]
enable_gc_all → 3/3 modules armed
ITER 1..N: GC in_sync=3/3 skew=0 | poll n_ok=3/3 | P_total≈1260 W | E_total: 2.49 → 4.38 Wh (accumulating)
@0x50 V=226 I=[5.58] P=[1256] (mains)
@0x51 V= — I=[11.30, 3.75] P=[—] (current sub-meter)
@0x52 V= — I=[ 3.73, 1.87, 7.50] P=[—] (current sub-meter; the 3rd input
is unused on this rig,
pickup ≈ zero)
Os valores de bancada ilustram a forma dos dados e o seu fluxo pelo sistema — não a precisão da medição.
Notas para implementação
-
Um só ciclo sincronizado é o sistema inteiro. Em cada tick: um
gclatch(uma única transação I²C General-Call) → todos os módulos iniciam atomicamente o instantâneo do período (check_sync= 3/3, desvio = 0) → umpoll_alllê a frota inteira → agregação. Sem desvio entre módulos a partir de uma cadeia de idas e voltas sequenciais. -
Comportamento de
total_powernuma frota heterogénea. O UI1 dá potência ativa (tem tensão → temP); os I2/I3 são apenas de corrente, por isso a sua contribuição paratotal_poweré zero. Assim, no cânone,total_power≈ a potência do módulo da rede. Para a potência por carga num sub-medidor, calcule-a do lado do master:P_subload[k] ≈ V_mains × I_sub[k](uma aproximação, correta quando os PF são próximos; um sub-medidor apenas de corrente não consegue reportar P exata por carga). -
Energia (Wh) — relógio de parede mestre.
E_totalcresce de forma monótona (2.55 → 6.94 Wh durante a janela de captura de bancada); o componente integra cada período pormaster_dt_ms(esp_timer), e não pelolatch_msdo lado do chip (um temporizador de diagnóstico do módulo que pode ler curto). Um tick espúrio acrescenta0 Whse não tiver decorrido nenhum período novo entre leituras — isto é normal (snap.valid = 0 nesse ciclo). -
Sondagem resistente a falhas (MISS). Se um dos módulos sair do barramento (desconexão, reinício),
poll_allassinala-o comstatus[i] != ESP_OKe continua a consultar os restantes — o mestre não bloqueia. Validado em bancada: um módulo desligado a meio da execução deixou a frota a consultar comn_ok=2/3sem paragem. O mesmo vale paracheck_sync—missed_idxaponta para o primeiro módulo fora de sincronia enquanto os restantes continuam a tirar instantâneos. -
Análise de saldo. No cânone dos 80%:
balance = P_mains − Σ(V_mains × I_sub[k])— uma estimativa de "o resto" (consumo de fundo, cargas não contabilizadas). O código dirigido percorre a frota, separando o handle da rede (o que temhas_voltage = true) dos sub-handles (todos os outros). -
Correntes por canal → desagregação de cargas. Através de
fleet_poll_allo master vê todos os canais de corrente de uma vez (1+2+3 = 6 na nossa frota de bancada), sem leitores separados por módulo. -
CT misto num módulo de 3 canais. Use a versão atual da biblioteca; os espelhos [1 2 3] no I3 estabilizam conforme configurado. A ordem pela qual os canais são associados não importa.
-
Latência de consulta para dimensionamento em produção (medido em HW). Na bancada a 50 kHz I²C: 2 módulos — média
89.4 ms(mín. 89.4 / máx. 89.6); 3 módulos — média112.1 ms(mín. 112.1 / máx. 112.3). Isto é ≈ 22–23 ms por módulo adicional, linear e com jitter muito baixo (mín. ≈ máx.). Umfleet_poll_allagrupado é determinístico num barramento limpo. Uma frota de 3 módulos (~112 ms) cabe num intervalo de consulta de 200 ms — ou seja, uma taxa de consulta de 5 Hz é alcançável (a cada segunda janela de módulo de 100 ms) sem saturar o barramento. O orçamento completo do barramento (quando a frota excede o intervalo de consulta) está na tabela de 04 · Cablagem, secção "Orçamento energético do barramento".
Cenário 2 — Fluxo de provisionamento (virgem → frota)
Objetivo: mover um módulo novo do seu endereço de fábrica 0x50 para um endereço de trabalho e acrescentá-lo a uma frota existente, persistindo a sua configuração (modelos de TC, etiqueta) na flash.
Hardware (validado em HW): um módulo virgem no 0x50 de fábrica (HW_VARIANT de 3 canais). O provisionamento move-o para o endereço 0x52 e grava a configuração na flash.
#include "rbamp_fleet.h"
#include "rbamp.h"
void provision_new_module(i2c_master_bus_handle_t bus,
rbamp_fleet_t fleet,
uint8_t desired_addr,
const char *label /* nullable */) {
/* PRECONDITION: exactly one virgin at 0x50 on the bus.
* MUST one-virgin-at-a-time — see ch.04 + ch.10. */
rbamp_handle_t dev = NULL;
esp_err_t err = rbamp_provision(bus, desired_addr,
/*save_config=*/true, &dev);
if (err == ESP_ERR_NOT_FOUND) {
ESP_LOGE("prov", "nobody answers at 0x50 — check VCC/I2C");
return;
}
if (err == ESP_ERR_INVALID_STATE) {
ESP_LOGE("prov", "0x50 or 0x%02X is already taken — "
"discipline violation? see ch.10",
desired_addr);
return;
}
if (err != ESP_OK) {
ESP_LOGE("prov", "provision fail: %s", esp_err_to_name(err));
return;
}
ESP_LOGI("prov", "provisioned virgin → 0x%02X (+saved)", desired_addr);
/* Label for fleet iterations (optional). */
if (label) rbamp_write_label(dev, label);
/* Bind the sensor class + CT model + one more SAVE_USER_CONFIG. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
/* Add to the fleet — from here the module is polled the usual way. */
rbamp_fleet_add(fleet, dev);
ESP_LOGI("prov", "module @0x%02X added to the fleet", desired_addr);
}
Saída de bancada (caminho de sucesso validado em hardware):
before: present(0x50)=yes present(0x52)=no
virgin @0x50: variant=3-channel, channels=3
rbamp_provision(→0x52, save_config=true) = ESP_OK
(lib log: "provisioned virgin → 0x52 (+saved)")
post: handle now answers @0x52, is_provisioned=true
after: present(0x50)=no present(0x52)=yes
is_provisioned devolve true após uma chamada bem-sucedida. Num módulo acabado de sair de fábrica (que nada tocou) o is_provisioned anterior será false — este é o estado normal 0xFB (ERR_FLASH_PARAMS_BAD) descrito em 10 · Resolução de problemas, e não é fatal.
Caminhos de falha
| Erro | Condição | Recuperação |
|---|---|---|
ESP_ERR_NOT_FOUND |
Ninguém responde em 0x50 |
Verifique se o módulo virgem está fisicamente ligado e alimentado (VCC); faça a verificação do barramento (10 · Resolução de problemas). |
ESP_ERR_INVALID_STATE |
Foi detetado um conflito em 0x50 ou desired_addr; módulos diferentes respondem de forma idêntica |
Violação da disciplina — mais de um virgem no barramento. Desligue a alimentação + desligue fisicamente todos menos um + tente de novo (ver o caminho de recuperação em 10 · Resolução de problemas). |
ESP_ERR_TIMEOUT |
O commit em duas fases foi concluído, mas o módulo não apareceu no novo endereço dentro da janela de arranque | Desligue e volte a ligar o módulo e tente de novo. Se persistir — problema de ciclos de flash. |
ESP_ERR_INVALID_ARG |
desired_addr fora de 0x08..0x77 |
Use um endereço válido de 7 bits. |
Uma visita detalhada aos modos de falha: 10 · Resolução de problemas, secção "Frota: rbamp_provision devolveu um erro".
Cenário 3 — TC mistas multicanal (I3, modelos diferentes por canal)
Objetivo: demonstrar rbamp_configure_channels num I3 — três canais com modelos de TC diferentes (p. ex. ch0=SCT-013-005 para uma carga pequena, ch1=SCT-013-030 para uma média, ch2=SCT-013-020 para uma grande) com um único ciclo terminal de flash (amigo da flash), e confirmar a persistência após um reinício.
#include "rbamp.h"
#include "esp_timer.h"
void configure_mixed_ct(rbamp_handle_t dev_i3) {
/* (a) Configure — three CT models in a single call. */
const uint8_t models[3] = { 1, 3, 6 };
/* 1=SCT-013-005 (5A), 3=SCT-013-030 (30A), 6=SCT-013-020 (20A) */
int64_t t0 = esp_timer_get_time();
esp_err_t err = rbamp_configure_channels(
dev_i3, RBAMP_SENSOR_SCT013, models, 3);
int64_t t1 = esp_timer_get_time();
if (err != ESP_OK) {
uint8_t reg_err;
rbamp_read_last_error(dev_i3, ®_err);
ESP_LOGE("3", "configure rejected: %s, REG_ERROR=0x%02X",
esp_err_to_name(err), reg_err);
return;
}
ESP_LOGI("3", "configure_channels latency = %lld ms",
(long long)((t1 - t0) / 1000));
/* (b) Verify the mirror via registers 0x51 / 0x52 / 0x53 (RAM). */
uint8_t m0, m1, m2;
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "applied: [%u %u %u] (expected [1 3 6])", m0, m1, m2);
/* (c) Persist verify — reset + re-read the mirror after boot. */
rbamp_reset(dev_i3);
vTaskDelay(pdMS_TO_TICKS(300)); /* boot window */
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "after reboot: [%u %u %u]", m0, m1, m2);
}
Saída de bancada (validada em hardware num I3 reflashed de raiz):
configure_channels(SCT013, {1, 3, 6}, 3) = ESP_OK
configure_channels latency = 1403 ms
applied: [1 3 6] (raw 0x01 0x03 0x06)
after reboot: [1 3 6] (persisted through CMD_RESET + boot)
A propriedade de "SAVE único" — porque importa
configure_channels faz uma gravação terminal CMD_SAVE_USER_CONFIG no fim. A alternativa — chamadas separadas de set_ct_model_ch para cada canal, cada uma com o seu próprio save_user_config a seguir — dá três ciclos de apagar + escrever na flash.
Comparação de latência em bancada (no mesmo I3):
| Abordagem | Latência | Ciclos de flash |
|---|---|---|
configure_channels(...) — 1 gravação SAVE no terminal |
~1403 ms | 1 |
3× (set_ct_model_ch + save_user_config) |
~3492 ms | 3 |
3× mais lento — ou seja, (~2.5×) × ~700 ms. O ponto-chave é a diferença de 3× no desgaste de ciclos na mesma página de flash: com a reconfiguração típica de módulos no terreno, isto traduz-se num custo de desgaste relevante. Use sempre configure_channels quando precisar de definir a classe do sensor + os modelos de CT por canal.
Para a família SCT-013: 1=SCT-013-005, 2=SCT-013-010, 3=SCT-013-030, 4=SCT-013-050, 5=SCT-013-100, 6=SCT-013-020, 7=SCT-013-060. Um código fora de {1, 2, 3, 4, 5, 6, 7} resulta em ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).
Cenário 4 — Sincronização GC da frota (sincronismo dos períodos tarifários)
Objetivo: demonstrar um instantâneo atómico em toda a frota com uma única trama I²C General-Call. Ao contrário do CMD_LATCH_PERIOD sequencial por módulo (em que o desvio se acumula em cada ida e volta), o GC sincroniza todos os módulos numa única transação de barramento.
Hardware: a mesma frota heterogénea UI1+I2+I3 (@0x50/0x51/0x52).
#include "rbamp_fleet.h"
static const char *TAG = "gc_sync";
void app_main(void) {
/* bus init + fleet_create + fleet_scan ... as in Sc.1 */
/* Step 1: enable GC on all modules in the fleet. */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "GC armed: %u/%u",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
for (int round = 0; round < 10; ++round) {
/* Step 2: a single broadcast snapshot — all modules atomically. */
ESP_ERROR_CHECK(rbamp_fleet_gclatch(fleet, /*group=*/0, tick,
/*settle_ms=*/50));
/* Step 3: in-sync check — all modules caught the same tick. */
size_t n_missed = 0;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "round %d tick=%u in_sync=%u/%u",
round, tick,
(unsigned)(n_total - n_missed), (unsigned)n_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(100));
}
}
Saída de bancada (10 rondas na frota UI1+I2+I3, pull-up de 4.7 kΩ):
rbamp_fleet_enable_gc_all() → 3/3 modules armed
round 0 tick=0 in_sync=3/3 skew=0
round 1 tick=1 in_sync=3/3 skew=0
round 2 tick=2 in_sync=3/3 skew=0
round 3 tick=3 in_sync=3/3 skew=0
round 4 tick=4 in_sync=3/3 skew=0
round 5 tick=5 in_sync=3/3 skew=0
round 6 tick=6 in_sync=3/3 skew=0
round 7 tick=7 in_sync=3/3 skew=0
round 8 tick=8 in_sync=3/3 skew=0
round 9 tick=9 in_sync=3/3 skew=0
Quando usar a sincronização GC:
-
Sincronização apertada. Se a diferença do instantâneo por minuto/por segundo entre módulos for relevante para o relato (por exemplo, um cálculo de balanço
rede − Σ(secundários)integrado no tempo — o desvio entre módulos introduz um erro sistemático), o GC entregaskew = 0por medição de bancada. Um instantâneo sequencial por módulo nos mesmos 3 módulos acumula 100–300 µs por módulo × N, o que se torna relevante numa janela de 60 minutos em análises de precisão. -
Frota grande. À medida que o número de módulos cresce, a diferença entre "N × round_trip sequencial" e "uma única trama GC" cresce linearmente.
-
Alinhamento entre instalações. Se tiver vários ESP32 em barramentos diferentes que partilham um relógio mestre, o tick GC pode ser sincronizado através do relógio de parede do lado do mestre — e então os instantâneos de barramentos diferentes ficam alinhados dentro de uma única janela de ida e volta na rede.
Testemunha através de check_sync: uma verificação de que todos os módulos receberam de facto a trama GC. Pode não detetar um módulo se este estava ocupado a arrancar / num ciclo de SAVE no momento da trama — missed_idx aponta para o primeiro fora de sincronia. Na validação em bancada, 10 rondas seguidas — 0 falhas.
Pré-condição. O GC tem de estar ativado em todos os módulos (rbamp_fleet_enable_gc_all ou, por dispositivo, rbamp_enable_gc + SAVE_USER_CONFIG + reinício). Um módulo novo com valores de fábrica não aceita GC — é intencional, uma proteção contra difusões acidentais num barramento em arranque.
Cenário 5 — Leitura rápida (módulo único)
Objetivo: imprimir U / I / P / PF / frequência no log do ESP-IDF uma vez por segundo. O mesmo "hello world" que escreveu em 05 · Arranque rápido, mas via rbamp_read_all() — uma leitura única de todo o bloco RT para uma estrutura.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "quick_read";
void app_main(void) {
/* ...bus_cfg setup, rbamp_new + rbamp_begin as in the Quickstart... */
rbamp_handle_t dev = NULL;
while (1) {
rbamp_snapshot_t s;
if (rbamp_read_all(dev, &s) != ESP_OK) {
ESP_LOGE(TAG, "read fail");
vTaskDelay(pdMS_TO_TICKS(1000));
continue;
}
ESP_LOGI(TAG, "U=%.1f V f=%.1f Hz channels=%u",
(double)s.voltage, (double)s.frequency, s.channels);
for (uint8_t ch = 0; ch < s.channels; ++ch) {
ESP_LOGI(TAG, " I%u=%.2f A P%u=%.1f W PF%u=%.2f",
ch, (double)s.current[ch],
ch, (double)s.power[ch],
ch, (double)s.power_factor[ch]);
}
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
O que acontece no barramento: rbamp_read_all() num UI3 faz ~53 transações de um byte (13 valores float × 4 bytes + 1 byte de frequência). A 50 kHz com margem para retentativas — da ordem de 25–30 ms. Se não precisar de todos os valores, chame as funções por propriedade (rbamp_read_voltage(), rbamp_read_current(ch)) — menos bytes no barramento.
Cenário 6 — Contador de Wh num LCD 16×2
Objetivo: um contador de Wh, atualizado uma vez por minuto, num LCD de caracteres 16×2 com um expansor I²C PCF8574 (compatível com HD44780). O LCD está no mesmo barramento I²C do rbAmp. O mecanismo-chave do componente é rbamp_read_period_snapshot(), que encapsula instantâneo + estabilização + verificação de validade + leitura + tick de Wh numa única chamada.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
/* Minimal LCD shim — inline in the example, no third-party drivers.
* The full lcd_print/lcd_clear functions are in examples/lcd_period/main/main.c. */
void app_main(void) {
/* ...bus_cfg + rbamp + lcd init... */
rbamp_handle_t dev = NULL;
uint32_t ok_count = 0, bad_count = 0;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK
|| !snap.valid) {
bad_count++;
continue;
}
ok_count++;
char line1[17], line2[17];
snprintf(line1, sizeof(line1), "P=%6.1f W ", (double)snap.avg_p[0]);
snprintf(line2, sizeof(line2), "%8.4f Wh ok%lu", rbamp_energy_wh(dev, 0),
(unsigned long)ok_count);
lcd_clear();
lcd_print(0, 0, line1);
lcd_print(0, 1, line2);
}
}
O projeto IDF completo — examples/lcd_period/.
Tratamento de instantâneos desatualizados. rbamp_read_period_snapshot() devolve ESP_ERR_INVALID_RESPONSE se o módulo não tiver conseguido preparar um instantâneo novo até ao momento da leitura. O componente regista ainda o seu carimbo temporal (esp_timer_get_time()) internamente — assim o instantâneo bem-sucedido seguinte não é contado em duplicado no intervalo.
Cenário 7 — Monitorização de 3 módulos (sequencial legado) num único barramento
Objetivo: sondar 3 módulos nos endereços 0x50 / 0x51 / 0x52 a partir de um master. Cada módulo tem de ter um endereço único (os endereços são atribuídos durante a instalação de fábrica / do integrador — ver 09 · Referência da API sobre os métodos de alteração de endereço com as respetivas notas de AVISO).
O padrão canónico para o firmware v1 é um rbamp_latch_period() sequencial em cada dispositivo + uma única estabilização partilhada de 50 ms + rbamp_read_period_snapshot(skip_latch=true) por dispositivo. Desfasamento entre dispositivos a 100 kHz: ~1 ms por dispositivo — desprezável face a um período de 60 segundos.
Na v1.3 do firmware (REG_VERSION = 0x04) o rbamp_broadcast_latch() é totalmente suportado depois de o GC estar ativado em toda a frota via rbamp_fleet_enable_gc_all() — o caminho canónico de sincronização da frota para sincronismo apertado entre sub-medidores (ver a secção GC da frota da Strategy 2 mais atrás neste capítulo). Em firmware legado v1.0-v1.2 (sem suporte a instantâneo General-Call) a chamada devolve ESP_ERR_NOT_SUPPORTED e a biblioteca recorre ao instantâneo por dispositivo mostrado acima. Ver 09 · Referência da API para detalhes.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
#define N_MODULES 3
static const char *TAG = "multi_module";
static const uint8_t ADDRS[N_MODULES] = { 0x50, 0x51, 0x52 };
void app_main(void) {
/* ...bus_cfg setup as in the Quickstart... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t modules[N_MODULES] = { NULL };
/* Create a handle for each module */
for (int i = 0; i < N_MODULES; ++i) {
if (rbamp_new(bus, ADDRS[i], &modules[i]) != ESP_OK ||
rbamp_begin(modules[i]) != ESP_OK) {
ESP_LOGE(TAG, "module 0x%02X init failed", ADDRS[i]);
modules[i] = NULL;
}
}
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Phase 1: sequential snapshot on each device, measure the skew */
const int64_t sync_start_us = esp_timer_get_time();
for (int i = 0; i < N_MODULES; ++i) {
if (modules[i]) rbamp_latch_period(modules[i]);
}
const uint32_t sync_us = (uint32_t)(esp_timer_get_time() - sync_start_us);
/* Phase 2: a single shared settle for all 3 modules */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read the snapshots with skip_latch=true */
ESP_LOGI(TAG, "sync_us=%u", (unsigned)sync_us);
for (int i = 0; i < N_MODULES; ++i) {
if (!modules[i]) continue;
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(modules[i], &snap, 0,
/*skip_latch=*/true) != ESP_OK) {
continue;
}
ESP_LOGI(TAG, "mod%d 0x%02X P=%.0f W Wh=%.3f",
i, ADDRS[i],
(double)snap.avg_p[0],
rbamp_energy_wh(modules[i], 0));
}
}
}
O projeto completo (com sondagem do barramento + relato de erros) — examples/multi_module/.
Cenário 8 — MQTT por canal
Objetivo: um módulo UI3 com 3 pinças de CT em três linhas independentes. Contadores de Wh por canal, publicados no MQTT uma vez por minuto. Mostra que rbamp_energy_wh(dev, ch) funciona em cada canal de forma independente — não é preciso um array manual total_wh[3] do lado do mestre.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static const char *TAG = "ui3_mqtt";
static const char *CH_NAMES[3] = { "main", "heatpump", "lights" };
static esp_mqtt_client_handle_t mqtt;
static void publish_channel(const char *name, float avg_p, double e_wh) {
char topic[64], payload[96];
snprintf(topic, sizeof(topic), "rbamp/%s/state", name);
snprintf(payload, sizeof(payload),
"{\"power\":%.1f,\"energy\":%.4f}", (double)avg_p, e_wh);
esp_mqtt_client_publish(mqtt, topic, payload, 0, /*qos*/1, /*retain*/1);
}
void app_main(void) {
/* ...wifi STA + mqtt_client init... */
/* ...bus_cfg + rbamp_new + rbamp_begin (50 kHz via Kconfig)... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) {
continue;
}
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
publish_channel(CH_NAMES[ch], snap.avg_p[ch],
rbamp_energy_wh(dev, ch));
}
}
}
O projeto completo — examples/mqtt_publisher/. Para o Auto-discovery MQTT do HA baseado neste padrão — ver 07 · Integrações DIY + examples/ha_discovery/.
Cenário 9 — Medição bidirecional do lado do mestre
Objetivo: separar a potência instantânea com sinal em consumo bruto e exportação bruta. Use este padrão no nível BASIC, onde o firmware corta os valores negativos em snap.avg_p[ch] (potência média do período) — amostre rbamp_read_power(dev, 0, &p) (potência instantânea, com sinal em todos os níveis) a 10 Hz do lado do master e agrupe você mesmo.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "bidir";
void bidir_task(void *arg) {
rbamp_handle_t dev = arg;
double consume_wh = 0.0, export_wh = 0.0;
int64_t t_prev_us = esp_timer_get_time();
while (1) {
vTaskDelay(pdMS_TO_TICKS(100)); /* 10 Hz, matches the RT cadence */
const int64_t t_now_us = esp_timer_get_time();
const 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;
const double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
/* Print once a second */
static int n = 0;
if (++n % 5 == 0) {
ESP_LOGI(TAG, "P=%.1f W cons=%.4f Wh exp=%.4f Wh net=%.4f Wh",
(double)p, consume_wh, export_wh,
consume_wh - export_wh);
}
}
}
Este é um cenário composto sem projeto IDF dedicado. Num módulo STD os contadores de energia são com sinal e rbamp_energy_wh(dev, 0) devolve um balanço líquido (a importação e a exportação são guardadas separadamente em rbamp_std_read_energy()) — esta separação do lado do mestre só é necessária em módulos BASIC, ou para relatar separadamente o consumo bruto / a exportação bruta a partir da potência em tempo real.
Cenário 10 — Balanço energético da casa inteira
Objetivo: 3 módulos — rede (bidirecional), solar (apenas geração), cargas (UI3 para cada aparelho). O painel combinado é publicado uma vez por minuto.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static rbamp_handle_t mains_dev, solar_dev, loads_dev;
static esp_mqtt_client_handle_t mqtt;
void app_main(void) {
/* ...wifi STA + mqtt init... */
/* ...bus_cfg + per-module rbamp_new(bus, 0x50/0x51/0x52, ...) +
* rbamp_begin() on each... */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Sequential snapshot + shared settle (the pattern from Scenario 3) */
rbamp_latch_period(mains_dev);
rbamp_latch_period(solar_dev);
rbamp_latch_period(loads_dev);
vTaskDelay(pdMS_TO_TICKS(50));
rbamp_period_snapshot_t sm, ss, sl;
if (rbamp_read_period_snapshot(mains_dev, &sm, 0, true) != ESP_OK || !sm.valid ||
rbamp_read_period_snapshot(solar_dev, &ss, 0, true) != ESP_OK || !ss.valid ||
rbamp_read_period_snapshot(loads_dev, &sl, 0, true) != ESP_OK || !sl.valid) {
continue;
}
char payload[256];
snprintf(payload, sizeof(payload),
"{\"mains\":%.3f,\"solar\":%.3f,"
"\"hp\":%.3f,\"ac\":%.3f,\"ev\":%.3f}",
rbamp_energy_wh(mains_dev, 0),
rbamp_energy_wh(solar_dev, 0),
rbamp_energy_wh(loads_dev, 0),
rbamp_energy_wh(loads_dev, 1),
rbamp_energy_wh(loads_dev, 2));
esp_mqtt_client_publish(mqtt, "home/energy/balance",
payload, 0, 1, 1);
}
}
Para uma separação explícita de consumo bruto / exportação bruta na rede — combine com o padrão do Cenário 5 (uma tarefa separada a 10 Hz sobre rbamp_read_power(mains_dev, 0, ...)).
Este é um cenário composto sem projeto IDF dedicado — monte-o a partir de examples/mqtt_publisher/ + examples/multi_module/.
Cenário 11 — Registo baseado em eventos (EMA)
Objetivo: em cada janela RT de 100 ms, comparar a potência instantânea com uma média móvel exponencial. Registar desvios significativos — cargas como um micro-ondas, uma chaleira ou um secador de cabelo "aparecem" no registo como um evento de ligar / desligar.
#include /* fabsf */
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define EMA_ALPHA 0.05f
#define EVENT_THRESHOLD_W 200.0f
static const char *TAG = "event";
void event_task(void *arg) {
rbamp_handle_t dev = arg;
float p_ema = 0.0f;
/* seed the EMA so the first reading is not a false event */
if (rbamp_read_power(dev, 0, &p_ema) != ESP_OK) p_ema = 0.0f;
while (1) {
vTaskDelay(pdMS_TO_TICKS(200));
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
const float delta = p - p_ema;
p_ema = (1.0f - EMA_ALPHA) * p_ema + EMA_ALPHA * p;
if (fabsf(delta) > EVENT_THRESHOLD_W) {
ESP_LOGI(TAG, "%s delta=%.0f W P=%.0f W EMA=%.0f W",
(delta > 0) ? "TURN_ON" : "TURN_OFF",
(double)delta, (double)p, (double)p_ema);
}
}
}
Um cenário composto — sem projeto IDF dedicado. Combine-o com a publicação MQTT do Cenário 4 para automações do lado do HA, ou escreva os eventos em SPIFFS com o padrão do Cenário 8 para um registo offline.
Cenário 12 — Registador CSV local em SPIFFS
Objetivo: escrever um instantâneo de período num ficheiro CSV na SPIFFS uma vez por minuto. Útil em implementações autónomas sem WiFi / MQTT, ou como buffer para uma sincronização diferida com a cloud.
Requer uma tabela de partições personalizada com a entrada storage,data,spiffs,,128K, em partitions.csv. Um exemplo está em examples/spiffs_logger/partitions.csv.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_spiffs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define LOG_PATH "/storage/log.csv"
#define ROTATE_BYTES (64 * 1024)
static const char *TAG = "spiffs_logger";
static void rotate_if_full(void) {
struct stat st;
if (stat(LOG_PATH, &st) == 0 && st.st_size >= ROTATE_BYTES) {
rename(LOG_PATH, "/storage/log_prev.csv");
}
}
void app_main(void) {
esp_vfs_spiffs_conf_t spiffs_cfg = {
.base_path = "/storage",
.partition_label = "storage",
.max_files = 4,
.format_if_mount_failed = true,
};
ESP_ERROR_CHECK(esp_vfs_spiffs_register(&spiffs_cfg));
/* ...bus_cfg + rbamp_new + rbamp_begin... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
rotate_if_full();
FILE *f = fopen(LOG_PATH, "a");
if (!f) {
ESP_LOGE(TAG, "fopen failed");
continue;
}
fprintf(f, "%lld,%.3f,%.4f,%u\n",
(long long)(esp_timer_get_time() / 1000),
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
fclose(f);
}
}
O projeto completo — examples/spiffs_logger/. O excerto acima é uma simplificação pedagógica com uma linha CSV de 4 colunas. O exemplo em si escreve uma linha CSV de 9 colunas com avg_p e Wh por canal para os 3 canais — mais útil para cenários de produção em módulos UI3.
Para sincronização diferida com a nuvem (registar localmente, enviar uma vez por hora) — veja a secção "Híbrido: armazenamento local + sincronização" em 08 · Integrações na nuvem.
Cenário 13 — Registador a bateria com deep-sleep
Objetivo: um ESP32 acorda uma vez a cada 10 minutos, tira um único instantâneo de período, publica via WiFi+MQTT e volta ao deep-sleep. A energia persiste na memória RTC entre ciclos de sono. O acumulador do componente está desativado — o master assegura a persistência do Wh por si.
⚠ Nota importante sobre deep-sleep. No firmware atual, rbamp_begin() emite sempre um CMD_LATCH_PERIOD de preparação, que repõe o acumulador de período do firmware. Isto significa que após um despertar de deep-sleep não pode simplesmente chamar rbamp_read_period_snapshot() por omissão — essa chamada tiraria outro instantâneo e devolveria dados quase nulos ~50 ms após a preparação. O padrão correto abaixo usa skip_latch=true para ler os dados acumulados durante o intervalo de sono, e o temporizador RTC do próprio master para o intervalo entre despertares (o campo snap.master_dt_ms reflete apenas o tempo dentro do ciclo de vigília atual, não de despertar a despertar).
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "esp_sleep.h"
#include "esp_timer.h"
#include "rbamp.h"
#define WAKE_INTERVAL_US (10ULL * 60ULL * 1000000ULL)
#define RTC_MAGIC 0xCAFEFEEDu
RTC_DATA_ATTR static uint32_t rtc_magic = 0;
RTC_DATA_ATTR static double rtc_total_wh = 0.0;
RTC_DATA_ATTR static bool rtc_primer_done = false;
RTC_DATA_ATTR static uint64_t rtc_last_wake_us = 0;
static const char *TAG = "deep_sleep";
void app_main(void) {
/* ...bus_cfg setup... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t dev = NULL;
if (rtc_magic != RTC_MAGIC) {
/* Cold start — initialize RTC-RAM */
rtc_magic = RTC_MAGIC;
rtc_total_wh = 0.0;
rtc_primer_done = false;
rtc_last_wake_us = 0;
}
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev));
ESP_ERROR_CHECK(rbamp_begin(dev)); /* issues the primer snapshot */
rbamp_energy_disable(dev); /* the master owns Wh itself */
if (!rtc_primer_done) {
/* First wake: the primer snapshot just captured the "dirty" data from
* before wake. Record the time and go straight back to sleep —
* the next wake in 10 min gets a full accumulator for the interval. */
rtc_last_wake_us = esp_timer_get_time();
rtc_primer_done = true;
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* skip_latch=true reads what the rbamp_begin() primer latched —
* that is, the accumulator for the elapsed 10-minute sleep interval. */
rbamp_period_snapshot_t snap;
esp_err_t snap_err = rbamp_read_period_snapshot(dev, &snap, /*settle_ms=*/0,
/*skip_latch=*/true);
if (snap_err != ESP_OK || !snap.valid) {
ESP_LOGW(TAG, "snapshot fail: %s (valid=%d)",
rbamp_err_to_str(snap_err), snap.valid);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* `snap.master_dt_ms` here is the time within the current wake (after
* the primer); for energy integration we use `esp_timer_get_time()`
* against `rtc_last_wake_us`. On ESP-IDF v5.x, the value returned by
* `esp_timer_get_time()` **survives deep sleep** — the timer is
* re-derived from the RTC slow-clock on wake. So the delta gives the
* real wake-to-wake interval in microseconds. */
const uint64_t now_us = esp_timer_get_time();
const double dt_s = (double)(now_us - rtc_last_wake_us) / 1e6;
rtc_last_wake_us = now_us;
rtc_total_wh += (double)snap.avg_p[0] * dt_s / 3600.0;
ESP_LOGI(TAG, "wake: P=%.1f W Wh=%.4f dt_s=%.1f",
(double)snap.avg_p[0], rtc_total_wh, dt_s);
publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
O projeto completo (com configuração do WiFi, publicação MQTT, proteções de marcador magic na RTC) — examples/deep_sleep_logger/.
rbamp_begin_resume() (componente 1.7.0 e posteriores) é a variante de inicialização sem a preparação de CMD_LATCH_PERIOD, por isso rbamp_read_period_snapshot() funciona diretamente após um despertar de deep-sleep. O padrão acima (skip_latch=true + o temporizador RTC do master) continua válido em versões antigas do componente.
Orçamento de energia (ESP32-WROOM, intervalo de despertar de 10 minutos):
- Duração do ciclo ativo: ~3 s (WiFi + MQTT + I²C)
- Corrente ativa: ~80 mA em média → ~0.07 mAh por despertar
- Corrente em repouso: ~10 µA (RTC + domínios retidos)
- ~10 mAh por dia → uma bateria Li-ion de 2000 mAh dura ~6 meses
Cenário 14 — I3 com TC diferente por canal (monitorização de cargas mistas)
Objetivo: um único módulo UI3 monitoriza três linhas independentes numa fase com níveis de carga diferentes:
- Canal 0 — uma única tomada (SCT-013-005, ≤5 A) — TV / router / stand-by.
- Canal 1 — a linha da cozinha (SCT-013-030, ≤30 A) — chaleira / micro-ondas.
- Canal 2 — uma caldeira de esquentador (SCT-013-020, ≤20 A) — carga de pico.
Os três canais são alimentados a partir de uma única fase (em fase com o canal U), por isso P/PF/Q estão corretos para os três — ver o aviso de tensão única em 03 · Seleção do sensor de corrente.
#include "driver/i2c_master.h"
#include "rbamp.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static const char *TAG = "ui3-mixed";
void mixed_load_task(void *arg) {
rbamp_handle_t dev = (rbamp_handle_t)arg;
/* Per-channel configuration — v1.3: order is arbitrary (pure staging) */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model_ch(dev, 2, 6); /* ch2: SCT-013-020 (boiler) */
rbamp_set_ct_model_ch(dev, 1, 3); /* ch1: SCT-013-030 (kitchen) */
rbamp_set_ct_model_ch(dev, 0, 1); /* ch0: SCT-013-005 (outlet) */
while (1) {
float u, i0, i1, i2, p0, p1, p2;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i0);
rbamp_read_current(dev, 1, &i1);
rbamp_read_current(dev, 2, &i2);
rbamp_read_power(dev, 0, &p0);
rbamp_read_power(dev, 1, &p1);
rbamp_read_power(dev, 2, &p2);
ESP_LOGI(TAG, "U=%.1f V", (double)u);
ESP_LOGI(TAG, " outlet: I=%.3f A P=%.1f W", (double)i0, (double)p0);
ESP_LOGI(TAG, " kitchen: I=%.2f A P=%.1f W", (double)i1, (double)p1);
ESP_LOGI(TAG, " boiler: I=%.2f A P=%.1f W", (double)i2, (double)p2);
ESP_LOGI(TAG, " total: P=%.1f W", (double)(p0 + p1 + p2));
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
Quando usar: monitorizar uma única fase com três grupos de carga de magnitudes de corrente diferentes. A grande vantagem é a resolução — cada pinça corresponde ao seu intervalo (uma SCT-013-005 dá leituras precisas numa carga de stand-by de 50 W, enquanto uma SCT-013-020 não satura num esquentador/caldeira de ~4 kW).
Cenário 15 — Submedição: 5×UI1 num barramento partilhado
Objetivo: monitorizar 5 linhas independentes num apartamento monofásico com sincronismo tarifário dos períodos. Um UI1 por linha (5 módulos no total).
Esta é a estratégia 1 de sincronização de períodos de 04 · Ligação: instantâneo sequencial + estabilização partilhada.
#define N_METERS 5
static rbamp_handle_t meters[N_METERS]; /* initialized in app_main */
void sub_meter_task(void *arg) {
int64_t period_start_us = esp_timer_get_time();
const int64_t PERIOD_S = 60; /* 60-second metering period */
while (1) {
/* Wait until the end of the period */
int64_t now_us = esp_timer_get_time();
int64_t elapsed_s = (now_us - period_start_us) / 1000000;
if (elapsed_s < PERIOD_S) {
vTaskDelay(pdMS_TO_TICKS((PERIOD_S - elapsed_s) * 1000));
continue;
}
/* Phase 1: sequential snapshot (skew ~5 ms between modules at 50 kHz) */
for (int i = 0; i < N_METERS; i++) {
rbamp_latch_period(meters[i]);
}
/* Phase 2: shared settle */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read snapshots with skip_latch=true */
float total_wh_period = 0.0f;
for (int i = 0; i < N_METERS; i++) {
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(meters[i], &snap, 0, /*skip_latch=*/true) == ESP_OK
&& snap.valid) {
float wh_this_period = snap.avg_p[0] * snap.period_ms / 3600000.0f;
ESP_LOGI("meter", "[%d] avg_p=%.1f W Wh_period=%.2f",
i, (double)snap.avg_p[0], (double)wh_this_period);
total_wh_period += wh_this_period;
}
}
ESP_LOGI("meter", "TOTAL for the period: %.2f Wh\n", (double)total_wh_period);
period_start_us = esp_timer_get_time();
}
}
Análise de desvio: 5 módulos × ~1 ms/instantâneo = ~5 ms. Em relação ao período de 60 s = 0.008%. Desprezável.
Orçamento do barramento: 5 módulos × ~5 ms de bloco RT = 25 ms por ronda completa; isto também cabe numa taxa de sondagem de 5 Hz (25 ms ≪ 100 ms). A folga do barramento é confortável até ~15 módulos UI1.
Cenário 16 — Instantâneo GC em difusão (sincronização apertada para >8 módulos)
Objetivo: com ≥ 8 módulos, o desvio da estratégia 1 (sequencial) aproxima-se de ~10 ms. Para sincronismo de períodos tarifários — estratégia 2, broadcast General-Call.
Pré-configuração (uma vez por módulo):
/* Enable GC reception on each module: the call writes FLEET_CONFIG.bit0,
saves the configuration and restarts the module (~1 s) */
rbamp_enable_gc(dev, true);
Instantâneo broadcast em tempo de execução com testemunho:
#define N_METERS 12
esp_err_t synced_snapshot(i2c_master_bus_handle_t bus,
rbamp_handle_t meters[], int n,
uint16_t tick_counter) {
/* All-call broadcast snapshot (group 0x00): the library builds the
General-Call frame and sends it to address 0x00 on the bus */
esp_err_t err = rbamp_broadcast_latch_group(bus, 0x00, tick_counter, 100);
if (err != ESP_OK) return err;
/* Settle: snapshot + 1 commit-cycle for witness refresh */
vTaskDelay(pdMS_TO_TICKS(50));
/* Witness check: each module echoes the tick of the last GC frame it accepted */
int n_ok = 0;
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) == ESP_OK && tick == tick_counter) {
n_ok++;
} else {
ESP_LOGW("gc-snapshot", "module %d did not take its snapshot (witness mismatch)", i);
}
}
if (n_ok < n) {
ESP_LOGW("gc-snapshot", "fallback to sequential snapshot for %d modules",
n - n_ok);
/* Strategy 1 fallback on the remaining ones */
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) != ESP_OK || tick != tick_counter) {
rbamp_latch_period(meters[i]);
}
}
vTaskDelay(pdMS_TO_TICKS(50));
}
return ESP_OK;
}
Análise de desvio: uma trama GC demora ~1 ms a 50 kHz → os 12 módulos tiram o seu instantâneo em simultâneo ao nível do barramento. O desvio é praticamente 0.
Quando usar: ≥ 8 módulos e/ou sincronização apertada.
Quando NÃO usar: num barramento misto com dispositivos que não são rbAmp (o GC pode entrar em conflito).
Cenário 17 — Filtragem por grupo GC (contagem multi-inquilino)
Objetivo: 10 módulos num único barramento, em que precisa de tirar instantâneos de subconjuntos de forma independente. Por exemplo, 5 módulos medem a tarifa A (diurna), 5 — a tarifa B (noturna); são armados e lidos em horários diferentes.
Configuração (uma vez):
/* Tariff A — modules 0..4 → group = 1 */
for (int i = 0; i < 5; i++) {
rbamp_set_group_id(meters[i], 1);
rbamp_save_user_config(meters[i]);
}
/* Tariff B — modules 5..9 → group = 2 */
for (int i = 5; i < 10; i++) {
rbamp_set_group_id(meters[i], 2);
rbamp_save_user_config(meters[i]);
}
Execução — instantâneo independente por tarifa:
void daytime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff A only (group 1) */
rbamp_broadcast_latch_group(bus, 1, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff A */
}
void nighttime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff B only (group 2) */
rbamp_broadcast_latch_group(bus, 2, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff B */
}
void all_modules_snapshot(i2c_master_bus_handle_t bus, uint16_t tick) {
/* group = 0x00 — all-call, all 10 take a snapshot */
rbamp_broadcast_latch_group(bus, 0, tick, 100);
}
Vantagens: um ciclo por tarifa = separação limpa dos intervalos de medição. Sem grupos, teria de manter ciclos de instantâneos sequenciais paralelos com resolução de conflitos.
Cenário 18 — Módulo STD: potência reativa, THD e energia cronometrada pelo mestre
Objetivo: ler as grandezas que só um módulo STD mede — potência reativa e aparente, THD, fator de potência de deslocamento — e contabilizar a energia num período próprio. A mesma API rbamp_* serve as duas linhas de módulos; rbamp_begin() deteta a linha. Num módulo BASIC o exemplo imprime uma nota e recua para o comportamento de quick_read — nada falha, as chamadas STD apenas reportam "não suportado".
Source: examples/std_meter/
rbamp_new(bus, 0x50, &dev);
rbamp_begin(dev); /* detects BASIC / STD */
const bool std = (rbamp_line(dev) == RBAMP_LINE_STD);
if (std) {
rbamp_std_info_t info;
rbamp_std_info(dev, &info);
/* THD and displacement PF are off by default (RAM-only setting;
* reverts at a module reset). */
rbamp_std_set_harmonics(dev, true);
/* Period energy depends on what the module offers. */
if (info.period_source == RBAMP_STD_PERIOD_LATCH) {
/* Snapshot banks: keep bank 0 (the library's) armed, add our own. */
rbamp_std_arm_banks(dev, (1u << 0) | (1u << 1));
rbamp_std_latch(dev, 1); /* primer: the period starts now */
} /* COUNTERS: nothing to arm */
}
while (1) {
rbamp_std_voltage_t v;
rbamp_std_read_voltage(dev, 0, &v); /* U, THD, phase angle */
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
rbamp_std_channel_t c;
rbamp_std_read_channel(dev, ch, &c); /* I, P, Q, S, PF, PF1, THD in one burst */
}
rbamp_std_health_t h; /* the frame counter must keep growing */
rbamp_std_read_health(dev, &h);
/* Every PERIOD_MS: */
/* - LATCH module: rbamp_std_latch(dev, 1); wait >= 300 ms;
* rbamp_std_read_latch(dev, 1, <);
* rbamp_std_latch_wh(<, dt_ms, RBAMP_STD_TOTAL, &wh_in, &wh_out);
* - COUNTERS module: rbamp_read_period_snapshot(dev, &ps, 0, false);
* ps.wh_net / ps.avg_p_total / ps.module_restarted */
vTaskDelay(pdMS_TO_TICKS(1000));
}
Notes:
-
dt_msé o tempo de relógio de parede do mestre entre dois instantâneos do banco — o módulo não tem relógio próprio para o período. -
Num módulo de contadores não existe banco de instantâneos nem nada a armar: o instantâneo de período da biblioteca lê os contadores persistidos e reporta a diferença;
module_restartedassinala um reinício dentro do período (a diferença continua válida). -
A máscara do banco de instantâneos está na RAM do módulo. Se um reinício do módulo a limpar,
rbamp_std_read_latch()volta a armar o banco e devolveESP_ERR_INVALID_STATEpara esse período — descarte-o e reinicie o seu ponto de referência dt. -
API completa: 09 · Referência da API, capítulo "Linha STD".
Tabela-resumo dos cenários
| # | LOC | barramento I²C | Período? | DRDY? | MQTT? | Persistência |
|---|---|---|---|---|---|---|
| 1 | ~120 | partilhado 3 módulos (UI1+I2+I3) | sim (sincronização GC) | não | sim | RAM (propriedade do master) |
| 2 | ~50 | dedicado (um virgem) | não | não | não | flash (save_config=true) |
| 3 | ~60 | dedicado (I3) | não | não | não | flash (SAVE_USER_CONFIG) |
| 4 | ~50 | partilhado com 3 módulos | sim (GC) | não | não | RAM |
| 5 | ~40 | dedicado | não | não | não | não |
| 6 | ~60 | partilhado com o LCD | sim | não | não | RAM |
| 7 | ~80 | partilhado com 3 módulos | sim | não | não | RAM |
| 8 | ~70 | dedicado | sim | não | sim | MQTT retained |
| 9 | ~50 | dedicado | não (RT) | não | não | RAM (propriedade do master) |
| 10 | ~80 | partilhado com 3 módulos | sim | não | sim | MQTT retained |
| 11 | ~80 | dedicado | não (RT) | sim | não | RAM |
| 12 | ~70 | dedicado | sim | não | não | SPIFFS |
| 13 | ~80 | dedicado | sim | não | sim | Memória RTC + MQTT |
| 14 | ~60 | I3 dedicado | não (RT) | não | não | RAM |
| 15 | ~80 | partilhado por 5×UI1 | sim | não | não | RAM |
| 16 | ~100 | partilhado por 12 módulos | sim (sincronização GC) | não | não | RAM |
| 17 | ~60 | partilhado por 10 módulos, multi-inquilino | sim (grupos GC) | não | não | RAM |
| 18 | ~110 | dedicado (módulo STD) | sim (banco de instantâneos ou contadores) | não | não | RAM (os contadores de vida vivem no módulo) |
O que vem a seguir
-
07 · Integrações DIY — Home Assistant / Node-RED / OpenHAB com base nestes cenários (incluindo
examples/ha_discovery/) -
08 · Integrações na nuvem — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Referência da API — todas as funções públicas documentadas
-
10 · Resolução de problemas — quando os cenários se comportam de forma diferente na sua bancada
Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/06_examples.md (v1.7.3)