05 · Avvio rapido
Un «hello world» di cinque minuti: aggiunga il componente a un progetto IDF, colleghi il modulo, selezioni un sensore, ottenga la prima lettura RT e il primo snapshot per periodo (Wh).
I dettagli (piedinatura per un chip ESP32 specifico, bus multimodulo, scelta di una SCT-013 per intervallo) si trovano nei capitoli adiacenti:
-
04 · Cablaggio — dettagli hardware e default GPIO per ogni chip ESP32 supportato
-
03 · Selezione del sensore di corrente — quale modello SCT-013 usare e perché
Di cosa avrà bisogno
- Un modulo rbAmp (qualsiasi linea di moduli; per semplicità un UI1 — un ingresso di tensione più un canale di corrente; le altre varianti sono elencate in 03)
-
Qualsiasi chip della famiglia ESP32 (
esp32,esp32s2,esp32s3,esp32c2,esp32c3,esp32c6,esp32h2) -
ESP-IDF v5.2+ installato (
. ~/esp/esp-idf/export.shoppure%IDF_PATH%\export.batsu Windows) -
Una pinza CT SCT-013 nominata per la sua corrente massima (5A / 10A / 30A / 50A / 100A)
- Un'alimentazione a 5 V per alimentare il modulo (da un USB-5V DevKitC o esterna)
- Un circuito CA da misurare (una lampada, un bollitore, un elettrodomestico)
Passo 0 — Imposti il target
Se questo è un nuovo progetto ESP-IDF e idf.py set-target non è ancora stato eseguito, lo faccia prima del primo idf.py build — altrimenti la build fallisce con "no target specified":
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Senza questo passo la build fallisce.
Passo 1 — Aggiunga il componente al progetto
Come dipendenza git (consigliato)
Nel file main/idf_component.yml del suo progetto (lo crei se non esiste). Il Component Manager di ESP-IDF scarica la release taggata:
dependencies:
rbamp:
git: https://github.com/rb-amp/rbamp-esp-idf.git
version: v1.7.3
Il componente viene scaricato alla successiva idf.py build (oppure idf.py reconfigure).
Manualmente (submodulo git / clone)
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp
Oppure aggiunga il percorso del componente al CMakeLists.txt della radice del progetto:
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
La dipendenza in main/
# main/CMakeLists.txt
idf_component_register(
SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES rbamp
)
Il componente richiama esp_driver_i2c, esp_timer e log — è tutto ciò che serve allo scenario base del Passo 3. Gli scenari di rete / SPIFFS / OLED richiedono REQUIRES aggiuntivi — vedi 06 · Esempi, la tabella CMakeLists all'inizio del capitolo.
Passo 2 — Cablaggio
Quattro fili + DRDY facoltativo:
| Pin rbAmp | ESP32 (predefinito) | ESP32-S3 (predefinito) | ESP32-C3 (predefinito) |
|---|---|---|---|
VCC |
+5 V (da 4.5 a 5.5 V) | uguale | uguale |
GND |
GND | GND | GND |
SDA |
GPIO21 | GPIO8 | GPIO5 |
SCL |
GPIO22 | GPIO9 | GPIO6 |
L'alimentazione deve essere a 5 V. Le linee I²C funzionano a logica 3.3 V — direttamente compatibili con i GPIO dell'ESP32. La scheda del modulo ha già pull-up integrati da 4.7 kΩ — per un singolo modulo non servono quelli esterni.
La tabella completa della piedinatura per ogni chip ESP32 si trova in 04 · Cablaggio.
⚠ La tensione di rete può uccidere. Scolleghi e blocchi il circuito prima di collegare i terminali L/N o di montare la pinza; faccia eseguire il cablaggio di rete e ogni lavoro dentro un quadro da una persona qualificata. Agganci UN solo conduttore (L) — mai l'intero cavo. Protegga la derivazione L con un fusibile secondo le norme locali.
La pinza SCT-013 si chiude attorno al conduttore di linea (L), con la freccia sul corpo della pinza che punta nella direzione della corrente verso il carico. Un modulo UI richiede anche il collegamento di tensione L/N; la pinza CT si inserisce nel jack CT da 3.5 mm del modulo (etichettato I0, I1, … sul PCB); il lato rete ha i terminali L e N. Vedi 04 · Cablaggio, «Collegamento di rete e CT».
Passo 3 — Primo progetto (prima lettura)
Un main/main.c minimo: avvii il bus, dica al modulo quale pinza CT ha montato, poi stampi U / I / P / PF una volta al secondo.
#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));
}
}
Compili e flashi + apra il monitor:
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
(Su Windows — idf.py -p COM3 ....)
Output atteso con un carico acceso (i valori dipendono dal carico):
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 circa la tensione di rete (220-240 V per reti a 230 V) — significa che il modulo è cablato correttamente.
Se I resta a 0.000 A con un carico acceso: il modulo non sa quale pinza CT è in uso (il passo di configurazione del sensore è stato saltato o non è riuscito) — senza di esso le letture di corrente restano a zero. PF è indefinito quando I=0 e può leggere nan, 0 o un segnaposto; lo ignori finché la corrente non è diversa da zero. Vedi 10 · Risoluzione dei problemi, "La corrente legge zero su un carico funzionante".
Passo 4 — Cosa fa la configurazione del sensore
Le due chiamate del Passo 3 indicano al modulo la classe e il modello del sensore. Senza di esse i coefficienti di calibrazione non vengono caricati e le letture di corrente restano a zero. L'ordine conta: prima la classe, poi il modello.
/* 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);
Codici modello:
code |
Modello | Intervallo | Uso tipico |
|---|---|---|---|
| 1 | SCT-013-005 | 0..5 A | Piccoli carichi, una sola presa |
| 2 | SCT-013-010 | 0..10 A | Frigorifero, lavatrice |
| 3 | SCT-013-030 | 0..30 A | Alimentazione domestica fino a ~7 kW |
| 4 | SCT-013-050 | 0..50 A | Caricatore EV, riscaldamento elettrico |
| 5 | SCT-013-100 | 0..100 A | Presa di servizio principale di una casa o di un piccolo ufficio |
| 6 | SCT-013-020 | 0..20 A | Scaldabagno, caldaia, grande elettrodomestico |
| 7 | SCT-013-060 | 0..60 A | Sotto-contatore industriale |
Per altre informazioni sulla selezione (inclusi gli altri codici supportati) — 03 · Selezione del sensore di corrente.
Queste due chiamate si fanno una volta alla prima installazione — la scelta viene salvata nella flash del modulo e sopravvive a un reset. Il tempo totale è di circa 1.4 secondi (due scritture in flash × ~700 ms ciascuna).
Nelle esecuzioni successive del firmware può saltare rbamp_set_sensor_class() e rbamp_set_ct_model() (il modulo ricorda). Non fa comunque danno — richiamarle con lo stesso valore non scrive nulla.
Passo 5 — Contabilità dell'energia (Wh)
Il modulo restituisce solo le grandezze istantanee + la potenza media su un periodo. I Wh stessi sono calcolati dal componente a partire da esp_timer_get_time():
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
dove master_dt_s è il numero di secondi tra due chiamate riuscite di rbamp_read_period_snapshot(). Il componente conserva nell'handle il timestamp dell'ultimo snapshot e calcola la differenza da solo.
Un modello minimo per la contabilità periodica (una volta al 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);
}
}
Dopo il Passo 3 le chiamate a rbamp_set_sensor_class() e rbamp_set_ct_model() sono già state eseguite una volta e salvate in flash del modulo; nel modello sopra sono lì per la rieseguizione del firmware — il modulo ignora una chiamata ripetuta con lo stesso valore. La gestione degli errori è in parte omessa per brevità — aggiunga ulteriori guardie if (err != ESP_OK) se vuole intercettare i rari disturbi di comunicazione all'avvio.
Cosa fa rbamp_read_period_snapshot() sotto il cofano (con skip_latch=false):
- Invia al modulo il comando di snapshot di periodo (
CMD_LATCH_PERIOD). - Attende
settle_ms(50 ms per impostazione predefinita) mentre il modulo prepara lo snapshot. - Verifica il flag di pronto; legge la potenza media/di picco.
- Aggiorna il contatore Wh interno:
+= avg_p × master_dt_s / 3600(se il componente è compilato senzaCONFIG_RBAMP_DISABLE_ENERGY).
rbamp_energy_wh() riparte da 0 dopo ogni reset o perdita di alimentazione dell'ESP32; lo salvi lei stessa se deve sopravvivere (vedi 06 · Esempi, Scenario 13).
La prima chiamata dopo rbamp_begin() è un primer: il modulo restituisce tutto ciò che ha accumulato dall'accensione (un intervallo inadatto alla contabilizzazione tariffaria). Il componente sa da solo che questo snapshot va scartato — il codice utente non lo vede mai.
Output atteso:
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 — Guida rapida per una flotta di N moduli
Questa guida rapida mostra come lavorare con un singolo modulo. Lo scenario canonico reale per la libreria riguarda più moduli su un unico bus sotto un unico handle di flotta (rete principale + N carichi secondari). L'esempio completo è in 06 · Esempi, scenario 1. > Prerequisiti per una flotta. Tutti i moduli escono di fabbrica all'indirizzo 0x50, e
rbamp_fleet_scan esclude i moduli che condividono un indirizzo. Dia a ciascun modulo un proprio indirizzo prima, un modulo alla volta sul bus (06 · Esempi, Scenario 2, rbamp_provision), e imposti la classe di sensore e il modello CT su ciascun modulo (03). Altrimenti la flotta risulta vuota o esclusa, e le correnti leggono 0. Potenza e Wh richiedono una variante UI: un bilancio "rete meno somma dei carichi" richiede un modulo UI su ogni carico.
Uno scheletro minimo di flotta:
#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));
}
}
Nello scenario canonico 80% uno dei moduli è una UI1 sull'alimentazione di rete (fornisce total_power e total_energy_wh), e gli altri sono sotto-contatori di corrente I2/I3 (solo corrente — niente potenza o Wh; usi i moduli UI dove servono potenza o energia per carico). I dettagli e gli scenari avanzati (disaggregazione rete + sotto-carichi, sincronizzazione GC per snapshot precisi, flusso di messa in servizio) sono nel capitolo 06.
Cosa c'è dopo
- 01 · Panoramica — cos'è rbAmp e cosa fa il componente
- 02 · Linee di moduli — quale classe per quale attività
-
06 · Esempi — scenari di lavoro: rete principale + N sotto-carichi (il canone 80%), flusso di messa in servizio, CT misti multicanale, sincronizzazione GC della flotta, MQTT, deep-sleep
-
07 · Integrazioni fai-da-te — Home Assistant / Node-RED / OpenHAB
-
08 · Integrazioni cloud — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Riferimento API — l'API pubblica completa (inclusi il gestore della flotta + la configurazione della flotta per dispositivo + la configurazione multi-canale + il modello di errore v1.3 + identificazione e provisioning)
-
10 · Risoluzione dei problemi — se qualcosa non funziona (mitigazione a tre livelli per i blocchi i2c, modalità di guasto di conflitto / blocco / messa in servizio della flotta)
Sorgente e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repo: docs/05_quickstart.md (v1.7.3)