Quando o firmware precisa ser previsível (tempo real), o desenho do filtro não é só “matemático”: você escolhe estruturas e limites para garantir custo computacional constante, estado pequeno e estabilidade numérica, principalmente se você for para ponto fixo ou tiver ADC+DMA alimentando o pipeline. (Essa preocupação de arquitetura e previsibilidade é típica de projetos de tempo real.)

1) Notch discreto: o “biquad” que apaga uma frequência

Um notch digital clássico pode ser implementado como um biquad IIR (segunda ordem) com zeros exatamente na frequência que você quer cancelar e polos próximos, controlando a largura do “buraco” via fator de qualidade (Q). Quanto maior o (Q), mais estreito é o notch (ótimo para interferência tonal estável), mas maior a sensibilidade a variação de (f_0) e a quantização dos coeficientes. Em termos práticos: para hum de rede em 60 Hz, se o sinal tiver variação de frequência (rede oscilando, ou a interferência “escorregando”), um (Q) alto demais pode deixar “vazar” parte do ruído. Para tom de comutação de um inversor ou fonte chaveada, se o clock for estável, dá para usar (Q) alto e atacar de forma cirúrgica.

O biquad notch mais comum pode ser escrito como:

\[
H(z)=\frac{1 – 2\cos(\omega_0)z^{-1} + z^{-2}}{1 – 2r\cos(\omega_0)z^{-1} + r^2 z^{-2}}
\]

onde \(\omega_0=2\pi f_0/F_s\) e (r) controla a “proximidade” dos polos aos zeros (quanto mais perto de 1, mais estreito e mais profundo). Uma ligação prática entre (r) e (Q) é aproximar a largura de banda por \(BW \approx f_0/Q\) e usar \(r \approx e^{-\pi BW/F_s}\). Isso funciona muito bem para firmware porque você calcula coeficientes uma vez (ou quando \(f_0\) muda) e o processamento por amostra fica constante.

Código em C: biquad notch (float) com inicialização por \(F_s, f_0, Q\)

#include <math.h>
#include <stdint.h>

#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif

typedef struct {
    // Coeficientes normalizados (a0 = 1)
    float b0, b1, b2;
    float a1, a2;

    // Estados (forma direta II transposta)
    float z1, z2;
} NotchBiquad;

/**
 * @brief Inicializa um filtro notch IIR (biquad) em forma direta II transposta.
 * @param f     Ponteiro para a estrutura do filtro.
 * @param Fs    Frequência de amostragem (Hz).
 * @param f0    Frequência central do notch (Hz).
 * @param Q     Fator de qualidade (adimensional). Ex.: 10..50 típicos.
 *
 * Observação prática:
 *  - Q maior => notch mais estreito, mais sensível a variações de f0 e quantização.
 *  - Q menor => notch mais largo, remove mais “vizinhança” de frequências.
 */
static inline void notch_init(NotchBiquad *f, float Fs, float f0, float Q)
{
    const float w0 = 2.0f * (float)M_PI * (f0 / Fs);

    // Largura de banda aproximada (Hz)
    const float BW = f0 / Q;

    // Polo raio r (aprox.) -> define a largura do notch
    const float r = expf(-(float)M_PI * (BW / Fs));

    const float c = cosf(w0);

    // Numerador (zeros no círculo unitário em ±w0)
    const float b0 = 1.0f;
    const float b1 = -2.0f * c;
    const float b2 = 1.0f;

    // Denominador (polos em raio r)
    const float a0 = 1.0f;
    const float a1 = -2.0f * r * c;
    const float a2 = r * r;

    // Normaliza por a0 (a0=1 aqui, mas mantemos o padrão)
    f->b0 = b0 / a0;
    f->b1 = b1 / a0;
    f->b2 = b2 / a0;
    f->a1 = a1 / a0;
    f->a2 = a2 / a0;

    f->z1 = 0.0f;
    f->z2 = 0.0f;
}

/**
 * @brief Processa 1 amostra pelo biquad notch (DF-II Transposta).
 * @param f Estrutura do filtro.
 * @param x Amostra de entrada.
 * @return  Amostra filtrada.
 */
static inline float notch_process(NotchBiquad *f, float x)
{
    // DF-II transposta:
    // y = b0*x + z1
    // z1 = b1*x - a1*y + z2
    // z2 = b2*x - a2*y
    const float y = (f->b0 * x) + f->z1;
    const float z1 = (f->b1 * x) - (f->a1 * y) + f->z2;
    const float z2 = (f->b2 * x) - (f->a2 * y);

    f->z1 = z1;
    f->z2 = z2;
    return y;
}

#include <math.h>
#include <stdint.h>

#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif

typedef struct {
    // Coeficientes normalizados (a0 = 1)
    float b0, b1, b2;
    float a1, a2;

    // Estados (forma direta II transposta)
    float z1, z2;
} NotchBiquad;

/**
 * @brief Inicializa um filtro notch IIR (biquad) em forma direta II transposta.
 * @param f     Ponteiro para a estrutura do filtro.
 * @param Fs    Frequência de amostragem (Hz).
 * @param f0    Frequência central do notch (Hz).
 * @param Q     Fator de qualidade (adimensional). Ex.: 10..50 típicos.
 *
 * Observação prática:
 *  - Q maior => notch mais estreito, mais sensível a variações de f0 e quantização.
 *  - Q menor => notch mais largo, remove mais “vizinhança” de frequências.
 */
static inline void notch_init(NotchBiquad *f, float Fs, float f0, float Q)
{
    const float w0 = 2.0f * (float)M_PI * (f0 / Fs);

    // Largura de banda aproximada (Hz)
    const float BW = f0 / Q;

    // Polo raio r (aprox.) -> define a largura do notch
    const float r = expf(-(float)M_PI * (BW / Fs));

    const float c = cosf(w0);

    // Numerador (zeros no círculo unitário em ±w0)
    const float b0 = 1.0f;
    const float b1 = -2.0f * c;
    const float b2 = 1.0f;

    // Denominador (polos em raio r)
    const float a0 = 1.0f;
    const float a1 = -2.0f * r * c;
    const float a2 = r * r;

    // Normaliza por a0 (a0=1 aqui, mas mantemos o padrão)
    f->b0 = b0 / a0;
    f->b1 = b1 / a0;
    f->b2 = b2 / a0;
    f->a1 = a1 / a0;
    f->a2 = a2 / a0;

    f->z1 = 0.0f;
    f->z2 = 0.0f;
}

/**
 * @brief Processa 1 amostra pelo biquad notch (DF-II Transposta).
 * @param f Estrutura do filtro.
 * @param x Amostra de entrada.
 * @return  Amostra filtrada.
 */
static inline float notch_process(NotchBiquad *f, float x)
{
    // DF-II transposta:
    // y = b0*x + z1
    // z1 = b1*x - a1*y + z2
    // z2 = b2*x - a2*y
    const float y = (f->b0 * x) + f->z1;
    const float z1 = (f->b1 * x) - (f->a1 * y) + f->z2;
    const float z2 = (f->b2 * x) - (f->a2 * y);

    f->z1 = z1;
    f->z2 = z2;
    return y;
}

Melhores usos do notch: quando você conhece (ou mede) a frequência indesejada e ela é estreita, relativamente estável e você quer preservar quase tudo ao redor. Em instrumentação, isso aparece em leitura de shunt/ADC contaminada por rede; em áudio, hum; em controle, ressonância mecânica estreita (desde que não destrua margem de fase indevidamente); em eletrônica de potência, uma componente tonal em corrente/tensão.

2) Média sincronizada: “soma coerente” alinhada à fase

