rbAmp
PT
Loja
Docs
Atualizado

14 · Exemplos STM32 HAL

Este capítulo é o equivalente STM32 de arduino-examples.md, micropython-examples.md e esp-idf-examples.md: os mesmos dez cenários, portados para STM32 HAL (C gerado pelo CubeMX) com FreeRTOS / CMSIS-OS2 opcional.

Nota

Estes exemplos falam com o rbAmp diretamente através da API bruta de registos I²C. Destinam-se a firmware embebido de produção no STM32 — controlo direto do HAL, pegada previsível de RAM/flash, integração com LwIP, FATFS, FreeRTOS e geração de HAL pelo CubeMX.

Configure o periférico I²C no CubeMX para 50 kHz (recomendado — veja o capítulo 11 §2.2) e envolva as leituras de registos numa repetição curta.

Famílias suportadas e cadeia de ferramentas

Família Validado Periférico I²C Notas
Família STM32F1 ✓ I2C1, I2C2 Alvo DIY comum
STM32F4 (Nucleo-F411, Discovery) ✓ I2C1..3 Relógio alto, muita RAM
STM32L4 / L4+ ✓ I2C1..4 Baixo consumo, registos de cópia de segurança RTC, STOP / STANDBY
STM32G0 / G4 ✓ I2C1..3 Periféricos modernos
STM32H7 (Nucleo-H743) ✓ I2C1..4 PHY Ethernet integrado → MQTT diretamente via LwIP

Cadeia de ferramentas: CubeMX 6.x + CubeIDE ou um projeto Makefile (arm-none-eabi-gcc). Os exemplos assumem uma versão de HAL compatível com o seu projeto gerado pelo CubeMX. A nova assinatura I²C do HAL (HAL_I2C_Mem_Read/Write) é suportada por todas as famílias modernas.

Nota sobre rede

A maioria dos chips STM32 não tem Wi-Fi integrado. Os exemplos dependentes de MQTT (4, 6, 8, 9) assumem um dos seguintes caminhos de rede:

  • Ethernet — placas STM32F4 / F7 / H7 com PHY integrado (LAN8742, DP83848) a correr LwIP + uma pequena biblioteca MQTT (Paho Embedded C, MQTT-C ou um fork compatível com HAL). Este é o caminho mais simples.
  • W5500 SPI Ethernet — para STM32F1 / L4 / G4 (sem MAC integrado). Usa a ioLibrary da WIZnet.
  • ESP32-AT via UART — um módulo ESP-AT atua como ponte Wi-Fi. Emita comandos AT a partir do ciclo principal do STM32.

Os exemplos abaixo mostram a lógica do rbAmp em todo o detalhe; a ativação da rede fica abstraída por duas funções stub que implementa no seu projeto:

C
extern HAL_StatusTypeDef Net_Init(void);                  // bring up the chosen stack
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

As implementações de referência de cada caminho de rede estão fora do âmbito deste capítulo; escolha a que se adapta ao seu hardware e substitua os stubs.

Estrutura do projeto

Estrutura de projeto gerada pelo CubeMX:

Text
example_NN/
├── example_NN.ioc                  ← CubeMX project (pins, peripherals, clock)
├── Makefile                        ← (or *.eww / *.uvprojx for IAR / STM32CubeIDE)
├── Core/
│   ├── Inc/main.h
│   ├── Inc/rbamp_io.h              ← common helpers
│   ├── Src/main.c                  ← USER CODE inside CubeMX markers
│   ├── Src/rbamp_io.c
│   └── Src/stm32xxxx_it.c          ← EXTI handlers (CubeMX-generated)
├── Drivers/
│   └── STM32xxxx_HAL_Driver/       ← HAL sources
└── Middlewares/                    ← FreeRTOS, LwIP, FATFS (optional)

Configuração de pinos no CubeMX usada em todos os exemplos, salvo indicação em contrário:

  • I2C1: SCL = PB6, SDA = PB7 (predefinições típicas do STM32F1 / Nucleo-F411)
  • UART1: TX = PA9, RX = PA10 — para depuração com printf
  • EXTI: PA0 = DRDY (flanco descendente, pull-up)
  • Velocidade I²C: 100 kHz

Índice dos exemplos

# Título Dificuldade Saída MQTT DRDY Multi-módulo Bidirecional Caso de utilização
1 Leitura rápida mínimo printf via 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 printf via 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 printf via 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 alimentado a bateria com modo STANDBY médio — sim — — — Medidor para exterior / fora da rede
10 Tarifa de tempo de uso (TOU) com relógio de parede SNTP médio printf via UART sim — — opcional Medição de tarifa de ponta / fora de ponta

Auxiliares comuns (rbamp_io.h / rbamp_io.c)

Coloque estes ficheiros em Core/Inc e Core/Src do seu projeto CubeMX. Para poupar espaço, a linha #include "rbamp_io.h" é omitida em cada exemplo abaixo.

rbamp_io.h

C
/**
 * @file rbamp_io.h
 * @brief Raw I2C helpers for the rbAmp slave (STM32 HAL).
 */
#ifndef RBAMP_IO_H
#define RBAMP_IO_H

#include 
#include 
#include "main.h"        /* CubeMX-generated, brings the HAL header */

