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

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/ build flash monitor. 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/
Nota

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

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:

  1. Descobrir — rbamp_fleet_scan encontra todos os módulos, verifica a identidade de cada um e elimina endereços em conflito.

  2. Configurar — rbamp_configure_channels define a classe do sensor + os modelos de CT por canal + um único SAVE_USER_CONFIG final, numa só chamada por módulo multicanal.

  3. Armar GC — rbamp_fleet_enable_gc_all ativa a receção de instantâneos General-Call em todos os módulos da frota.

  4. Ciclo — a cada tick o master executa um _gclatch atómico (um instantâneo síncrono em toda a frota), verifica com _check_sync, lê com _poll_all, integra a energia por master_dt e 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

C
#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)

Text
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)
Nota

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) → um poll_all lê a frota inteira → agregação. Sem desvio entre módulos a partir de uma cadeia de idas e voltas sequenciais.

  • Comportamento de total_power numa frota heterogénea. O UI1 dá potência ativa (tem tensão → tem P); os I2/I3 são apenas de corrente, por isso a sua contribuição para total_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_total cresce de forma monótona (2.55 → 6.94 Wh durante a janela de captura de bancada); o componente integra cada período por master_dt_ms (esp_timer), e não pelo latch_ms do lado do chip (um temporizador de diagnóstico do módulo que pode ler curto). Um tick espúrio acrescenta 0 Wh se 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_all assinala-o com status[i] != ESP_OK e 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 com n_ok=2/3 sem paragem. O mesmo vale para check_sync — missed_idx aponta 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 tem has_voltage = true) dos sub-handles (todos os outros).

  • Correntes por canal → desagregação de cargas. Através de fleet_poll_all o 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édia 112.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.). Um fleet_poll_all agrupado é 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.

C
#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):

Text
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.

C
#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):

Text
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.

Códigos de modelo de TC válidos.

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).

C
#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Ω):

Text
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 entrega skew = 0 por 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.

C
#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.

C
#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).

Nota

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.

C
#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.

C
#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.

C
#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.

C
#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.

C
#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.

Nota

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.

C
#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.

Segurança

⚠ 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).

C
#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/.

Segurança

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.

C
#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.

C
#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):

C
/* 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:

C
#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):

C
/* 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:

C
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/

C
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_restarted assinala 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 devolve ESP_ERR_INVALID_STATE para 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


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