A média sincronizada (às vezes chamada de synchronous averaging, time synchronous averaging) não é “só uma média móvel”. A sacada é que você escolhe uma janela exatamente igual a um período do fenômeno repetitivo (ou múltiplos inteiros) e reinicia/alinha essa janela usando um evento de referência: um zero-cross, um pulso de encoder, um índice, ou um marcador derivado do PWM. Se você tem (N) amostras por período e faz uma média sobre (K) períodos alinhados, o componente que se repete com a mesma fase soma e cresce proporcionalmente, enquanto ruído aleatório cai como (\sqrt{K}) no RMS. Além disso, componentes que não “encaixam” naquele período tendem a se cancelar.

Em termos de filtro, isso se comporta como um filtro tipo comb (pente) extremamente eficiente para rejeitar tudo que não é coerente com o período escolhido. A diferença para um notch é que você não está mirando uma única frequência: você está favorecendo toda a forma de onda repetitiva no domínio do tempo, desde que sincronizada.

Código em C: média sincronizada por períodos (com referência externa)

A seguir vai uma implementação simples (e bem útil) para firmware: você acumula amostras de cada posição dentro do período e, a cada período completo, você atualiza a média. Isso é perfeito quando você tem um “gatilho de início de período” (por exemplo, interrupção de índice do encoder ou zero-cross).

#include <stdint.h>
#include <string.h>

typedef struct {
    uint16_t N;          // amostras por período
    uint16_t idx;        // posição atual no período [0..N-1]
    uint32_t K;          // quantos períodos já acumulados (limite/controle externo)

    // Buffers de acumulação (use int64 se seu range for grande)
    int64_t *acc;        // soma por posição
    int32_t *avg;        // média por posição (resultado)
} SyncAvg;

/**
 * @brief Inicializa a média sincronizada.
 * @param s       Estrutura.
 * @param acc     Buffer de acumulação de tamanho N (int64_t).
 * @param avg     Buffer de saída média de tamanho N (int32_t).
 * @param N       Amostras por período.
 */
static inline void syncavg_init(SyncAvg *s, int64_t *acc, int32_t *avg, uint16_t N)
{
    s->N = N;
    s->idx = 0;
    s->K = 0;
    s->acc = acc;
    s->avg = avg;

    memset(s->acc, 0, (size_t)N * sizeof(int64_t));
    memset(s->avg, 0, (size_t)N * sizeof(int32_t));
}

/**
 * @brief Deve ser chamado quando ocorre o "marcador" de início de período (ex.: zero-cross ou índice do encoder).
 *        Isso força alinhamento de fase.
 */
static inline void syncavg_period_reset(SyncAvg *s)
{
    s->idx = 0;
}

/**
 * @brief Alimenta a média sincronizada com uma amostra do ADC já alinhada ao relógio de amostragem.
 * @param s Estrutura.
 * @param x Amostra (ex.: ADC já convertido para int32).
 *
 * Funcionamento:
 *  - A cada amostra, acumula na posição idx.
 *  - Ao completar N amostras, fecha um período e atualiza avg[].
 *  - A referência de fase vem de syncavg_period_reset() (externa).
 */
static inline void syncavg_push_sample(SyncAvg *s, int32_t x)
{
    s->acc[s->idx] += (int64_t)x;
    s->idx++;

    if (s->idx >= s->N) {
        s->idx = 0;
        s->K++;

        // Atualiza a média inteira por posição (custo O(N) por período).
        // Se N for grande e seu MCU for apertado, dá para atualizar de forma incremental.
        for (uint16_t i = 0; i < s->N; i++) {
            s->avg[i] = (int32_t)(s->acc[i] / (int64_t)s->K);
        }
    }
}

#include <stdint.h>
#include <string.h>

typedef struct {
    uint16_t N;          // amostras por período
    uint16_t idx;        // posição atual no período [0..N-1]
    uint32_t K;          // quantos períodos já acumulados (limite/controle externo)

    // Buffers de acumulação (use int64 se seu range for grande)
    int64_t *acc;        // soma por posição
    int32_t *avg;        // média por posição (resultado)
} SyncAvg;

/**
 * @brief Inicializa a média sincronizada.
 * @param s       Estrutura.
 * @param acc     Buffer de acumulação de tamanho N (int64_t).
 * @param avg     Buffer de saída média de tamanho N (int32_t).
 * @param N       Amostras por período.
 */
static inline void syncavg_init(SyncAvg *s, int64_t *acc, int32_t *avg, uint16_t N)
{
    s->N = N;
    s->idx = 0;
    s->K = 0;
    s->acc = acc;
    s->avg = avg;

    memset(s->acc, 0, (size_t)N * sizeof(int64_t));
    memset(s->avg, 0, (size_t)N * sizeof(int32_t));
}

/**
 * @brief Deve ser chamado quando ocorre o "marcador" de início de período (ex.: zero-cross ou índice do encoder).
 *        Isso força alinhamento de fase.
 */
static inline void syncavg_period_reset(SyncAvg *s)
{
    s->idx = 0;
}

/**
 * @brief Alimenta a média sincronizada com uma amostra do ADC já alinhada ao relógio de amostragem.
 * @param s Estrutura.
 * @param x Amostra (ex.: ADC já convertido para int32).
 *
 * Funcionamento:
 *  - A cada amostra, acumula na posição idx.
 *  - Ao completar N amostras, fecha um período e atualiza avg[].
 *  - A referência de fase vem de syncavg_period_reset() (externa).
 */
static inline void syncavg_push_sample(SyncAvg *s, int32_t x)
{
    s->acc[s->idx] += (int64_t)x;
    s->idx++;

    if (s->idx >= s->N) {
        s->idx = 0;
        s->K++;

        // Atualiza a média inteira por posição (custo O(N) por período).
        // Se N for grande e seu MCU for apertado, dá para atualizar de forma incremental.
        for (uint16_t i = 0; i < s->N; i++) {
            s->avg[i] = (int32_t)(s->acc[i] / (int64_t)s->K);
        }
    }
}

Melhores usos da média sincronizada: quando existe um evento/clock de referência que define o período do fenômeno e você quer extrair o comportamento repetitivo com máxima imunidade a ruído. Isso aparece em análise vibroacústica sincronizada com rotação (encoder), em medição de ripple sincronizada com PWM, em leitura de sinais biomédicos quando há marcador, e em sistemas de potência quando você quer “ver” a forma média ao longo de ciclos de rede sem ser enganado por ruído ou eventos transientes fora de fase.

3) Exemplo prático combinando os dois: remover hum e depois reforçar a forma repetitiva

Em pipeline real, é comum usar notch primeiro para derrubar uma interferência tonal forte e, em seguida, média sincronizada para aumentar SNR do que restou (principalmente se o sinal útil é repetitivo e você tem referência). A ordem pode inverter dependendo do caso: se a interferência também for coerente com o mesmo período, a média pode reforçá-la, então o notch antes costuma ser mais seguro.

Abaixo, um esqueleto de uso. Imagine ADC a 4 kHz, hum em 60 Hz, e você quer fazer média sincronizada por ciclo de 60 Hz usando zero-cross (logo \(N \approx 4000/60 \approx 66\) amostras por ciclo; na prática você ajusta para manter N inteiro e usar PLL/medição de período se a rede variar).

#include <stdio.h>

// Reaproveita NotchBiquad e SyncAvg já definidos acima.

#define FS_HZ        4000.0f
#define NOTCH_F0_HZ  60.0f
#define NOTCH_Q      25.0f

#define N_SAMPLES_PER_PERIOD  66  // exemplo (depende do seu sincronismo real)