#ifdef __cplusplus
extern "C" {
#endif

/* I2C transaction timeout in milliseconds (HAL_GetTick units). */
#define RBAMP_I2C_TIMEOUT_MS  50U

/**
 * @brief  Bind the helpers to a HAL I2C handle.
 * @details Stores the pointer internally; call once at startup. The handle
 *          must have been initialised by HAL_I2C_Init() (typically by CubeMX).
 */
void RbAmpIO_Bind(I2C_HandleTypeDef *hi2c);

/**
 * @brief  Read one byte from a register of an rbAmp slave.
 * @param  addr  7-bit slave address (e.g. 0x50).
 * @param  reg   Register address inside the slave.
 * @param  out   Output byte.
 * @return HAL_OK on success.
 */
HAL_StatusTypeDef RbAmpIO_ReadU8(uint8_t addr, uint8_t reg, uint8_t *out);

/**
 * @brief  Read a little-endian float32 from four consecutive registers.
 * @details Reads four consecutive bytes. rbAmp supports READ auto-increment
 *          (a single burst-read is valid for atomicity). The per-byte form
 *          is shown for clarity. See chapter 11 for asymmetry rules.
 */
HAL_StatusTypeDef RbAmpIO_ReadFloatLE(uint8_t addr, uint8_t reg, float *out);

/**
 * @brief  Read a little-endian uint32 from four consecutive registers.
 */
HAL_StatusTypeDef RbAmpIO_ReadU32LE(uint8_t addr, uint8_t reg, uint32_t *out);

/**
 * @brief  Write a single byte to a register.
 */
HAL_StatusTypeDef RbAmpIO_WriteU8(uint8_t addr, 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  tick16  Caller's 16-bit window counter (mirrored at GC_TICK 0x59).
 * @param  group   GROUP_ID filter (0 = all-call).
 * @return HAL_OK on ACK; HAL_ERROR on NACK — fall back to per-module snapshot.
 */
HAL_StatusTypeDef RbAmpIO_BroadcastLatch(uint16_t tick16, uint8_t group);

/**
 * @brief  Probe whether a slave responds at the given address (1-byte read).
 * @return true if the slave acks, false otherwise.
 */
bool RbAmpIO_Probe(uint8_t addr);

/**
 * @brief  Block until DATA_VALID bit 0 of register 0xCE reads 1, or timeout.
 * @return HAL_OK if ready in time, HAL_TIMEOUT otherwise.
 */
HAL_StatusTypeDef RbAmpIO_WaitReady(uint8_t addr, uint32_t timeout_ms);

/* ===== rbAmp register addresses (subset used in examples) ===== */
#define RB_REG_STATUS           0x00U
#define RB_REG_COMMAND          0x01U
#define RB_REG_VERSION          0x03U
#define RB_REG_AC_FREQ          0x20U
#define RB_REG_PERIOD_VALID     0x07U
#define RB_REG_U_RMS            0x86U
#define RB_REG_I0_RMS           0x8EU
#define RB_REG_I1_RMS           0x92U
#define RB_REG_I2_RMS           0x96U
#define RB_REG_P0_REAL          0xA6U
#define RB_REG_PF0              0xB2U
#define RB_REG_Q0               0xD0U
#define RB_REG_DATA_VALID       0xCEU
#define RB_REG_PERIOD_AVG_P0    0xDCU
#define RB_REG_PERIOD_AVG_P1    0xC2U
#define RB_REG_PERIOD_AVG_P2    0xC6U
#define RB_REG_PERIOD_MAX_P    0xE0U
#define RB_REG_PERIOD_LATCH_MS  0xECU

/* ===== Commands ===== */
#define RB_CMD_RESET            0x01U
#define RB_CMD_LATCH_PERIOD     0x27U

#ifdef __cplusplus
}
#endif

#endif /* RBAMP_IO_H */

rbamp_io.c

C
#include "rbamp_io.h"
#include 

/* HAL I2C uses the 8-bit address format: left-shift the 7-bit address. */
#define ADDR8(addr7)  ((uint16_t)((addr7) << 1))

static I2C_HandleTypeDef *s_hi2c = NULL;

void RbAmpIO_Bind(I2C_HandleTypeDef *hi2c) {
    s_hi2c = hi2c;
}

HAL_StatusTypeDef RbAmpIO_ReadU8(uint8_t addr, uint8_t reg, uint8_t *out) {
    return HAL_I2C_Mem_Read(s_hi2c, ADDR8(addr), reg,
                            I2C_MEMADD_SIZE_8BIT, out, 1,
                            RBAMP_I2C_TIMEOUT_MS);
}

HAL_StatusTypeDef RbAmpIO_ReadFloatLE(uint8_t addr, uint8_t reg, float *out) {
    uint8_t buf[4];
    for (int i = 0; i < 4; i++) {
        HAL_StatusTypeDef st = HAL_I2C_Mem_Read(s_hi2c, ADDR8(addr), reg + i,
                                                 I2C_MEMADD_SIZE_8BIT,
                                                 &buf[i], 1,
                                                 RBAMP_I2C_TIMEOUT_MS);
        if (st != HAL_OK) return st;
    }
    memcpy(out, buf, sizeof(float));   /* STM32 is little-endian — host order matches */
    return HAL_OK;
}

HAL_StatusTypeDef RbAmpIO_ReadU32LE(uint8_t addr, uint8_t reg, uint32_t *out) {
    uint8_t buf[4];
    for (int i = 0; i < 4; i++) {
        HAL_StatusTypeDef st = HAL_I2C_Mem_Read(s_hi2c, ADDR8(addr), reg + i,
                                                 I2C_MEMADD_SIZE_8BIT,
                                                 &buf[i], 1,
                                                 RBAMP_I2C_TIMEOUT_MS);
        if (st != HAL_OK) return st;
    }
    *out = (uint32_t)buf[0] | (uint32_t)buf[1] << 8
         | (uint32_t)buf[2] << 16 | (uint32_t)buf[3] << 24;
    return HAL_OK;
}

HAL_StatusTypeDef RbAmpIO_WriteU8(uint8_t addr, uint8_t reg, uint8_t val) {
    return HAL_I2C_Mem_Write(s_hi2c, ADDR8(addr), reg,
                              I2C_MEMADD_SIZE_8BIT, &val, 1,
                              RBAMP_I2C_TIMEOUT_MS);
}

HAL_StatusTypeDef RbAmpIO_BroadcastLatch(uint16_t tick16, uint8_t group) {
    /* Canonical 5-byte general-call frame: A5 27 group tick_lo tick_hi.
     * HAL_I2C_Master_Transmit accepts the 8-bit address; 0x00 << 1 = 0x00. */
    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),
    };
    return HAL_I2C_Master_Transmit(s_hi2c, ADDR8(0x00), tx, sizeof tx,
                                    RBAMP_I2C_TIMEOUT_MS);
}

bool RbAmpIO_Probe(uint8_t addr) {
    /* HAL_I2C_IsDeviceReady performs an address-only NACK probe. */
    return HAL_I2C_IsDeviceReady(s_hi2c, ADDR8(addr), /*trials=*/2,
                                  RBAMP_I2C_TIMEOUT_MS) == HAL_OK;
}

HAL_StatusTypeDef RbAmpIO_WaitReady(uint8_t addr, uint32_t timeout_ms) {
    uint32_t deadline = HAL_GetTick() + timeout_ms;
    while (HAL_GetTick() < deadline) {
        uint8_t v = 0;
        if (RbAmpIO_ReadU8(addr, RB_REG_DATA_VALID, &v) == HAL_OK && (v & 0x01U)) {
            return HAL_OK;
        }
        HAL_Delay(50);
    }
    return HAL_TIMEOUT;
}

Redirecionamento de printf

Todos os exemplos chamam printf() através da UART. No seu main.c, adicione o auxiliar canónico de redirecionamento (funciona com newlib-nano):

C
extern UART_HandleTypeDef huart1;

/**
 * @brief  Standard newlib `_write` retarget — sends bytes to UART1.
 * @details A bounded timeout (100 ms) prevents a stuck/unplugged UART from
 *          starving the IWDG (which `HAL_MAX_DELAY` would do). On timeout the
 *          chunk is dropped — preferable to a reset.
 */
int _write(int file, char *ptr, int len) {
    if (HAL_UART_Transmit(&huart1, (uint8_t*)ptr, len, 100) != HAL_OK) {
        return -1;                              /* drop chunk, do NOT block */
    }
    return len;
}

Para projetos Cube IDE com semihosting desativado e newlib-nano selecionado, printf("%.1f", ...) requer -u _printf_float nas flags do linker.


Exemplo 1 — Leitura rápida (mínima)

Objetivo: imprimir U, I, P, PF na UART uma vez por segundo. Hardware: qualquer STM32 + um rbAmp UI1 + USB-UART para a consola do computador.

