05 · Inicio rápido
Un «hola mundo» de cinco minutos: añada el componente a un proyecto IDF, conecte el módulo, seleccione un sensor, tome su primera lectura RT y su primera instantánea por periodo (Wh).
Los detalles (pinout para un chip ESP32 concreto, bus multimódulo, elección de una SCT-013 por rango) están en los capítulos siguientes:
-
04 · Cableado: detalles de hardware y valores por defecto de GPIO por chip para todos los chips ESP32 admitidos
-
03 · Selección del sensor de corriente: qué modelo SCT-013 usar y por qué
Lo que necesitará
- Un módulo rbAmp (cualquier línea de módulos; por simplicidad, un UI1: una entrada de tensión más un canal de corriente; las demás variantes están en 03)
-
Cualquier chip de la familia ESP32 (
esp32,esp32s2,esp32s3,esp32c2,esp32c3,esp32c6,esp32h2) -
ESP-IDF v5.2+ instalado (
. ~/esp/esp-idf/export.sho%IDF_PATH%\export.baten Windows) -
Una pinza de CT SCT-013 con la corriente nominal máxima de su instalación (5 A / 10 A / 30 A / 50 A / 100 A)
- Una alimentación de 5 V para el módulo (desde un DevKitC con USB-5V o una fuente externa)
- Un circuito de CA que medir (una lámpara, un hervidor, un electrodoméstico)
Paso 0: establezca el objetivo
Si es un proyecto ESP-IDF nuevo y todavía no se ha ejecutado idf.py set-target, hágalo antes del primer idf.py build; de lo contrario, la compilación falla con «no target specified»:
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Sin este paso la compilación falla.
Paso 1: añada el componente al proyecto
Como dependencia git (recomendado)
En el archivo main/idf_component.yml de su proyecto (cree el archivo si no existe). El Gestor de componentes de ESP-IDF descarga la versión etiquetada:
dependencies:
rbamp:
git: https://github.com/rb-amp/rbamp-esp-idf.git
version: v1.7.3
El componente se descarga en el siguiente idf.py build (o idf.py reconfigure).
Manualmente (submódulo de git / clonado)
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp
O añada la ruta del componente al CMakeLists.txt raíz del proyecto:
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
La dependencia en main/
# main/CMakeLists.txt
idf_component_register(
SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES rbamp
)
El componente incorpora esp_driver_i2c, esp_timer y log: es todo lo que necesita el escenario básico del paso 3. Los escenarios de red / SPIFFS / OLED requieren REQUIRES adicionales: véase 06 · Ejemplos, la tabla de CMakeLists al inicio del capítulo.
Paso 2 — Cableado
Cuatro cables más DRDY opcional:
| Pin de rbAmp | ESP32 (por defecto) | ESP32-S3 (por defecto) | ESP32-C3 (por defecto) |
|---|---|---|---|
VCC |
+5 V (4.5 a 5.5 V) | igual | igual |
GND |
GND | GND | GND |
SDA |
GPIO21 | GPIO8 | GPIO5 |
SCL |
GPIO22 | GPIO9 | GPIO6 |
La alimentación debe ser de 5 V. Las líneas I²C funcionan a lógica de 3.3 V, directamente compatible con los GPIO del ESP32. La placa del módulo ya incorpora resistencias de pull-up de 4.7 kΩ: para un único módulo no hacen falta externas.
La tabla completa de pinout de cada chip ESP32 está en 04 · Cableado.
⚠ La tensión de red puede matar. Desconecte y bloquee el circuito antes de conectar los terminales L/N o colocar la pinza; que un técnico cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro. Pinze UN solo conductor (L): nunca el cable completo. Proteja la derivación L con fusible según la normativa local.
La pinza SCT-013 se cierra alrededor del conductor de fase (L), con la flecha del cuerpo de la pinza apuntando en el sentido de la corriente hacia la carga. Un módulo UI también necesita su conexión de tensión L/N; la pinza CT se enchufa a la toma CT de 3.5 mm del módulo (marcada I0, I1, … en la placa); el lado de red tiene los terminales L y N. Véase 04 · Cableado, «Conexión de red y CT».
Paso 3: primer proyecto (primera lectura)
Un main/main.c mínimo: inicie el bus, indique al módulo qué pinza CT ha montado e imprima U / I / P / PF una 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, grabe y abra el monitor:
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
(En Windows: idf.py -p COM3 ....)
Salida esperada con una carga conectada (los valores dependen de su 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 muestra aproximadamente la tensión de red (220-240 V para redes de 230 V): eso significa que el módulo está bien cableado.
Si I se queda en 0.000 A con una carga conectada: el módulo no sabe qué pinza de CT está usando (se omitió o falló el paso de configuración del sensor); sin ello, las lecturas de corriente se quedan en cero. PF no está definido cuando I=0 y puede leer nan, 0 o un valor de relleno; ignórelo hasta que la corriente sea distinta de cero. Vea 10 · Solución de problemas, «La corriente lee cero con una carga que funciona».
Paso 4: qué hace la configuración del sensor
Las dos llamadas del paso 3 indican al módulo la clase y el modelo del sensor. Sin ellas no se cargan los coeficientes de calibración y las lecturas de corriente permanecen en cero. El orden importa: primero la clase, después el 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 | Rango | Uso típico |
|---|---|---|---|
| 1 | SCT-013-005 | 0..5 A | Cargas pequeñas, una sola toma |
| 2 | SCT-013-010 | 0..10 A | Frigorífico, lavadora |
| 3 | SCT-013-030 | 0..30 A | Alimentación doméstica de hasta ~7 kW |
| 4 | SCT-013-050 | 0..50 A | Cargador de VE, calefacción eléctrica |
| 5 | SCT-013-100 | 0..100 A | Acometida principal de una vivienda o pequeña oficina |
| 6 | SCT-013-020 | 0..20 A | Calentador de agua, caldera, electrodoméstico grande |
| 7 | SCT-013-060 | 0..60 A | Submedidor industrial |
Más sobre la selección (incluidos los demás códigos admitidos): 03 · Selección del sensor de corriente.
Estas dos llamadas se hacen una vez en la primera instalación: la elección se guarda en la flash del módulo y sobrevive a un reinicio. El tiempo total es de unos 1.4 segundos (dos escrituras en flash × ~700 ms cada una).
En las siguientes ejecuciones del firmware puede omitir rbamp_set_sensor_class() y rbamp_set_ct_model() (el módulo lo recuerda). Tampoco hace daño: volver a llamar con el mismo valor no escribe.
Paso 5 — Contabilidad de energía (Wh)
El módulo devuelve solo magnitudes instantáneas más la potencia media de un período. Los propios Wh los calcula el componente a partir de esp_timer_get_time():
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
donde master_dt_s es el número de segundos entre dos llamadas correctas a rbamp_read_period_snapshot(). El componente guarda en el manejador la marca de tiempo de la última instantánea y calcula la diferencia por sí mismo.
Una plantilla mínima para la contabilidad periódica (una 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);
}
}
Tras el Paso 3, las llamadas a rbamp_set_sensor_class() y rbamp_set_ct_model() ya se ejecutaron una vez y se guardaron en la flash del módulo; en la plantilla anterior están para una nueva ejecución del firmware: el módulo ignora una llamada repetida con el mismo valor. El tratamiento de errores se omite en parte por brevedad: añada guardas if (err != ESP_OK) si quiere detectar los raros fallos de comunicación durante el arranque.
Lo que hace rbamp_read_period_snapshot() internamente (con skip_latch=false):
- Envía al módulo el comando de instantánea de periodo (
CMD_LATCH_PERIOD). - Espera
settle_ms(50 ms por defecto) mientras el módulo prepara la instantánea. - Comprueba el indicador de listo; lee la potencia media/pico.
- Actualiza el contador interno de Wh:
+= avg_p × master_dt_s / 3600(si el componente se compila sinCONFIG_RBAMP_DISABLE_ENERGY).
rbamp_energy_wh() vuelve a 0 tras cada reinicio del ESP32 o corte de alimentación; persístalo usted mismo si necesita que sobreviva (vea 06 · Ejemplos, escenario 13).
La primera llamada tras rbamp_begin() es un cebado: el módulo devuelve lo acumulado desde el encendido (un intervalo no apto para la contabilidad tarifaria). El componente sabe por sí mismo que esta instantánea debe descartarse: el código del usuario nunca la ve.
Salida 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
...
Paso 6 — Inicio rápido para una flota de N módulos
Este inicio rápido muestra cómo trabajar con un único módulo. El escenario canónico real de la biblioteca son varios módulos en un mismo bus bajo un único manejador de flota (acometida + N subcircuitos). El ejemplo completo está en 06 · Ejemplos, escenario 1. > Requisitos previos para una flota. Todos los módulos salen de fábrica en la dirección 0x50, y
rbamp_fleet_scan excluye los módulos que comparten dirección. Asigne primero a cada módulo su propia dirección, un módulo en el bus cada vez (06 · Ejemplos, escenario 2, rbamp_provision), y establezca la clase de sensor y el modelo de CT en cada módulo (03). De lo contrario, la flota quedará vacía o excluida, y las corrientes leerán 0. La potencia y los Wh necesitan una variante UI: un balance «red menos suma de cargas» necesita un módulo UI en cada carga.
Un esqueleto mínimo de flota:
#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));
}
}
En el escenario canónico del 80 % uno de los módulos es un UI1 en la acometida de red (proporciona total_power y total_energy_wh), y el resto son subcontadores de corriente I2/I3 (solo corriente — sin potencia ni Wh; use módulos UI donde necesite potencia o energía por carga). Los detalles y los escenarios avanzados (desagregación red + subcircuitos, sincronización GC para instantáneas precisas, flujo de aprovisionamiento) están en el capítulo 06.
Lo que viene después
- 01 · Visión general: qué es rbAmp y qué hace el componente
- 02 · Líneas de módulos — qué nivel para qué tarea
-
06 · Ejemplos — escenarios de trabajo: acometida + N subcircuitos (el canon del 80 %), flujo de aprovisionamiento, CT mixtas multicanal, sincronización GC de la flota, MQTT, suspensión profunda
-
07 · Integraciones DIY: Home Assistant / Node-RED / OpenHAB
-
08 · Integraciones en la nube — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Referencia de la API: la API pública completa (incluidos el gestor de flota, la configuración de flota por dispositivo, la configuración multicanal, el modelo de errores v1.3 y la identificación y aprovisionamiento)
-
10 · Solución de problemas — si algo no funciona (mitigación de tres capas para bloqueos I²C, modos de fallo de conflicto / bloqueo / aprovisionamiento en la flota)
Código fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/05_quickstart.md (v1.7.3)