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:
-
04 · Cablagem — detalhes de hardware e valores GPIO predefinidos por chip para todos os ESP32 suportados
-
03 · Seleção do sensor de corrente — qual o modelo SCT-013 a usar e porquê
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.shou%IDF_PATH%\export.batno 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":
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Sem este passo a compilação falha.
Passo 1 — Adicionar o componente ao projeto
Como dependência git (recomendado)
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:
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)
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:
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
A dependência em main/
# 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.
⚠ 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".
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.
#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:
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):
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
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.
/* 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.
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():
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):
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);
}
}
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):
- Envia ao módulo o comando de instantâneo de período (
CMD_LATCH_PERIOD). - Aguarda
settle_ms(50 ms por omissão) enquanto o módulo prepara o instantâneo. - Verifica o flag de pronto; lê a potência média/pico.
- Atualiza o contador interno de Wh:
+= avg_p × master_dt_s / 3600(se o componente for compilado semCONFIG_RBAMP_DISABLE_ENERGY).
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:
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
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:
#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)