No CubeMX:

  • ative o I2C1 (Standard, 100 kHz) em PB6/PB7
  • ative o USART1 (115200 8N1) em PA9/PA10
  • tudo o resto por defeito

Código de utilizador em main.c — os blocos /* USER CODE BEGIN 2 */ e /* USER CODE BEGIN WHILE */ mostrados abaixo ficam dentro da função main() gerada pelo CubeMX, entre as chamadas de inicialização e o ciclo while(1). Não os cole ao nível do ficheiro — têm de ficar dentro de main().

Forma de referência (o envolvente int main(void) { … } é gerado pelo CubeMX e mostrado aqui apenas como contexto):

C
/* USER CODE BEGIN Includes */
#include 
#include "rbamp_io.h"
/* USER CODE END Includes */

extern I2C_HandleTypeDef hi2c1;
extern UART_HandleTypeDef huart1;

int _write(int file, char *ptr, int len) {
    if (HAL_UART_Transmit(&huart1, (uint8_t*)ptr, len, 100) != HAL_OK) return -1;
    return len;
}

#define RB_ADDR  0x50U

int main(void)                  /* generated by CubeMX */
{
    HAL_Init();                 /* generated by CubeMX */
    SystemClock_Config();       /* generated by CubeMX */
    MX_GPIO_Init();             /* generated */
    MX_I2C1_Init();             /* generated */
    MX_USART1_UART_Init();      /* generated */

    /* USER CODE BEGIN 2 */
    RbAmpIO_Bind(&hi2c1);

    /* Wait until the first RT window has been computed. */
    if (RbAmpIO_WaitReady(RB_ADDR, 2000) != HAL_OK) {
        printf("ERROR: rbAmp not ready\r\n");
        Error_Handler();
    }

    uint8_t ver = 0;
    RbAmpIO_ReadU8(RB_ADDR, RB_REG_VERSION, &ver);
    printf("rbAmp version: 0x%02X\r\n", ver);
    /* USER CODE END 2 */

    /* USER CODE BEGIN WHILE */
    while (1) {
        float u, i_, p, pf;
        RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_U_RMS,   &u );
        RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_I0_RMS,  &i_);
        RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_P0_REAL, &p );
        RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PF0,     &pf);
        printf("U=%.1fV  I=%.3fA  P=%+.1fW  PF=%+.3f\r\n", u, i_, p, pf);
        HAL_Delay(1000);
    /* USER CODE END WHILE */
    }
}
Nota

Convenção usada neste capítulo: os exemplos 2–10 omitem o main(void) envolvente e as chamadas de inicialização do CubeMX por brevidade, mostrando apenas os blocos /* USER CODE BEGIN 2 */ / /* USER CODE BEGIN WHILE */. Cada trecho que começa com RbAmpIO_Bind(&hi2c1); é o conteúdo de main(), não código ao nível do ficheiro.

Saída esperada na consola:

Text
rbAmp version: 0x04
U=230.1V  I=0.262A  P=+60.2W  PF=+0.998
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: STM32 + rbAmp + SSD1306 (0x3C) no mesmo barramento. Contabilização: unidirecional (nível BASIC). Biblioteca: qualquer driver SSD1306 para STM32-HAL (por exemplo afiskon/stm32-ssd1306).

C
#include 
#include 
#include "rbamp_io.h"
#include "ssd1306.h"        /* your driver of choice */
#include "ssd1306_fonts.h"

extern I2C_HandleTypeDef hi2c1;
#define RB_ADDR  0x50U

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
ssd1306_Init();
RbAmpIO_WaitReady(RB_ADDR, 2000);

/* Primer snapshot — discard the snapshot it produces. */
RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
uint32_t t_prev_ms = HAL_GetTick();
double total_wh = 0.0;
/* USER CODE END 2 */

while (1) {
    HAL_Delay(60UL * 1000UL);

    /* 1) Final snapshot — closes the period [t_prev_ms .. now]. */
    RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    uint32_t t_now_ms = HAL_GetTick();
    HAL_Delay(50);                              /* let firmware finalise snapshot */

    /* 2) Check PERIOD_VALID. */
    uint8_t valid = 0;
    RbAmpIO_ReadU8(RB_ADDR, RB_REG_PERIOD_VALID, &valid);
    if ((valid & 0x01U) == 0) {
        printf("WARN: stale snapshot\r\n");
        t_prev_ms = HAL_GetTick();
        continue;
    }

    /* 3) Read time-averaged power, channel 0. */
    float avg_p = 0.0f;
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P0, &avg_p);

    /* 4) Energy uses the MASTER clock. */
    float dt_s = (float)(t_now_ms - t_prev_ms) / 1000.0f;
    double e_wh = (double)avg_p * dt_s / 3600.0;
    total_wh += e_wh;
    t_prev_ms = t_now_ms;

    /* 5) Render on OLED. */
    char line[24];
    ssd1306_Fill(Black);

    snprintf(line, sizeof(line), "P:  %6.1f W", avg_p);
    ssd1306_SetCursor(0, 0);   ssd1306_WriteString(line, Font_7x10, White);

    snprintf(line, sizeof(line), "dt: %6.1f s", dt_s);
    ssd1306_SetCursor(0, 16);  ssd1306_WriteString(line, Font_7x10, White);

    snprintf(line, sizeof(line), "%.2f Wh", total_wh);
    ssd1306_SetCursor(0, 32);  ssd1306_WriteString(line, Font_11x18, White);

    ssd1306_UpdateScreen();
    printf("avg_P=%.1f  E_period=%.3f  total=%.3f\r\n", avg_p, e_wh, total_wh);
}
Nota

O driver SSD1306 e o rbAmp partilham o hi2c1 — nunca reinicialize o periférico; use apenas o mesmo identificador para ambos.


Exemplo 3 — Monitor multi-módulo

Objetivo: consultar três módulos (alimentação principal, esquentador, AC) e imprimir o total. Hardware: STM32 + 3 × rbAmp UI1 em 0x50, 0x51, 0x52.

C
#include 
#include "rbamp_io.h"

extern I2C_HandleTypeDef hi2c1;

typedef struct {
    uint8_t  addr;
    const char *label;
} module_t;

static const module_t modules[] = {
    { 0x50, "Mains " },
    { 0x51, "Boiler" },
    { 0x52, "AC    " },
};
#define N_MODULES (sizeof(modules) / sizeof(modules[0]))

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);

/* Bus probe — halt if any module is missing. */
for (size_t i = 0; i < N_MODULES; i++) {
    if (!RbAmpIO_Probe(modules[i].addr)) {
        printf("ERROR: %s at 0x%02X not found\r\n",
               modules[i].label, modules[i].addr);
        Error_Handler();
    }
}
printf("All modules OK\r\n");
/* USER CODE END 2 */