static int64_t acc_buf[N_SAMPLES_PER_PERIOD];
static int32_t avg_buf[N_SAMPLES_PER_PERIOD];

int main(void)
{
    NotchBiquad notch;
    notch_init(&notch, FS_HZ, NOTCH_F0_HZ, NOTCH_Q);

    SyncAvg s;
    syncavg_init(&s, acc_buf, avg_buf, N_SAMPLES_PER_PERIOD);

    // Exemplo: loop de aquisição (mock)
    for (int n = 0; n < 20000; n++) {
        // Em firmware real: x_raw vem do ADC (DMA buffer), e zero-cross chama syncavg_period_reset(&s)
        int32_t x_raw = (int32_t)(1000 * sinf(2.0f * (float)M_PI * 10.0f * (n / FS_HZ))); // sinal útil 10 Hz
        x_raw += (int32_t)(300 * sinf(2.0f * (float)M_PI * 60.0f * (n / FS_HZ)));        // hum 60 Hz

        // Notch (float) -> converte de volta para int32
        float y_notch = notch_process(&notch, (float)x_raw);
        int32_t y = (int32_t)y_notch;

        // Evento externo de sincronismo: aqui é só demonstração (a cada N amostras)
        if ((n % N_SAMPLES_PER_PERIOD) == 0) {
            syncavg_period_reset(&s);
        }

        // Média sincronizada
        syncavg_push_sample(&s, y);

        // Quando s.K aumenta, avg_buf contém a forma média por período
        if (s.K > 0 && (n % (N_SAMPLES_PER_PERIOD * 20)) == 0) {
            printf("K=%lu, avg[0]=%ld, avg[10]=%ld\n",
                   (unsigned long)s.K, (long)avg_buf[0], (long)avg_buf[10]);
        }
    }

    return 0;
}

#include <stdio.h>

// Reaproveita NotchBiquad e SyncAvg já definidos acima.

#define FS_HZ        4000.0f
#define NOTCH_F0_HZ  60.0f
#define NOTCH_Q      25.0f

#define N_SAMPLES_PER_PERIOD  66  // exemplo (depende do seu sincronismo real)

static int64_t acc_buf[N_SAMPLES_PER_PERIOD];
static int32_t avg_buf[N_SAMPLES_PER_PERIOD];

int main(void)
{
    NotchBiquad notch;
    notch_init(¬ch, FS_HZ, NOTCH_F0_HZ, NOTCH_Q);

    SyncAvg s;
    syncavg_init(&s, acc_buf, avg_buf, N_SAMPLES_PER_PERIOD);

    // Exemplo: loop de aquisição (mock)
    for (int n = 0; n < 20000; n++) {
        // Em firmware real: x_raw vem do ADC (DMA buffer), e zero-cross chama syncavg_period_reset(&s)
        int32_t x_raw = (int32_t)(1000 * sinf(2.0f * (float)M_PI * 10.0f * (n / FS_HZ))); // sinal útil 10 Hz
        x_raw += (int32_t)(300 * sinf(2.0f * (float)M_PI * 60.0f * (n / FS_HZ)));        // hum 60 Hz

        // Notch (float) -> converte de volta para int32
        float y_notch = notch_process(¬ch, (float)x_raw);
        int32_t y = (int32_t)y_notch;

        // Evento externo de sincronismo: aqui é só demonstração (a cada N amostras)
        if ((n % N_SAMPLES_PER_PERIOD) == 0) {
            syncavg_period_reset(&s);
        }

        // Média sincronizada
        syncavg_push_sample(&s, y);

        // Quando s.K aumenta, avg_buf contém a forma média por período
        if (s.K > 0 && (n % (N_SAMPLES_PER_PERIOD * 20)) == 0) {
            printf("K=%lu, avg[0]=%ld, avg[10]=%ld\n",
                   (unsigned long)s.K, (long)avg_buf[0], (long)avg_buf[10]);
        }
    }

    return 0;
}

Fechando a ideia: o notch discreto e a média sincronizada resolvem problemas parecidos (melhorar a qualidade do sinal), mas por “mecanismos” bem diferentes, e isso muda totalmente quando cada um é a melhor escolha. O notch é a ferramenta certa quando você conhece uma frequência indesejada bem definida e relativamente estável e quer arrancá-la do sinal com o mínimo de impacto no restante do espectro. Em firmware, isso costuma ser “hum” de 50/60 Hz, tons de chaveamento, ou uma ressonância estreita que aparece como pico bem localizado. O ponto crítico é que o notch é tão bom quanto a precisão do seu (f_0) e a escolha de (Q): se a interferência varia de frequência, um notch muito estreito deixa passar; se você alarga demais, começa a “machucar” conteúdo útil perto de (f_0). Além disso, como é um IIR, você precisa cuidar de estabilidade numérica e do formato de implementação (a forma direta II transposta tende a ser mais robusta em ponto flutuante e também costuma ser a melhor porta de entrada para depois migrar para ponto fixo).

Já a média sincronizada não é “um filtro de frequência” no sentido clássico; ela é uma técnica de extração por coerência: tudo que está alinhado com o período de referência fica mais forte, e o que não está alinhado tende a desaparecer. Por isso ela é superior quando o sinal útil é repetitivo e você tem um marcador de fase confiável, como encoder em máquina rotativa, o próprio PWM em conversores/inversores, ou zero-cross da rede. O ganho prático é enorme porque ela aumenta SNR sem precisar “inventar” um modelo espectral do ruído, mas ela também tem uma fragilidade: se o sincronismo for ruim (jitter, período variável, marcador inconsistente) a média “borrará” a forma de onda e pode até criar artefatos que parecem sinal real. Em projetos de rede elétrica, por exemplo, se você fixa (N) como “amostras por ciclo” sem acompanhar a variação real da frequência, a média começa a perder fase ao longo dos ciclos; nesse caso, ou você mede o período e ajusta (N) dinamicamente, ou você reamostra o ciclo para um grid fixo antes de acumular.

Na prática, em pipeline embarcado, uma combinação muito comum é usar notch primeiro para remover uma interferência tonal forte e depois usar média sincronizada para revelar a forma repetitiva de interesse com ruído bem mais baixo. Isso funciona especialmente bem quando a interferência não é coerente com o período que você está usando para sincronizar; se for coerente, a média pode reforçar a interferência, e aí o notch vira praticamente obrigatório antes. Se o seu sistema estiver no limite de CPU, o notch custa um número fixo e pequeno de multiplicações por amostra, enquanto a média sincronizada pode custar pouco por amostra mas “cobra” um custo por período quando você atualiza a forma média; dá para manter determinismo atualizando médias de forma incremental, ou reduzindo taxa, ou usando buffers e processamento em tarefa de menor prioridade.

The post Filtro notch discreto (notch IIR) e média sincronizada (sync averaging) first appeared on MCU & FPGA.

• Filtragem Digital, Cepstrum e Detecção Acústica em MCU
• Detecção de Assobio Humano com o Algoritmo de Goertzel no RP2040

1. Introdução — Por que combinar Goertzel com aprendizado estatístico?

Nos dois artigos anteriores desta série, exploramos duas estratégias clássicas e complementares de processamento digital de sinais em microcontroladores:

1. Séries de Taylor + Cepstrum → análise estrutural e harmônica do sinal
2. Algoritmo de Goertzel → detecção espectral dirigida e altamente eficiente

Ambas funcionam muito bem, mas compartilham uma característica importante:
a decisão final é baseada em limiares fixos.

