13 · Exemplos ESP-IDF
Este capítulo é o equivalente ESP-IDF de arduino-examples.md e micropython-examples.md: os mesmos dez cenários, portados para C nativo com ESP-IDF 5.x, com FreeRTOS, o novo driver de mestre I²C, esp-mqtt, esp-netif e as APIs de sono profundo / memória RTC.
Estes exemplos falam diretamente com o rbAmp através da API de registos I²C em bruto. Destinam-se a firmware nativo ESP32 de qualidade de produção, onde interessam o controlo direto, um desenho completo de tarefas FreeRTOS, um layout de projeto favorável a OTA e uma pegada de memória mínima.
Para uma interface mais cómoda e estruturada — use o componente ESP-IDF rbamp (veja a tabela de bibliotecas cliente no README). O componente envolve os pormenores ao nível dos registos num rbamp_handle_t opaco com funções com nome (rbamp_read_voltage(), rbamp_latch_period(), rbamp_read_period_snapshot(), etc.), um acumulador Wh por canal, auxiliares multi-módulo, integração completa com idf.py menuconfig através de Kconfig (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, etc.), e a disciplina de repetição + verificação de sanidade da SPEC §B.5, obrigatória para o i2c_master do ESP-IDF v5. A maioria dos projetos deve começar pelo componente e recorrer à API de baixo nível apenas quando necessário.
Versão do ESP-IDF
Os exemplos são escritos para o ESP-IDF 5.2+, com o novo driver de mestre I²C em driver/i2c_master.h. A API antiga driver/i2c.h continua a funcionar e os auxiliares são fáceis de adaptar — veja a nota incluída no cabeçalho comum.
Alvos validados neste capítulo: ESP32, ESP32-S3, ESP32-C3. Outros alvos (ESP32-C6, H2) não exigem alterações de código.
Estrutura do projeto
Todos os exemplos partilham o mesmo esqueleto mínimo de projeto (um projeto ESP-IDF por exemplo):
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 topo:
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 ".")
Um sdkconfig.defaults mínimo é mostrado em cada exemplo onde são necessários valores Kconfig não predefinidos (credenciais Wi-Fi, broker MQTT, cifra NVS, etc.). Todos os exemplos assumem a frequência de tick por defeito CONFIG_FREERTOS_HZ=100 (granularidade de 10 ms).
Compilar e gravar:
idf.py set-target esp32
idf.py menuconfig # set Wi-Fi creds, MQTT host etc.
idf.py build flash monitor
Índice dos exemplos
| # | Título | Dificuldade | Saída | MQTT | DRDY | Multi-módulo | Bidirecional | Caso de utilização |
|---|---|---|---|---|---|---|---|---|
| 1 | Leitura rápida | mínimo | Registo UART | — | — | — | — | Teste de funcionamento |
| 2 | Contador de energia de 60 segundos no OLED | baixo | SSD1306 | — | — | — | — | Contador Wh em caixa |
| 3 | Monitor multi-módulo | baixo | Registo UART | — | — | sim (3) | — | Monitorização de toda a casa |
| 4 | Medidor de energia por aparelho (UI3) | médio | — | sim | — | — | — | Sub-medição no HA |
| 5 | Bidirecional no mestre num módulo BASIC | médio | Registo UART | — | sim | — | sim (mestre) | Casa solar em nível BASIC |
| 6 | Balanço energético doméstico | alta | — | sim | — | sim (3) | sim | Balanço energético doméstico completo |
| 7 | Deteção de eventos de energia | médio | UART + SD | — | sim | — | — | Registo de eventos de eletrodomésticos |
| 8 | Publicador MQTT com auto-discovery do HA | médio | — | sim (+disco) | — | — | opcional | Integração HA pronta a usar |
| 9 | Registador remoto com bateria e sono profundo | médio | — | sim | — | — | — | Medidor para exterior / fora da rede |
| 10 | Tarifa de tempo de uso (TOU) com relógio de parede SNTP | médio | Registo UART | sim | — | — | opcional | Medição de tarifa de ponta / fora de ponta |
Auxiliares comuns (rbamp_io.h / rbamp_io.c)
Estes auxiliares são incluídos em todos os exemplos. Para poupar espaço no resto deste capítulo, a linha #include "rbamp_io.h" e quaisquer chamadas rbamp_io_* são mostradas sem redefinir os 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;
}
Adaptação para o driver I²C antigo (driver/i2c.h)
Para projetos fixados no ESP-IDF ≤ 5.1, substitua os identificadores de barramento / dispositivo pela API clássica ao nível das portas:
i2c_param_config()+i2c_driver_install()em vez dei2c_new_master_busi2c_master_write_read_device()em vez dei2c_master_transmit_receivei2c_master_write_to_device()em vez dei2c_master_transmit
As assinaturas das funções auxiliares mantêm-se; só os seus corpos mudam.
Exemplo 1 — Leitura rápida (mínima)
Objetivo: imprimir U, I, P, PF pela UART uma vez por segundo. Hardware: ESP32 + um rbAmp UI1, I²C no 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));
}
}
Saída de registo esperada (lâmpada 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
...
Exemplo 2 — medidor de energia de 60 segundos no OLED
Objetivo: contador de Wh atualizado uma vez por minuto, mostrado num SSD1306 de 128×64 que partilha o barramento I²C do rbAmp. Hardware: ESP32 + rbAmp + OLED SSD1306 (em 0x3C) no mesmo barramento. Contabilização: unidirecional (nível BASIC). Biblioteca: qualquer componente IDF para SSD1306 (por exemplo nopnop2002/esp-idf-ssd1306). Por brevidade, a API do OLED abaixo é simbólica — substitua pelas chamadas do seu 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);
}
}
Se o componente SSD1306 tiver o seu próprio dispositivo I²C, aponte-o para o mesmo i2c_master_bus_handle_t, para que o rbAmp e o OLED partilhem um único driver de barramento — nunca instale dois drivers na mesma porta.
Exemplo 3 — Monitor multi-módulo
Objetivo: consultar três módulos (alimentação principal, esquentador, AC) e imprimir o total. Hardware: ESP32 + 3 × rbAmp UI1 em 0x50, 0x51, 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() é o equivalente IDF 5.x de um ping Arduino Wire.beginTransmission() / endTransmission() — perfeito para uma análise do barramento no arranque.
Exemplo 4 — medidor de energia por aparelho (UI3)
Objetivo: um módulo UI3 com três pinças CT em três cargas diferentes na mesma fase; contadores Wh independentes publicados via MQTT a 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]);
}
}
}
Exemplo 5 — bidirecional no mestre num módulo BASIC
Objetivo: implementar contabilização bidirecional no mestre enquanto o módulo tem firmware BASIC (o acumulador de período limita a zero as amostras negativas). O ESP32 reage à descida do DRDY através de uma ISR de GPIO e separa consumo / exportação. Hardware: ESP32 + rbAmp UI1 com DRDY ligado ao 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:
- A ISR apenas envia um sentinela para uma fila (
xQueueSendFromISR). Todo o trabalho de I²C acontece na tarefa worker — mais seguro e evita manter bloqueios em contexto de ISR. - No ESP-IDF 5.x prefira
gpio_install_isr_service()uma vez +gpio_isr_handler_add()por pino (em vez de um único manipulador global).
Exemplo 6 — balanço energético doméstico
Objetivo: painel completo de balanço energético. Três módulos:
- rbAmp #1 na alimentação principal (STD — bidirecional)
- rbAmp n.º 2 na saída do inversor solar (BASIC ok)
- rbAmp #3 UI3 em três grandes cargas (bomba de calor HP, AC, VE)
O mestre usa rbamp_io_broadcast_latch(bus) para instantâneos síncronos e publica um único saldo retido em 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() e mqtt_start() são o mesmo código repetitivo do Exemplo 4 — mantidos como extern para evitar duplicação. Num projeto real, coloque-os em net_helpers.c e ligue através de idf_component_register(... PRIV_REQUIRES esp_wifi esp_event nvs_flash mqtt esp_netif ...).
Exemplo 7 — deteção de eventos de energia
Objetivo: em cada flanco DRDY, comparar a P instantânea com uma EMA e registar os desvios significativos num cartão SD montado via SPI. Hardware: ESP32 + rbAmp + módulo de cartão SD SPI (FATFS via 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);
}
Exemplo 8 — Publicador MQTT com descoberta automática do Home Assistant [Auto-discovery]
Objetivo: uma integração HA pronta a usar. O ESP32 liga-se ao Wi-Fi e a um broker MQTT, publica configurações de descoberta automática do HA (retidas) e emite um estado JSON por minuto. Hardware: ESP32 + um 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);
}
}
Exemplo 9 — Registador remoto com bateria e sono profundo
Objetivo: um registador para exterior / fora da rede que acorda a cada 10 minutos, captura um período, publica via MQTT e volta ao sono profundo. Consumo médio de corrente de alguns mA — uma única célula de iões de lítio dura meses. Hardware: ESP32 (ou ESP32-S3) + um rbAmp UI1 + iões de lítio. O rbAmp pode ser desligado da alimentação através de um MOSFET no GPIO 4. Persistência: RTC_DATA_ATTR sobrevive ao sono profundo; nvs_flash sobrevive a uma perda total de energia.
#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();
}
Orçamento de energia (típico, ESP32-WROOM):
- Duração acordada por despertar: ~3 s (Wi-Fi + MQTT + I²C).
- Corrente de despertar: ~80 mA em média → ~0.07 mAh por despertar.
- Corrente em sono: ~10 µA (domínios RTC + retidos).
- Um despertar a cada 10 min → ~10 mAh/dia → uma célula de iões de lítio de 2000 mAh dura ~6 meses.
Notes:
RTC_DATA_ATTRsobrevive ao deep sleep, mas perde-se numa perda total de energia (bateria desligada). Para persistência absoluta, grave o total corrente na NVS a cada despertar.- O passo de captura de primer é controlado por
s_primer_done— a primeira amostra após um arranque a frio é corretamente descartada. mqtt_start_with_timeout()é um auxiliar simples que chamaesp_mqtt_client_start()e aguardaMQTT_EVENT_CONNECTEDcom um prazo. Implemente como um pequeno invólucro em torno de um manipulador de eventos; não mostrado aqui por brevidade.
Exemplo 10 — Tarifa de tempo de uso (TOU) com relógio de parede SNTP
Objetivo: faturar a energia segundo um horário de tarifa por período (tarifas diferentes para as horas de ponta e de fora de ponta). O ESP32 mantém um relógio de parede real através de SNTP, atribui cada período fechado ao escalão tarifário correto, repõe os totais diários à meia-noite e publica as mensagens com carimbos ISO. Hardware: ESP32 + um 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:
- A API SNTP do IDF 5.x é
esp_netif_sntp_init/esp_netif_sntp_sync_wait(substitui o antigosntp_setservername/sntp_initdo LwIP). Devolve o controlo quando a hora é plausível. setenv("TZ", ...)seguido detzset()faz com quelocaltime_r()aplique automaticamente as regras de horário de verão — sem tratamento manual do desfasamento.- Para a medição bidirecional STD, chame
accumulate()duas vezes — uma para o consumo e outra para a exportação — e publique o consumo de ponta e fora de ponta e a exportação de ponta e fora de ponta. - A passagem diária publica um payload retido em
rbamp/tou/day_close; o HA ou o Grafana podem subscrevê-lo para registar os totais diários.
Comparação de exemplos
| # | Complexidade | Saída | MQTT | DRDY | Multi-módulo | Bidirecional | Persistência | Caso de utilização |
|---|---|---|---|---|---|---|---|---|
| 1 | mínimo | Registo UART | — | — | — | — | — | teste de funcionamento |
| 2 | baixo | OLED | — | — | — | — | RAM | contador em caixa |
| 3 | baixo | Registo UART | — | — | sim (3) | — | — | monitorização doméstica |
| 4 | médio | — | sim | — | — | — | RAM | por eletrodoméstico no HA |
| 5 | médio | Registo UART | — | sim | — | sim (mestre) | RAM | casa solar em nível BASIC |
| 6 | alta | — | sim | — | sim (3) | sim | RAM | balanço energético doméstico completo |
| 7 | médio | UART + SD | — | sim | — | — | Cartão SD | deteção de eventos |
| 8 | médio | — | sim (+disco) | — | — | opcional | RAM + MQTT | Auto-discovery do HA |
| 9 | médio | — | sim | — | — | — | Memória RTC | registador para exterior / fora da rede |
| 10 | médio | Registo UART | sim | — | — | opcional | RAM + MQTT | TOU pico/fora de pico com SNTP |
Boas práticas
- Verifique sempre os caminhos de retorno de
ESP_ERROR_CHECK(). As transações I²C podem falhar de forma transitória em barramentos longos; o código de produção deve repetir em vez de abortar. - Mantenha as ISRs minimalistas. Os manipuladores de GPIO devem enviar um sentinela para uma fila e deixar uma tarefa FreeRTOS fazer o trabalho de I²C.
- Partilhe um driver I²C por porta. Vários escravos (rbAmp + OLED + EEPROM) ligam-se ao mesmo
i2c_master_bus_handle_t— nunca instale dois drivers na mesma porta. - Use
esp_timer_get_time()para o relógio mestre. Precisão de microssegundos, monotónico, imune ao jitter devTaskDelay. PERIOD_VALID(0x07) tem de ser verificado após cadaCMD_LATCH_PERIOD. Os instantâneos desatualizados acontecem se o mestre consultar mais depressa do que o firmware integra.- Aguarde ≥ 50 ms depois de um instantâneo antes de ler
0xDC..0xEF— o firmware finaliza o instantâneo dentro do seu ciclo principal. - Use
i2c_master_probe()para varrer o barramento — é o equivalente do IDF 5.x ao pingendTransmission()do Arduino. - Para aplicações com bateria, controle a alimentação do rbAmp através de um MOSFET e chame
esp_sleep_enable_timer_wakeup()+esp_deep_sleep_start()entre amostras. UseRTC_DATA_ATTRpara o estado que tem de sobreviver à suspensão. - Guarde os totais Wh na NVS se precisar que sobrevivam a uma perda total de energia (remoção da bateria). A memória lenta RTC só sobrevive ao sono profundo.
O que se segue
Depois de percorrer estes dez exemplos:
- Para o componente
rbampdo ESP-IDF, veja a tabela de bibliotecas cliente no README. - Para desenvolvimento ESP32 em estilo Arduino, veja arduino-examples.md (bruto).
- Para MicroPython / CircuitPython, veja micropython-examples.md (bruto).
- Para a integração ESPHome (YAML declarativo), veja
tools/esphome-rbamp/docs/en/. - A especificação formal dos registos I²C usada aqui está em api-reference.md.
- Para a integração Python em SBC Linux (CPython), veja python-sbc-examples.md (bruto).