while (1) {
    float total_p = 0.0f;
    printf("---\r\n");

    /* Round-robin read. */
    for (size_t i = 0; i < N_MODULES; i++) {
        float u = 0.0f, p = 0.0f;
        RbAmpIO_ReadFloatLE(modules[i].addr, RB_REG_U_RMS,   &u);
        RbAmpIO_ReadFloatLE(modules[i].addr, RB_REG_P0_REAL, &p);
        printf("[%s] U=%.1f  P=%+.1f W\r\n", modules[i].label, u, p);
        total_p += p;
    }
    printf("TOTAL: %.1f W\r\n", total_p);
    HAL_Delay(2000);
}

HAL_I2C_IsDeviceReady() (dentro de RbAmpIO_Probe()) é o equivalente STM32 da sondagem Wire.endTransmission() do Arduino.


Exemplo 4 — medidor de energia por aparelho (UI3)

Objetivo: um módulo UI3 com três pinças de corrente em três cargas diferentes na mesma fase; contadores Wh independentes publicados em MQTT a cada minuto. Hardware: STM32 + 1 × rbAmp UI3 + PHY Ethernet (ou ponte W5500 / ESP32-AT). Stubs de rede: Net_Init() e Net_MqttPublish() (veja a introdução do capítulo).

C
#include 
#include "rbamp_io.h"

extern I2C_HandleTypeDef hi2c1;
extern HAL_StatusTypeDef Net_Init(void);
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

#define RB_ADDR  0x50U
static const char *CH_NAMES[3] = { "main", "heatpump", "lights" };

/**
 * @brief  Publish one channel's data to MQTT.
 */
static void mqtt_publish_channel(const char *ch_name, float avg_p, double e_wh) {
    char topic[64], payload[64];
    int t = snprintf(topic, sizeof(topic), "rbamp/%s/state", ch_name);
    int n = snprintf(payload, sizeof(payload),
                     "{\"power\":%.1f,\"energy\":%.4f}", avg_p, e_wh);
    (void)t;
    Net_MqttPublish(topic, (const uint8_t*)payload, (uint32_t)n, /*qos*/ 0, /*retain*/ 0);
}

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
Net_Init();
RbAmpIO_WaitReady(RB_ADDR, 2000);

RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);   /* primer */
uint32_t t_prev_ms = HAL_GetTick();
double total_wh[3] = { 0.0, 0.0, 0.0 };
/* USER CODE END 2 */