Neste terceiro artigo, damos um passo conceitual além, mantendo o Goertzel como extrator de características espectrais, mas substituindo o decisor rígido por um modelo de aprendizado estatístico leve, adequado a MCUs como o RP2040.

O objetivo não é “colocar inteligência artificial por marketing”, mas sim responder a um problema real:

Como tornar a detecção mais robusta quando o ambiente muda, o usuário muda ou o ruído não é previsível?

1.1 O papel do Goertzel nesta nova arquitetura

É importante deixar claro desde o início:

• Goertzel não será substituído
• Não vamos rodar FFT gigante
• Não vamos usar redes neurais profundas
• Goertzel continua sendo o sensor espectral

Nesta arquitetura, o Goertzel atua como um extrator determinístico de características (features):

• Energia na frequência fundamental
• Relação entre harmônicos
• Estabilidade espectral ao longo do tempo

Esses valores passam a ser dados de entrada para um bloco estatístico que decide se o padrão observado se parece ou não com um assobio humano real.

1.2 O que entendemos aqui por “aprendizado estatístico”

Neste artigo, aprendizado estatístico não significa deep learning.

Vamos trabalhar com modelos:

• Interpretáveis
• Leves
• Computacionalmente previsíveis
• Treináveis com poucos dados

Exemplos que abordaremos ao longo do artigo:

• Média e variância adaptativas
• Distância estatística (z-score, Mahalanobis simplificada)
• Classificador linear simples
• Modelo incremental (online learning)

Tudo isso é:

• Executável em ponto flutuante simples
• Compatível com firmware bare-metal
• Determinístico em tempo real

1.3 Por que limiares fixos falham em campo

Nos artigos anteriores, usamos decisões do tipo:

• score > S_ON
• score < S_OFF

Isso funciona bem quando:

• O ambiente é estável
• O microfone é sempre o mesmo
• O usuário assobia sempre da mesma forma

Mas em campo real:

• Pessoas assobiam diferente
• Distância ao microfone muda
• Ruído de fundo varia
• Ganho analógico muda com temperatura e alimentação

Resultado:
limiar bom hoje, ruim amanhã.

O aprendizado estatístico resolve exatamente isso:

• Ele aprende o padrão típico
• Ele tolera variações naturais
• Ele se adapta lentamente ao ambiente

1.4 Visão geral da nova arquitetura

A nova cadeia de processamento será:

ADC
 └── DC-block
     └── Frame (256 amostras)
         └── Goertzel (fundamental + harmônicos)
             └── Vetor de características
                 └── Modelo estatístico adaptativo
                     └── Decisão (assobio / não assobio)
                         └── LED / evento

Comparando com o artigo anterior:

1.5 O que você terá ao final deste artigo

Ao final deste terceiro artigo da série, você terá:

• Um detector de assobio adaptativo
• Baseado em Goertzel + estatística
• Código 100% em C
• Executando em tempo real no RP2040
• Sem dependência de bibliotecas externas
• Com arquitetura reutilizável para:
  • Detecção de padrões acústicos
  • Sensores inteligentes
  • Interfaces por som
  • Pré-processamento para tinyML

Mais importante:
você entenderá como transformar DSP em dados e dados em decisão, de forma técnica.

The post Detecção de Assobio com Goertzel e Aprendizado Estatístico no RP2040 first appeared on MCU & FPGA.

Introdução

A escolha de um microcontrolador é uma das decisões mais críticas no desenvolvimento de sistemas embarcados, pois impacta diretamente o custo, o consumo de energia, a complexidade do firmware, a conectividade disponível e até mesmo a viabilidade do produto final. Nos últimos anos, o mercado passou a oferecer famílias extremamente distintas, que atendem desde projetos educacionais e protótipos rápidos até aplicações industriais, IoT em larga escala e dispositivos vestíveis de ultra-baixo consumo.

Neste artigo comparativo, analisamos cinco plataformas amplamente utilizadas — ESP32, STM32, Arduino (AVR), RP2040 e nRF52 — destacando suas arquiteturas, capacidades de processamento, conectividade, consumo energético e contextos de uso. O objetivo não é eleger um “melhor” microcontrolador, mas fornecer critérios técnicos claros para que o engenheiro ou desenvolvedor escolha a solução mais adequada ao seu projeto.

The post Comparativo Técnico de Microcontroladores: ESP32, STM32, Arduino, RP2040 e nRF52 first appeared on MCU & FPGA.

1. Introdução — Por que Goertzel?

No artigo anterior desta série, exploramos uma abordagem baseada em filtragem digital construída com Séries de Taylor, seguida pelo cálculo do cepstrum, para identificar a periodicidade característica de um assobio humano. Aquela estratégia privilegiou uma análise global do espectro, permitindo identificar a estrutura harmônica do sinal de forma robusta, mesmo em ambientes com ruído.

Neste novo artigo, damos continuidade direta a essa série, adotando uma estratégia complementar e mais enxuta: o algoritmo de Goertzel. Em vez de calcular todo o espectro via FFT, o Goertzel permite extrair seletivamente a energia de frequências específicas, tornando-o ideal para microcontroladores com recursos limitados — como o RP2040 — quando o interesse está restrito a faixas bem definidas.

O assobio humano típico apresenta uma frequência fundamental relativamente estável, geralmente entre 800 Hz e 3000 Hz, com harmônicos previsíveis. O algoritmo de Goertzel explora exatamente esse cenário:

“Eu sei qual frequência quero detectar — e só ela importa.”

1.1 Estratégia geral adotada neste artigo

A arquitetura de processamento deste artigo será:

1. Aquisição do sinal acústico (ADC do RP2040)
2. Pré-processamento simples (remoção de DC e normalização)
3. Aplicação do algoritmo de Goertzel para:
   • Frequência fundamental
   • Harmônicos selecionados
4. Construção de um critério de decisão espectral
5. Confirmação temporal (evitar falsos positivos)
6. Acionamento de um LED quando o assobio é detectado

Diferentemente do artigo anterior:

• Não calcularemos FFT
• Não calcularemos cepstrum
• Usaremos análise espectral pontual
• Menor uso de RAM e CPU
• Menor latência

Isso permite uma comparação clara entre duas filosofias de DSP embarcado:

• FFT + Cepstrum → análise estrutural
• Goertzel → análise dirigida por frequência

1.2 Quando Goertzel é a escolha correta (e quando não é)

Goertzel é uma excelente escolha quando:

• Você conhece as frequências de interesse
• O número de frequências é pequeno
• O MCU possui RAM limitada
• A latência precisa ser baixa
• O sistema é reativo (event-driven)

Goertzel NÃO é a melhor escolha quando:

• A frequência fundamental varia muito
• Você precisa analisar o espectro completo
• O sinal tem múltiplas fontes concorrentes
• A estrutura harmônica é desconhecida

Este artigo assume explicitamente o caso ideal para Goertzel:
detectar um fenômeno acústico específico e conhecido.

1.3 Relação direta com o artigo anterior

Este artigo não substitui o anterior — ele o complementa.

A ideia da série é exatamente essa: mostrar estratégias diferentes para o mesmo problema, permitindo ao engenheiro escolher conscientemente.

1.4 O que você terá ao final deste artigo

Ao final deste artigo, você terá:

• Um detector de assobio funcional
• Código 100% em C, portátil
• Execução em tempo real no RP2040
• Arquitetura reutilizável para:
  • DTMF
  • Tons de controle
  • Alarmes acústicos
  • Interfaces sonoras simples

The post Detecção de Assobio Humano com o Algoritmo de Goertzel no RP2040 first appeared on MCU & FPGA.

1 — Motivação, Visão Geral do Problema e Arquitetura da Solução

