13 · Ejemplos de ESP-IDF
Este capítulo es el equivalente en ESP-IDF de arduino-examples.md y micropython-examples.md: los mismos diez escenarios, portados a C nativo de ESP-IDF 5.x con FreeRTOS, el nuevo controlador maestro I²C, esp-mqtt, esp-netif y las API de sueño profundo y memoria RTC.
Estos ejemplos hablan directamente con rbAmp mediante la API de registros I²C en bruto. Están pensados para firmware nativo de ESP32 de calidad de producción, donde importan el control directo, un diseño completo de tareas FreeRTOS, una estructura de proyecto apta para OTA y una huella de memoria mínima.
Para una interfaz más cómoda y estructurada, use el componente rbamp de ESP-IDF (véase la tabla de bibliotecas cliente del README). El componente encapsula los detalles de registro tras un rbamp_handle_t opaco con funciones con nombre (rbamp_read_voltage(), rbamp_latch_period(), rbamp_read_period_snapshot(), etc.), un acumulador de Wh por canal, auxiliares multimódulo, integración completa con idf.py menuconfig mediante Kconfig (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, etc.), y la disciplina de reintento + comprobación de cordura de la SPEC §B.5, obligatoria para el i2c_master de ESP-IDF v5. La mayoría de los proyectos de usuario deben partir del componente y recurrir a la API en bruto solo cuando haga falta.
Versión de ESP-IDF
Los ejemplos están escritos para ESP-IDF 5.2+ usando el nuevo controlador I²C maestro de driver/i2c_master.h. La API heredada driver/i2c.h sigue funcionando y las funciones auxiliares son fáciles de portar; vea la nota en el encabezado común.
Objetivos validados en este capítulo: ESP32, ESP32-S3, ESP32-C3. Otros objetivos (ESP32-C6, H2) no requieren cambios en el código.
Estructura del proyecto
Todos los ejemplos comparten la misma estructura mínima de proyecto (un proyecto ESP-IDF por ejemplo):
example_NN/
├── CMakeLists.txt
├── sdkconfig.defaults
└── main/
├── CMakeLists.txt
├── rbamp_io.h ← common helpers (header-only or .c)
├── rbamp_io.c
└── example_NN.c ← the example itself
CMakeLists.txt de nivel superior:
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(example_NN)
main/CMakeLists.txt:
idf_component_register(SRCS "example_NN.c" "rbamp_io.c"
INCLUDE_DIRS ".")
En cada ejemplo se muestra un sdkconfig.defaults mínimo cuando hacen falta valores de Kconfig distintos de los predeterminados (credenciales Wi-Fi, broker MQTT, cifrado NVS, etc.). Todos los ejemplos suponen la frecuencia de tick predeterminada CONFIG_FREERTOS_HZ=100 (granularidad de 10 ms).
Compilar y cargar:
idf.py set-target esp32
idf.py menuconfig # set Wi-Fi creds, MQTT host etc.
idf.py build flash monitor
Índice de ejemplos
| # | Título | Dificultad | Salida | MQTT | DRDY | Multimódulo | Bidireccional | Caso de uso |
|---|---|---|---|---|---|---|---|---|
| 1 | Lectura rápida | mínimo | Registro UART | — | — | — | — | Prueba de humo |
| 2 | Medidor de energía de 60 segundos en OLED | bajo | SSD1306 | — | — | — | — | Contador Wh encapsulado |
| 3 | Monitor multimódulo | bajo | Registro UART | — | — | sí (3) | — | Monitorización de toda la vivienda |
| 4 | Medidor de energía por aparato (UI3) | medio | — | sí | — | — | — | Submedición en HA |
| 5 | Bidireccional en el maestro con un módulo BASIC | medio | Registro UART | — | sí | — | sí (maestro) | Vivienda solar en nivel BASIC |
| 6 | Balance energético de la vivienda | alta | — | sí | — | sí (3) | sí | Balance energético de la vivienda |
| 7 | Detección de eventos de corriente | medio | UART + SD | — | sí | — | — | Registro de eventos de electrodomésticos |
| 8 | Publicador MQTT con auto-descubrimiento de HA | medio | — | sí (+disco) | — | — | opcional | Integración de HA lista para usar |
| 9 | Registrador remoto alimentado por batería con sueño profundo | medio | — | sí | — | — | — | Medidor exterior / autónomo |
| 10 | Tarifa por franjas horarias (TOU) con hora de pared SNTP | medio | Registro UART | sí | — | — | opcional | Medición por tarifa punta / valle |
Auxiliares comunes (rbamp_io.h / rbamp_io.c)
Estos auxiliares se incluyen en todos los ejemplos. Para ahorrar espacio en el resto de este capítulo, la línea #include "rbamp_io.h" y las llamadas rbamp_io_* se muestran sin volver a definir los auxiliares.
rbamp_io.h
/**
* @file rbamp_io.h
* @brief Raw I2C helpers for the rbAmp slave (ESP-IDF 5.x master driver).
*/
#pragma once
#include
#include
#include "esp_err.h"
#include "driver/i2c_master.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Initialise an I2C master bus on the given pins.
* @param port I2C port number (I2C_NUM_0 or I2C_NUM_1).
* @param sda_gpio SDA pin.
* @param scl_gpio SCL pin.
* @param out_bus Output handle of the created bus.
* @return ESP_OK on success, an esp_err_t otherwise.
*/
esp_err_t rbamp_io_init_bus(i2c_port_num_t port,
int sda_gpio, int scl_gpio,
i2c_master_bus_handle_t *out_bus);
/**
* @brief Attach an rbAmp slave device to a bus.
* @param bus Bus handle from rbamp_io_init_bus().
* @param addr 7-bit slave address (default 0x50).
* @param out_dev Output handle of the device.
* @return ESP_OK on success.
*/
esp_err_t rbamp_io_add_device(i2c_master_bus_handle_t bus, uint8_t addr,
i2c_master_dev_handle_t *out_dev);
/**
* @brief Read one byte from a register.
* @details Per-byte helper. WRITE transactions on rbAmp do not auto-increment
* (multi-byte writes must address each byte explicitly). READ
* transactions DO auto-increment — burst-read is also valid; see
* chapter 11 for the asymmetry rules.
*/
esp_err_t rbamp_io_read_u8(i2c_master_dev_handle_t dev,
uint8_t reg, uint8_t *out);
/**
* @brief Read a little-endian float32 from four consecutive registers.
* Performs four separate read transactions.
*/
esp_err_t rbamp_io_read_float_le(i2c_master_dev_handle_t dev,
uint8_t reg, float *out);
/**
* @brief Read a little-endian uint32 from four consecutive registers.
*/
esp_err_t rbamp_io_read_u32_le(i2c_master_dev_handle_t dev,
uint8_t reg, uint32_t *out);
/**
* @brief Write a single byte to a register.
*/
esp_err_t rbamp_io_write_u8(i2c_master_dev_handle_t dev,
uint8_t reg, uint8_t val);
/**
* @brief Broadcast CMD_LATCH_PERIOD to every rbAmp with GC reception
* enabled (FLEET_CONFIG.bit0 = 1; opt-in, default OFF).
* @details Canonical 5-byte general-call frame: A5 27 group tick_lo tick_hi.
* Slaves reject any first byte != 0xA5. See chapter 11 §6.3.2.
* @param bus Bus handle (broadcast — no per-device handle).
* @param tick16 Caller's 16-bit window counter (mirrored at GC_TICK 0x59).
* @param group GROUP_ID filter (0 = all-call).
* @return ESP_OK on ACK (at least one slave accepted).
* ESP_ERR_NOT_FOUND on bus-level NACK — fall back to per-module snapshot.
*/
esp_err_t rbamp_io_broadcast_latch(i2c_master_bus_handle_t bus,
uint16_t tick16, uint8_t group);
/**
* @brief Block (with timeout) until DATA_VALID bit 0 of register 0xCE reads 1.
* @param dev Device handle.
* @param timeout_ms Maximum time to wait.
* @return ESP_OK if ready in time; ESP_ERR_TIMEOUT otherwise.
*/
esp_err_t rbamp_io_wait_ready(i2c_master_dev_handle_t dev, uint32_t timeout_ms);
/* ===== rbAmp register addresses (subset used in examples) ===== */
#define RB_REG_STATUS 0x00
#define RB_REG_COMMAND 0x01
#define RB_REG_VERSION 0x03
#define RB_REG_AC_FREQ 0x20
#define RB_REG_PERIOD_VALID 0x07
#define RB_REG_U_RMS 0x86
#define RB_REG_I0_RMS 0x8E
#define RB_REG_I1_RMS 0x92
#define RB_REG_I2_RMS 0x96
#define RB_REG_P0_REAL 0xA6
#define RB_REG_PF0 0xB2
#define RB_REG_Q0 0xD0
#define RB_REG_DATA_VALID 0xCE
#define RB_REG_PERIOD_AVG_P0 0xDC
#define RB_REG_PERIOD_AVG_P1 0xC2
#define RB_REG_PERIOD_AVG_P2 0xC6
#define RB_REG_PERIOD_MAX_P 0xE0
#define RB_REG_PERIOD_LATCH_MS 0xEC
/* ===== Commands ===== */
#define RB_CMD_RESET 0x01
#define RB_CMD_LATCH_PERIOD 0x27
#ifdef __cplusplus
}
#endif
rbamp_io.c
#include "rbamp_io.h"
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
static const char *TAG = "rbamp_io";
/* I2C transaction timeout. rbAmp processes all reads in ISR/main-loop within
* a few hundred microseconds, so 50 ms is plenty. */
#define RB_I2C_TIMEOUT_MS 50
#define RB_I2C_SPEED_HZ 50000
esp_err_t rbamp_io_init_bus(i2c_port_num_t port,
int sda_gpio, int scl_gpio,
i2c_master_bus_handle_t *out_bus) {
i2c_master_bus_config_t bus_cfg = {
.i2c_port = port,
.sda_io_num = sda_gpio,
.scl_io_num = scl_gpio,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = false, // pull-ups live on the rbAmp board
};
return i2c_new_master_bus(&bus_cfg, out_bus);
}
esp_err_t rbamp_io_add_device(i2c_master_bus_handle_t bus, uint8_t addr,
i2c_master_dev_handle_t *out_dev) {
i2c_device_config_t dev_cfg = {
.dev_addr_length = I2C_ADDR_BIT_LEN_7,
.device_address = addr,
.scl_speed_hz = RB_I2C_SPEED_HZ,
};
return i2c_master_bus_add_device(bus, &dev_cfg, out_dev);
}
esp_err_t rbamp_io_read_u8(i2c_master_dev_handle_t dev,
uint8_t reg, uint8_t *out) {
return i2c_master_transmit_receive(dev, ®, 1, out, 1, RB_I2C_TIMEOUT_MS);
}
esp_err_t rbamp_io_read_float_le(i2c_master_dev_handle_t dev,
uint8_t reg, float *out) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
uint8_t r = reg + i;
esp_err_t err = i2c_master_transmit_receive(dev, &r, 1, &buf[i], 1,
RB_I2C_TIMEOUT_MS);
if (err != ESP_OK) return err;
}
memcpy(out, buf, sizeof(float)); // host is little-endian (xtensa, RISC-V)
return ESP_OK;
}
esp_err_t rbamp_io_read_u32_le(i2c_master_dev_handle_t dev,
uint8_t reg, uint32_t *out) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
uint8_t r = reg + i;
esp_err_t err = i2c_master_transmit_receive(dev, &r, 1, &buf[i], 1,
RB_I2C_TIMEOUT_MS);
if (err != ESP_OK) return err;
}
*out = (uint32_t)buf[0] | (uint32_t)buf[1] << 8
| (uint32_t)buf[2] << 16 | (uint32_t)buf[3] << 24;
return ESP_OK;
}
esp_err_t rbamp_io_write_u8(i2c_master_dev_handle_t dev,
uint8_t reg, uint8_t val) {
uint8_t tx[2] = { reg, val };
return i2c_master_transmit(dev, tx, 2, RB_I2C_TIMEOUT_MS);
}
esp_err_t rbamp_io_broadcast_latch(i2c_master_bus_handle_t bus,
uint16_t tick16, uint8_t group) {
/* Canonical 5-byte general-call frame: A5 27 group tick_lo tick_hi.
* Attach a transient device at address 0x00 for the broadcast write. */
i2c_master_dev_handle_t gc;
i2c_device_config_t cfg = {
.dev_addr_length = I2C_ADDR_BIT_LEN_7,
.device_address = 0x00,
.scl_speed_hz = RB_I2C_SPEED_HZ,
};
esp_err_t err = i2c_master_bus_add_device(bus, &cfg, &gc);
if (err != ESP_OK) return err;
uint8_t tx[5] = {
0xA5, // frame magic
RB_CMD_LATCH_PERIOD, // opcode 0x27
group, // group_id (0 = all-call)
(uint8_t)(tick16 & 0xFF),
(uint8_t)((tick16 >> 8) & 0xFF),
};
err = i2c_master_transmit(gc, tx, sizeof tx, RB_I2C_TIMEOUT_MS);
i2c_master_bus_rm_device(gc);
/* On bus-level NACK i2c_master_transmit returns ESP_ERR_INVALID_RESPONSE
* or ESP_FAIL — translate to ESP_ERR_NOT_FOUND so the caller falls back
* to per-module sequential snapshot. */
return (err == ESP_OK) ? ESP_OK : ESP_ERR_NOT_FOUND;
}
esp_err_t rbamp_io_wait_ready(i2c_master_dev_handle_t dev, uint32_t timeout_ms) {
TickType_t deadline = xTaskGetTickCount() + pdMS_TO_TICKS(timeout_ms);
while (xTaskGetTickCount() < deadline) {
uint8_t v = 0;
if (rbamp_io_read_u8(dev, RB_REG_DATA_VALID, &v) == ESP_OK
&& (v & 0x01)) {
return ESP_OK;
}
vTaskDelay(pdMS_TO_TICKS(50));
}
ESP_LOGW(TAG, "rbAmp not ready after %lu ms", (unsigned long)timeout_ms);
return ESP_ERR_TIMEOUT;
}
Migración al controlador I²C heredado (driver/i2c.h)
Para proyectos fijados a ESP-IDF ≤ 5.1, sustituya los manejadores de bus / dispositivo por la API clásica a nivel de puerto:
i2c_param_config()+i2c_driver_install()en lugar dei2c_new_master_busi2c_master_write_read_device()en lugar dei2c_master_transmit_receivei2c_master_write_to_device()en lugar dei2c_master_transmit
Las firmas de las funciones auxiliares se mantienen; solo cambian sus cuerpos.
Ejemplo 1: lectura rápida (mínimo)
Objetivo: imprimir U, I, P, PF por UART una vez por segundo. Hardware: ESP32 + un rbAmp UI1, I²C en GPIO 21 (SDA) / GPIO 22 (SCL).
main/example_01.c:
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_quickread";
#define I2C_PORT I2C_NUM_0
#define PIN_SDA 21
#define PIN_SCL 22
#define RB_ADDR 0x50
void app_main(void) {
// 1) Bring up the I2C bus and attach the slave.
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_PORT, PIN_SDA, PIN_SCL, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
// 2) Wait until the first RT window has been computed.
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
uint8_t ver = 0;
// VERSION read is one-shot at startup; ESP_ERROR_CHECK is acceptable here.
if (rbamp_io_read_u8(dev, RB_REG_VERSION, &ver) == ESP_OK) {
ESP_LOGI(TAG, "rbAmp version: 0x%02X", ver);
}
// 3) Read loop. Do NOT wrap per-sample I2C reads in ESP_ERROR_CHECK —
// a transient NACK on a long bus would abort() and reboot the chip.
while (1) {
float u = 0, i_ = 0, p = 0, pf = 0;
esp_err_t e = ESP_OK;
e |= rbamp_io_read_float_le(dev, RB_REG_U_RMS, &u );
e |= rbamp_io_read_float_le(dev, RB_REG_I0_RMS, &i_);
e |= rbamp_io_read_float_le(dev, RB_REG_P0_REAL, &p );
e |= rbamp_io_read_float_le(dev, RB_REG_PF0, &pf);
if (e == ESP_OK) {
ESP_LOGI(TAG, "U=%.1fV I=%.3fA P=%+.1fW PF=%+.3f", u, i_, p, pf);
} else {
ESP_LOGW(TAG, "I2C read failed (e=0x%x) — will retry", e);
}
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Salida de registro esperada (incandescente de 60 W a 230 V):
I (1234) rbamp_quickread: rbAmp version: 0x04
I (2236) rbamp_quickread: U=230.1V I=0.262A P=+60.2W PF=+0.998
I (3238) rbamp_quickread: U=229.9V I=0.262A P=+60.1W PF=+0.998
...
Ejemplo 2: medidor de energía de 60 segundos en OLED
Objetivo: contador de Wh actualizado una vez por minuto, mostrado en un SSD1306 de 128×64 que comparte el bus I²C del rbAmp. Hardware: ESP32 + rbAmp + OLED SSD1306 (en 0x3C) en el mismo bus. Contabilidad: unidireccional (nivel BASIC). Biblioteca: cualquier componente SSD1306 de IDF (p. ej. nopnop2002/esp-idf-ssd1306). Por brevedad, la API del OLED que sigue es simbólica: sustitúyala por las llamadas de su componente.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp_io.h"
#include "ssd1306.h" // your driver of choice
static const char *TAG = "rbamp_oled";
#define RB_ADDR 0x50
void app_main(void) {
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
// OLED handle — initialised on the same bus.
SSD1306_t oled = {0};
i2c_master_init_external(&oled, /* bus = */ I2C_NUM_0, /* addr = */ 0x3C);
ssd1306_init(&oled, 128, 64);
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
// Primer snapshot — the snapshot it produces is discarded.
ESP_ERROR_CHECK(rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD));
int64_t t_prev_us = esp_timer_get_time();
double total_wh = 0.0;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60 * 1000));
// 1) Final snapshot — closes the just-elapsed period.
ESP_ERROR_CHECK(rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD));
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50)); // let firmware finalise the snapshot
// 2) Check PERIOD_VALID before trusting the data.
uint8_t valid = 0;
ESP_ERROR_CHECK(rbamp_io_read_u8(dev, RB_REG_PERIOD_VALID, &valid));
if ((valid & 0x01) == 0) {
ESP_LOGW(TAG, "Stale snapshot — skipping");
t_prev_us = esp_timer_get_time();
continue;
}
// 3) Read time-averaged P for channel 0.
float avg_p = 0.0f;
ESP_ERROR_CHECK(rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P0, &avg_p));
// 4) Energy uses the MASTER clock.
float dt_s = (float)(t_now_us - t_prev_us) / 1000000.0f;
double e_wh = (double)avg_p * dt_s / 3600.0;
total_wh += e_wh;
t_prev_us = t_now_us;
// 5) Render on OLED.
char line[32];
ssd1306_clear_screen(&oled, false);
snprintf(line, sizeof(line), "P: %6.1f W", avg_p); ssd1306_display_text(&oled, 0, line, strlen(line), false);
snprintf(line, sizeof(line), "dt: %6.1f s", dt_s); ssd1306_display_text(&oled, 2, line, strlen(line), false);
snprintf(line, sizeof(line), "%.2f Wh", total_wh); ssd1306_display_text_x3(&oled, 4, line, strlen(line), false);
ESP_LOGI(TAG, "avg_P=%.1f E_period=%.3f total=%.3f", avg_p, e_wh, total_wh);
}
}
Si su componente SSD1306 gestiona su propio dispositivo I²C, apúntelo al mismo i2c_master_bus_handle_t para que rbAmp y la OLED compartan un único controlador de bus; nunca instale dos controladores en el mismo puerto.
Ejemplo 3: monitor multimódulo
Objetivo: sondear tres módulos (alimentación principal, calentador de agua, AC) e imprimir el total. Hardware: ESP32 + 3 × rbAmp UI1 en 0x50, 0x51 y 0x52.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_multi";
typedef struct {
uint8_t addr;
const char *label;
i2c_master_dev_handle_t dev;
} module_t;
static module_t s_modules[] = {
{ 0x50, "Mains ", NULL },
{ 0x51, "Boiler", NULL },
{ 0x52, "AC ", NULL },
};
static const int N_MODULES = sizeof(s_modules) / sizeof(s_modules[0]);
/**
* @brief Probe a slave with a 1-byte read to confirm presence.
*/
static bool module_probe(i2c_master_bus_handle_t bus, uint8_t addr) {
return i2c_master_probe(bus, addr, 100) == ESP_OK;
}
void app_main(void) {
i2c_master_bus_handle_t bus;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
// Verify every module is present and attach a device handle.
for (int i = 0; i < N_MODULES; i++) {
if (!module_probe(bus, s_modules[i].addr)) {
ESP_LOGE(TAG, "%s at 0x%02X not found — halting",
s_modules[i].label, s_modules[i].addr);
while (1) vTaskDelay(portMAX_DELAY);
}
ESP_ERROR_CHECK(rbamp_io_add_device(bus, s_modules[i].addr,
&s_modules[i].dev));
}
ESP_LOGI(TAG, "All modules OK");
while (1) {
float total_p = 0.0f;
ESP_LOGI(TAG, "---");
for (int i = 0; i < N_MODULES; i++) {
float u = 0.0f, p = 0.0f;
rbamp_io_read_float_le(s_modules[i].dev, RB_REG_U_RMS, &u);
rbamp_io_read_float_le(s_modules[i].dev, RB_REG_P0_REAL, &p);
ESP_LOGI(TAG, "[%s] U=%.1f P=%+.1f W", s_modules[i].label, u, p);
total_p += p;
}
ESP_LOGI(TAG, "TOTAL: %.1f W", total_p);
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
i2c_master_probe() es el equivalente de IDF 5.x del ping Wire.beginTransmission() / endTransmission() de Arduino: ideal para un escaneo del bus al arrancar.
Ejemplo 4: medidor de energía por aparato (UI3)
Objetivo: un módulo UI3 con tres pinzas CT en tres cargas distintas de la misma fase; contadores de Wh independientes publicados por MQTT cada minuto. Hardware: ESP32 + 1 × rbAmp UI3 + Wi-Fi + broker MQTT. Componentes: esp_wifi, esp_event, esp_netif, mqtt_client (esp-mqtt integrado).
sdkconfig.defaults (relevante):
CONFIG_ESP_WIFI_SSID="ssid"
CONFIG_ESP_WIFI_PASSWORD="password"
CONFIG_BROKER_URL="mqtt://192.168.1.10"
main/example_04.c:
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_ui3";
#define RB_ADDR 0x50
static const char *CH_NAMES[3] = { "main", "heatpump", "lights" };
/* Shared MQTT client handle. */
static esp_mqtt_client_handle_t s_mqtt;
/* ---------- Wi-Fi station bring-up (minimal) ---------- */
static EventGroupHandle_t s_wifi_evt;
#define WIFI_BIT_CONNECTED BIT0
static void wifi_evt_handler(void *arg, esp_event_base_t base,
int32_t id, void *data) {
if (base == WIFI_EVENT && id == WIFI_EVENT_STA_DISCONNECTED) {
esp_wifi_connect();
} else if (base == IP_EVENT && id == IP_EVENT_STA_GOT_IP) {
xEventGroupSetBits(s_wifi_evt, WIFI_BIT_CONNECTED);
}
}
static void wifi_init_sta(void) {
// First-boot or partition mismatch can return ESP_ERR_NVS_NO_FREE_PAGES /
// ESP_ERR_NVS_NEW_VERSION_FOUND — recover by erasing and re-initialising.
esp_err_t err = nvs_flash_init();
if (err == ESP_ERR_NVS_NO_FREE_PAGES ||
err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
ESP_ERROR_CHECK(nvs_flash_erase());
err = nvs_flash_init();
}
ESP_ERROR_CHECK(err);
ESP_ERROR_CHECK(esp_netif_init());
ESP_ERROR_CHECK(esp_event_loop_create_default());
esp_netif_create_default_wifi_sta();
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&cfg));
s_wifi_evt = xEventGroupCreate();
ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID,
wifi_evt_handler, NULL));
ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP,
wifi_evt_handler, NULL));
wifi_config_t wcfg = {
.sta = {
.ssid = CONFIG_ESP_WIFI_SSID,
.password = CONFIG_ESP_WIFI_PASSWORD,
},
};
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wcfg));
ESP_ERROR_CHECK(esp_wifi_start());
xEventGroupWaitBits(s_wifi_evt, WIFI_BIT_CONNECTED, pdFALSE, pdTRUE,
portMAX_DELAY);
ESP_LOGI(TAG, "Wi-Fi connected");
}
/* ---------- MQTT bring-up ---------- */
static void mqtt_init(void) {
esp_mqtt_client_config_t cfg = {
.broker.address.uri = CONFIG_BROKER_URL,
};
s_mqtt = esp_mqtt_client_init(&cfg);
ESP_ERROR_CHECK(esp_mqtt_client_start(s_mqtt));
}
/**
* @brief Publish one channel's state to MQTT.
*/
static void mqtt_publish_channel(const char *name, float avg_p, double e_wh) {
char topic[64], payload[64];
snprintf(topic, sizeof(topic), "rbamp/%s/state", name);
snprintf(payload, sizeof(payload), "{\"power\":%.1f,\"energy\":%.4f}",
avg_p, e_wh);
esp_mqtt_client_publish(s_mqtt, topic, payload, 0, /*qos*/ 0, /*retain*/ 0);
}
void app_main(void) {
wifi_init_sta();
mqtt_init();
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
ESP_ERROR_CHECK(rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD));
int64_t t_prev_us = esp_timer_get_time();
double total_wh[3] = {0.0, 0.0, 0.0};
while (1) {
vTaskDelay(pdMS_TO_TICKS(60 * 1000));
ESP_ERROR_CHECK(rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD));
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));
uint8_t valid = 0;
rbamp_io_read_u8(dev, RB_REG_PERIOD_VALID, &valid);
if ((valid & 0x01) == 0) {
ESP_LOGW(TAG, "stale snapshot");
t_prev_us = esp_timer_get_time();
continue;
}
// PERIOD_AVG_P_W per channel: I0 at 0xDC, I1 at 0xC2, I2 at 0xC6.
float avg_p[3];
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P0, &avg_p[0]);
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P1, &avg_p[1]);
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P2, &avg_p[2]);
float dt_s = (float)(t_now_us - t_prev_us) / 1000000.0f;
t_prev_us = t_now_us;
for (int ch = 0; ch < 3; ch++) {
double e = (double)avg_p[ch] * dt_s / 3600.0;
total_wh[ch] += e;
ESP_LOGI(TAG, "[%s] avg_P=%+.1f W E_total=%.3f Wh",
CH_NAMES[ch], avg_p[ch], total_wh[ch]);
mqtt_publish_channel(CH_NAMES[ch], avg_p[ch], total_wh[ch]);
}
}
}
Ejemplo 5: bidireccional en el maestro con un módulo BASIC
Objetivo: implementar contabilidad bidireccional en el maestro mientras el módulo tiene firmware BASIC (el acumulador de periodo fija a cero las muestras negativas). El ESP32 reacciona al flanco de bajada de DRDY mediante una ISR de GPIO y separa el consumo y la exportación. Hardware: ESP32 + rbAmp UI1 con DRDY conectado al GPIO 15.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "driver/gpio.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_bidir";
#define RB_ADDR 0x50
#define PIN_DRDY 15
static QueueHandle_t s_drdy_q;
/**
* @brief GPIO ISR for DRDY falling edge.
* @details Pushes a sentinel into a queue. All real work happens in the task
* (no I2C inside an ISR).
*/
static void IRAM_ATTR drdy_isr(void *arg) {
uint8_t sentinel = 1;
BaseType_t hp_woken = pdFALSE;
xQueueSendFromISR(s_drdy_q, &sentinel, &hp_woken);
if (hp_woken) portYIELD_FROM_ISR();
}
/**
* @brief Worker task that integrates RT P_real into consumption / export buckets.
*/
static void accumulator_task(void *arg) {
i2c_master_dev_handle_t dev = (i2c_master_dev_handle_t)arg;
double e_consumed_wh = 0.0;
double e_exported_wh = 0.0;
int64_t t_last_us = esp_timer_get_time();
int64_t t_last_print_us = t_last_us;
while (1) {
uint8_t sentinel = 0;
if (xQueueReceive(s_drdy_q, &sentinel, portMAX_DELAY) != pdTRUE) continue;
int64_t t_now_us = esp_timer_get_time();
float p = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_P0_REAL, &p); // signed P
float dt_s = (float)(t_now_us - t_last_us) / 1000000.0f;
t_last_us = t_now_us;
if (p > 0) {
e_consumed_wh += p * dt_s / 3600.0;
} else {
e_exported_wh += -p * dt_s / 3600.0;
}
// Print summary every 5 s, not on every RT window.
if (t_now_us - t_last_print_us >= 5LL * 1000000LL) {
t_last_print_us = t_now_us;
ESP_LOGI(TAG,
"P=%+8.1fW consumed=%.4f Wh exported=%.4f Wh net=%+.4f Wh",
p, e_consumed_wh, e_exported_wh,
e_consumed_wh - e_exported_wh);
}
}
}
void app_main(void) {
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
// DRDY input with internal pull-up; falling-edge ISR.
gpio_config_t io = {
.pin_bit_mask = 1ULL << PIN_DRDY,
.mode = GPIO_MODE_INPUT,
.pull_up_en = GPIO_PULLUP_ENABLE,
.intr_type = GPIO_INTR_NEGEDGE,
};
ESP_ERROR_CHECK(gpio_config(&io));
s_drdy_q = xQueueCreate(8, sizeof(uint8_t));
ESP_ERROR_CHECK(gpio_install_isr_service(ESP_INTR_FLAG_IRAM));
ESP_ERROR_CHECK(gpio_isr_handler_add(PIN_DRDY, drdy_isr, NULL));
xTaskCreate(accumulator_task, "rb_acc", 4096, dev, 5, NULL);
ESP_LOGI(TAG, "Bidirectional accumulator started");
vTaskSuspend(NULL); // app_main idle
}
Notes:
- La ISR solo introduce un centinela en una cola (
xQueueSendFromISR). Todo el trabajo I²C se hace en la tarea de trabajo: más seguro y evita mantener bloqueos en contexto de ISR. - En ESP-IDF 5.x es preferible llamar una vez a
gpio_install_isr_service()y luego agpio_isr_handler_add()por cada pin (en lugar de un único manejador global).
Ejemplo 6: balance energético del hogar
Objetivo: panel de balance energético completo. Tres módulos:
- rbAmp n.º 1 en la alimentación principal (STD: bidireccional)
- rbAmp n.º 2 en la salida del inversor solar (BASIC válido)
- rbAmp n.º 3, UI3, en tres cargas grandes (calefacción, AC, VE)
El maestro usa rbamp_io_broadcast_latch(bus) para instantáneas síncronas y publica un único saldo retenido por MQTT.
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_balance";
#define ADDR_MAINS 0x50 // bidirectional (STD)
#define ADDR_SOLAR 0x51 // generation only
#define ADDR_LOADS 0x52 // UI3
/* Bidirectional mains module (STD line)? Set true and fill the
* PERIOD_AVG_P_NEG address from the SKU datasheet. Keep false on BASIC. */
#define HAS_NEG_REG_MAINS false
#define REG_PERIOD_AVG_P_NEG_MAINS 0x00
extern void wifi_init_sta(void); // reuse Ex. 4 boilerplate
extern esp_mqtt_client_handle_t mqtt_start(void);
void app_main(void) {
wifi_init_sta();
esp_mqtt_client_handle_t mqtt = mqtt_start();
i2c_master_bus_handle_t bus;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
i2c_master_dev_handle_t mains, solar, loads;
ESP_ERROR_CHECK(rbamp_io_add_device(bus, ADDR_MAINS, &mains));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, ADDR_SOLAR, &solar));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, ADDR_LOADS, &loads));
ESP_ERROR_CHECK(rbamp_io_wait_ready(mains, 2000));
ESP_ERROR_CHECK(rbamp_io_wait_ready(solar, 2000));
ESP_ERROR_CHECK(rbamp_io_wait_ready(loads, 2000));
// Primer snapshot on all modules (general call). GC reception is opt-in
// (FLEET_CONFIG.bit0, default OFF) — fall back to per-module on NACK.
uint16_t gc_tick = 0;
if (rbamp_io_broadcast_latch(bus, gc_tick++, 0) != ESP_OK) {
rbamp_io_write_u8(mains, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
rbamp_io_write_u8(solar, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
rbamp_io_write_u8(loads, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
}
int64_t t_prev_us = esp_timer_get_time();
struct {
double mains_in_wh, mains_out_wh, solar_total_wh;
double loads_wh[3];
} totals = {0};
ESP_LOGI(TAG, "Home balance started");
while (1) {
vTaskDelay(pdMS_TO_TICKS(60 * 1000));
// Synchronous snapshot — all three modules snapshot at the same instant.
if (rbamp_io_broadcast_latch(bus, gc_tick++, 0) != ESP_OK) {
rbamp_io_write_u8(mains, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
rbamp_io_write_u8(solar, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
rbamp_io_write_u8(loads, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
}
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));
float dt_s = (float)(t_now_us - t_prev_us) / 1000000.0f;
t_prev_us = t_now_us;
/* ----- MAINS (bidirectional, STD) ----- */
uint8_t valid;
if (rbamp_io_read_u8(mains, RB_REG_PERIOD_VALID, &valid) == ESP_OK
&& (valid & 0x01)) {
float p_consume = 0.0f, p_export = 0.0f;
rbamp_io_read_float_le(mains, RB_REG_PERIOD_AVG_P0, &p_consume);
if (HAS_NEG_REG_MAINS) {
rbamp_io_read_float_le(mains, REG_PERIOD_AVG_P_NEG_MAINS, &p_export);
}
totals.mains_in_wh += p_consume * dt_s / 3600.0;
totals.mains_out_wh += p_export * dt_s / 3600.0;
}
/* ----- SOLAR (generation only) -----
* CT arrow points toward the home → P > 0 = inverter exporting. */
if (rbamp_io_read_u8(solar, RB_REG_PERIOD_VALID, &valid) == ESP_OK
&& (valid & 0x01)) {
float p = 0.0f;
rbamp_io_read_float_le(solar, RB_REG_PERIOD_AVG_P0, &p);
totals.solar_total_wh += p * dt_s / 3600.0;
}
/* ----- LOADS (UI3, three channels) ----- */
if (rbamp_io_read_u8(loads, RB_REG_PERIOD_VALID, &valid) == ESP_OK
&& (valid & 0x01)) {
float p[3] = {0};
rbamp_io_read_float_le(loads, RB_REG_PERIOD_AVG_P0, &p[0]); // I0
rbamp_io_read_float_le(loads, RB_REG_PERIOD_AVG_P1, &p[1]); // I1
rbamp_io_read_float_le(loads, RB_REG_PERIOD_AVG_P2, &p[2]); // I2
for (int i = 0; i < 3; i++) {
totals.loads_wh[i] += p[i] * dt_s / 3600.0;
}
}
double total_consumed = totals.mains_in_wh + totals.solar_total_wh
- totals.mains_out_wh;
double solar_self_used = totals.solar_total_wh - totals.mains_out_wh;
if (solar_self_used < 0.0) solar_self_used = 0.0;
ESP_LOGI(TAG, "MAINS in=%.2f out=%.2f",
totals.mains_in_wh, totals.mains_out_wh);
ESP_LOGI(TAG, "SOLAR gen=%.2f self-used=%.2f exported=%.2f",
totals.solar_total_wh, solar_self_used, totals.mains_out_wh);
ESP_LOGI(TAG, "LOADS HP=%.2f AC=%.2f EV=%.2f",
totals.loads_wh[0], totals.loads_wh[1], totals.loads_wh[2]);
ESP_LOGI(TAG, "TOTAL household consumed=%.2f Wh", total_consumed);
char payload[512];
snprintf(payload, sizeof(payload),
"{\"mains_in\":%.3f,\"mains_out\":%.3f,\"solar\":%.3f,"
"\"self_used\":%.3f,\"total_consumed\":%.3f,"
"\"hp\":%.3f,\"ac\":%.3f,\"ev\":%.3f}",
totals.mains_in_wh, totals.mains_out_wh, totals.solar_total_wh,
solar_self_used, total_consumed,
totals.loads_wh[0], totals.loads_wh[1], totals.loads_wh[2]);
esp_mqtt_client_publish(mqtt, "home/energy/balance",
payload, 0, /*qos*/ 1, /*retain*/ 1);
}
}
wifi_init_sta() y mqtt_start() son el mismo código repetitivo del Ejemplo 4: se declaran como extern para evitar duplicación. En un proyecto real, colóquelos en net_helpers.c y enlácelos mediante idf_component_register(... PRIV_REQUIRES esp_wifi esp_event nvs_flash mqtt esp_netif ...).
Ejemplo 7: detección de eventos de corriente
Objetivo: en cada flanco de DRDY, comparar la P instantánea con una EMA y registrar las desviaciones significativas en una tarjeta SD montada por SPI. Hardware: ESP32 + rbAmp + módulo de tarjeta SD por SPI (FATFS mediante vfs_fat_sdmmc).
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "driver/gpio.h"
#include "driver/spi_common.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_vfs_fat.h"
#include "sdmmc_cmd.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_event";
#define RB_ADDR 0x50
#define PIN_DRDY 15
#define MOUNT_POINT "/sdcard"
#define EMA_ALPHA 0.05f // ~2 s time constant at 10 Hz updates
#define EVENT_THRESHOLD_W 200.0f
static QueueHandle_t s_drdy_q;
static FILE *s_logfile = NULL;
static void IRAM_ATTR drdy_isr(void *arg) {
uint8_t s = 1;
BaseType_t hp = pdFALSE;
xQueueSendFromISR(s_drdy_q, &s, &hp);
if (hp) portYIELD_FROM_ISR();
}
/**
* @brief Mount an SPI SD card under MOUNT_POINT using FATFS.
*/
static esp_err_t mount_sd_card(void) {
sdmmc_host_t host = SDSPI_HOST_DEFAULT();
spi_bus_config_t buscfg = {
.mosi_io_num = 23, .miso_io_num = 19, .sclk_io_num = 18,
.quadwp_io_num = -1, .quadhd_io_num = -1, .max_transfer_sz = 4000,
};
ESP_ERROR_CHECK(spi_bus_initialize(host.slot, &buscfg, SDSPI_DEFAULT_DMA));
sdspi_device_config_t slot = SDSPI_DEVICE_CONFIG_DEFAULT();
slot.gpio_cs = 5;
slot.host_id = host.slot;
esp_vfs_fat_sdmmc_mount_config_t mount_cfg = {
.format_if_mount_failed = false, .max_files = 4, .allocation_unit_size = 16 * 1024,
};
sdmmc_card_t *card;
return esp_vfs_fat_sdspi_mount(MOUNT_POINT, &host, &slot, &mount_cfg, &card);
}
static void event_task(void *arg) {
i2c_master_dev_handle_t dev = (i2c_master_dev_handle_t)arg;
// Seed the EMA with the current power so we don't log a spurious startup event.
float p_ema = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_P0_REAL, &p_ema);
while (1) {
uint8_t s; xQueueReceive(s_drdy_q, &s, portMAX_DELAY);
float p = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_P0_REAL, &p);
float delta = p - p_ema;
p_ema = (1.0f - EMA_ALPHA) * p_ema + EMA_ALPHA * p;
if (fabsf(delta) > EVENT_THRESHOLD_W) {
const char *type = (delta > 0) ? "TURN_ON" : "TURN_OFF";
ESP_LOGI(TAG, "%s delta=%+.1f W P=%.1f W EMA=%.1f W",
type, delta, p, p_ema);
if (s_logfile) {
fprintf(s_logfile,
"%" PRId64 " %s delta=%+.1f W P=%.1f W EMA=%.1f W\n",
esp_timer_get_time() / 1000, type, delta, p, p_ema);
fflush(s_logfile); // ensure the line hits the card
}
}
}
}
void app_main(void) {
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
if (mount_sd_card() == ESP_OK) {
s_logfile = fopen(MOUNT_POINT "/events.log", "a");
if (s_logfile) ESP_LOGI(TAG, "Logging to %s/events.log", MOUNT_POINT);
}
gpio_config_t io = {
.pin_bit_mask = 1ULL << PIN_DRDY,
.mode = GPIO_MODE_INPUT,
.pull_up_en = GPIO_PULLUP_ENABLE,
.intr_type = GPIO_INTR_NEGEDGE,
};
ESP_ERROR_CHECK(gpio_config(&io));
s_drdy_q = xQueueCreate(16, sizeof(uint8_t));
ESP_ERROR_CHECK(gpio_install_isr_service(ESP_INTR_FLAG_IRAM));
ESP_ERROR_CHECK(gpio_isr_handler_add(PIN_DRDY, drdy_isr, NULL));
xTaskCreate(event_task, "rb_evt", 6144, dev, 5, NULL);
ESP_LOGI(TAG, "Event detector started");
vTaskSuspend(NULL);
}
Ejemplo 8: publicador MQTT con descubrimiento automático de Home Assistant
Objetivo: una integración de HA lista para usar. El ESP32 se conecta a Wi-Fi y a un broker MQTT, publica las configuraciones de descubrimiento automático de HA (retenidas) y emite un estado JSON cada minuto. Hardware: ESP32 + un rbAmp UI1 + Wi-Fi + broker MQTT.
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_ha";
#define RB_ADDR 0x50
#define DEVICE_ID "rbamp_main"
#define DEVICE_NAME "Mains rbAmp"
extern void wifi_init_sta(void); // reuse Ex. 4 boilerplate
static esp_mqtt_client_handle_t s_mqtt;
static volatile bool s_mqtt_connected = false;
static void mqtt_event_handler(void *arg, esp_event_base_t base,
int32_t id, void *data) {
if (id == MQTT_EVENT_CONNECTED) s_mqtt_connected = true;
else if (id == MQTT_EVENT_DISCONNECTED) s_mqtt_connected = false;
}
/**
* @brief Publish one HA discovery config (retained).
*/
static void publish_discovery_sensor(const char *key, const char *friendly,
const char *unit, const char *dev_class,
const char *state_class) {
char topic[128], payload[512];
snprintf(topic, sizeof(topic),
"homeassistant/sensor/" DEVICE_ID "/%s/config", key);
int n = snprintf(payload, sizeof(payload),
"{"
"\"name\":\"" DEVICE_NAME " %s\","
"\"unique_id\":\"" DEVICE_ID "_%s\","
"\"state_topic\":\"rbamp/" DEVICE_ID "/state\","
"\"value_template\":\"{{ value_json.%s }}\","
"\"state_class\":\"%s\","
"\"device\":{"
"\"identifiers\":[\"" DEVICE_ID "\"],"
"\"name\":\"" DEVICE_NAME "\","
"\"manufacturer\":\"rbAmp\","
"\"model\":\"rbAmp UI*\""
"}",
friendly, key, key, state_class);
if (unit) n += snprintf(payload + n, sizeof(payload) - n,
",\"unit_of_measurement\":\"%s\"", unit);
if (dev_class) n += snprintf(payload + n, sizeof(payload) - n,
",\"device_class\":\"%s\"", dev_class);
snprintf(payload + n, sizeof(payload) - n, "}");
esp_mqtt_client_publish(s_mqtt, topic, payload, 0, /*qos*/ 1, /*retain*/ 1);
}
/**
* @brief Publish the full set of HA discovery configs for one rbAmp.
*/
static void publish_discovery_all(void) {
publish_discovery_sensor("voltage", "Voltage", "V", "voltage", "measurement");
publish_discovery_sensor("current", "Current", "A", "current", "measurement");
publish_discovery_sensor("power", "Power", "W", "power", "measurement");
publish_discovery_sensor("energy", "Energy", "Wh", "energy", "total_increasing");
publish_discovery_sensor("frequency", "Frequency", "Hz", "frequency", "measurement");
publish_discovery_sensor("power_factor", "Power Factor", NULL, "power_factor", "measurement");
publish_discovery_sensor("apparent_power", "Apparent Power", "VA", "apparent_power", "measurement");
publish_discovery_sensor("reactive_power", "Reactive Power", "var", "reactive_power", "measurement");
}
void app_main(void) {
wifi_init_sta();
// MQTT client.
esp_mqtt_client_config_t cfg = {
.broker.address.uri = CONFIG_BROKER_URL,
};
s_mqtt = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(s_mqtt, ESP_EVENT_ANY_ID,
mqtt_event_handler, NULL);
esp_mqtt_client_start(s_mqtt);
// Wait for the first CONNECTED event, then publish discovery once.
while (!s_mqtt_connected) vTaskDelay(pdMS_TO_TICKS(100));
publish_discovery_all();
// rbAmp bring-up.
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD); // primer
int64_t t_prev_us = esp_timer_get_time();
double total_wh = 0.0;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60 * 1000));
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));
uint8_t valid = 0;
rbamp_io_read_u8(dev, RB_REG_PERIOD_VALID, &valid);
if ((valid & 0x01) == 0) {
t_prev_us = esp_timer_get_time();
continue;
}
float avg_p = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P0, &avg_p);
float dt_s = (float)(t_now_us - t_prev_us) / 1000000.0f;
total_wh += (double)avg_p * dt_s / 3600.0;
t_prev_us = t_now_us;
// Live RT values for the state payload.
float u = 0, i_ = 0, pf = 0, q = 0;
uint8_t freq = 0;
rbamp_io_read_float_le(dev, RB_REG_U_RMS, &u);
rbamp_io_read_float_le(dev, RB_REG_I0_RMS, &i_);
rbamp_io_read_float_le(dev, RB_REG_PF0, &pf);
rbamp_io_read_float_le(dev, RB_REG_Q0, &q);
rbamp_io_read_u8 (dev, RB_REG_AC_FREQ, &freq);
char payload[384];
snprintf(payload, sizeof(payload),
"{"
"\"voltage\":%.1f,"
"\"current\":%.3f,"
"\"power\":%.1f,"
"\"energy\":%.3f,"
"\"frequency\":%u,"
"\"power_factor\":%.3f,"
"\"apparent_power\":%.1f,"
"\"reactive_power\":%.1f"
"}",
u, i_, avg_p, total_wh, (unsigned)freq, pf, u * i_, q);
esp_mqtt_client_publish(s_mqtt, "rbamp/" DEVICE_ID "/state",
payload, 0, /*qos*/ 0, /*retain*/ 0);
ESP_LOGI(TAG, "Published: %s", payload);
}
}
Ejemplo 9: registrador remoto alimentado por batería con sueño profundo
Objetivo: un registrador exterior / autónomo que se despierta cada 10 minutos, toma una instantánea de un periodo, publica por MQTT y vuelve al sueño profundo. Consumo medio de unos pocos mA: una sola celda de Li-ion dura meses. Hardware: ESP32 (o ESP32-S3) + un rbAmp UI1 + Li-ion. El rbAmp puede cortarse mediante un MOSFET en GPIO 4. Persistencia: RTC_DATA_ATTR sobrevive al sueño profundo; nvs_flash sobrevive a la pérdida completa de alimentación.
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_sleep.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_remote";
#define RB_ADDR 0x50
#define PIN_RBAMP_POWER 4
#define SLEEP_US (10ULL * 60ULL * 1000ULL * 1000ULL) // 10-minute wake interval
/* Variables that survive deep sleep. RTC slow memory is preserved while at
* least one RTC domain is powered.
* IMPORTANT: after a brown-out, watchdog reset, or any non-deep-sleep boot,
* RTC slow memory may contain garbage. A magic-marker sentinel lets us
* distinguish a fresh cold boot from a deep-sleep wake. */
RTC_DATA_ATTR static uint32_t s_rtc_magic = 0; /* set to RTC_MAGIC on init */
RTC_DATA_ATTR static double s_total_wh = 0.0;
RTC_DATA_ATTR static uint32_t s_wake_count = 0;
RTC_DATA_ATTR static bool s_primer_done = false;
RTC_DATA_ATTR static int64_t s_t_prev_us = 0;
#define RTC_MAGIC 0xCAFEFEEDu
/**
* @brief Power-gate the rbAmp module.
* @param on true = enable, false = disable.
*/
static void rbamp_power(bool on) {
gpio_set_direction(PIN_RBAMP_POWER, GPIO_MODE_OUTPUT);
gpio_set_level(PIN_RBAMP_POWER, on ? 1 : 0);
if (on) vTaskDelay(pdMS_TO_TICKS(300)); // give the LDO + MCU time to boot
}
extern void wifi_init_sta(void); // standard boilerplate
extern esp_mqtt_client_handle_t mqtt_start_with_timeout(uint32_t timeout_ms);
void app_main(void) {
// Cold-boot detection: any non-deep-sleep reset (power-on, brown-out,
// watchdog) may leave RTC slow memory uninitialised. Gate every retained
// variable through the magic-marker sentinel.
if (s_rtc_magic != RTC_MAGIC) {
ESP_LOGI(TAG, "Cold boot — initialising RTC state");
s_total_wh = 0.0;
s_wake_count = 0;
s_primer_done = false;
s_t_prev_us = 0;
s_rtc_magic = RTC_MAGIC;
}
s_wake_count++;
// ----- Power up the rbAmp and bring up I2C -----
rbamp_power(true);
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
if (rbamp_io_wait_ready(dev, 2000) != ESP_OK) {
ESP_LOGE(TAG, "rbAmp not ready — sleeping");
rbamp_power(false);
esp_sleep_enable_timer_wakeup(SLEEP_US);
esp_deep_sleep_start();
}
// ----- First wake after cold boot: primer snapshot only -----
if (!s_primer_done) {
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
s_t_prev_us = esp_timer_get_time();
s_primer_done = true;
ESP_LOGI(TAG, "Primer done — sleeping until first real period");
rbamp_power(false);
esp_sleep_enable_timer_wakeup(SLEEP_US);
esp_deep_sleep_start();
}
// ----- Subsequent wakes: close the period and read its average power -----
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));
uint8_t valid = 0;
rbamp_io_read_u8(dev, RB_REG_PERIOD_VALID, &valid);
if ((valid & 0x01) == 0) {
ESP_LOGW(TAG, "Stale snapshot — skipping this cycle");
s_t_prev_us = t_now_us;
rbamp_power(false);
esp_sleep_enable_timer_wakeup(SLEEP_US);
esp_deep_sleep_start();
}
float avg_p = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P0, &avg_p);
float dt_s = (float)(t_now_us - s_t_prev_us) / 1000000.0f;
s_t_prev_us = t_now_us;
s_total_wh += (double)avg_p * dt_s / 3600.0;
// ----- Publish via Wi-Fi + MQTT (graceful fallback on failure) -----
wifi_init_sta();
esp_mqtt_client_handle_t mqtt = mqtt_start_with_timeout(8000);
if (mqtt) {
char payload[256];
snprintf(payload, sizeof(payload),
"{\"wake\":%" PRIu32 ",\"dt_s\":%.1f,"
"\"avg_p\":%.1f,\"energy_wh\":%.3f}",
s_wake_count, dt_s, avg_p, s_total_wh);
esp_mqtt_client_publish(mqtt, "rbamp/remote/state",
payload, 0, /*qos*/ 1, /*retain*/ 1);
ESP_LOGI(TAG, "Published: %s", payload);
esp_mqtt_client_stop(mqtt);
esp_mqtt_client_destroy(mqtt);
} else {
ESP_LOGW(TAG, "Wi-Fi/MQTT failed — value buffered in RTC, retry next wake");
}
esp_wifi_stop();
rbamp_power(false);
esp_sleep_enable_timer_wakeup(SLEEP_US);
ESP_LOGI(TAG, "Deep sleep");
esp_deep_sleep_start();
}
Presupuesto de energía (típico, ESP32-WROOM):
- Tiempo despierto por despertar: ~3 s (Wi-Fi + MQTT + I²C).
- Corriente en vigilia: ~80 mA de media → ~0.07 mAh por despertar.
- Corriente en reposo: ~10 µA (dominios RTC + retenidos).
- Un despertar cada 10 min → ~10 mAh/día → una celda de Li-ion de 2000 mAh dura ~6 meses.
Notes:
RTC_DATA_ATTRsobrevive a la suspensión profunda, pero se pierde con un corte total de alimentación (desconexión de la batería). Para una persistencia absoluta, guarde el total acumulado en NVS en cada despertar.- El paso de instantánea de cebado está condicionado por
s_primer_done: la primera muestra tras un arranque en frío se descarta correctamente. mqtt_start_with_timeout()es un auxiliar ligero que llama aesp_mqtt_client_start()y espera aMQTT_EVENT_CONNECTEDcon un plazo. Impleméntelo como un pequeño envoltorio alrededor de un manejador de eventos; no se muestra aquí por brevedad.
Ejemplo 10: tarifa por franjas horarias (TOU) con hora de pared SNTP
Objetivo: facturar la energía según un horario de tarifa por franjas horarias (tarifas distintas para horas punta y valle). El ESP32 mantiene una hora de pared real mediante SNTP, asigna cada periodo cerrado al tramo tarifario correspondiente, reinicia los totales diarios a medianoche y publica las cargas útiles con marcas de tiempo ISO. Hardware: ESP32 + un rbAmp UI1 + Wi-Fi.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "esp_netif_sntp.h"
#include "esp_sntp.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "rbamp_io.h"
static const char *TAG = "rbamp_tou";
#define RB_ADDR 0x50
/* POSIX TZ string. Examples:
* Central Europe: "CET-1CEST,M3.5.0/2,M10.5.0/3"
* US Eastern: "EST5EDT,M3.2.0/2,M11.1.0/2"
* UTC fixed: "UTC0"
*/
#define TZ_INFO "CET-1CEST,M3.5.0/2,M10.5.0/3"
#define PEAK_START_HOUR 8 // inclusive
#define PEAK_END_HOUR 22 // exclusive
extern void wifi_init_sta(void);
extern esp_mqtt_client_handle_t mqtt_start(void);
/* Tariff buckets. */
typedef struct {
double peak_wh, off_peak_wh;
int day_of_year; // tm_yday to detect a day roll-over
} day_totals_t;
typedef struct {
double peak_wh, off_peak_wh;
} lifetime_totals_t;
static day_totals_t s_today = { .day_of_year = -1 };
static lifetime_totals_t s_lifetime = { 0 };
static esp_mqtt_client_handle_t s_mqtt;
/**
* @brief Synchronise the system clock with SNTP and apply the local timezone.
* @details Blocks until the first valid time is received (timeout 15 s).
*/
static esp_err_t sntp_sync(void) {
esp_sntp_config_t cfg = ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(2,
ESP_SNTP_SERVER_LIST("pool.ntp.org", "time.google.com"));
cfg.start = true;
ESP_ERROR_CHECK(esp_netif_sntp_init(&cfg));
if (esp_netif_sntp_sync_wait(pdMS_TO_TICKS(15000)) != ESP_OK) {
ESP_LOGW(TAG, "SNTP sync timed out");
return ESP_ERR_TIMEOUT;
}
setenv("TZ", TZ_INFO, 1);
tzset();
time_t now; time(&now);
struct tm lt; localtime_r(&now, <);
ESP_LOGI(TAG, "SNTP sync: %04d-%02d-%02d %02d:%02d:%02d %s",
lt.tm_year + 1900, lt.tm_mon + 1, lt.tm_mday,
lt.tm_hour, lt.tm_min, lt.tm_sec, lt.tm_zone);
return ESP_OK;
}
/**
* @brief Decide whether a given hour falls inside the peak tariff window.
* @details For schedules that cross midnight, change to
* `(hour >= PEAK_START_HOUR || hour < PEAK_END_HOUR)`.
*/
static inline bool is_peak_hour(int hour) {
return (hour >= PEAK_START_HOUR && hour < PEAK_END_HOUR);
}
/**
* @brief Add one period's energy to the right bucket and handle midnight roll-over.
*/
static void accumulate(double e_wh, const struct tm *tm_now) {
if (s_today.day_of_year != tm_now->tm_yday) {
if (s_today.day_of_year >= 0) {
char payload[192];
snprintf(payload, sizeof(payload),
"{\"yday\":%d,\"peak_wh\":%.3f,\"off_peak_wh\":%.3f,"
"\"total_wh\":%.3f}",
s_today.day_of_year, s_today.peak_wh, s_today.off_peak_wh,
s_today.peak_wh + s_today.off_peak_wh);
esp_mqtt_client_publish(s_mqtt, "rbamp/tou/day_close",
payload, 0, /*qos*/ 1, /*retain*/ 1);
ESP_LOGI(TAG, "Day closed: %s", payload);
}
s_today.peak_wh = 0.0;
s_today.off_peak_wh = 0.0;
s_today.day_of_year = tm_now->tm_yday;
}
if (is_peak_hour(tm_now->tm_hour)) {
s_today.peak_wh += e_wh;
s_lifetime.peak_wh += e_wh;
} else {
s_today.off_peak_wh += e_wh;
s_lifetime.off_peak_wh += e_wh;
}
}
void app_main(void) {
wifi_init_sta();
sntp_sync();
s_mqtt = mqtt_start();
i2c_master_bus_handle_t bus;
i2c_master_dev_handle_t dev;
ESP_ERROR_CHECK(rbamp_io_init_bus(I2C_NUM_0, 21, 22, &bus));
ESP_ERROR_CHECK(rbamp_io_add_device(bus, RB_ADDR, &dev));
ESP_ERROR_CHECK(rbamp_io_wait_ready(dev, 2000));
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD); // primer
int64_t t_prev_us = esp_timer_get_time();
ESP_LOGI(TAG, "TOU started: peak %02d:00..%02d:00 local",
PEAK_START_HOUR, PEAK_END_HOUR);
while (1) {
vTaskDelay(pdMS_TO_TICKS(60 * 1000));
rbamp_io_write_u8(dev, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
int64_t t_now_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));
uint8_t valid = 0;
rbamp_io_read_u8(dev, RB_REG_PERIOD_VALID, &valid);
if ((valid & 0x01) == 0) {
t_prev_us = esp_timer_get_time();
continue;
}
float avg_p = 0.0f;
rbamp_io_read_float_le(dev, RB_REG_PERIOD_AVG_P0, &avg_p);
float dt_s = (float)(t_now_us - t_prev_us) / 1000000.0f;
double e_wh = (double)avg_p * dt_s / 3600.0;
t_prev_us = t_now_us;
// Tag with the current local time.
time_t now_s; time(&now_s);
struct tm tm_now; localtime_r(&now_s, &tm_now);
if (tm_now.tm_year + 1900 < 2023) {
ESP_LOGW(TAG, "Clock not yet synced — retrying SNTP");
sntp_sync();
// Reset t_prev_us so the NEXT valid period does not get an
// inflated dt_s spanning the SNTP retry interval.
t_prev_us = esp_timer_get_time();
continue;
}
accumulate(e_wh, &tm_now);
bool peak = is_peak_hour(tm_now.tm_hour);
char iso[40];
strftime(iso, sizeof(iso), "%Y-%m-%dT%H:%M:%S%z", &tm_now);
char payload[384];
snprintf(payload, sizeof(payload),
"{"
"\"ts\":\"%s\","
"\"tariff\":\"%s\","
"\"avg_p\":%.1f,"
"\"period_wh\":%.4f,"
"\"today_peak_wh\":%.3f,"
"\"today_off_peak_wh\":%.3f,"
"\"life_peak_wh\":%.3f,"
"\"life_off_peak_wh\":%.3f"
"}",
iso, peak ? "peak" : "off_peak",
avg_p, e_wh,
s_today.peak_wh, s_today.off_peak_wh,
s_lifetime.peak_wh, s_lifetime.off_peak_wh);
esp_mqtt_client_publish(s_mqtt, "rbamp/tou/state",
payload, 0, /*qos*/ 0, /*retain*/ 0);
ESP_LOGI(TAG, "%s", payload);
}
}
Notes:
- La API SNTP de IDF 5.x es
esp_netif_sntp_init/esp_netif_sntp_sync_wait(sustituye asntp_setservername/sntp_initde LwIP). Devuelve el control cuando la hora es plausible. setenv("TZ", ...)seguido detzset()hace quelocaltime_r()aplique las reglas de horario de verano automáticamente; no hace falta gestionar el desfase a mano.- Para la medición bidireccional de un STD, llame a
accumulate()dos veces: una para el consumo y otra para la exportación, y publique tanto el consumo punta / valle como la exportación punta / valle. - El cambio de día publica una carga retenida en
rbamp/tou/day_close; HA o Grafana pueden suscribirse para registrar los totales diarios.
Comparación de ejemplos
| # | Complejidad | Salida | MQTT | DRDY | Multimódulo | Bidireccional | Persistencia | Caso de uso |
|---|---|---|---|---|---|---|---|---|
| 1 | mínimo | Registro UART | — | — | — | — | — | prueba de humo |
| 2 | bajo | OLED | — | — | — | — | RAM | medidor en caja |
| 3 | bajo | Registro UART | — | — | sí (3) | — | — | monitorización doméstica |
| 4 | medio | — | sí | — | — | — | RAM | por electrodoméstico en HA |
| 5 | medio | Registro UART | — | sí | — | sí (maestro) | RAM | vivienda solar en nivel BASIC |
| 6 | alta | — | sí | — | sí (3) | sí | RAM | balance energético de toda la casa |
| 7 | medio | UART + SD | — | sí | — | — | Tarjeta SD | detección de eventos |
| 8 | medio | — | sí (+disco) | — | — | opcional | RAM + MQTT | Auto-descubrimiento de HA |
| 9 | medio | — | sí | — | — | — | Memoria RTC | registrador exterior / autónomo |
| 10 | medio | Registro UART | sí | — | — | opcional | RAM + MQTT | TOU punta/fuera de punta con SNTP |
Buenas prácticas
- Compruebe siempre las rutas de retorno de
ESP_ERROR_CHECK(). Las transacciones I²C pueden fallar de forma transitoria en buses largos; el código de producción debe reintentar en lugar de abortar. - Mantenga las ISR pequeñas. Los manejadores de GPIO deben introducir un centinela en una cola y dejar que una tarea FreeRTOS haga el trabajo de I²C.
- Comparta un único controlador I²C por puerto. Varios esclavos (rbAmp + OLED + EEPROM) se conectan al mismo
i2c_master_bus_handle_t: nunca instale dos controladores en el mismo puerto. - Use
esp_timer_get_time()para el reloj maestro. Precisión de microsegundos, monótono, y resiste la variación devTaskDelay. PERIOD_VALID(0x07) debe comprobarse tras cadaCMD_LATCH_PERIOD. Las instantáneas obsoletas aparecen si el maestro consulta más rápido de lo que integra el firmware.- Espere ≥ 50 ms tras una instantánea antes de leer
0xDC..0xEF: el firmware finaliza la instantánea dentro de su bucle principal. - Use
i2c_master_probe()para los escaneos del bus: es el equivalente en IDF 5.x del pingendTransmission()de Arduino. - En aplicaciones con batería, controle la alimentación de rbAmp mediante un MOSFET y llame a
esp_sleep_enable_timer_wakeup()+esp_deep_sleep_start()entre muestras. UseRTC_DATA_ATTRpara el estado que debe sobrevivir a la suspensión. - Guarde los totales de Wh en NVS si necesita que sobrevivan a una pérdida total de alimentación (retirada de la batería). La memoria lenta RTC solo sobrevive al sueño profundo.
Lo siguiente
Tras repasar estos diez ejemplos:
- Para el componente
rbampde ESP-IDF de alto nivel, consulte la tabla de bibliotecas cliente del README. - Para desarrollo ESP32 al estilo Arduino, véase arduino-examples.md (sin formato).
- Para MicroPython / CircuitPython, véase micropython-examples.md (sin formato).
- Para la integración con ESPHome (YAML declarativo), consulte
tools/esphome-rbamp/docs/en/. - La especificación formal de registros I²C que se usa aquí está en api-reference.md.
- Para la integración con SBC Linux (CPython), véase python-sbc-examples.md (sin formato).