while (1) {
    HAL_Delay(60UL * 1000UL);

    RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    uint32_t t_now_ms = HAL_GetTick();
    HAL_Delay(50);

    uint8_t valid = 0;
    RbAmpIO_ReadU8(RB_ADDR, RB_REG_PERIOD_VALID, &valid);
    if ((valid & 0x01U) == 0) {
        t_prev_ms = HAL_GetTick();
        continue;
    }

    /* PERIOD_AVG_P_W per channel: I0 at 0xDC, I1 at 0xC2, I2 at 0xC6. */
    float avg_p[3];
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P0, &avg_p[0]);
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P1, &avg_p[1]);
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P2, &avg_p[2]);

    float dt_s = (float)(t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    for (int ch = 0; ch < 3; ch++) {
        double e = (double)avg_p[ch] * dt_s / 3600.0;
        total_wh[ch] += e;
        printf("[%s] avg_P=%+.1f W  E_total=%.3f Wh\r\n",
               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 flanco descendente do DRDY dispara uma interrupção EXTI; a ISR define uma flag, e o ciclo principal lê o P_real RT e separa consumo / exportação. Hardware: STM32 + rbAmp UI1; DRDY ligado ao PA0 (configurado como GPIO_EXTI0 descendente, com pull-up no CubeMX).

No CubeMX:

  • PA0 → modo GPIO_EXTI0, pull-up, disparo flanco descendente [Falling edge]
  • NVIC: ative a EXTI line 0 interrupt

stm32xxxx_it.c — gerado pelo CubeMX, apenas o bloco de código do utilizador:

C
extern volatile uint8_t g_data_ready;     /* defined in main.c */

void EXTI0_IRQHandler(void) {
    HAL_GPIO_EXTI_IRQHandler(GPIO_PIN_0);
}

void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) {
    if (GPIO_Pin == GPIO_PIN_0) {
        g_data_ready = 1;                 /* tiny ISR — set a flag and return */
    }
}

Código de utilizador em main.c:

C
#include 
#include 
#include "rbamp_io.h"

extern I2C_HandleTypeDef hi2c1;
volatile uint8_t g_data_ready = 0;

#define RB_ADDR  0x50U

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
RbAmpIO_WaitReady(RB_ADDR, 2000);

double e_consumed_wh = 0.0;
double e_exported_wh = 0.0;
uint32_t t_last_sample_ms = HAL_GetTick();
uint32_t t_last_print_ms  = t_last_sample_ms;
printf("Bidirectional accumulator started\r\n");
/* USER CODE END 2 */

while (1) {
    if (!g_data_ready) {
        continue;                          /* main loop also free to do other work */
    }
    __disable_irq();
    g_data_ready = 0;                      /* clear flag atomically */
    __enable_irq();

    uint32_t t_now = HAL_GetTick();

    /* Signed instantaneous P_real: + consume, − export. */
    float p = 0.0f;
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_P0_REAL, &p);
    float dt_s = (float)(t_now - t_last_sample_ms) / 1000.0f;
    t_last_sample_ms = t_now;

    if (p > 0.0f) {
        e_consumed_wh += (double)p * dt_s / 3600.0;
    } else {
        e_exported_wh += (double)(-p) * dt_s / 3600.0;
    }

    /* Summary print every 5 s — not on every RT window. */
    if (t_now - t_last_print_ms >= 5000) {
        t_last_print_ms = t_now;
        printf("P=%+8.1fW   consumed=%.4f Wh  exported=%.4f Wh  net=%+.4f Wh\r\n",
               p, e_consumed_wh, e_exported_wh,
               e_consumed_wh - e_exported_wh);
    }
}

Notes:

  • A ISR do EXTI é mínima — apenas define g_data_ready. Todo o trabalho I²C é executado no ciclo principal.
  • O qualificador volatile é essencial: o compilador tem de recarregar g_data_ready da RAM em cada iteração do ciclo.
  • Uma janela curta de __disable_irq() / __enable_irq() em volta da limpeza evita uma corrida com um disparo EXTI quase simultâneo.

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 RbAmpIO_BroadcastLatch() para instantâneos síncronos e publica um saldo retido em MQTT a cada minuto.

C
#include 
#include 
#include "rbamp_io.h"

extern I2C_HandleTypeDef hi2c1;
extern HAL_StatusTypeDef Net_Init(void);
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

#define ADDR_MAINS  0x50U   /* bidirectional (STD) */
#define ADDR_SOLAR  0x51U   /* generation only */
#define ADDR_LOADS  0x52U   /* UI3 */

/* PERIOD_AVG_P_NEG address for the mains module — see the SKU datasheet
 * of the STD product. Set to 0xFF for BASIC modules. */
#define REG_PERIOD_AVG_P_NEG_MAINS  0xFFU

typedef struct {
    double mains_in_wh;
    double mains_out_wh;
    double solar_total_wh;
    double loads_wh[3];
} totals_t;

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
Net_Init();
RbAmpIO_WaitReady(ADDR_MAINS, 2000);
RbAmpIO_WaitReady(ADDR_SOLAR, 2000);
RbAmpIO_WaitReady(ADDR_LOADS, 2000);

static uint16_t gc_tick = 0;
if (RbAmpIO_BroadcastLatch(gc_tick++, 0) != HAL_OK) {
    /* GC NACK — fall back to per-module sequential snapshot. */
    RbAmpIO_WriteU8(ADDR_MAINS, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    RbAmpIO_WriteU8(ADDR_SOLAR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    RbAmpIO_WriteU8(ADDR_LOADS, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
}
uint32_t t_prev_ms = HAL_GetTick();

totals_t totals = {0};
printf("Home balance started\r\n");
/* USER CODE END 2 */

while (1) {
    HAL_Delay(60UL * 1000UL);

    /* Synchronous snapshot — all modules snapshot at the same instant. */
    if (RbAmpIO_BroadcastLatch(gc_tick++, 0) != HAL_OK) {
        /* GC NACK — fall back to per-module snapshot (skew ~1 ms/module). */
        RbAmpIO_WriteU8(ADDR_MAINS, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
        RbAmpIO_WriteU8(ADDR_SOLAR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
        RbAmpIO_WriteU8(ADDR_LOADS, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    }
    uint32_t t_now_ms = HAL_GetTick();
    HAL_Delay(50);

    float dt_s = (float)(t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    /* ----- MAINS (bidirectional, STD) ----- */
    uint8_t valid;
    if (RbAmpIO_ReadU8(ADDR_MAINS, RB_REG_PERIOD_VALID, &valid) == HAL_OK
        && (valid & 0x01U)) {
        float p_consume = 0.0f, p_export = 0.0f;
        RbAmpIO_ReadFloatLE(ADDR_MAINS, RB_REG_PERIOD_AVG_P0, &p_consume);
        if (REG_PERIOD_AVG_P_NEG_MAINS != 0xFFU) {
            RbAmpIO_ReadFloatLE(ADDR_MAINS, REG_PERIOD_AVG_P_NEG_MAINS, &p_export);
        }
        totals.mains_in_wh  += (double)p_consume * dt_s / 3600.0;
        totals.mains_out_wh += (double)p_export  * dt_s / 3600.0;
    }

    /* ----- SOLAR (generation only) ----- */
    if (RbAmpIO_ReadU8(ADDR_SOLAR, RB_REG_PERIOD_VALID, &valid) == HAL_OK
        && (valid & 0x01U)) {
        float p = 0.0f;
        RbAmpIO_ReadFloatLE(ADDR_SOLAR, RB_REG_PERIOD_AVG_P0, &p);
        totals.solar_total_wh += (double)p * dt_s / 3600.0;
    }

    /* ----- LOADS (UI3, three channels) ----- */
    if (RbAmpIO_ReadU8(ADDR_LOADS, RB_REG_PERIOD_VALID, &valid) == HAL_OK
        && (valid & 0x01U)) {
        float p[3] = {0};
        RbAmpIO_ReadFloatLE(ADDR_LOADS, RB_REG_PERIOD_AVG_P0, &p[0]);  /* I0 */
        RbAmpIO_ReadFloatLE(ADDR_LOADS, RB_REG_PERIOD_AVG_P1, &p[1]);  /* I1 */
        RbAmpIO_ReadFloatLE(ADDR_LOADS, RB_REG_PERIOD_AVG_P2, &p[2]);  /* I2 */
        for (int i = 0; i < 3; i++) {
            totals.loads_wh[i] += (double)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;

    printf("MAINS  in=%.2f  out=%.2f\r\n", totals.mains_in_wh, totals.mains_out_wh);
    printf("SOLAR  gen=%.2f  self-used=%.2f  exported=%.2f\r\n",
           totals.solar_total_wh, solar_self_used, totals.mains_out_wh);
    printf("LOADS  HP=%.2f  AC=%.2f  EV=%.2f\r\n",
           totals.loads_wh[0], totals.loads_wh[1], totals.loads_wh[2]);
    printf("TOTAL  household consumed=%.2f Wh\r\n", total_consumed);

    char payload[512];
    int n = 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]);
    Net_MqttPublish("home/energy/balance", (const uint8_t*)payload,
                     (uint32_t)n, /*qos*/ 1, /*retain*/ 1);
}

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 via SDIO + FATFS. Hardware: STM32F4 / L4 / H7 + rbAmp + cartão SD na interface SDIO (CubeMX: ative o middleware FATFS + SDIO).

Configuração no CubeMX:

  • Modo SDIO = barramento SD de 4 bits [SD 4 bits Wide bus] ou SD de 1 bit [SD 1 bit]
  • Middleware FATFS ativado, ponto de montagem predefinido
  • PA0 = GPIO_EXTI0, descendente, pull-up (DRDY)
C
#include 
#include 
#include 
#include "rbamp_io.h"
#include "fatfs.h"

extern I2C_HandleTypeDef hi2c1;
extern FATFS  SDFatFS;
extern char   SDPath[4];
extern volatile uint8_t g_data_ready;  /* set by EXTI0 callback */

#define RB_ADDR  0x50U
#define EMA_ALPHA         0.05f
#define EVENT_THRESHOLD_W 200.0f

static FIL  s_logfile;
static bool s_log_open = false;       /* guard — f_write on closed FIL is UB */

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
RbAmpIO_WaitReady(RB_ADDR, 2000);

/* Mount the SD card (CubeMX has already set up SDFatFS / SDPath).
 * Both mount and open MUST succeed before we touch s_logfile in the loop. */
if (f_mount(&SDFatFS, SDPath, 1) == FR_OK) {
    if (f_open(&s_logfile, "events.log",
               FA_OPEN_APPEND | FA_WRITE) == FR_OK) {
        s_log_open = true;
        printf("SD mounted; logging to events.log\r\n");
    } else {
        printf("WARN: f_open(events.log) failed — file logging disabled\r\n");
    }
} else {
    printf("WARN: f_mount failed — file logging disabled\r\n");
}

/* Seed the EMA with current power so we do not log a spurious startup event. */
float p_ema = 0.0f;
RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_P0_REAL, &p_ema);
printf("Event detector started\r\n");
/* USER CODE END 2 */

while (1) {
    if (!g_data_ready) continue;
    __disable_irq(); g_data_ready = 0; __enable_irq();

    float p = 0.0f;
    RbAmpIO_ReadFloatLE(RB_ADDR, 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.0f) ? "TURN_ON" : "TURN_OFF";
        char line[128];
        int n = snprintf(line, sizeof(line),
                         "%lu  %s  delta=%+.1f W  P=%.1f W  EMA=%.1f W\r\n",
                         (unsigned long)HAL_GetTick(),
                         type, delta, p, p_ema);
        printf("%s", line);
        if (s_log_open) {                       /* never touch a closed FIL */
            UINT bw;
            f_write(&s_logfile, line, n, &bw);
            f_sync(&s_logfile);                 /* flush to the card */
        }
    }
}

Exemplo 8 — Publicador MQTT com descoberta automática do Home Assistant [Auto-discovery]

Objetivo: uma integração HA pronta a usar. O STM32 publica configurações de descoberta automática do HA (retidas) e emite um estado JSON por minuto. Hardware: STM32 com Ethernet (H7 / F7 / F4 + LAN8742) ou qualquer STM32 + ponte Ethernet.

C
#include 
#include 
#include "rbamp_io.h"

extern I2C_HandleTypeDef hi2c1;
extern HAL_StatusTypeDef Net_Init(void);
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

#define RB_ADDR     0x50U
#define DEVICE_ID   "rbamp_main"
#define DEVICE_NAME "Mains rbAmp"

/**
 * @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/%s/%s/config", DEVICE_ID, key);

    int n = snprintf(payload, sizeof(payload),
        "{"
          "\"name\":\"%s %s\","
          "\"unique_id\":\"%s_%s\","
          "\"state_topic\":\"rbamp/%s/state\","
          "\"value_template\":\"{{ value_json.%s }}\","
          "\"state_class\":\"%s\","
          "\"device\":{"
            "\"identifiers\":[\"%s\"],"
            "\"name\":\"%s\","
            "\"manufacturer\":\"rbAmp\","
            "\"model\":\"rbAmp UI*\""
          "}",
        DEVICE_NAME, friendly, DEVICE_ID, key,
        DEVICE_ID, key, state_class,
        DEVICE_ID, DEVICE_NAME);
    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);
    n += snprintf(payload + n, sizeof(payload) - n, "}");

    Net_MqttPublish(topic, (const uint8_t*)payload, (uint32_t)n,
                    /*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");
}

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
Net_Init();
publish_discovery_all();

RbAmpIO_WaitReady(RB_ADDR, 2000);
RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);  /* primer */
uint32_t t_prev_ms = HAL_GetTick();
double total_wh = 0.0;
/* USER CODE END 2 */

while (1) {
    HAL_Delay(60UL * 1000UL);

    RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    uint32_t t_now_ms = HAL_GetTick();
    HAL_Delay(50);

    uint8_t valid = 0;
    RbAmpIO_ReadU8(RB_ADDR, RB_REG_PERIOD_VALID, &valid);
    if ((valid & 0x01U) == 0) {
        t_prev_ms = HAL_GetTick();
        continue;
    }
    float avg_p = 0.0f;
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P0, &avg_p);
    float dt_s = (float)(t_now_ms - t_prev_ms) / 1000.0f;
    total_wh += (double)avg_p * dt_s / 3600.0;
    t_prev_ms = t_now_ms;

    /* Live RT values for the state payload. */
    float u = 0, i_ = 0, pf = 0, q = 0;
    uint8_t freq = 0;
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_U_RMS,  &u);
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_I0_RMS, &i_);
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PF0,    &pf);
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_Q0,     &q);
    RbAmpIO_ReadU8     (RB_ADDR, RB_REG_AC_FREQ, &freq);

    char payload[384];
    int n = 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);

    char topic[64];
    snprintf(topic, sizeof(topic), "rbamp/%s/state", DEVICE_ID);
    Net_MqttPublish(topic, (const uint8_t*)payload, (uint32_t)n,
                    /*qos*/ 0, /*retain*/ 0);
    printf("Published: %s\r\n", payload);
}

