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

05 · Arranque rápido

Um hello-world de cinco minutos: adicione o componente a um projeto IDF, ligue o módulo, selecione um sensor, faça a sua primeira leitura RT e o seu primeiro instantâneo por período (Wh).

Os detalhes (pinagem para um chip ESP32 específico, barramento multimódulo, escolha de um SCT-013 por intervalo) estão nos capítulos adjacentes:

Fluxograma dos passos desde a cablagem até à primeira leitura e ao primeiro valor de energia.

O que vai precisar

  • Um módulo rbAmp (qualquer linha de módulo; por simplicidade, um UI1 — uma entrada de tensão mais um canal de corrente; as outras variantes estão listadas em 03)
  • Qualquer chip da família ESP32 (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2)

  • ESP-IDF v5.2+ instalado (. ~/esp/esp-idf/export.sh ou %IDF_PATH%\export.bat no Windows)

  • Uma pinça de CT SCT-013 com calibre para a sua corrente máxima (5A / 10A / 30A / 50A / 100A)

  • Uma alimentação de 5 V para o módulo (a partir de um USB-5V DevKitC ou de uma fonte externa)
  • Um circuito AC a medir (um candeeiro, uma chaleira, um eletrodoméstico)

Passo 0 — Definir o alvo

Se este for um projeto ESP-IDF novo e ainda não tiver corrido idf.py set-target, faça-o antes do primeiro idf.py build — caso contrário a compilação falha com "no target specified":

Shell
idf.py set-target esp32      # or esp32s3 / esp32c3 / esp32c6 / ...

Sem este passo a compilação falha.

Passo 1 — Adicionar o componente ao projeto

No ficheiro main/idf_component.yml do seu projeto (crie o ficheiro se não existir). O Gestor de Componentes do ESP-IDF obtém a versão etiquetada:

YAML
dependencies:
  rbamp:
    git: https://github.com/rb-amp/rbamp-esp-idf.git
    version: v1.7.3

O componente é descarregado no próximo idf.py build (ou idf.py reconfigure).

Manualmente (submódulo git / clone)

Shell
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp

Ou acrescente o caminho do componente ao CMakeLists.txt da raiz do projeto:

CMake
list(APPEND EXTRA_COMPONENT_DIRS
     ${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`

A dependência em main/

CMake
# main/CMakeLists.txt
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES rbamp
)

O componente puxa esp_driver_i2c, esp_timer e log — é tudo o que o cenário básico do Passo 3 precisa. Os cenários de rede / SPIFFS / OLED exigem REQUIRES adicionais — ver 06 · Exemplos, a tabela CMakeLists no início do capítulo.

Passo 2 — Ligação

Quatro fios + DRDY opcional:

pino rbAmp ESP32 (predefinido) ESP32-S3 (predefinido) ESP32-C3 (predefinido)
VCC +5 V (4.5 a 5.5 V) igual igual
GND GND GND GND
SDA GPIO21 GPIO8 GPIO5
SCL GPIO22 GPIO9 GPIO6

A alimentação tem de ser de 5 V. As linhas I²C funcionam em lógica de 3.3 V — diretamente compatível com os GPIO do ESP32. A placa do módulo já tem resistências pull-up de 4.7 kΩ integradas — para um único módulo não são necessárias externas.

A tabela completa de pinagem de cada chip ESP32 está em 04 · Ligação.

Segurança

⚠ A tensão da rede pode matar. Desligue e bloqueie o circuito antes de ligar os terminais L/N ou de colocar a pinça; deixe trabalho na rede e qualquer intervenção dentro de um quadro a um técnico qualificado. Prenda APENAS um condutor (L) — nunca o cabo inteiro. Proteja a derivação L com fusível segundo as regras locais.

A pinça SCT-013 fecha-se em volta do condutor de fase (L), com a seta no corpo da pinça a apontar no sentido da corrente em direção à carga. Um módulo UI também precisa da sua ligação de tensão L/N; a pinça CT liga-se à tomada jack de 3.5 mm do módulo (rotulada I0, I1, … na PCB); o lado da rede tem os terminais L e N. Ver 04 · Ligação, "Rede e ligação CT".

Ligação passo a passo da derivação de rede e da pinça.

Passo 3 — Primeiro projeto (primeira leitura)

Um main/main.c mínimo: inicialize o barramento, diga ao módulo que pinça CT montou e imprima U / I / P / PF uma vez por segundo.

C
#include 
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"

static const char *TAG = "app";

void app_main(void) {
    const i2c_master_bus_config_t bus_cfg = {
        .i2c_port  = I2C_NUM_0,
        .sda_io_num = GPIO_NUM_21,            /* ESP32 — adjust for your chip */
        .scl_io_num = GPIO_NUM_22,
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .glitch_ignore_cnt = 7,
        .flags.enable_internal_pullup = true, /* optional with the module's own pull-ups */
    };
    i2c_master_bus_handle_t bus;
    ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));

    rbamp_handle_t dev = NULL;
    ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev));    /* default address 0x50 */

    /* rbamp_begin blocks while it tries to reach the slave;
     * it runs a primer-snapshot and a valid-check, ~250 ms. */
    while (rbamp_begin(dev) != ESP_OK) {
        ESP_LOGE(TAG, "rbAmp not responding — check wiring and power");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    ESP_LOGI(TAG, "Module ready.");

    /* Sensor configuration (see Step 4): class first, then model.
     * Code 3 = SCT-013-030; use the code of the clamp you fitted. */
    if (rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) != ESP_OK ||
        rbamp_set_ct_model(dev, 3) != ESP_OK) {
        ESP_LOGE(TAG, "sensor configuration failed");
        return;
    }
    ESP_LOGI(TAG, "Sensor configured.");

    while (1) {
        float u = NAN, i = NAN, p = NAN, pf = NAN;
        if (rbamp_read_voltage(dev, 0, &u)        != ESP_OK) u  = NAN;
        if (rbamp_read_current(dev, 0, &i)        != ESP_OK) i  = NAN;
        if (rbamp_read_power(dev, 0, &p)          != ESP_OK) p  = NAN;
        if (rbamp_read_power_factor(dev, 0, &pf)  != ESP_OK) pf = NAN;

        ESP_LOGI(TAG, "U=%.1f V  I=%.3f A  P=%.1f W  PF=%.3f",
                 (double)u, (double)i, (double)p, (double)pf);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Compile e grave + abra o monitor:

Shell
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

(No Windows — idf.py -p COM3 ....)

Saída esperada com uma carga ligada (os valores dependem da sua carga):

Text
I (1234) app: Module ready.
I (2634) app: Sensor configured.
I (3634) app: U=230.4 V  I=0.523 A  P=119.8 W  PF=0.987
Segurança

U mostra aproximadamente a tensão da rede (220-240 V para redes de 230 V) — isso significa que o módulo está corretamente ligado.

Se I continuar em 0.000 A com uma carga ligada: o módulo não sabe qual pinça de CT está em uso (o passo de configuração do sensor foi ignorado ou falhou) — sem isso as leituras de corrente ficam a zero. PF é indefinido quando I=0 e pode ler nan, 0 ou um valor de substituição; ignore-o até a corrente ser diferente de zero. Veja 10 · Resolução de problemas, "A corrente lê zero numa carga a funcionar".

Passo 4 — O que faz a configuração do sensor

As duas chamadas do Passo 3 indicam ao módulo a classe e o modelo do sensor. Sem elas, os coeficientes de calibração não são carregados e as leituras de corrente ficam a zero. A ordem importa: primeiro a classe, depois o modelo.

C
/* Step A: sensor class. The current rbAmp SKU uses SCT-013 clamps. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
/* Step B: model. For example, SCT-013-030 for a household feed up to ~7 kW. */
rbamp_set_ct_model(dev, 3);

Códigos de modelo:

code Modelo Gama Utilização típica
1 SCT-013-005 0..5 A Cargas pequenas, uma só tomada
2 SCT-013-010 0..10 A Frigorífico, máquina de lavar roupa
3 SCT-013-030 0..30 A Alimentação doméstica até ~7 kW
4 SCT-013-050 0..50 A Carregador de VE, aquecimento elétrico
5 SCT-013-100 0..100 A Entrada de serviço principal de uma casa ou pequeno escritório
6 SCT-013-020 0..20 A Esquentador, caldeira, grande eletrodoméstico
7 SCT-013-060 0..60 A Subcontador industrial

Mais sobre a seleção (incluindo os outros códigos suportados) — 03 · Seleção do sensor de corrente.

Nota

Estas duas chamadas são feitas uma vez na primeira instalação — a escolha fica guardada na flash do módulo e sobrevive a um reinício. O tempo total é de cerca de 1.4 segundos (duas escritas na flash × ~700 ms cada).

Em execuções seguintes do firmware pode saltar rbamp_set_sensor_class() e rbamp_set_ct_model() (o módulo lembra-se). Mas também não faz mal chamá-las — chamar de novo com o mesmo valor não escreve.

Passo 5 — Contabilização de energia (Wh)

O módulo devolve apenas as grandezas instantâneas + a potência média num período. Os próprios Wh são calculados pelo componente a partir de esp_timer_get_time():

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

onde master_dt_s é o número de segundos entre duas chamadas bem-sucedidas a rbamp_read_period_snapshot(). O componente guarda o carimbo do último instantâneo no handle e calcula a diferença por si.

Um modelo mínimo para contabilização periódica (uma vez por minuto):

C
void app_main(void) {
    /* ...bus + rbamp_new + rbamp_begin + set_sensor_class + set_ct_model (Step 3)... */

    while (1) {
        vTaskDelay(pdMS_TO_TICKS(60000));   /* 60-second period */

        rbamp_period_snapshot_t snap;
        esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
        if (err != ESP_OK || !snap.valid) {
            ESP_LOGW(TAG, "snapshot error: %s", rbamp_err_to_str(err));
            continue;
        }

        ESP_LOGI(TAG, "avg P over period: %.2f W   accumulated: %.4f Wh   dt=%u ms",
                 (double)snap.avg_p[0],
                 rbamp_energy_wh(dev, 0),
                 (unsigned)snap.master_dt_ms);
    }
}
Nota

Após o Passo 3, as chamadas a rbamp_set_sensor_class() e rbamp_set_ct_model() já correram uma vez e ficaram guardadas na flash do módulo; no modelo acima estão lá para a nova execução do firmware — o módulo ignora uma chamada repetida com o mesmo valor. O tratamento de erros está parcialmente omitido por brevidade — acrescente guardas if (err != ESP_OK) se quiser apanhar as raras falhas de comunicação no arranque.

O que rbamp_read_period_snapshot() faz por baixo (com skip_latch=false):

  1. Envia ao módulo o comando de instantâneo de período (CMD_LATCH_PERIOD).
  2. Aguarda settle_ms (50 ms por omissão) enquanto o módulo prepara o instantâneo.
  3. Verifica o flag de pronto; lê a potência média/pico.
  4. Atualiza o contador interno de Wh: += avg_p × master_dt_s / 3600 (se o componente for compilado sem CONFIG_RBAMP_DISABLE_ENERGY).
O contador de Wh vive na RAM.

rbamp_energy_wh() recomeça em 0 após cada reinício ou perda de alimentação do ESP32; persista-o você próprio se precisar que sobreviva (ver 06 · Exemplos, Cenário 13).

A primeira chamada após rbamp_begin() é um primer: o módulo devolve o que tiver acumulado desde o arranque (um intervalo inadequado para a contabilização tarifária). O componente sabe por si que este instantâneo tem de ser descartado — o código do utilizador nunca o vê.

Saída esperada:

Text
I (61234) app: avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
I (121234) app: avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Passo 6 — Arranque rápido para uma frota de N módulos

Este arranque rápido mostra o trabalho com um único módulo. O cenário canónico real da biblioteca são vários módulos num mesmo barramento, sob um único handle de frota (rede + N cargas secundárias). O exemplo completo está em 06 · Exemplos, cenário 1. > Pré-requisitos para uma frota. Todos os módulos saem de fábrica no endereço 0x50, e

Segurança

rbamp_fleet_scan exclui os módulos que partilham um endereço. Dê a cada módulo o seu próprio endereço primeiro, um módulo no barramento de cada vez (06 · Exemplos, Cenário 2, rbamp_provision), e defina a classe de sensor e o modelo de CT em cada módulo (03). Caso contrário, a frota fica vazia ou excluída, e as correntes lêem 0. Potência e Wh precisam de uma variante UI: um balanço "rede menos a soma das cargas" precisa de um módulo UI em cada carga.

Um esqueleto mínimo de frota:

C
#include "rbamp_fleet.h"

void app_main(void) {
    /* ... bus init as in Step 3 ... */

    rbamp_fleet_t fleet;
    ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));

    size_t added = 0;
    esp_err_t scan = rbamp_fleet_scan(fleet, /*match_product=*/true, &added);
    if (scan == ESP_ERR_INVALID_STATE) {
        ESP_LOGE("app", "bus wedged — see ch.10 \"Fleet: INVALID_STATE\"");
        return;
    }
    ESP_LOGI("app", "fleet: %u modules; excluded: %u",
             (unsigned)added,
             (unsigned)rbamp_fleet_excluded_count(fleet));

    rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
    rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];

    while (1) {
        size_t n_ok = 0;
        rbamp_fleet_poll_all(fleet, snaps, status,
                             RBAMP_FLEET_MAX_MODULES, &n_ok);

        float p_total;
        rbamp_fleet_total_power(fleet, &p_total);
        ESP_LOGI("app", "fleet: %u/%u modules OK, total P = %.1f W",
                 (unsigned)n_ok, (unsigned)rbamp_fleet_count(fleet), p_total);

        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

No cenário canónico dos 80% um dos módulos é um UI1 na alimentação da rede (fornece total_power e total_energy_wh), e os restantes são sub-medidores de corrente I2/I3 (apenas corrente — sem potência nem Wh; use módulos UI onde precisar de potência ou energia por carga). Os detalhes e os cenários avançados (desagregação rede + cargas secundárias, sincronização GC para instantâneos apertados, o fluxo de provisionamento) estão no capítulo 06.

O que vem a seguir

  • 01 · Visão geral — o que é o rbAmp e o que faz o componente
  • 02 · Linhas de módulos — que nível para que tarefa
  • 06 · Exemplos — cenários de funcionamento: rede + N cargas secundárias (o cânone dos 80%), fluxo de provisionamento, TC mistas multicanal, sincronização GC da frota, MQTT, deep-sleep

  • 07 · Integrações DIY — Home Assistant / Node-RED / OpenHAB

  • 08 · Integrações na nuvem — AWS IoT / Azure / GCP / InfluxDB Cloud

  • 09 · Referência da API — a API pública completa (incluindo o gestor de frota + a configuração de frota por dispositivo + a configuração multicanal + o modelo de erros v1.3 + identificação e provisionamento)

  • 10 · Resolução de problemas — se algo não funcionar (mitigação em três camadas de bloqueio I²C, modos de falha de conflito / bloqueio / provisionamento na frota)


Código-fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/05_quickstart.md (v1.7.3)