06 · Ejemplos
Este capítulo abre con los escenarios principales: los patrones de despliegue reales para los que se diseñó la biblioteca (acometida + N subcircuitos en un único bus, instantáneas sincronizadas por GC). Les siguen los escenarios de un solo módulo, desde un «hola mundo» mínimo hasta un registrador con suspensión profunda alimentado por batería.
La mayoría de los escenarios se entregan como proyectos IDF listos para compilar en examples/, que puede compilar con idf.py -C examples/. El código de este capítulo es una versión destilada de la lógica clave, no el proyecto completo (bus_cfg / puesta en marcha de WiFi / Kconfig se omiten por brevedad).
| # | Escenario | Dificultad | Fuente |
|---|---|---|---|
| 1 | Red + N subcargas: el canon del 80 % | medio | examples/fleet_sync/ |
| 2 | Flujo de aprovisionamiento (virgen → flota) | bajo | (composition) |
| 3 | CT mixtos multicanal (I3, modelos distintos) | medio | (composition) |
| 4 | Sincronización GC de la flota: sincronía de períodos tarifarios | medio | examples/fleet_sync/ |
| 5 | Lectura rápida (un único módulo) | mínimo | examples/quick_read/ |
| 6 | Medidor de Wh en un LCD de 16×2 | bajo | examples/lcd_period/ |
| 7 | Monitorización de 3 módulos (secuencial heredado) | bajo | examples/multi_module/ |
| 8 | MQTT por canal | medio | examples/mqtt_publisher/ |
| 9 | Medición bidireccional en el lado del master | medio | (composition) |
| 10 | Balance energético de toda la vivienda (3 módulos) | alta | (composition) |
| 11 | Registro basado en eventos (EMA) | medio | (composition) |
| 12 | Registrador CSV local en SPIFFS | medio | examples/spiffs_logger/ |
| 13 | Registrador con batería y deep sleep | medio | examples/deep_sleep_logger/ |
| 14 | I3 con CT distinta por canal (análisis en profundidad de cargas mixtas) | medio | (composition) |
| 15 | Submedición: 5×UI1 en un bus compartido | alta | (composition) |
| 16 | Instantánea de difusión GC para más de 8 módulos | alta | (composition) |
| 17 | Filtrado por grupo GC (medición multiinquilino) | alta | (composition) |
| 18 | Módulo STD: potencia reactiva / aparente, THD, energía con temporización del master | medio | examples/std_meter/ |
El escenario 18 muestra la línea de módulos STD. Los escenarios 1–4 son los principales, construidos en torno al despliegue canónico de la biblioteca. Su código usa la API de flota y está validado en banco con hardware real (una flota heterogénea UI1+I2+I3). Los escenarios 5–13 son de un solo módulo y patrones de composición; los 14–17 son escenarios de flota extendida (un análisis en profundidad de las capacidades introducidas en 1–4). El escenario 7 es la instantánea secuencial heredada por módulo, sin la API de flota, conservada para comparación y como ruta de migración.
Todos los escenarios suponen que la clase de sensor y el modelo de CT ya se configuraron con rbamp_set_sensor_class() + rbamp_set_ct_model() (véase 05 · Inicio rápido, paso 3). Esto se hace una vez en la instalación: los ajustes se guardan en la flash del módulo y sobreviven a un reinicio.
REQUIRES adicional para main/CMakeLists.txt
El componente base incorpora esp_driver_i2c, esp_timer y log. Algunos escenarios usan componentes adicionales de ESP-IDF: añádalos al REQUIRES de su main/:
| Escenario | REQUIRES adicionales |
|---|---|
| 1: principal + N cargas secundarias (flota) | — (solo rbamp) |
| 2: flujo de aprovisionamiento | — |
| 3 — Multicanal con CT mixtas (I3) | — |
| 4 — Sincronización GC de la flota | — |
| 5: lectura rápida | — |
| 6: medidor de Wh en LCD | rbamp (el driver de la LCD es un componente aparte que usted elige) |
| 7 — Multimódulo (secuencial heredado) | — |
| 8: MQTT por canal | rbamp mqtt esp_wifi esp_event esp_netif nvs_flash |
| 9: medición bidireccional | — |
| 10: balance de energía | — |
| 11 — Registro basado en eventos | — |
| 12 — Registrador SPIFFS | rbamp spiffs |
| 13: registrador con deep sleep | rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (si publica) |
| 18: medidor STD | — (solo rbamp) |
Los componentes de red también requieren nvs_flash_init() en app_main y la puesta en marcha de WiFi. Por brevedad, todo esto se omite en los fragmentos siguientes; el proyecto completo siempre está en examples/.
Nota importante sobre los fragmentos siguientes. Cada fragmento es una destilación de la lógica clave, no un app_main completo. En código real, la línea rbamp_handle_t dev va siempre 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 un solo módulo) o de rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (para la flota). Cuando termine el trabajo: rbamp_del(dev) / rbamp_fleet_destroy(fleet) (se omiten donde app_main entra en un bucle infinito: el manejador vive hasta que el chip se reinicie).
Escenario 1 — Acometida + N subcircuitos (el canon del 80 %): sistema de medición integrado
Objetivo: el despliegue canónico de la biblioteca — un sistema de medición coherente sobre una flota heterogénea, cerrado en un único bucle:
-
Descubrir:
rbamp_fleet_scanencuentra todos los módulos, verifica su identidad y descarta las direcciones en conflicto. -
Configurar:
rbamp_configure_channelsestablece la clase de sensor, los modelos de CT por canal y un únicoSAVE_USER_CONFIGfinal en una sola llamada por módulo multicanal. -
Armado GC —
rbamp_fleet_enable_gc_allhabilita la recepción de instantáneas General-Call en todos los módulos de la flota. -
Bucle — en cada ciclo el maestro realiza un
_gclatchatómico (una instantánea síncrona en toda la flota), comprueba_check_sync, lee_poll_all, integra la energía segúnmaster_dty calcula_total_power+_total_energy_wh.
Este es el ejemplo principal del capítulo: muestra toda la biblioteca en funcionamiento con la configuración canónica. Cada uno de los otros escenarios (2-17) desglosa este flujo en bloques individuales o lo amplía con integraciones de terceros (LCD, MQTT, SD).
Hardware (validado en HW): una flota heterogénea de 3 módulos en un único bus, con una resistencia pull-up externa de 4.7 kΩ en SDA/SCL (véase 04 · Cableado, sección «Bus multimódulo — la topología principal»):
@0x50— UI1, contador de red en la acometida (un canal de corriente + tensión).@0x51— I2, un subcontador de corriente de dos canales (sin tensión).@0x52: I3, un submedidor de corriente de tres canales (sin tensión).
La carga de referencia en la línea es de ~0.57 A.
Código: bucle integrado
#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 */
}
}
Salida de banco (validada en hardware con la flota completa)
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)
Las cifras de banco ilustran la forma de los datos y su flujo por el sistema, no la precisión de la medida.
Notas para el despliegue
-
Un único bucle sincronizado es todo el sistema. En cada ciclo: un
gclatch(una única transacción I²C General-Call) → todos los módulos inician de forma atómica su instantánea de periodo (check_sync= 3/3, desfase = 0) → unpoll_alllee toda la flota → agregación. No hay deriva entre módulos por una cadena de ida y vuelta secuenciales. -
Comportamiento de
total_poweren una flota heterogénea. UI1 da potencia activa (tiene tensión → tieneP); I2/I3 solo miden corriente, así que su aportación atotal_poweres cero. Por tanto, en el canon,total_power≈ la potencia del módulo de red. Para la potencia por carga en un subcontador, calcúlela en el lado del maestro:P_subload[k] ≈ V_red × I_sub[k](una aproximación, correcta cuando los PF son próximos; un subcontador solo de corriente no puede informar de la P exacta por carga). -
Energía (Wh): reloj de pared del master.
E_totalcrece de forma monótona (de 2.55 a 6.94 Wh durante la ventana de captura de banco); el componente integra cada período mediantemaster_dt_ms(esp_timer), no mediantelatch_msdel chip (un temporizador de diagnóstico del módulo que puede leerse corto). Una marca espuria suma0 Whsi no ha transcurrido ningún período nuevo entre sondeos: esto es normal (snap.valid = 0 en ese ciclo). -
Sondeo resistente a MISS. Si uno de los módulos sale del bus (desconexión, reinicio),
poll_alllo marca constatus[i] != ESP_OKy sigue sondeando el resto: el master no se cuelga. Verificado en banco: un módulo que se desconectó a mitad de ejecución dejó la flota sondeando conn_ok=2/3sin bloqueo. Lo mismo vale paracheck_sync:missed_idxseñala el primer módulo desincronizado mientras los demás siguen tomando instantáneas. -
Análisis de balance. En el canon del 80 %:
balance = P_red − Σ(V_red × I_sub[k])— una estimación de «el resto» (consumo de fondo, cargas no contabilizadas). El código dirigido recorre la flota separando el manejador de red (el que tienehas_voltage = true) de los submanejadores (todos los demás). -
Corrientes por canal → desagregación de cargas. Mediante
fleet_poll_all, el maestro ve todos los canales de corriente a la vez (1+2+3 = 6 en nuestra flota de banco), sin lectores independientes por módulo. -
CT mixtos en un módulo de 3 canales. Use la versión actual de la biblioteca; los espejos [1 2 3] en I3 se asientan según lo configurado. El orden en que se asocian los canales no importa.
-
Latencia de sondeo para dimensionar en producción (medida en HW). En banco a 50 kHz de I²C: 2 módulos, media
89.4 ms(mín. 89.4 / máx. 89.6); 3 módulos, media112.1 ms(mín. 112.1 / máx. 112.3). Es ≈ 22-23 ms por módulo adicional, lineal y con muy poco jitter (mín. ≈ máx.). Unfleet_poll_allpor lotes es determinista en un bus limpio. Una flota de 3 módulos (~112 ms) cabe en un intervalo de sondeo de 200 ms: es decir, una frecuencia de sondeo de 5 Hz es alcanzable (cada segunda ventana de módulo de 100 ms) sin saturar el bus. El presupuesto completo del bus (cuando la flota supera el intervalo de sondeo) está en la tabla de 04 · Cableado, sección «Presupuesto energético del bus».
Escenario 2 — Flujo de aprovisionamiento (virgen → flota)
Objetivo: trasladar un módulo nuevo de su dirección de fábrica 0x50 a una dirección de trabajo y añadirlo a una flota existente, guardando su configuración (modelos de CT, etiqueta) en flash.
Hardware (validado en HW): un módulo virgen en la dirección de fábrica 0x50 (HW_VARIANT de 3 canales). El aprovisionamiento lo traslada a la dirección 0x52 y guarda la configuración en flash.
#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);
}
Salida de banco (camino de éxito validado en hardware):
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 devuelve true tras una llamada correcta. En un módulo recién salido de fábrica (que nada ha tocado todavía), el is_provisioned previo será false: es el estado 0xFB (ERR_FLASH_PARAMS_BAD) normal, descrito en 10 · Solución de problemas, y no es fatal.
Rutas de fallo
| Error | Condición | Recuperación |
|---|---|---|
ESP_ERR_NOT_FOUND |
Nadie responde en 0x50 |
Compruebe que el módulo virgen está conectado físicamente y con alimentación (VCC); explore el bus (10 · Solución de problemas). |
ESP_ERR_INVALID_STATE |
Se detectó un conflicto en 0x50 o en desired_addr; varios módulos responden de forma idéntica |
Violación de la disciplina — más de un virgen en el bus. Corte la alimentación, desconecte físicamente todos menos uno y reintente (véase la ruta de recuperación en 10 · Solución de problemas). |
ESP_ERR_TIMEOUT |
La confirmación en dos fases se completó, pero el módulo no apareció en la nueva dirección dentro de la ventana de arranque | Corte la alimentación del módulo y reintente. Si persiste, es un problema de ciclos de flash. |
ESP_ERR_INVALID_ARG |
desired_addr fuera de 0x08..0x77 |
Use una dirección válida de 7 bits. |
Recorrido detallado de los modos de fallo: 10 · Solución de problemas, sección «Flota: rbamp_provision devolvió un error».
Escenario 3 — Multicanal con CT mixtas (I3, modelos distintos por canal)
Objetivo: demostrar rbamp_configure_channels en un I3: tres canales con modelos de CT distintos (p. ej., ch0=SCT-013-005 para una carga pequeña, ch1=SCT-013-030 para una mediana, ch2=SCT-013-020 para una grande) con un único ciclo de escritura en flash terminal (amable con la flash) y confirmar la persistencia tras un reinicio.
#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);
}
Salida de banco (validada en HW sobre un I3 regrabado limpio):
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)
La propiedad de «guardado único»: por qué importa
configure_channels hace un CMD_SAVE_USER_CONFIG de terminal al final. La alternativa — llamadas separadas a set_ct_model_ch por cada canal, cada una con su propio save_user_config posterior — da tres ciclos de borrado y escritura en flash.
Comparativa de latencia en banco (sobre el mismo I3):
| Enfoque | Latencia | Ciclos de flash |
|---|---|---|
configure_channels(...) — 1 GUARDADO en terminal |
~1403 ms | 1 |
3× (set_ct_model_ch + save_user_config) |
~3492 ms | 3 |
3× más lento: es decir, (~2.5×) × ~700 ms. El punto clave es la diferencia de 3× en ciclos de desgaste sobre la misma página de flash: con la reconfiguración habitual de módulos en campo, esto se traduce en un coste de desgaste importante. Use siempre configure_channels cuando necesite establecer la clase de sensor y los modelos de CT por canal.
Para la familia 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. Un código fuera de {1, 2, 3, 4, 5, 6, 7} da ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).
Escenario 4 — Sincronización GC de flota (sincronía de periodos tarifarios)
Objetivo: demostrar una instantánea atómica en toda la flota con una única trama I²C General-Call. A diferencia del CMD_LATCH_PERIOD secuencial por módulo (donde el desfase se acumula en cada ida y vuelta), GC sincroniza todos los módulos en una única transacción de bus.
Hardware: la misma flota heterogénea UI1+I2+I3 (@0x50/0x51/0x52).
#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));
}
}
Salida de banco (10 rondas sobre la flota UI1+I2+I3, pull-up de 4.7 kΩ):
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
Cuándo usar la sincronización GC:
-
Sincronización ajustada. Si la diferencia de instantáneas entre módulos por minuto o por segundo importa para los informes (por ejemplo, un cálculo de balance
red − Σ(sub)integrado en el tiempo: el desfase entre módulos introduce un error sistemático), GC aportaskew = 0según la medición en banco. Una instantánea secuencial por módulo en los mismos 3 módulos acumula 100-300 µs por módulo × N, lo que se nota en una ventana de 60 minutos en análisis de precisión. -
Flota grande. A medida que crece el número de módulos, la diferencia entre «N × ida y vuelta secuencial» y «una sola trama GC» crece linealmente.
-
Alineación entre despliegues. Si tiene varios ESP32 en buses distintos que comparten un reloj maestro, la marca GC puede sincronizarse mediante el reloj de pared del master, y entonces las instantáneas de buses distintos quedan alineadas dentro de una única ventana de ida y vuelta de red.
Testigo mediante check_sync: una comprobación de que todos los módulos recibieron realmente la trama GC. Puede pasar por alto un módulo si estaba arrancando o en un ciclo de guardado en el momento de la trama: missed_idx señala el primero desincronizado. En la validación en banco, 10 rondas seguidas: 0 fallos.
Condición previa. GC debe estar habilitado en todos los módulos (rbamp_fleet_enable_gc_all o, por dispositivo, rbamp_enable_gc + SAVE_USER_CONFIG + reinicio). Un módulo nuevo con valores de fábrica no acepta GC: es así por diseño, como protección frente a difusiones accidentales en un bus de puesta en marcha.
Escenario 5: lectura rápida (un solo módulo)
Objetivo: imprimir U / I / P / PF / frecuencia en el registro de ESP-IDF una vez por segundo. El mismo «hola mundo» que escribió en 05 · Inicio rápido, pero mediante rbamp_read_all(): una lectura única de todo el bloque RT en una sola estructura.
#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));
}
}
Qué ocurre en el bus: rbamp_read_all() en un UI3 realiza unas 53 transacciones de un byte (13 valores float × 4 bytes + 1 byte de frecuencia). A 50 kHz con margen de reintentos, del orden de 25-30 ms. Si no necesita todos los valores, llame a las funciones por propiedad (rbamp_read_voltage(), rbamp_read_current(ch)): menos bytes en el bus.
Escenario 6 — Contador de Wh en una LCD de 16×2
Objetivo: un contador de Wh, actualizado una vez por minuto, en una LCD de caracteres de 16×2 con expansor I²C PCF8574 (compatible con HD44780). La LCD está en el mismo bus I²C que el rbAmp. El mecanismo clave del componente es rbamp_read_period_snapshot(), que encapsula instantánea + asentamiento + comprobación de validez + lectura + avance de Wh en una sola llamada.
#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);
}
}
El proyecto IDF completo — examples/lcd_period/.
Gestión de instantáneas obsoletas. rbamp_read_period_snapshot() devuelve ESP_ERR_INVALID_RESPONSE si el módulo no logró preparar una instantánea nueva en el momento de la lectura. El componente igualmente registra su marca de tiempo (esp_timer_get_time()) de forma interna, así que la siguiente instantánea válida no se cuenta dos veces en el intervalo.
Escenario 7: monitorización de 3 módulos (secuencial heredado) en un único bus
Objetivo: sondear 3 módulos en las direcciones 0x50 / 0x51 / 0x52 desde un único maestro. Cada módulo debe tener una dirección única (las direcciones se asignan durante la instalación en fábrica o por el integrador; véase 09 · Referencia de API sobre los métodos de cambio de dirección con sus notas de ADVERTENCIA).
El patrón canónico para firmware v1 es un rbamp_latch_period() secuencial en cada dispositivo + una única pausa común de 50 ms + rbamp_read_period_snapshot(skip_latch=true) por dispositivo. El desfase entre dispositivos a 100 kHz: ~1 ms por dispositivo, despreciable frente a un período de 60 segundos.
En firmware v1.3 (REG_VERSION = 0x04), rbamp_broadcast_latch() está totalmente soportada una vez habilitado GC en toda la flota mediante rbamp_fleet_enable_gc_all() — la ruta canónica de sincronización de flota para una sincronía estrecha entre subcontadores (véase la sección de flota GC Strategy 2 anterior en este capítulo). En firmware heredado v1.0-v1.2 (sin soporte de instantánea General-Call) la llamada devuelve ESP_ERR_NOT_SUPPORTED y la biblioteca recurre a la instantánea por dispositivo mostrada arriba. Véase 09 · Referencia de API para más detalles.
#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));
}
}
}
El proyecto completo (con sonda de escaneo del bus y notificación de errores): examples/multi_module/.
Escenario 8 — MQTT por canal
Objetivo: un módulo UI3 con 3 pinzas de CT en tres líneas independientes. Contadores de Wh por canal, publicados en MQTT una vez por minuto. Muestra que rbamp_energy_wh(dev, ch) funciona en cada canal de forma independiente, sin necesidad de un array manual total_wh[3] en el lado del master.
#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));
}
}
}
El proyecto completo — examples/mqtt_publisher/. Para el autodescubrimiento MQTT de HA basado en este patrón, véase 07 · Integraciones caseras + examples/ha_discovery/.
Escenario 9: medición bidireccional en el lado del master
Objetivo: separar la potencia instantánea con signo en consumo bruto y exportación bruta. Use este patrón en el nivel BASIC, donde el firmware recorta los valores negativos en snap.avg_p[ch] (potencia promediada por periodo): muestree rbamp_read_power(dev, 0, &p) (potencia instantánea, con signo en todos los niveles) a 10 Hz en el lado del maestro y agrúpela usted mismo.
#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);
}
}
}
Es un escenario compuesto sin proyecto IDF dedicado. En un módulo STD los contadores de energía tienen signo y rbamp_energy_wh(dev, 0) devuelve un balance neto (la importación y la exportación se guardan por separado en rbamp_std_read_energy()): esta separación en el master solo hace falta en módulos BASIC, o para informar por separado del consumo bruto y de la exportación bruta a partir de la potencia en tiempo real.
Escenario 10: balance energético de toda la vivienda
Objetivo: 3 módulos: red (bidireccional), solar (solo generación), cargas (UI3 para cada aparato). El panel combinado se publica una vez por minuto.
#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 una separación explícita de consumo bruto / exportación bruta en la red, combínelo con el patrón del Escenario 5 (una tarea separada a 10 Hz sobre rbamp_read_power(mains_dev, 0, ...)).
Es un escenario compuesto sin proyecto IDF propio: móntelo a partir de examples/mqtt_publisher/ + examples/multi_module/.
Escenario 11: registro basado en eventos (EMA)
Objetivo: en cada ventana RT de 100 ms, comparar la potencia instantánea con una media móvil exponencial. Registre las desviaciones significativas: cargas como un microondas, un hervidor o un secador de pelo «aparecen» en el registro como un evento de encendido / apagado.
#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);
}
}
}
Escenario compuesto: no tiene proyecto IDF propio. Combínelo con la publicación MQTT del escenario 4 para automatizaciones en HA, o escriba los eventos en SPIFFS con el patrón del escenario 8 para un registro sin conexión.
Escenario 12: registrador CSV local en SPIFFS
Objetivo: escribir una instantánea de período en un archivo CSV en SPIFFS una vez por minuto. Útil para despliegues autónomos sin WiFi / MQTT, o como búfer para una sincronización diferida con la nube.
Requiere una tabla de particiones personalizada con la entrada storage,data,spiffs,,128K, en partitions.csv. Hay un ejemplo en examples/spiffs_logger/partitions.csv.
#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);
}
}
El proyecto completo: examples/spiffs_logger/. El fragmento anterior es una simplificación didáctica con una fila CSV de 4 columnas. El ejemplo escribe una fila CSV de 9 columnas, con avg_p y Wh por canal para los 3 canales: más útil para escenarios de producción con módulos UI3.
Para la sincronización diferida con la nube (registrar localmente, enviar una vez por hora), véase la sección «Híbrido: almacenamiento local + sincronización» en 08 · Integraciones en la nube.
Escenario 13: registrador con batería y deep sleep
Objetivo: un ESP32 despierta una vez cada 10 minutos, toma una única instantánea de periodo, publica por WiFi+MQTT y vuelve a la suspensión profunda. La energía persiste en la memoria RTC entre ciclos de suspensión. El acumulador del componente está desactivado: el maestro se encarga por sí mismo de persistir los Wh.
⚠ Nota importante sobre la suspensión profunda. En el firmware actual, rbamp_begin() siempre emite un cebado CMD_LATCH_PERIOD, que reinicia el acumulador de periodo del firmware. Esto significa que tras un despertar de suspensión profunda no puede simplemente llamar a rbamp_read_period_snapshot() por defecto: esa llamada tomaría otra instantánea y devolvería datos casi nulos ~50 ms después del cebado. El patrón correcto de abajo usa skip_latch=true para leer los datos acumulados durante el intervalo de suspensión, y el temporizador RTC propio del maestro para el intervalo entre despertares (el campo snap.master_dt_ms refleja solo el tiempo dentro del ciclo de vigilia actual, no de despertar a despertar).
#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();
}
El proyecto completo (con configuración de WiFi, publicación MQTT y protecciones con marcador mágico en RTC) — examples/deep_sleep_logger/.
rbamp_begin_resume() (componente 1.7.0 y posteriores) es la variante de inicialización sin el cebado CMD_LATCH_PERIOD, así que rbamp_read_period_snapshot() funciona directamente tras un despertar de suspensión profunda. El patrón anterior (skip_latch=true + el RTC del maestro) sigue siendo válido en versiones antiguas del componente.
Presupuesto de energía (ESP32-WROOM, intervalo de despertar de 10 minutos):
- Duración del ciclo activo: ~3 s (WiFi + MQTT + I²C)
- Corriente activa: ~80 mA de media → ~0.07 mAh por despertar
- Corriente de reposo: ~10 µA (RTC + dominios retenidos)
- ~10 mAh al día → una celda Li-ion de 2000 mAh dura ~6 meses
Escenario 14 — I3 con CT distinta por canal (monitorización de cargas mixtas)
Objetivo: un único módulo UI3 monitoriza tres líneas independientes en una fase con niveles de carga distintos:
- Canal 0: una sola toma (SCT-013-005, ≤5 A): TV / router / standby.
- Canal 1 — la línea de la cocina (SCT-013-030, ≤30 A) — hervidor / microondas.
- Canal 2 — una caldera de calentador de agua (SCT-013-020, ≤20 A) — carga de pico.
Las tres canales se alimentan desde una única fase (en fase con el canal U), así que P/PF/Q son correctos para las tres: véase la advertencia de tensión única en 03 · Selección de sensor de corriente.
#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));
}
}
Cuándo usarlo: monitorizar una sola fase con tres grupos de carga de magnitud de corriente distinta. La ventaja principal es la resolución: cada pinza se ajusta a su rango (una SCT-013-005 da lecturas precisas en una carga de espera de 50 W, mientras que una SCT-013-020 no se satura con un calentador de agua de ~4 kW).
Escenario 15: submedición con 5×UI1 en un bus compartido
Objetivo: monitorizar 5 líneas independientes en un piso monofásico con sincronía tarifaria de los periodos. Un UI1 por línea (5 módulos en total).
Esta es la estrategia 1 de sincronización de periodos de 04 · Cableado: instantánea secuencial + asentamiento compartido.
#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álisis de desfase: 5 módulos × ~1 ms/instantánea = ~5 ms. Respecto al periodo de 60 s = 0.008 %. Despreciable.
Presupuesto de bus: 5 módulos × ~5 ms de bloque RT = 25 ms por ronda completa; esto también cabe con un sondeo de 5 Hz (25 ms ≪ 100 ms). El margen del bus es cómodo hasta unos ~15 módulos UI1.
Escenario 16: instantánea de difusión GC (sincronía ajustada para más de 8 módulos)
Objetivo: con ≥ 8 módulos, el desfase de la estrategia 1 (secuencial) se acerca a ~10 ms. Para la sincronía de periodos tarifarios, estrategia 2, difusión General-Call.
Preconfiguración (una vez por módulo):
/* 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ánea de difusión en tiempo de ejecución con testigo:
#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álisis de desfase: una trama GC dura ~1 ms a 50 kHz → los 12 módulos toman su instantánea simultáneamente a nivel de bus. El desfase es prácticamente 0.
Cuándo usarlo: ≥ 8 módulos y/o sincronización ajustada.
Cuándo NO usarlo: en un bus mixto con dispositivos que no son rbAmp (GC puede entrar en conflicto).
Escenario 17 — Filtrado por grupo GC (medición multiinquilino)
Objetivo: 10 módulos en un único bus, donde necesita tomar instantáneas de subconjuntos de forma independiente. Por ejemplo, 5 módulos miden la tarifa A (diurna) y 5 la tarifa B (nocturna); se arman y leen en horarios distintos.
Configuración (una vez):
/* 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]);
}
Ejecución: instantánea independiente por tarifa:
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);
}
Ventajas: un ciclo por tarifa = separación limpia de los intervalos de medición. Sin grupos, habría que mantener bucles secuenciales paralelos de instantáneas con resolución de conflictos.
Escenario 18: módulo STD, potencia reactiva, THD y energía con temporización del master
Objetivo: leer las magnitudes que solo mide un módulo STD — potencia reactiva y aparente, THD, factor de potencia de desplazamiento — y contabilizar la energía en un periodo propio. La misma API rbamp_* sirve para ambas líneas de módulos; rbamp_begin() detecta la línea. En un módulo BASIC el ejemplo muestra una nota y recurre al comportamiento de quick_read — nada falla, las llamadas STD simplemente informan de «no soportado».
Source: examples/std_meter/
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_mses el tiempo de reloj de pared del master entre dos instantáneas del banco: el módulo no tiene reloj propio para el período. -
En un módulo de contadores no hay banco de instantáneas ni nada que armar: la instantánea de período de la biblioteca lee los contadores persistidos e informa de la diferencia;
module_restartedmarca un reinicio dentro del período (la diferencia sigue siendo válida). -
La máscara del banco de instantáneas está en la RAM del módulo. Si un reinicio del módulo la borra,
rbamp_std_read_latch()vuelve a armar el banco y devuelveESP_ERR_INVALID_STATEpara ese período: descártelo y reinicie su ancla de dt. -
API completa: 09 · Referencia de la API, capítulo «Línea STD».
Tabla resumen de escenarios
| # | LOC | bus I²C | ¿Período? | DRDY? | MQTT? | Persistencia |
|---|---|---|---|---|---|---|
| 1 | ~120 | compartido por 3 módulos (UI1+I2+I3) | sí (sincronización GC) | no | sí | RAM (propiedad del maestro) |
| 2 | ~50 | dedicado (uno virgen) | no | no | no | flash (save_config=true) |
| 3 | ~60 | dedicado (I3) | no | no | no | flash (SAVE_USER_CONFIG) |
| 4 | ~50 | 3 módulos compartidos | sí (GC) | no | no | RAM |
| 5 | ~40 | dedicado | no | no | no | no |
| 6 | ~60 | compartido con LCD | sí | no | no | RAM |
| 7 | ~80 | 3 módulos compartidos | sí | no | no | RAM |
| 8 | ~70 | dedicado | sí | no | sí | MQTT retenido |
| 9 | ~50 | dedicado | no (RT) | no | no | RAM (propiedad del maestro) |
| 10 | ~80 | 3 módulos compartidos | sí | no | sí | MQTT retenido |
| 11 | ~80 | dedicado | no (RT) | sí | no | RAM |
| 12 | ~70 | dedicado | sí | no | no | SPIFFS |
| 13 | ~80 | dedicado | sí | no | sí | Memoria RTC + MQTT |
| 14 | ~60 | I3 dedicado | no (RT) | no | no | RAM |
| 15 | ~80 | compartido por 5×UI1 | sí | no | no | RAM |
| 16 | ~100 | compartido por 12 módulos | sí (sincronización GC) | no | no | RAM |
| 17 | ~60 | compartido por 10 módulos multiinquilino | sí (grupos GC) | no | no | RAM |
| 18 | ~110 | dedicado (módulo STD) | sí (banco de instantáneas o contadores) | no | no | RAM (los contadores de vida residen en el módulo) |
Lo que viene después
-
07 · Integraciones DIY: Home Assistant / Node-RED / OpenHAB basados en estos escenarios (incluido
examples/ha_discovery/) -
08 · Integraciones en la nube — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Referencia de API — todas las funciones públicas documentadas
-
10 · Solución de problemas: cuando los escenarios se comportan de forma distinta en su banco de pruebas
Fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/06_examples.md (v1.7.3)