Exemplo 9 — Registador com bateria e modo STANDBY

Objetivo: um registador exterior / sem rede elétrica que acorda do STANDBY a cada 10 minutos pelo alarme RTC, instantâneo de um período, publica por MQTT e volta ao STANDBY. O consumo de corrente é dominado pelo raro despertar — o STANDBY fica num único dígito em µA na maioria das famílias STM32. Hardware: STM32L4 / L5 (melhor baixo consumo), ou F4/F7 com menos funcionalidades. O rbAmp pode ser alimentado por um interruptor high-side num GPIO, para não consumir nada durante o STANDBY. Persistência: os registos de cópia de segurança RTC RTC->BKP0R..BKPxR (variam conforme a família) sobrevivem ao STANDBY e ao VBAT.

C
#include 
#include 
#include "rbamp_io.h"
/* CubeMX-generated: RTC + Wakeup timer + Backup registers in PWR */

extern I2C_HandleTypeDef hi2c1;
extern RTC_HandleTypeDef hrtc;
extern HAL_StatusTypeDef Net_Init(void);
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

#define RB_ADDR  0x50U
#define WAKE_SECONDS  (10U * 60U)       /* 10 minutes */

/* Backup-register layout (uint32 per slot). All survive STANDBY and VBAT.
 * BKP0..1: total_wh (double, split into two uint32 halves)
 * BKP2:    wake_count
 * BKP3:    primer_done (0/1) + flags
 * BKP4..5: t_prev_ms_ticks (uint64 split)
 */
#define BKP_TOTAL_WH_LO  RTC_BKP_DR0
#define BKP_TOTAL_WH_HI  RTC_BKP_DR1
#define BKP_WAKE_COUNT   RTC_BKP_DR2
#define BKP_PRIMER       RTC_BKP_DR3
#define BKP_T_PREV_LO    RTC_BKP_DR4
#define BKP_T_PREV_HI    RTC_BKP_DR5

static void bkp_load(double *total_wh, uint32_t *wakes,
                     uint8_t *primer, uint64_t *t_prev_ms) {
    uint32_t lo = HAL_RTCEx_BKUPRead(&hrtc, BKP_TOTAL_WH_LO);
    uint32_t hi = HAL_RTCEx_BKUPRead(&hrtc, BKP_TOTAL_WH_HI);
    uint64_t bits = ((uint64_t)hi << 32) | lo;
    memcpy(total_wh, &bits, sizeof(double));
    *wakes  = HAL_RTCEx_BKUPRead(&hrtc, BKP_WAKE_COUNT);
    *primer = (uint8_t)HAL_RTCEx_BKUPRead(&hrtc, BKP_PRIMER);
    uint32_t plo = HAL_RTCEx_BKUPRead(&hrtc, BKP_T_PREV_LO);
    uint32_t phi = HAL_RTCEx_BKUPRead(&hrtc, BKP_T_PREV_HI);
    *t_prev_ms = ((uint64_t)phi << 32) | plo;
}

static void bkp_save(double total_wh, uint32_t wakes,
                     uint8_t primer, uint64_t t_prev_ms) {
    HAL_PWR_EnableBkUpAccess();
    uint64_t bits;
    memcpy(&bits, &total_wh, sizeof(double));
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_TOTAL_WH_LO, (uint32_t)(bits & 0xFFFFFFFFU));
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_TOTAL_WH_HI, (uint32_t)(bits >> 32));
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_WAKE_COUNT,  wakes);
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_PRIMER,      primer);
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_T_PREV_LO,   (uint32_t)(t_prev_ms & 0xFFFFFFFFU));
    HAL_RTCEx_BKUPWrite(&hrtc, BKP_T_PREV_HI,   (uint32_t)(t_prev_ms >> 32));
}