1.1 Motivação técnica

Assobios humanos possuem uma característica muito interessante do ponto de vista de processamento digital de sinais (DSP): eles apresentam uma frequência fundamental bem definida, normalmente entre 800 Hz e 3 kHz, acompanhada por harmônicas que decrescem em amplitude. Isso os torna excelentes candidatos para estudo de extração de pitch, separação espectral e detecção robusta de eventos acústicos em sistemas embarcados.

No contexto de microcontroladores como o RP2040, o desafio é duplo:

1. Executar algoritmos matematicamente consistentes com baixo custo computacional.
2. Evitar bibliotecas pesadas de DSP, favorecendo implementações determinísticas, explicáveis e portáveis.

Este artigo foi desenhado exatamente com esse espírito: mostrar que é possível construir um pipeline de detecção de assobio usando apenas matemática clássica, séries de Taylor e algoritmos fundamentais de DSP, sem FFTs complexas ou frameworks externos.

1.2 Problema a ser resolvido

O problema central pode ser descrito em três níveis:

1. Separação espectral
   O sinal do microfone contém:
   • Ruído ambiente
   • Voz humana
   • Sons impulsivos
   • O assobio propriamente dito
   Precisamos isolar a frequência fundamental do assobio e suas harmônicas.
2. Identificação confiável do assobio
   Apenas detectar energia em uma faixa de frequência não é suficiente, pois outros sons podem cair nessa banda.
   Precisamos identificar periodicidade — aqui entra o cepstrum, que trabalha no domínio da quefrência.
3. Ação física
   Após a detecção confiável:
   • Acender um LED quando um assobio é detectado
   • Apagar o LED quando o assobio desaparece

Tudo isso deve funcionar em tempo real, em um RP2040, usando a BitDogLab como plataforma de referência.

1.3 Arquitetura geral do sistema

O pipeline completo que iremos construir ao longo do artigo é o seguinte:

Microfone (ADC)
       ↓
Pré-processamento (remoção de DC)
       ↓
Filtro Digital por Séries de Taylor
(separação da fundamental e harmônicas)
       ↓
Cálculo do Cepstrum
(log + autocorrelação simplificada)
       ↓
Detecção de Pitch (assobio)
       ↓
Controle do LED (GPIO)

Microfone (ADC)
       ↓
Pré-processamento (remoção de DC)
       ↓
Filtro Digital por Séries de Taylor
(separação da fundamental e harmônicas)
       ↓
Cálculo do Cepstrum
(log + autocorrelação simplificada)
       ↓
Detecção de Pitch (assobio)
       ↓
Controle do LED (GPIO)

Cada bloco será implementado incrementalmente, de forma que:

• O código compile e funcione a cada etapa
• Possamos validar o comportamento do sistema progressivamente
• Ao final, teremos um firmware completo, funcional e didático

1.4 Por que Séries de Taylor em filtros digitais?

Normalmente, filtros digitais são apresentados como:

• IIR (Butterworth, Chebyshev, etc.)
• FIR por convolução
• FFT + máscara espectral

Aqui escolhemos Séries de Taylor por três razões estratégicas:

1. Controle matemático total
   Um filtro baseado em Taylor é, na prática, uma aproximação explícita de operadores diferenciais, o que permite entender exatamente o que está sendo implementado.
2. Eficiência em microcontroladores
   Séries truncadas resultam em:
   • Poucas multiplicações
   • Nenhuma função transcendental cara em tempo real
3. Valor didático elevado
   Esse método conecta:
   • Cálculo diferencial
   • Sistemas lineares
   • DSP clássico
     Em um único algoritmo executável em hardware real.

Mais adiante, mostraremos como aproximar respostas passa-faixa usando expansões de Taylor aplicadas a operadores discretos.

1.5 O papel do Cepstrum na detecção do assobio

Mesmo após filtrar o sinal, ainda temos um problema:
harmônicas também são periódicas, e ruídos podem enganar um detector simples.

O cepstrum resolve isso explorando uma ideia elegante:

A periodicidade no domínio do tempo vira um pico no domínio da quefrência.

Em termos práticos:

• Um assobio gera um pico claro no cepstrum
• Voz humana tende a gerar padrões mais espalhados
• Ruído branco praticamente não gera picos estáveis

Isso torna o cepstrum extremamente robusto para identificar assobios reais, mesmo em ambientes ruidosos.

The post Filtro Digital com Séries de Taylor e Cepstrum para Detecção de Assobio em RP2040 first appeared on MCU & FPGA.

Neste contexto, o sistema de build CMake se torna uma ferramenta central. Apesar de sua aparência intimidadora para quem está começando, o CMake é uma ponte poderosa entre o código-fonte e o binário que rodará no seu dispositivo. Ele permite organizar dependências, configurar variáveis, compilar múltiplos arquivos e até mesmo lidar com diferentes toolchains de forma automatizada. E quando combinamos o CMake com o ecossistema do RP2040, especialmente com o Pico SDK, temos um ambiente robusto, escalável e flexível — desde projetos educacionais até aplicações industriais.

Por isso, este artigo tem como objetivo guiar o leitor iniciante passo a passo pela análise de um projeto real baseado no RP2040, explicando detalhadamente cada trecho do arquivo CMakeLists.txt e os scripts auxiliares que compõem a infraestrutura de build. Vamos abordar o papel de cada linha, o porquê das decisões adotadas, e quais boas práticas estão sendo aplicadas — além de sugerir melhorias e comparações com abordagens de outras plataformas.

Este não é apenas um guia técnico: é também um convite à compreensão. Ao final desta leitura, você não apenas será capaz de compilar um projeto com confiança, mas também entenderá por que cada etapa é importante. Assim, poderá adaptar seus projetos futuros com segurança e domínio técnico, explorando todo o potencial do RP2040.

Prepare seu editor de texto e acompanhe cada seção com atenção — pois cada linha que vamos explorar é um pequeno degrau em direção à maestria no desenvolvimento embarcado moderno.

Para este artigo foi usado os seguintes arquivos CMakeLists.txt:

• https://github.com/carlosdelfino/embarcatech_etapa_2_cap_2_Tarefa-Pr-tica-IOT-3/blob/main/rp2040_mqtt_server_example/CMakeLists.txt
• https://github.com/carlosdelfino/embarcatech_etapa_2_cap_2_Tarefa-Pr-tica-IOT-3/blob/main/rp2040_mqtt_client_example/CMakeLists.txt

1. Configuração Inicial do CMake: Definindo Versão e Padrões do Projeto

Logo no início do arquivo CMakeLists.txt, temos um trecho essencial para garantir a compatibilidade e padronização do ambiente de compilação. Veja abaixo:

cmake_minimum_required(VERSION 3.13)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

Explicação Didática

1. cmake_minimum_required(VERSION 3.13)
   Esta linha define a versão mínima do CMake exigida para processar corretamente este projeto. O valor 3.13 é uma escolha segura para projetos com RP2040, pois é compatível com as versões mais estáveis do SDK da Raspberry Pi e da extensão para VSCode. Se o desenvolvedor tentar compilar o projeto com uma versão mais antiga do CMake, ele receberá uma mensagem de erro clara, evitando comportamento indefinido ou suporte incompleto a recursos.
2. set(CMAKE_C_STANDARD 11)
   Define que o código C será compilado segundo o padrão C11, uma versão estável e moderna da linguagem C, que inclui melhorias importantes como atomics, static assertions e melhor suporte a multithreading.
3. set(CMAKE_CXX_STANDARD 17)
   Determina que, caso o projeto inclua arquivos em C++, eles devem seguir o padrão C++17. Este padrão oferece recursos como structured bindings, if constexpr, e std::optional, que podem ser úteis em aplicações mais complexas.
4. set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
   Esta opção gera o arquivo compile_commands.json, que descreve os comandos de compilação de cada fonte no projeto. Ele é extremamente útil para ferramentas externas como servidores de linguagem (LSPs), linters e analisadores estáticos, como o clangd.

Análise Crítica

• A escolha de C11 e C++17 é apropriada: garante modernidade sem sacrificar a compatibilidade com a maioria dos toolchains usados no mundo embarcado.
• A inclusão de CMAKE_EXPORT_COMPILE_COMMANDS mostra preocupação com a qualidade do desenvolvimento, pois favorece a integração com IDEs modernas e ferramentas de verificação de código.
• Poderia ser interessante tornar os padrões configuráveis via variável de cache (CACHE STRING), permitindo ao usuário customizar sem alterar diretamente o CMakeLists.txt.

Observações Didáticas

• Para iniciantes: Pense nesta seção como o “acordo inicial” entre você e o compilador. Aqui você diz: “vamos trabalhar com a linguagem C moderna, C++ moderno e quero um ambiente que me ajude a detectar erros logo no começo”.
• Boas práticas: Sempre explicite o padrão da linguagem em projetos embarcados. Evita surpresas e garante consistência entre diferentes ambientes de build.
• Dica extra: O compile_commands.json pode ser usado por ferramentas como o clang-tidy ou cppcheck para inspeções profundas do seu código.

2. Configuração da Extensão VSCode e Inclusão do SDK

Após definir os padrões iniciais de compilação, o projeto introduz uma etapa importante para integração com o ambiente de desenvolvimento e o SDK do RP2040. Veja o trecho a seguir:

# == DO NOT EDIT THE FOLLOWING LINES for the Raspberry Pi Pico VS Code Extension to work ==
if(WIN32)
    set(USERHOME $ENV{USERPROFILE})
else()
    set(USERHOME $ENV{HOME})
endif()
set(sdkVersion 2.1.1)
set(toolchainVersion 14_2_Rel1)
set(picotoolVersion 2.1.1)
set(picoVscode ${USERHOME}/.pico-sdk/cmake/pico-vscode.cmake)
if (EXISTS ${picoVscode})
    include(${picoVscode})
endif()
# ====================================================================================

Explicação Didática

1. Bloco condicional if(WIN32)…
   Aqui é verificado se o sistema operacional é Windows (WIN32). Se for, define a variável USERHOME como o caminho da variável de ambiente USERPROFILE. Caso contrário (Linux/macOS), usa HOME.
   Isso garante portabilidade do projeto entre sistemas operacionais, o que é essencial para ambientes colaborativos e didáticos.
2. set(sdkVersion ...), toolchainVersion ..., picotoolVersion ...)
   Essas linhas servem como metadados informativos que descrevem as versões usadas no ambiente de desenvolvimento. Embora não sejam diretamente utilizadas pelo CMake nesta etapa, são úteis para documentação, scripts externos ou para controle de consistência do ambiente de build.
3. set(picoVscode ...) e include(...)
   Essa etapa tenta localizar o arquivo pico-vscode.cmake, que é utilizado pela extensão oficial da Raspberry Pi no VSCode para configurar corretamente o ambiente.
   Se o arquivo existir, ele é incluído, permitindo que recursos como auto-complete, debug remoto, e templates automáticos funcionem adequadamente.

Análise Crítica

• O uso de EXISTS para checar a presença do arquivo evita erros e torna o projeto mais robusto.
• Esta seção é essencial para ambientes com suporte a IDEs modernas, mas pode ser omitida com segurança se o projeto for construído apenas via terminal.
• A presença dos comentários DO NOT EDIT é uma prática comum para marcar blocos sensíveis que são exigidos por ferramentas externas.

Observações Didáticas

• Para iniciantes: Essa parte pode parecer obscura à primeira vista, mas pense nela como a “ponte” entre o CMake e o seu editor (VSCode). Se ela estiver funcionando, você terá suporte a atalhos, intellisense e debug facilitado.
• Dica de compatibilidade: Quando você compartilha seu projeto com colegas usando Windows e você usa Linux (ou vice-versa), esse bloco ajuda a manter tudo funcionando sem dor de cabeça.
• Importante saber: Se o arquivo pico-vscode.cmake não estiver instalado, o build ainda funcionará — mas você perderá integração com o VSCode.

3. Parametrização por Ambiente: Importando o env.cmake

Este bloco mostra como carregar configurações externas e definir valores padrão para variáveis críticas de conexão, como Wi-Fi e MQTT. Veja o trecho abaixo:

if(EXISTS "${CMAKE_SOURCE_DIR}/env.cmake")
    include("${CMAKE_SOURCE_DIR}/env.cmake")
    message(STATUS "Arquivo env.cmake carregado com sucesso.")
else()
    message(FATAL_ERROR "Arquivo env.cmake não encontrado!")
endif()

Explicação Didática

1. if(EXISTS "${CMAKE_SOURCE_DIR}/env.cmake")
   Verifica se o arquivo env.cmake existe no diretório raiz do projeto. Essa verificação é crucial para não interromper o processo de configuração se o arquivo estiver ausente ou mal posicionado.
2. include(...)
   Se o arquivo existir, ele é carregado e suas variáveis passam a ser conhecidas no escopo do CMake. Isso permite separar a configuração sensível ou personalizada (como senhas e tópicos MQTT) do corpo principal do projeto.
3. message(STATUS "...") e message(FATAL_ERROR "...")
   Usadas para informar claramente ao usuário o sucesso ou falha dessa etapa. Um erro fatal é gerado se o env.cmake estiver ausente, forçando o desenvolvedor a corrigi-lo antes de prosseguir — uma forma de evitar builds incompletos ou configurações erradas.

A seguir, são aplicadas validações adicionais:

if(NOT DEFINED ENV{WIFI_SSID})
    message(WARNING "Variável WIFI_SSID não definida no .env.")
    set(ENV{WIFI_SSID} "ArvoreDosSaberes")
endif()
# ... outros blocos semelhantes para WIFI_PASSWORD, MQTT_BROKER, etc.

Explicação Didática

Cada bloco verifica se uma variável de ambiente essencial está definida (ENV{VARIAVEL}). Se não estiver, ele:

• Emite um aviso não fatal, alertando o usuário;
• Define um valor padrão razoável para que o build continue.

Ao final, todas as variáveis são capturadas explicitamente para o escopo interno do CMake:

set(WIFI_SSID "$ENV{WIFI_SSID}")
set(WIFI_PASSWORD "$ENV{WIFI_PASSWORD}")
set(MQTT_BROKER "$ENV{MQTT_BROKER}")
set(MQTT_BASE_TOPIC "$ENV{MQTT_BASE_TOPIC}")
set(MQTT_RACK_NUMBER "$ENV{MQTT_RACK_NUMBER}")

Análise Crítica

• O uso do env.cmake permite separar configuração de ambiente do código — uma excelente prática que segue os princípios da engenharia de software moderna.
• Fornecer valores padrão facilita testes e uso didático, mas o ideal seria mover os valores sensíveis (como senhas) para fora do controle de versão (usando, por exemplo, .gitignore).
• Poderia haver uma variável global ou opção no CMake para desativar temporariamente os erros fatais, facilitando builds rápidos durante o desenvolvimento.

Observações Didáticas

• Analogia simples: Pense no env.cmake como um “cartão de visita” que você entrega ao projeto, dizendo quem você é (SSID, senha, broker). Assim, ele sabe com quem falar e como se comportar.
• Organização é tudo: Ao manter essas variáveis fora do CMakeLists.txt, você pode trocar de rede ou broker sem reconfigurar o projeto inteiro — basta editar ou substituir o env.cmake.
• Cuidado comum: Não deixar o env.cmake com credenciais sensíveis visíveis em repositórios públicos. Para isso, use .gitignore.

4. Inicialização do SDK e Definição do Executável

Com todas as variáveis e configurações preparadas, o próximo passo é estruturar o projeto de forma que o SDK da Raspberry Pi Pico possa ser utilizado corretamente, e o firmware final seja construído como um executável nomeado. O trecho em destaque é o seguinte:

# Pull in Raspberry Pi Pico SDK (must be before project)
include(pico_sdk_import.cmake)

project(firmware_client_mqtt C CXX ASM)

# Initialise the Raspberry Pi Pico SDK
pico_sdk_init()

Explicação Didática

1. include(pico_sdk_import.cmake)
   Este comando inclui o script pico_sdk_import.cmake, normalmente localizado na raiz do SDK da Raspberry Pi. Ele é responsável por carregar as bibliotecas, drivers e configurações internas que fazem parte do Pico SDK.
   É essencial que esta linha venha antes do comando project(...), pois o SDK precisa estar carregado para que o CMake reconheça suas funções auxiliares como pico_sdk_init() ou pico_enable_stdio_usb().
2. project(firmware_client_mqtt C CXX ASM)
   Define oficialmente o nome do projeto, bem como os tipos de código que ele conterá:
   • C: código C (linguagem base do projeto);
   • CXX: suporte a C++, mesmo que opcional;
   • ASM: suporte à linguagem Assembly, caso você deseje manipular diretamente registradores ou realizar otimizações de baixo nível.
3. pico_sdk_init()
   Esta função é uma macro do Pico SDK que realiza a configuração padrão do ambiente, ativando funcionalidades como drivers de hardware (hardware_gpio, hardware_adc, etc.), bibliotecas utilitárias e integração com o sistema de build.

Em seguida, o projeto define o binário principal:

add_executable(firmware_client_mqtt
    firmware_client_mqtt.c
)

E depois configura nome e versão para fins de organização:

pico_set_program_name(firmware_client_mqtt "firmware_client_mqtt")
pico_set_program_version(firmware_client_mqtt "0.1")

Explicação Didática

4. add_executable(...)
   Esta linha define o arquivo principal a ser compilado, neste caso, firmware_client_mqtt.c. O nome dado ao executável será usado como base para gerar o binário .uf2 (formato de firmware usado pelo RP2040).
   Também é possível incluir múltiplos arquivos .c, .cpp ou .s (Assembly) se o projeto for modularizado.
5. pico_set_program_name e pico_set_program_version
   Estes comandos definem metadados do projeto, como nome e versão, que podem ser usados por ferramentas de depuração ou sistemas de versionamento. Embora opcionais, são úteis em ambientes colaborativos ou industriais.

Análise Crítica

• Esta seção está tecnicamente correta e bem estruturada, seguindo as recomendações do Pico SDK.
• O uso explícito de C, CXX e ASM torna o projeto mais versátil e pronto para escalar em complexidade.
• O nome do projeto (firmware_client_mqtt) é repetido em vários pontos. Poderia ser definido via uma variável (set(PROJECT_NAME firmware_client_mqtt)) para facilitar manutenção futura.

Observações Didáticas

• Analogia prática: Essa parte é como “ligar a tomada” do seu projeto. Você diz ao sistema: “meu projeto se chama X, usa essas linguagens, e quero usar as bibliotecas do SDK da Raspberry Pi”.
• Dica extra: Ao compilar, o CMake vai gerar automaticamente arquivos .elf, .bin e .uf2, prontos para serem gravados na flash do RP2040.
• Boas práticas: Sempre modularize seu código desde o começo. Mesmo que só tenha um arquivo .c, mantenha espaço para crescer (ex: src/, include/).

5. Ativando Entradas/Saídas e Ligando Bibliotecas Essenciais

Depois de declarar o executável e configurar seu nome e versão, o projeto define como o firmware irá se comunicar com o mundo externo — por portas seriais ou USB — e quais bibliotecas devem ser incluídas na hora da linkagem. Veja o trecho:

pico_enable_stdio_uart(firmware_client_mqtt 0)
pico_enable_stdio_usb(firmware_client_mqtt 1)

Explicação Didática

1. pico_enable_stdio_uart(<target> <boolean>)
   Define se a UART (porta serial física) será usada como saída padrão (stdout) do programa. No exemplo acima, o valor 0 desativa a UART. Isso pode ser útil se o projeto não utilizar os pinos GPIO dedicados à UART, ou se estiver usando USB para comunicação com o PC.
2. pico_enable_stdio_usb(<target> <boolean>)
   Ativa a comunicação serial via USB virtual (CDC). Com 1, o firmware pode imprimir mensagens no terminal conectado via cabo USB — muito útil para debug com ferramentas como minicom, PuTTY, Thonny ou o console do VSCode.

Em seguida, são declaradas as bibliotecas necessárias à aplicação:

target_link_libraries(firmware_client_mqtt
    pico_stdlib
    pico_cyw43_arch_lwip_threadsafe_background
    pico_lwip_mqtt
)

Explicação Didática

3. target_link_libraries(...)
   Essa linha especifica quais bibliotecas serão ligadas (linkadas) ao firmware durante a compilação.
   • pico_stdlib: a biblioteca padrão do SDK, que fornece funções básicas como printf, controle de pinos, delays, etc.
   • pico_cyw43_arch_lwip_threadsafe_background: fornece acesso ao chip Wi-Fi CYW43 (usado no RP2040 W) em modo cooperativo com a pilha TCP/IP lwIP.
   • pico_lwip_mqtt: adiciona suporte ao protocolo MQTT com base na biblioteca lwIP, permitindo que o firmware se comunique com brokers MQTT como o Mosquitto, HiveMQ, etc.

Análise Crítica

• Desativar UART e ativar apenas USB (como neste projeto) é uma escolha moderna e prática, já que a maioria dos computadores não possui porta serial física.
• O uso de pico_lwip_mqtt demonstra um foco em conectividade IoT. Esta biblioteca ainda é pouco documentada fora dos exemplos oficiais, então usar os exemplos do SDK como base é uma boa prática.
• Poderia ser interessante encapsular as bibliotecas adicionais em uma função auxiliar (add_custom_dependencies()), principalmente em projetos maiores.

Observações Didáticas

• Para iniciantes: Pense na UART e na USB como “canais de conversa” entre o RP2040 e o mundo externo. Você pode escolher usar um, ambos, ou nenhum.
• Boas práticas: Se for usar UART, lembre-se de configurar os pinos no firmware (gpio_set_function(...)). Se usar USB, não esqueça que a comunicação começa após a USB ser enumerada pelo host — o que leva alguns milissegundos após reset.
• Importante saber: A biblioteca pico_cyw43_arch_lwip_threadsafe_background executa tarefas de rede em segundo plano, sem precisar de um RTOS. Ideal para projetos simples mas que precisam de conectividade Wi-Fi confiável.

6. Inclusão de Diretórios e Definição de Macros de Conexão

Com a estrutura principal pronta e as bibliotecas já ligadas, o projeto agora configura o acesso aos diretórios de cabeçalhos e exporta as variáveis de ambiente para uso direto no código C:

target_include_directories(firmware_client_mqtt PRIVATE ${CMAKE_CURRENT_LIST_DIR})

Explicação Didática

1. target_include_directories(...)
   Especifica para o compilador onde ele deve procurar os arquivos .h durante a compilação.
   • firmware_client_mqtt: é o alvo (o executável).
   • PRIVATE: significa que esses diretórios são usados apenas internamente para este alvo (e não propagados a outras dependências).
   • ${CMAKE_CURRENT_LIST_DIR}: refere-se ao diretório atual onde está o CMakeLists.txt. Isso permite que o main.c e outros arquivos no mesmo diretório acessem os headers locais diretamente.

Agora, as variáveis de ambiente definidas anteriormente são “injetadas” no código-fonte como macros com #define, utilizando o comando:

target_compile_definitions(firmware_client_mqtt PRIVATE 
    WIFI_SSID=\"${WIFI_SSID}\" 
    WIFI_PASSWORD=\"${WIFI_PASSWORD}\" 
    MQTT_BROKER=\"${MQTT_BROKER}\" 
    MQTT_BASE_TOPIC=\"${MQTT_BASE_TOPIC}\"
    MQTT_RACK_NUMBER=\"${MQTT_RACK_NUMBER}\"
)

Explicação Didática

2. target_compile_definitions(...)
   Insere macros de pré-processador no projeto. Na prática, é como se o CMake escrevesse automaticamente estas linhas no seu código: #define WIFI_SSID "ArvoreDosSaberes" #define WIFI_PASSWORD "Arduino2022" #define MQTT_BROKER "mqtt.rapport.tec.br" #define MQTT_BASE_TOPIC "rack_inteligente" #define MQTT_RACK_NUMBER "3" Isso permite que o código-fonte seja genérico e portátil, pegando os dados do ambiente e não de strings fixas.

Análise Crítica

• O uso de target_compile_definitions é altamente recomendável, pois centraliza a configuração no CMake em vez de espalhar definições pelo código-fonte.
• A sintaxe de escape com \"...\" garante que as strings sejam corretamente interpretadas como literais no código C. Uma falha comum de iniciantes é esquecer essas aspas.
• Em projetos maiores, pode-se usar arquivos .h autogerados a partir do CMake para organizar essas definições (ex: config.h.in com configure_file()).

Observações Didáticas

• Para iniciantes: Pense que você está mandando um bilhete do CMake para o seu código C. Esse bilhete diz: “ei, aqui está o nome da sua rede Wi-Fi e os dados do MQTT”.
• Erros comuns: Se você esquecer de escapar as aspas (\"), o compilador vai entender errado a definição e gerar erros como “expected identifier”.
• Boas práticas: Nunca inclua senhas reais ou dados sensíveis diretamente no main.c. Use sempre esse método de parametrização, ou proteja via arquivos ignorados no Git.

7. Geração dos Arquivos de Saída: pico_add_extra_outputs

No final do arquivo, encontramos a seguinte linha:

pico_add_extra_outputs(firmware_client_mqtt)

Explicação Didática

Este comando é uma macro fornecida pelo Pico SDK que automatiza a criação de diferentes formatos de saída do firmware. A partir do executável gerado (firmware_client_mqtt.elf), ela cuida de produzir também:

• firmware_client_mqtt.bin: imagem binária “crua”, usada em alguns programadores.
• firmware_client_mqtt.uf2: formato específico do RP2040, utilizado para arrastar e soltar o firmware diretamente na unidade USB visível quando o RP2040 está em modo de bootloader.
• Arquivos .map, .hex, .dis ou .lst também podem ser gerados, dependendo das opções do CMake.

Tudo isso acontece de forma automática, dispensando a escrita manual de comandos extras.

Análise Crítica

• O uso de pico_add_extra_outputs é obrigatório em projetos com RP2040 se você quiser gerar arquivos .uf2, que são os mais práticos para upload via USB.
• Essa macro também facilita o debug, já que o .elf gerado pode ser carregado diretamente por ferramentas como GDB, OpenOCD ou o depurador do VSCode.
• Poderia ser complementada com scripts de pós-build para, por exemplo, copiar o .uf2 para um diretório específico ou ativar gravação automática via picotool.

Observações Didáticas

• Para iniciantes: Essa etapa é como pedir ao compilador: “não me dê só o resultado final, me dê também outras versões do programa — uma para o bootloader, outra para depurar, outra para backup”.
• Boas práticas: Após cada build, confira a pasta build/ — os arquivos .uf2, .elf e .bin estarão lá. O .uf2 é o que você deve arrastar e soltar no RP2040 quando ele estiver em modo boot (pressionando o botão BOOTSEL).
• Dica de produtividade: Se você estiver usando VSCode com a extensão oficial, essa macro garante que o botão “Build” funcione corretamente e gere o .uf2 automaticamente.

Finalização da Análise Técnica

Com essa última linha, fechamos a análise completa e detalhada do arquivo CMakeLists.txt. Todas as etapas — desde configuração básica, carregamento do SDK, definição do executável, inclusão de bibliotecas, parâmetros de ambiente até a geração dos arquivos finais — foram explicadas com clareza e espírito didático.

Perfeito! Vamos então à conclusão geral do artigo, amarrando todo o conteúdo de forma coesa e didática.

Conclusão

Ao longo deste artigo, percorremos — linha por linha — a estrutura de um CMakeLists.txt real utilizado em um projeto baseado no microcontrolador RP2040, com foco em conectividade Wi-Fi e MQTT. O objetivo foi mais do que explicar comandos: buscamos desenvolver no leitor a compreensão do porquê de cada configuração, tornando-o capaz de analisar, adaptar e evoluir seus próprios projetos.

Iniciamos com a definição dos padrões de compilação e seguimos pela configuração do ambiente de desenvolvimento, mostrando como tornar o projeto compatível com ferramentas modernas como o VSCode. Depois, vimos como separar parâmetros de configuração em arquivos auxiliares (env.cmake) e como capturar variáveis de ambiente de forma segura e elegante. Em seguida, exploramos a inicialização do SDK, a declaração do executável, a ativação dos canais de comunicação via USB e UART, a ligação com bibliotecas críticas como pico_lwip_mqtt, e, por fim, a geração dos arquivos .uf2 e .elf prontos para gravação.

Além do conteúdo técnico, discutimos boas práticas como:

• Separar configuração do código-fonte com env.cmake;
• Utilizar target_compile_definitions para injetar parâmetros no pré-processador;
• Escapar corretamente strings definidas no CMake;
• Manter o projeto modular e escalável com target_include_directories e target_link_libraries;
• Evitar hardcoding de dados sensíveis e trabalhar com variáveis de ambiente.

Esse conhecimento é fundamental para qualquer desenvolvedor embarcado que deseje usar o RP2040 de forma profissional e segura. A compreensão profunda da infraestrutura de build é o que separa um programador iniciante de um desenvolvedor capaz de integrar sistemas complexos, automatizar tarefas, e resolver problemas de forma elegante.

Próximos Passos

Se você chegou até aqui, parabéns! Seu próximo passo pode ser:

• Explorar o conteúdo do arquivo env.cmake em detalhes;
• Modularizar seu projeto criando subdiretórios como src/ e include/;
• Automatizar tarefas de pós-build, como upload via picotool;
• Adicionar testes unitários usando CMocka ou Unity em conjunto com CMake;
• Criar templates de projetos reutilizáveis com base nessa estrutura.

Indicações de Leitura Complementar

• Documentação oficial do Pico SDK
• Tutorial CMake da JetBrains
• CMake para Embedded (platformIO-style)

The post Como Estruturar um Projeto Profissional com CMake para o RP2040: Guia Didático Passo a Passo first appeared on MCU & FPGA.