/**
 * @brief  Arm the RTC wake-up timer and enter STANDBY.
 * @details On the next wake (or RESET via NRST), execution restarts at the
 *          reset vector — exactly like a fresh boot.
 */
static void enter_standby(uint32_t seconds) {
    HAL_RTCEx_SetWakeUpTimer_IT(&hrtc, seconds,
                                 RTC_WAKEUPCLOCK_CK_SPRE_16BITS);
    HAL_PWR_EnterSTANDBYMode();
    /* never returns */
}

/* USER CODE BEGIN 2 */
double   total_wh;
uint32_t wake_count;
uint8_t  primer_done;
uint64_t t_prev_unused;            /* reserved BKP slot; see note below */
bkp_load(&total_wh, &wake_count, &primer_done, &t_prev_unused);
(void)t_prev_unused;               /* HAL_GetTick() resets after STANDBY — */
                                    /* the dt is approximated by WAKE_SECONDS  */
                                    /* instead. Slot kept for forward compat;  */
                                    /* upgrade to HAL_RTC_GetTime/Date if you  */
                                    /* need true wall-clock dt across sleeps.  */
wake_count++;

RbAmpIO_Bind(&hi2c1);
if (RbAmpIO_WaitReady(RB_ADDR, 2000) != HAL_OK) {
    bkp_save(total_wh, wake_count, primer_done, /*t_prev=*/0);
    enter_standby(WAKE_SECONDS);
}

/* First wake-up after a cold boot: primer snapshot only. */
if (!primer_done) {
    RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    primer_done = 1;
    bkp_save(total_wh, wake_count, primer_done, /*t_prev=*/0);
    printf("Primer done — entering STANDBY\r\n");
    enter_standby(WAKE_SECONDS);
}

/* Subsequent wake-ups: close the period and read its average power. */
RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
HAL_Delay(50);

uint8_t valid = 0;
RbAmpIO_ReadU8(RB_ADDR, RB_REG_PERIOD_VALID, &valid);
if ((valid & 0x01U) == 0) {
    bkp_save(total_wh, wake_count, primer_done, /*t_prev=*/0);
    enter_standby(WAKE_SECONDS);
}

float avg_p = 0.0f;
RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P0, &avg_p);
/* dt approximation: STANDBY resets HAL_GetTick(), and the WAKE_SECONDS-driven
 * RTC wake-timer is the wall-clock interval to single-digit-% accuracy with
 * an LSE crystal. For tighter accounting, read HAL_RTC_GetTime/Date before
 * STANDBY and compute dt against the stored epoch. */
float dt_s = (float)WAKE_SECONDS;
total_wh += (double)avg_p * dt_s / 3600.0;

/* Publish via Wi-Fi / Ethernet (graceful fallback). */
if (Net_Init() == HAL_OK) {
    char payload[256];
    int n = snprintf(payload, sizeof(payload),
        "{\"wake\":%lu,\"dt_s\":%.1f,\"avg_p\":%.1f,\"energy_wh\":%.3f}",
        (unsigned long)wake_count, dt_s, avg_p, total_wh);
    Net_MqttPublish("rbamp/remote/state",
                    (const uint8_t*)payload, (uint32_t)n,
                    /*qos*/ 1, /*retain*/ 1);
    printf("Published: %s\r\n", payload);
}

bkp_save(total_wh, wake_count, primer_done, /*t_prev=*/0);
enter_standby(WAKE_SECONDS);
/* USER CODE END 2 */

Notes:

  • Os registos de cópia de segurança (BKP_DR*) sobrevivem ao STANDBY e ao VBAT, mas não a uma perda total de energia sem uma bateria de cópia VBAT. Para persistência absoluta, espelhe periodicamente o total na flash interna.
  • HAL_GetTick() é reposto a cada STANDBY → use o calendário RTC (HAL_RTC_GetTime/Date) para um dt absoluto de relógio de parede, se a sua aplicação o exigir.
  • O RTC do CubeMX deve ser configurado com LSE (cristal de 32.768 kHz) para uma temporização precisa a longo prazo; a deriva do LSI pode chegar a 5–10 % com a temperatura.
  • Para STM32F1 / F4, o enum da fonte de relógio de despertar pode diferir ligeiramente; consulte a referência HAL da família para os valores RTC_WAKEUPCLOCK_*.

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. O STM32 mantém um relógio de parede real através de SNTP (LwIP lwip/apps/sntp.h), 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: STM32 com Ethernet (STM32H7 / F7 / F4 + LAN8742) ou qualquer STM32 + ponte Ethernet.

C
#include 
#include 
#include 
#include "rbamp_io.h"
#include "lwip/apps/sntp.h"

extern I2C_HandleTypeDef hi2c1;
extern RTC_HandleTypeDef hrtc;
extern HAL_StatusTypeDef Net_Init(void);
extern HAL_StatusTypeDef Net_MqttPublish(const char *topic,
                                          const uint8_t *payload, uint32_t len,
                                          uint8_t qos, uint8_t retain);

#define RB_ADDR  0x50U

#define TZ_OFFSET_HOURS  2          /* CEST = UTC+2; recompute on roll-over for DST */
#define PEAK_START_HOUR  8
#define PEAK_END_HOUR    22

/* IMPORTANT: LwIP's SNTP populates the system clock via the SNTP_SET_SYSTEM_TIME
 * macro that you MUST define in lwipopts.h. Without it, time(NULL) stays at 0
 * forever and sntp_sync() will always time out. Minimal hook:
 *
 *     #include 
 *     #define SNTP_SET_SYSTEM_TIME(sec) \
 *         do { struct timeval tv = { (time_t)(sec), 0 }; \
 *              settimeofday(&tv, NULL); } while (0)
 *
 * Also requires _gettimeofday() / time() to be retargeted to the same source
 * (newlib's default works once settimeofday is wired). */

typedef struct {
    double peak_wh;
    double off_peak_wh;
    int    day_of_year;             /* tm_yday */
} day_totals_t;
typedef struct {
    double peak_wh;
    double off_peak_wh;
} lifetime_totals_t;

static day_totals_t      s_today    = { .day_of_year = -1 };
static lifetime_totals_t s_lifetime = { 0 };

/**
 * @brief  Start SNTP and wait until the system clock looks plausible (year > 2023).
 */
static HAL_StatusTypeDef sntp_sync(uint32_t timeout_ms) {
    sntp_setoperatingmode(SNTP_OPMODE_POLL);
    sntp_setservername(0, "pool.ntp.org");
    sntp_setservername(1, "time.google.com");
    sntp_init();

    uint32_t deadline = HAL_GetTick() + timeout_ms;
    while (HAL_GetTick() < deadline) {
        time_t now = time(NULL);
        struct tm lt;
        gmtime_r(&now, <);
        if (lt.tm_year + 1900 >= 2023) {
            printf("SNTP sync: %04d-%02d-%02d %02d:%02d:%02d UTC\r\n",
                   lt.tm_year + 1900, lt.tm_mon + 1, lt.tm_mday,
                   lt.tm_hour, lt.tm_min, lt.tm_sec);
            return HAL_OK;
        }
        HAL_Delay(500);
    }
    return HAL_TIMEOUT;
}

static struct tm local_time(void) {
    time_t now = time(NULL) + (TZ_OFFSET_HOURS * 3600);
    struct tm lt;
    gmtime_r(&now, <);
    return lt;
}

static bool is_peak_hour(int hour) {
    /* For schedules that cross midnight, swap to
     *    return (hour >= PEAK_START_HOUR) || (hour < PEAK_END_HOUR);
     */
    return (hour >= PEAK_START_HOUR) && (hour < PEAK_END_HOUR);
}

static void iso_now(char *out, size_t out_len) {
    struct tm lt = local_time();
    const char sign = (TZ_OFFSET_HOURS >= 0) ? '+' : '-';
    snprintf(out, out_len, "%04d-%02d-%02dT%02d:%02d:%02d%c%02d00",
             lt.tm_year + 1900, lt.tm_mon + 1, lt.tm_mday,
             lt.tm_hour, lt.tm_min, lt.tm_sec,
             sign, (TZ_OFFSET_HOURS < 0) ? -TZ_OFFSET_HOURS : TZ_OFFSET_HOURS);
}

/**
 * @brief  Add one period's energy to the right tariff bucket and roll over at midnight.
 */
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];
            int n = 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);
            Net_MqttPublish("rbamp/tou/day_close",
                            (const uint8_t*)payload, (uint32_t)n,
                            /*qos*/ 1, /*retain*/ 1);
            printf("Day closed: %s\r\n", 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;
    }
}

/* USER CODE BEGIN 2 */
RbAmpIO_Bind(&hi2c1);
Net_Init();
sntp_sync(15000);

RbAmpIO_WaitReady(RB_ADDR, 2000);
RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);   /* primer */
uint32_t t_prev_ms = HAL_GetTick();
printf("TOU started: peak %02d:00..%02d:00 local\r\n",
       PEAK_START_HOUR, PEAK_END_HOUR);
/* USER CODE END 2 */

while (1) {
    HAL_Delay(60UL * 1000UL);

    RbAmpIO_WriteU8(RB_ADDR, RB_REG_COMMAND, RB_CMD_LATCH_PERIOD);
    uint32_t t_now_ms = HAL_GetTick();
    HAL_Delay(50);

    uint8_t valid = 0;
    RbAmpIO_ReadU8(RB_ADDR, RB_REG_PERIOD_VALID, &valid);
    if ((valid & 0x01U) == 0) {
        t_prev_ms = HAL_GetTick();
        continue;
    }
    float avg_p = 0.0f;
    RbAmpIO_ReadFloatLE(RB_ADDR, RB_REG_PERIOD_AVG_P0, &avg_p);
    float dt_s = (float)(t_now_ms - t_prev_ms) / 1000.0f;
    double e_wh = (double)avg_p * dt_s / 3600.0;
    t_prev_ms = t_now_ms;

    /* Guard against fresh boot before SNTP succeeds. */
    struct tm lt = local_time();
    if (lt.tm_year + 1900 < 2023) {
        printf("WARN: clock not yet synced, retrying SNTP\r\n");
        sntp_sync(15000);
        continue;
    }
    accumulate(e_wh, <);
    bool peak = is_peak_hour(lt.tm_hour);

    char iso[40];
    iso_now(iso, sizeof(iso));

    char payload[384];
    int n = 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);
    Net_MqttPublish("rbamp/tou/state", (const uint8_t*)payload,
                    (uint32_t)n, /*qos*/ 0, /*retain*/ 0);
    printf("%s\r\n", payload);
}

Notes:

  • O cliente SNTP do LwIP preenche a fonte time(NULL) da biblioteca C através dos hooks SYS_ARCH_RAND / sys_now do LwIP; nos portes STM32, gmtime_r() devolve então valores razoáveis.
  • Para o tratamento completo do horário de verão, guarde o desfasamento TZ numa pequena tabela de consulta e recalcule na mudança de dia, ou faça passar a hora por tzset() com uma string TZ POSIX, se a sua compilação newlib a suportar (a maioria suporta).
  • Para a medição bidirecional STD, chame accumulate() duas vezes — uma para o lado do consumo e outra para o lado da exportação — e publique ambos os escalões de ponta e fora de ponta.

Comparação de exemplos

# Complexidade Saída MQTT DRDY Multi-módulo Bidirecional Persistência Caso de utilização
1 mínimo printf via UART — — — — — teste de funcionamento
2 baixo OLED — — — — RAM contador em caixa
3 baixo printf via UART — — sim (3) — — monitorização doméstica
4 médio — sim — — — RAM por eletrodoméstico no HA
5 médio printf via 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 (FATFS) — sim — — Cartão SD deteção de eventos
8 médio — sim (+disco) — — opcional RAM + MQTT Auto-discovery do HA
9 médio — sim — — — Registos BKP do RTC registador para exterior / fora da rede
10 médio printf via UART sim — — opcional RAM + MQTT TOU pico/fora de pico com SNTP

Boas práticas

  • Verifique sempre os códigos de retorno do HAL. As transações I²C podem falhar de forma transitória em barramentos longos; o código de produção deve repetir a operação em vez de a ignorar. Envolva as repetições à volta das chamadas RbAmpIO_*, se for necessário.
  • Mantenha as ISRs minimalistas. Os callbacks de EXTI / SysTick / conclusão de DMA devem definir uma flag volatile uint8_t e retornar. Todo o trabalho de I²C / printf pertence ao ciclo principal.
  • Um driver HAL I²C por periférico. O rbAmp e o OLED partilham o hi2c1 — nunca reinicialize o periférico; use apenas o identificador partilhado.
  • Use HAL_GetTick() para o relógio mestre. Precisão de milissegundos, monotónico, sobrevive à maioria das operações HAL.
  • PERIOD_VALID (0x07) tem de ser verificado após cada CMD_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 HAL_I2C_IsDeviceReady() para análises do barramento — equivalente STM32 do ping endTransmission() do Arduino.
  • Para aplicações com bateria, entre em STOP ou STANDBY entre amostras e arme o temporizador de despertar RTC. O STANDBY reinicia a execução no vetor de reset — use registos de cópia de segurança para o estado que tem de sobreviver.
  • Guarde os totais de Wh na flash interna se precisar que sobrevivam a uma perda total de energia (remoção da bateria sem VBAT). Os registos de cópia de segurança RTC só sobrevivem quando há VBAT ou VDD presente.
  • Suporte de float em printf requer -u _printf_float nas flags do linker do CubeIDE (compilação newlib-nano).

O que se segue

Depois de percorrer estes dez exemplos: