Em firmware industrial e IoT de produção, o problema raramente é “como ler um sensor” ou “como reagir a uma interrupção”. O desafio real está em como transformar eventos assíncronos e imprevisíveis (interrupções de hardware, timeouts, pacotes de rede, watchdogs) em fluxos determinísticos, observáveis e recuperáveis — sem violar latência, sem bloquear ISRs, sem explodir prioridade e sem criar acoplamentos frágeis entre camadas.

O Zephyr RTOS se destaca exatamente por oferecer primitivas complementares — Interrupções, Soft Timers (k_timer) e Workqueues (k_work) — que, quando combinadas corretamente, permitem desenhar pipelines de eventos robustos, usados em produtos reais: gateways industriais, sensores remotos, equipamentos médicos, automação predial e dispositivos conectados operando por anos no campo.

Este artigo não trata essas primitivas de forma isolada. O foco é arquitetural:
como compor essas ferramentas para criar fluxos de processamento desacoplados, previsíveis e testáveis, respeitando as regras fundamentais de sistemas embarcados modernos:

• ISR mínima: interrupção apenas sinaliza, nunca processa.
• Tempo como evento: temporização explícita, não “sleep espalhado”.
• Processamento fora de ISR: trabalho pesado sempre em contexto de thread.
• Backpressure e ordenação: eventos fluem por etapas bem definidas.
• Escalabilidade: o desenho deve sobreviver ao crescimento do sistema.

Ao longo das próximas seções, vamos evoluir de um modelo mental até códigos concretos em C, mostrando:

1. O papel correto de Interrupções no Zephyr.
2. Como Soft Timers viram fontes de eventos temporais confiáveis.
3. Como Workqueues funcionam como estágios de processamento.
4. Como integrar tudo isso em pipelines de eventos industriais, com exemplos reais de firmware.

A ideia é que, ao final, você não apenas “saiba usar” essas APIs, mas consiga enxergar a arquitetura por trás de um firmware profissional — aquele que não depende de sorte, nem de atrasos mágicos, nem de lógica escondida em ISR.

The post Zephyr e Integração Avançada: Interrupções + Soft Timers + Workqueues first appeared on MCU & FPGA.

Frase-chave foco

1 – Introdução: o papel de Interrupções e Soft Timers em um RTOS moderno

Em sistemas embarcados modernos, especialmente aqueles baseados em um RTOS (Real-Time Operating System) como o Zephyr OS, a forma como lidamos com eventos assíncronos define diretamente a robustez, a previsibilidade temporal e a escalabilidade do firmware. Dois mecanismos são absolutamente centrais nesse contexto: interrupções de hardware e soft timers. Embora ambos sejam usados para reagir a eventos no tempo ou no mundo físico, eles possuem naturezas, custos e implicações arquiteturais bastante distintas.

As interrupções permitem que o hardware “interrompa” a execução normal da CPU para tratar eventos críticos e de baixa latência, como mudanças em GPIOs, chegada de dados em periféricos ou estouros de contadores. Já os soft timers do Zephyr são abstrações de alto nível baseadas no kernel, que permitem executar callbacks temporizados sem recorrer a timers de hardware dedicados ou lógica de polling. Essa separação clara entre o que é tempo crítico e o que é tempo gerenciado pelo kernel é uma das grandes virtudes do Zephyr.

Um erro comum de quem vem de arquiteturas bare-metal ou de RTOS mais simples é tentar resolver tudo com interrupções. No Zephyr, isso é um anti-padrão arquitetural. O sistema foi projetado para que interrupções sejam curtas, determinísticas e não bloqueantes, delegando o processamento mais pesado para threads, workqueues ou timers. Entender essa filosofia é essencial para escrever firmware escalável e seguro.

Ao longo deste artigo, vamos explorar:

• Como o Zephyr trata interrupções de forma portável e segura
• Como configurar e usar ISRs (Interrupt Service Routines) corretamente
• Como funcionam os Soft Timers (k_timer)
• Quando usar interrupção, timer ou thread
• Padrões e armadilhas comuns em projetos reais

Sempre com exemplos em C, comentados e aplicáveis a placas reais como STM32, nRF e RP2040.

2 – Modelo de Interrupções no Zephyr: conceitos fundamentais

Antes de escrever qualquer ISR no Zephyr, é fundamental entender que o sistema adota um modelo de interrupções abstraído, desacoplado do hardware específico, mas ainda permitindo acesso direto quando necessário. O Zephyr se apoia em três pilares principais:

1. Árvore de dispositivos (Devicetree)
2. API genérica de IRQ do kernel
3. Separação rígida entre contexto de interrupção e contexto de thread

No Zephyr, interrupções não são configuradas diretamente em registradores no código da aplicação (como em bare-metal). Em vez disso, elas são declaradas e conectadas por meio do Devicetree, que descreve o hardware de forma declarativa. Isso permite que o mesmo código rode, sem modificações, em arquiteturas distintas.

O que é uma ISR no Zephyr?

Uma ISR (Interrupt Service Routine) no Zephyr é uma função C comum, mas com restrições severas:

• Não pode bloquear
• Não pode usar k_sleep()
• Não pode alocar memória dinâmica
• Não pode chamar APIs que dependem do escalonador

Ela deve apenas:

• Reconhecer o evento
• Capturar dados mínimos
• Sinalizar uma thread, timer ou workqueue

Esse modelo força uma arquitetura mais limpa e previsível.

3 – Conectando uma interrupção no Zephyr (exemplo com GPIO)

Vamos começar com um exemplo clássico: interrupção por mudança de nível em um pino GPIO, algo extremamente comum em botões, sensores e sinais externos.

Passo 1 – Definição no Devicetree (conceito)

O Zephyr já fornece nós de GPIO prontos no Devicetree. Em geral, você não precisa criar nada manualmente, apenas referenciar o pino correto.

Exemplo conceitual (simplificado):

button0: button_0 {
    gpios = <&gpioa 0 GPIO_ACTIVE_LOW>;
};

button0: button_0 {
    gpios = <&gpioa 0 GPIO_ACTIVE_LOW>;
};

Passo 2 – Estrutura de callback de GPIO

No Zephyr, interrupções de GPIO usam a estrutura gpio_callback.

#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

/* Callback associado à interrupção */
static struct gpio_callback button_cb_data;

#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

/* Callback associado à interrupção */
static struct gpio_callback button_cb_data;

Passo 3 – Implementação da ISR

A função de callback será executada em contexto de interrupção:

void button_pressed_isr(const struct device *dev,
                        struct gpio_callback *cb,
                        uint32_t pins)
{
    ARG_UNUSED(dev);
    ARG_UNUSED(cb);
    ARG_UNUSED(pins);

    /* ISR deve ser curta e não bloqueante */
    printk("Botão pressionado!\n");
}

void button_pressed_isr(const struct device *dev,
                        struct gpio_callback *cb,
                        uint32_t pins)
{
    ARG_UNUSED(dev);
    ARG_UNUSED(cb);
    ARG_UNUSED(pins);

    /* ISR deve ser curta e não bloqueante */
    printk("Botão pressionado!\n");
}

Observação importante:
Mesmo o printk() não é ideal dentro de ISR em sistemas críticos. Ele é usado aqui apenas para fins didáticos. Em projetos reais, o correto é sinalizar uma thread.

Passo 4 – Configuração do GPIO e da interrupção

const struct device *button_dev;

button_dev = DEVICE_DT_GET(DT_NODELABEL(gpioa));

gpio_pin_configure(button_dev, 0, GPIO_INPUT | GPIO_PULL_UP);

gpio_pin_interrupt_configure(button_dev,
                              0,
                              GPIO_INT_EDGE_FALLING);

gpio_init_callback(&button_cb_data,
                   button_pressed_isr,
                   BIT(0));

gpio_add_callback(button_dev, &button_cb_data);

const struct device *button_dev;

button_dev = DEVICE_DT_GET(DT_NODELABEL(gpioa));

gpio_pin_configure(button_dev, 0, GPIO_INPUT | GPIO_PULL_UP);

gpio_pin_interrupt_configure(button_dev,
                              0,
                              GPIO_INT_EDGE_FALLING);

gpio_init_callback(&button_cb_data,
                   button_pressed_isr,
                   BIT(0));

gpio_add_callback(button_dev, &button_cb_data);

Neste ponto:

• O hardware gera a interrupção
• O driver de GPIO chama a ISR
• O kernel garante isolamento e segurança

4 – Arquitetura correta: ISR + sinalização de thread

A forma correta de usar interrupções no Zephyr é acordar ou sinalizar uma thread, e não executar lógica pesada na ISR.

Exemplo usando semaforos:

K_SEM_DEFINE(button_sem, 0, 1);

void button_pressed_isr(const struct device *dev,
                        struct gpio_callback *cb,
                        uint32_t pins)
{
    k_sem_give(&button_sem);
}

K_SEM_DEFINE(button_sem, 0, 1);

void button_pressed_isr(const struct device *dev,
                        struct gpio_callback *cb,
                        uint32_t pins)
{
    k_sem_give(&button_sem);
}

Thread associada:

void button_thread(void)
{
    while (1) {
        k_sem_take(&button_sem, K_FOREVER);
        printk("Evento tratado em thread\n");
    }
}

void button_thread(void)
{
    while (1) {
        k_sem_take(&button_sem, K_FOREVER);
        printk("Evento tratado em thread\n");
    }
}

Essa arquitetura:

• Mantém ISRs determinísticas
• Evita jitter
• Escala melhor com múltiplos eventos

The post Interrupções e Soft Timers no Zephyr OS first appeared on MCU & FPGA.

1. Introdução: por que usar Zephyr no Arduino DUE

O Zephyr Project é um sistema operacional de tempo real (RTOS – Real-Time Operating System) moderno, modular e altamente configurável, projetado para sistemas embarcados que exigem previsibilidade temporal, portabilidade e escalabilidade. Diferente do ecossistema Arduino tradicional — baseado em superloop e bibliotecas monolíticas — o Zephyr oferece um modelo arquitetural profissional, alinhado a práticas industriais, como device tree, Kconfig, CMake e um kernel preemptivo completo.

O Arduino DUE ocupa um espaço interessante nesse contexto. Baseado no microcontrolador Atmel/Microchip SAM3X8E, um ARM Cortex-M3 de 32 bits operando a 84 MHz, ele oferece recursos raros no “mundo Arduino”: barramento externo, controlador DMA (Direct Memory Access), múltiplas UARTs, SPI, TWI (I²C – Inter-Integrated Circuit), além de USB nativo (USB OTG). Esses recursos fazem do DUE uma excelente plataforma didática para aprender Zephyr em um hardware amplamente conhecido.

Neste artigo, você aprenderá passo a passo, de forma minuciosa, como criar um projeto Zephyr totalmente funcional para o Arduino DUE, utilizando todos os recursos documentados oficialmente pela fundação Zephyr para essa placa. O foco não será apenas “compilar e rodar”, mas entender a arquitetura do projeto, as decisões de configuração e o papel de cada arquivo envolvido.

2. Visão geral do suporte do Zephyr ao Arduino DUE

Antes de escrever qualquer linha de código, é fundamental entender como o Zephyr enxerga o Arduino DUE. No Zephyr, placas não são tratadas como “kits genéricos”, mas como descrições formais de hardware, compostas por:

• Board Definition: define CPU, clock, memória e periféricos básicos
• Device Tree (DTS): descreve os dispositivos de hardware de forma declarativa
• Kconfig da placa: habilita ou restringe funcionalidades do kernel
• Arquivos de build: integram a placa ao sistema CMake do Zephyr

No caso do Arduino DUE, o Zephyr fornece oficialmente:

• Arquivo de board baseado no SAM3X8E
• Mapeamento correto de pinos compatível com o layout do DUE
• Suporte a:
  • GPIO (General Purpose Input/Output)
  • UART (console serial)
  • SPI
  • I²C (TWI no SAM)
  • Temporizadores e SysTick
• Programação via porta USB de programação (a mesma usada com o bossac)

Isso significa que não é necessário criar uma placa customizada para começar: o Arduino DUE já está plenamente integrado ao ecossistema Zephyr.

3. Pré-requisitos do ambiente de desenvolvimento

Antes de criar o projeto, o ambiente Zephyr precisa estar corretamente instalado. Assumiremos aqui que você já leu os artigos anteriores da série e possui:

• Linux (Ubuntu 22.04 ou superior recomendado)
• Python 3.10+
• west (ferramenta de meta-build do Zephyr)
• Zephyr SDK instalada
• Toolchain ARM embarcada funcional

Para validar rapidamente se o ambiente está correto, execute:

west --version

west --version

E depois:

west boards | grep due

west boards | grep due

Se o ambiente estiver correto, você verá a placa arduino_due listada entre as placas suportadas. Esse comando é extremamente importante: ele confirma que o Zephyr reconhece oficialmente o Arduino DUE no seu workspace.

4. Estrutura recomendada de workspace

Um erro comum entre iniciantes é misturar código de aplicação com o repositório do Zephyr. A abordagem correta é usar um workspace limpo, com a seguinte estrutura conceitual:

zephyr-workspace/
├── zephyr/              # Código-fonte do Zephyr RTOS
├── modules/             # Módulos externos (opcional)
├── bootloader/          # Bootloaders (opcional)
└── arduino_due_app/     # SUA aplicação

zephyr-workspace/
├── zephyr/              # Código-fonte do Zephyr RTOS
├── modules/             # Módulos externos (opcional)
├── bootloader/          # Bootloaders (opcional)
└── arduino_due_app/     # SUA aplicação

Dentro da pasta arduino_due_app, ficará apenas o código da aplicação, sem dependências diretas do kernel. Essa separação é crucial para manter o projeto sustentável e escalável.

5. Criando o projeto do zero para o Arduino DUE

Agora vamos criar efetivamente o projeto.

5.1 Criando o diretório da aplicação

mkdir arduino_due_app
cd arduino_due_app

mkdir arduino_due_app
cd arduino_due_app

5.2 Estrutura mínima de um projeto Zephyr

Crie a seguinte estrutura inicial:

arduino_due_app/
├── CMakeLists.txt
├── prj.conf
└── src/
    └── main.c

arduino_due_app/
├── CMakeLists.txt
├── prj.conf
└── src/
    └── main.c

Essa é a estrutura mínima obrigatória para qualquer aplicação Zephyr.

6. Arquivo CMakeLists.txt: integração com o Zephyr

Crie o arquivo CMakeLists.txt com o conteúdo:

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(arduino_due_app)

target_sources(app PRIVATE src/main.c)

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(arduino_due_app)

target_sources(app PRIVATE src/main.c)

O que esse arquivo faz, exatamente?

• cmake_minimum_required: garante compatibilidade mínima do CMake
• find_package(Zephyr ...): importa todo o sistema de build do Zephyr
• project(...): define o nome lógico do projeto
• target_sources(...): registra os arquivos C da aplicação

Aqui ocorre algo importante: você não define compilador, flags ou linker script. Tudo isso é herdado automaticamente da definição da placa (arduino_due) e do kernel.

7. Arquivo prj.conf: configuração do kernel (Kconfig)

O prj.conf controla quais partes do kernel Zephyr serão compiladas.

Comece com o mínimo funcional:

CONFIG_PRINTK=y
CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

CONFIG_PRINTK=y
CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

Essas opções habilitam:

• printk() – saída básica de debug
• Driver de porta serial
• Console padrão via UART

No Arduino DUE, isso será mapeado automaticamente para a UART correta definida no device tree da placa.

8. Arquivo main.c: primeira aplicação

Crie src/main.c:

#include <zephyr/kernel.h>
#include <zephyr/sys/printk.h>

int main(void)
{
    printk("Zephyr rodando no Arduino DUE!\n");

    while (1) {
        printk("Tick\n");
        k_sleep(K_SECONDS(1));
    }

    return 0;
}

#include <zephyr/kernel.h>
#include <zephyr/sys/printk.h>

int main(void)
{
    printk("Zephyr rodando no Arduino DUE!\n");

    while (1) {
        printk("Tick\n");
        k_sleep(K_SECONDS(1));
    }

    return 0;
}

Conceitos importantes aqui

• #include <zephyr/kernel.h>: acesso ao kernel, threads e temporização
• printk(): saída síncrona simples (não é printf)
• k_sleep(): API de temporização do kernel
• main() existe, mas não é o ponto de entrada real — o kernel já está inicializado antes dela ser chamada

9. Compilando o projeto para o Arduino DUE

Agora vem a parte crítica: build correto para a placa certa.

Dentro da pasta arduino_due_app:

west build -b arduino_due

west build -b arduino_due

O Zephyr irá:

1. Ler a definição da placa Arduino DUE
2. Selecionar o SoC SAM3X8E
3. Configurar clocks, memória e periféricos
4. Gerar o firmware final

Se tudo estiver correto, o build terminará sem erros.

10. Gravando o firmware no Arduino DUE

O Arduino DUE utiliza o bootloader SAM-BA, compatível com a ferramenta bossac.

Com a placa conectada via porta USB de programação, execute:

west flash

west flash

O Zephyr cuidará automaticamente do processo de gravação usando o método correto definido para a placa.

Após o reset, abra um terminal serial:

minicom -D /dev/ttyACM0 -b 115200

minicom -D /dev/ttyACM0 -b 115200

Você deverá ver:

Zephyr rodando no Arduino DUE!
Tick
Tick
Tick

Zephyr rodando no Arduino DUE!
Tick
Tick
Tick

11. Próximos passos

A partir daqui, você já tem:

• Um projeto Zephyr funcional
• Build e flash corretamente configurados
• Console serial ativo
• Base sólida para evoluir

Nos próximos artigos, podemos avançar para:

• Device Tree do Arduino DUE em detalhes
• GPIO e LEDs
• UARTs adicionais
• SPI e I²C
• Timers e interrupções
• Multithreading real no Cortex-M3

The post Criando um Projeto Zephyr RTOS no Arduino DUE – Guia Completo e Didático first appeared on MCU & FPGA.

Em sistemas embarcados com RTOS, especialmente em aplicações industriais, automotivas e IoT crítico, o maior desafio não é apenas “fazer funcionar”, mas manter previsibilidade temporal, escalabilidade e manutenibilidade. É nesse ponto que os padrões de projeto aplicados a RTOS se tornam fundamentais.

Diferente de aplicações desktop, padrões em RTOS precisam respeitar restrições de tempo real, uso determinístico de memória, prioridades, latência de interrupções e sincronização segura entre contexto de ISR e tarefas. Muitos padrões clássicos de software são adaptados ou reinterpretados nesse contexto.

Neste artigo, começaremos pelos padrões estruturais básicos de tarefas, que formam a fundação de praticamente qualquer sistema com FreeRTOS.

1 – Padrões Fundamentais de Estruturação de Tarefas

1.1 Superloop + Tasks (Incremental RTOS Adoption)

Problema resolvido:
Projetos legados em superloop (while(1)) tornam-se difíceis de manter à medida que crescem. Migrar tudo de uma vez para RTOS é arriscado.

Ideia do padrão:
Manter o superloop como uma tarefa principal, introduzindo gradualmente novas tarefas RTOS.

Quando usar:

• Migração de firmware bare-metal para FreeRTOS
• Sistemas simples que estão crescendo
• Prototipação controlada

Estrutura típica:

void LegacySuperloopTask(void *pvParameters)
{
    for (;;)
    {
        ReadSensors();
        ProcessData();
        UpdateOutputs();

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

void LegacySuperloopTask(void *pvParameters)
{
    for (;;)
    {
        ReadSensors();
        ProcessData();
        UpdateOutputs();

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

xTaskCreate(
    LegacySuperloopTask,
    "Legacy",
    1024,
    NULL,
    tskIDLE_PRIORITY + 1,
    NULL
);

xTaskCreate(
    LegacySuperloopTask,
    "Legacy",
    1024,
    NULL,
    tskIDLE_PRIORITY + 1,
    NULL
);

Vantagens:

• Baixo risco na migração
• Preserva código validado
• Facilita testes incrementais

Risco comum:
Transformar essa tarefa em um “monstro” que ignora o espírito do RTOS. Este padrão deve ser transitório, não permanente.

1.2 One Task Per Responsibility (Uma tarefa por responsabilidade)

Problema resolvido:
Tarefas que fazem “de tudo” dificultam análise temporal, debugging e escalonamento.

Ideia do padrão:
Cada tarefa possui uma única responsabilidade funcional bem definida.

Exemplo típico em FreeRTOS:

• Task de aquisição
• Task de processamento
• Task de comunicação

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        ReadADC();
        xTaskNotify(ProcessTaskHandle, 0, eNoAction);
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        ReadADC();
        xTaskNotify(ProcessTaskHandle, 0, eNoAction);
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

void ProcessTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        FilterData();
        ComputeResults();
    }
}

void ProcessTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        FilterData();
        ComputeResults();
    }
}

Vantagens:

• Facilita análise de prioridades
• Reduz acoplamento
• Favorece paralelismo real

Boas práticas:

• Nomear tarefas claramente
• Documentar WCET (Worst Case Execution Time)
• Evitar bloqueios longos

1.3 Cyclic Executive com RTOS

Problema resolvido:
Algumas aplicações precisam de periodicidade rígida, mesmo usando RTOS.

Ideia do padrão:
Uma tarefa de alta prioridade atua como orquestrador temporal, liberando outras tarefas de forma cíclica.

Estrutura conceitual:

• Task cíclica principal
• Subtarefas acionadas por notificações

void CyclicTask(void *pvParameters)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();

    for (;;)
    {
        xTaskNotify(TaskAHandle, 0, eNoAction);
        xTaskNotify(TaskBHandle, 0, eNoAction);

        vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(10));
    }
}

void CyclicTask(void *pvParameters)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();

    for (;;)
    {
        xTaskNotify(TaskAHandle, 0, eNoAction);
        xTaskNotify(TaskBHandle, 0, eNoAction);

        vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(10));
    }
}

Vantagens:

• Controle temporal explícito
• Previsibilidade elevada
• Útil em controle e automação

Limitação:
Menos flexível que arquiteturas puramente orientadas a eventos.

1.4 Idle Task como Padrão Arquitetural

Problema resolvido:
Desperdício de CPU e energia quando o sistema está ocioso.

Ideia do padrão:
Usar a Idle Task como ponto central para:

• Economia de energia
• Limpeza de recursos
• Instrumentação

void vApplicationIdleHook(void)
{
    EnterLowPowerMode();
}

void vApplicationIdleHook(void)
{
    EnterLowPowerMode();
}

Uso típico:

• __WFI() em Cortex-M
• Estatísticas de CPU
• Monitoramento de heap

Importante:
Nunca bloquear, nunca usar delays e nunca acessar recursos não protegidos.

2 – Padrões de Comunicação e Sincronização em RTOS

Em FreeRTOS, concorrência mal projetada é a principal fonte de bugs: deadlocks, starvation, jitter temporal e corrupção de dados. Os padrões desta seção existem para substituir variáveis globais, flags soltas e volatile mal utilizados por mecanismos determinísticos e auditáveis.

Aqui falamos de comunicação, não apenas de sincronização.

2.1 Event Queue (Fila de Eventos)

Problema resolvido:
Múltiplos produtores gerando eventos assíncronos para um único consumidor.

Ideia do padrão:
Eventos são encapsulados em estruturas e enviados por uma fila RTOS. O consumidor processa eventos em ordem temporal.

Quando usar:

• Interface homem-máquina
• Eventos de sensores
• Drivers desacoplados da lógica de aplicação

Estrutura típica do evento:

typedef enum {
    EVT_BUTTON,
    EVT_SENSOR,
    EVT_TIMEOUT
} EventType;

typedef struct {
    EventType type;
    uint32_t  data;
} AppEvent;

typedef enum {
    EVT_BUTTON,
    EVT_SENSOR,
    EVT_TIMEOUT
} EventType;

typedef struct {
    EventType type;
    uint32_t  data;
} AppEvent;

Fila global (criada na inicialização):

QueueHandle_t EventQueue;

EventQueue = xQueueCreate(10, sizeof(AppEvent));

QueueHandle_t EventQueue;

EventQueue = xQueueCreate(10, sizeof(AppEvent));

Produtor:

void ButtonISR(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    AppEvent evt = {
        .type = EVT_BUTTON,
        .data = 1
    };

    xQueueSendFromISR(EventQueue, &evt, &xHigherPriorityTaskWoken);
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

void ButtonISR(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    AppEvent evt = {
        .type = EVT_BUTTON,
        .data = 1
    };

    xQueueSendFromISR(EventQueue, &evt, &xHigherPriorityTaskWoken);
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

Consumidor:

void EventTask(void *pvParameters)
{
    AppEvent evt;

    for (;;)
    {
        if (xQueueReceive(EventQueue, &evt, portMAX_DELAY))
        {
            switch (evt.type)
            {
                case EVT_BUTTON:
                    HandleButton(evt.data);
                    break;

                case EVT_SENSOR:
                    HandleSensor(evt.data);
                    break;

                default:
                    break;
            }
        }
    }
}

void EventTask(void *pvParameters)
{
    AppEvent evt;

    for (;;)
    {
        if (xQueueReceive(EventQueue, &evt, portMAX_DELAY))
        {
            switch (evt.type)
            {
                case EVT_BUTTON:
                    HandleButton(evt.data);
                    break;

                case EVT_SENSOR:
                    HandleSensor(evt.data);
                    break;

                default:
                    break;
            }
        }
    }
}

Vantagens:

• Desacoplamento total
• Ordem garantida
• Fácil instrumentação

Erro comum:
Usar fila para stream contínuo de dados (para isso existem buffers).

2.2 Mailbox (Fila de Mensagem Única)

Problema resolvido:
Apenas o último valor importa, não o histórico.

Ideia do padrão:
Uma fila de tamanho 1 funciona como mailbox sobrescrevível.

QueueHandle_t Mailbox;

Mailbox = xQueueCreate(1, sizeof(uint32_t));

QueueHandle_t Mailbox;

Mailbox = xQueueCreate(1, sizeof(uint32_t));

Produtor:

uint32_t temperature = ReadTemperature();
xQueueOverwrite(Mailbox, &temperature);

uint32_t temperature = ReadTemperature();
xQueueOverwrite(Mailbox, &temperature);

Consumidor:

uint32_t temp;

if (xQueuePeek(Mailbox, &temp, 0))
{
    UseTemperature(temp);
}

uint32_t temp;

if (xQueuePeek(Mailbox, &temp, 0))
{
    UseTemperature(temp);
}

Quando usar:

• Telemetria
• Estados globais observáveis
• Última leitura válida

Vantagem-chave:
Evita backlog artificial.

2.3 Publish–Subscribe (Pub-Sub) com FreeRTOS

Problema resolvido:
Múltiplos consumidores interessados no mesmo evento.

Ideia do padrão:
Uma tarefa “dispatcher” recebe eventos e os redistribui para múltiplas filas.

Arquitetura:

ISR / Producers
      ↓
  Event Queue
      ↓
  Dispatcher Task
     ↓          ↓           ↓
 Task A Task B Task C

ISR / Producers
      ↓
  Event Queue
      ↓
  Dispatcher Task
     ↓          ↓           ↓
 Task A Task B Task C

Dispatcher:

void DispatcherTask(void *pvParameters)
{
    AppEvent evt;

    for (;;)
    {
        if (xQueueReceive(EventQueue, &evt, portMAX_DELAY))
        {
            xQueueSend(QueueA, &evt, 0);
            xQueueSend(QueueB, &evt, 0);
        }
    }
}

void DispatcherTask(void *pvParameters)
{
    AppEvent evt;

    for (;;)
    {
        if (xQueueReceive(EventQueue, &evt, portMAX_DELAY))
        {
            xQueueSend(QueueA, &evt, 0);
            xQueueSend(QueueB, &evt, 0);
        }
    }
}

Vantagens:

• Extensível
• Isola produtores de consumidores
• Facilita testes

Custo:
Mais RAM e latência — aceitável em troca de clareza.

2.4 Task Notification como Padrão de Sinalização Rápida

Problema resolvido:
Overhead de filas quando apenas sinalização simples é necessária.

Ideia do padrão:
Usar Task Notifications como semáforos ultraleves.

Produtor:

xTaskNotify(TaskHandle, 0x01, eSetBits);

xTaskNotify(TaskHandle, 0x01, eSetBits);

Consumidor:

uint32_t flags;

xTaskNotifyWait(0, 0xFFFFFFFF, &flags, portMAX_DELAY);

if (flags & 0x01)
{
    ProcessEvent();
}

uint32_t flags;

xTaskNotifyWait(0, 0xFFFFFFFF, &flags, portMAX_DELAY);

if (flags & 0x01)
{
    ProcessEvent();
}

Vantagens:

• Zero alocação dinâmica
• Extremamente rápido
• Ideal para ISR → Task

Limitação:
Apenas 32 bits por tarefa → não serve para dados complexos.

2.5 Stream Buffer e Message Buffer

Problema resolvido:
Troca eficiente de fluxos contínuos de dados.

Stream Buffer

• Dados binários contínuos
• Sem fronteira de mensagem

StreamBufferHandle_t sb;
sb = xStreamBufferCreate(128, 1);

StreamBufferHandle_t sb;
sb = xStreamBufferCreate(128, 1);

Message Buffer

• Mensagens delimitadas
• Ideal para pacotes

MessageBufferHandle_t mb;
mb = xMessageBufferCreate(128);

MessageBufferHandle_t mb;
mb = xMessageBufferCreate(128);

Uso típico:

• UART
• SPI
• Áudio
• Protocolos binários

Boa prática:
Preferir buffers a filas para dados “em volume”.

3 – Padrões de Exclusão Mútua, Proteção de Recursos e Prevenção de Deadlock

Em FreeRTOS, concorrência não controlada não falha sempre — falha quando você menos espera. Esta seção trata de padrões que evitam corrupção de dados, inversão de prioridade e deadlocks, sem sacrificar o determinismo.

3.1 Mutex com Priority Inheritance

Problema resolvido:
Duas ou mais tarefas acessam o mesmo recurso (UART, I²C, SPI, memória compartilhada).

Risco clássico:
Priority Inversion — tarefa de baixa prioridade bloqueia uma de alta.

Ideia do padrão:
Usar Mutex (não semáforo) para herança de prioridade automática.

SemaphoreHandle_t uartMutex;

uartMutex = xSemaphoreCreateMutex();

SemaphoreHandle_t uartMutex;

uartMutex = xSemaphoreCreateMutex();

Uso correto:

void UartTask(void *pvParameters)
{
    for (;;)
    {
        if (xSemaphoreTake(uartMutex, portMAX_DELAY))
        {
            UART_Write("Hello RTOS\n");
            xSemaphoreGive(uartMutex);
        }
    }
}

void UartTask(void *pvParameters)
{
    for (;;)
    {
        if (xSemaphoreTake(uartMutex, portMAX_DELAY))
        {
            UART_Write("Hello RTOS\n");
            xSemaphoreGive(uartMutex);
        }
    }
}

Por que não semáforo binário?

• Semáforos não fazem herança de prioridade
• Mutexes são projetados para exclusão mútua real

Regra de ouro:
Mutex protege recurso, não evento.

3.2 Gatekeeper Task (Padrão Fundamental em FreeRTOS)

Problema resolvido:
Múltiplas tarefas acessando um único periférico (UART, Flash, Display).

Ideia do padrão:
Apenas uma tarefa é dona do recurso. As demais pedem serviço via fila.

Este é um dos padrões mais importantes para firmware de produção.

Estrutura:

Tasks ──► Request Queue ──► Gatekeeper Task ──► Hardware

Tasks ──► Request Queue ──► Gatekeeper Task ──► Hardware

Mensagem de requisição:

typedef struct {
    char message[64];
} UartRequest;

typedef struct {
    char message[64];
} UartRequest;

Gatekeeper:

void UartGatekeeperTask(void *pvParameters)
{
    UartRequest req;

    for (;;)
    {
        if (xQueueReceive(UartQueue, &req, portMAX_DELAY))
        {
            UART_Write(req.message);
        }
    }
}

void UartGatekeeperTask(void *pvParameters)
{
    UartRequest req;

    for (;;)
    {
        if (xQueueReceive(UartQueue, &req, portMAX_DELAY))
        {
            UART_Write(req.message);
        }
    }
}

Cliente:

UartRequest req = { .message = "Log message\n" };
xQueueSend(UartQueue, &req, portMAX_DELAY);

UartRequest req = { .message = "Log message\n" };
xQueueSend(UartQueue, &req, portMAX_DELAY);

Vantagens:

• Elimina mutexes
• Elimina deadlocks
• Simplifica drivers

Trade-off:
Leve aumento de latência → ganho enorme em robustez.

3.3 Critical Section (Uso cirúrgico)

Problema resolvido:
Trechos extremamente curtos que não podem ser interrompidos.

taskENTER_CRITICAL();
sharedCounter++;
taskEXIT_CRITICAL();

taskENTER_CRITICAL();
sharedCounter++;
taskEXIT_CRITICAL();

O que acontece:

• Desabilita interrupções (localmente)
• Bloqueia escalonamento

Quando usar:

• Incrementos atômicos
• Flags simples
• Estruturas lock-free auxiliares

Quando NÃO usar:
Código longo
Acesso a drivers
Comunicação entre tarefas

Se você precisa de printf() dentro de critical section, algo está errado.

3.4 Read–Modify–Write protegido (Anti-pattern clássico)

Problema comum (ERRADO):

if (flag == 0)
{
    flag = 1;
}

if (flag == 0)
{
    flag = 1;
}

Correção com mutex:

xSemaphoreTake(flagMutex, portMAX_DELAY);
if (flag == 0)
{
    flag = 1;
}
xSemaphoreGive(flagMutex);

xSemaphoreTake(flagMutex, portMAX_DELAY);
if (flag == 0)
{
    flag = 1;
}
xSemaphoreGive(flagMutex);

Ou melhor ainda:
Substituir flag por task notification ou event group.

3.5 Event Groups como Padrão de Coordenação

Problema resolvido:
Sincronizar múltiplas tarefas com condições compostas.

EventGroupHandle_t systemEvents;

#define EVT_NET_READY   (1 << 0)
#define EVT_SENSOR_OK   (1 << 1)

EventGroupHandle_t systemEvents;

#define EVT_NET_READY   (1 << 0)
#define EVT_SENSOR_OK   (1 << 1)

Sinalização:

xEventGroupSetBits(systemEvents, EVT_NET_READY);

xEventGroupSetBits(systemEvents, EVT_NET_READY);

Aguardar múltiplas condições:

xEventGroupWaitBits(
    systemEvents,
    EVT_NET_READY | EVT_SENSOR_OK,
    pdFALSE,
    pdTRUE,
    portMAX_DELAY
);

xEventGroupWaitBits(
    systemEvents,
    EVT_NET_READY | EVT_SENSOR_OK,
    pdFALSE,
    pdTRUE,
    portMAX_DELAY
);

Uso típico:

• Startup sequencial
• Estados globais do sistema
• Dependências entre subsistemas

Vantagem:
Muito mais expressivo que flags globais.

3.6 Deadlock Avoidance (Padrões de Prevenção)

Causa clássica de deadlock:

• Ordem inconsistente de aquisição de mutexes

Padrão de prevenção:
Sempre adquirir recursos na mesma ordem

xSemaphoreTake(mutexA, portMAX_DELAY);
xSemaphoreTake(mutexB, portMAX_DELAY);

/* uso */

xSemaphoreGive(mutexB);
xSemaphoreGive(mutexA);

xSemaphoreTake(mutexA, portMAX_DELAY);
xSemaphoreTake(mutexB, portMAX_DELAY);

/* uso */

xSemaphoreGive(mutexB);
xSemaphoreGive(mutexA);

Alternativa mais segura:
Eliminar múltiplos mutexes → usar Gatekeeper.

4 – Padrões de Controle de Fluxo, Estados e Recuperação em RTOS

Em sistemas com FreeRTOS, fluxo implícito é inimigo do determinismo. if encadeado, flags globais e dependências ocultas tornam o comportamento do sistema impossível de prever sob carga, falhas ou eventos raros.

Os padrões desta seção tornam o comportamento do sistema explícito, rastreável e recuperável.

4.1 State Machine (Máquina de Estados Finita – FSM)

Problema resolvido:
Fluxo de controle espalhado por múltiplas tarefas e condicionais.

Ideia do padrão:
Representar o comportamento como estados explícitos e transições bem definidas.

Estrutura básica

typedef enum {
    STATE_INIT,
    STATE_IDLE,
    STATE_ACTIVE,
    STATE_ERROR
} SystemState;

typedef enum {
    STATE_INIT,
    STATE_IDLE,
    STATE_ACTIVE,
    STATE_ERROR
} SystemState;

static SystemState currentState = STATE_INIT;

static SystemState currentState = STATE_INIT;

Execução da máquina de estados (task dedicada)

void StateMachineTask(void *pvParameters)
{
    for (;;)
    {
        switch (currentState)
        {
            case STATE_INIT:
                InitHardware();
                currentState = STATE_IDLE;
                break;

            case STATE_IDLE:
                if (StartCondition())
                    currentState = STATE_ACTIVE;
                break;

            case STATE_ACTIVE:
                RunControlLoop();
                if (FaultDetected())
                    currentState = STATE_ERROR;
                break;

            case STATE_ERROR:
                HandleFault();
                currentState = STATE_IDLE;
                break;
        }

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

void StateMachineTask(void *pvParameters)
{
    for (;;)
    {
        switch (currentState)
        {
            case STATE_INIT:
                InitHardware();
                currentState = STATE_IDLE;
                break;

            case STATE_IDLE:
                if (StartCondition())
                    currentState = STATE_ACTIVE;
                break;

            case STATE_ACTIVE:
                RunControlLoop();
                if (FaultDetected())
                    currentState = STATE_ERROR;
                break;

            case STATE_ERROR:
                HandleFault();
                currentState = STATE_IDLE;
                break;
        }

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

Vantagens:

• Fluxo claro
• Fácil depuração
• Excelente para controle e sequenciamento

Limitação:
Cresce mal quando há muitos estados e eventos → entra a HSM.

4.2 Hierarchical State Machine (HSM)

Problema resolvido:
Explosão combinatória de estados.

Ideia do padrão:
Estados possuem comportamento comum herdado de estados “pais”.

Exemplo conceitual

SYSTEM
 ├── OPERATIONAL
 │    ├── IDLE
 │    └── ACTIVE
 └── FAULT
      ├── WARNING
      └── CRITICAL

SYSTEM
 ├── OPERATIONAL
 │    ├── IDLE
 │    └── ACTIVE
 └── FAULT
      ├── WARNING
      └── CRITICAL

Implementação simplificada em C

typedef enum {
    SUPER_OPERATIONAL,
    SUPER_FAULT
} SuperState;

typedef enum {
    SUB_IDLE,
    SUB_ACTIVE,
    SUB_WARNING,
    SUB_CRITICAL
} SubState;

static SuperState superState;
static SubState   subState;

typedef enum {
    SUPER_OPERATIONAL,
    SUPER_FAULT
} SuperState;

typedef enum {
    SUB_IDLE,
    SUB_ACTIVE,
    SUB_WARNING,
    SUB_CRITICAL
} SubState;

static SuperState superState;
static SubState   subState;

void StateMachineStep(void)
{
    switch (superState)
    {
        case SUPER_OPERATIONAL:
            if (FaultDetected())
            {
                superState = SUPER_FAULT;
                subState = SUB_WARNING;
                break;
            }

            if (subState == SUB_IDLE && StartCondition())
                subState = SUB_ACTIVE;

            break;

        case SUPER_FAULT:
            HandleFaultCommon();

            if (subState == SUB_WARNING && EscalateFault())
                subState = SUB_CRITICAL;

            if (FaultCleared())
            {
                superState = SUPER_OPERATIONAL;
                subState = SUB_IDLE;
            }
            break;
    }
}

void StateMachineStep(void)
{
    switch (superState)
    {
        case SUPER_OPERATIONAL:
            if (FaultDetected())
            {
                superState = SUPER_FAULT;
                subState = SUB_WARNING;
                break;
            }

            if (subState == SUB_IDLE && StartCondition())
                subState = SUB_ACTIVE;

            break;

        case SUPER_FAULT:
            HandleFaultCommon();

            if (subState == SUB_WARNING && EscalateFault())
                subState = SUB_CRITICAL;

            if (FaultCleared())
            {
                superState = SUPER_OPERATIONAL;
                subState = SUB_IDLE;
            }
            break;
    }
}

Vantagens:

• Redução de duplicação
• Escala bem
• Muito usada em automotivo e aeroespacial

4.3 Mode Manager (Gerenciador de Modos)

Problema resolvido:
Múltiplas tarefas precisam reagir a mudanças globais de modo.

Ideia do padrão:
Uma tarefa central gerencia o modo do sistema, e os demais módulos se adaptam.

Modos típicos

typedef enum {
    MODE_STARTUP,
    MODE_NORMAL,
    MODE_LOW_POWER,
    MODE_MAINTENANCE
} SystemMode;

typedef enum {
    MODE_STARTUP,
    MODE_NORMAL,
    MODE_LOW_POWER,
    MODE_MAINTENANCE
} SystemMode;

Mode Manager

static SystemMode currentMode;

void ModeManagerTask(void *pvParameters)
{
    for (;;)
    {
        if (LowPowerRequested())
            currentMode = MODE_LOW_POWER;

        if (MaintenanceRequested())
            currentMode = MODE_MAINTENANCE;

        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

static SystemMode currentMode;

void ModeManagerTask(void *pvParameters)
{
    for (;;)
    {
        if (LowPowerRequested())
            currentMode = MODE_LOW_POWER;

        if (MaintenanceRequested())
            currentMode = MODE_MAINTENANCE;

        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

Uso pelas tarefas

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        if (currentMode == MODE_NORMAL)
            ReadSensors();

        vTaskDelay(pdMS_TO_TICKS(50));
    }
}

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        if (currentMode == MODE_NORMAL)
            ReadSensors();

        vTaskDelay(pdMS_TO_TICKS(50));
    }
}

Boa prática:
Substituir variável global por:

• Event Groups
• Message Queue
• Broadcast via Pub-Sub

4.4 Recovery Pattern (Padrão de Recuperação)

Problema resolvido:
Falhas transitórias travam o sistema.

Ideia do padrão:
Falhas são tratadas como estados, não exceções implícitas.

Exemplo de recuperação controlada

case STATE_ERROR:
    LogFault();
    ResetSubsystem();
    if (RetryAllowed())
        currentState = STATE_INIT;
    else
        EnterSafeState();
    break;

case STATE_ERROR:
    LogFault();
    ResetSubsystem();
    if (RetryAllowed())
        currentState = STATE_INIT;
    else
        EnterSafeState();
    break;

Vantagens:

• Evita reboot desnecessário
• Permite retry controlado
• Essencial para sistemas remotos

4.5 Watchdog como Padrão Arquitetural

Problema resolvido:
Deadlocks silenciosos e travamentos não detectados.

Ideia do padrão:
Cada tarefa sinaliza vida periodicamente para um supervisor.

void SupervisorTask(void *pvParameters)
{
    for (;;)
    {
        if (!AllTasksAlive())
            SystemReset();

        FeedWatchdog();
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void SupervisorTask(void *pvParameters)
{
    for (;;)
    {
        if (!AllTasksAlive())
            SystemReset();

        FeedWatchdog();
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Importante:
O watchdog não substitui arquitetura correta — ele a complementa.

Excelente. Agora avançamos para a arquitetura interna do firmware, onde decisões erradas costumam gerar acoplamento irreversível, e decisões corretas permitem portabilidade, testes e evolução por anos.

5 – Padrões de Arquitetura em Camadas, Drivers e Serviços em RTOS

Em sistemas com FreeRTOS, misturar driver, lógica de negócio e política de tempo real na mesma tarefa é um erro estrutural. Os padrões desta seção tratam de separação de responsabilidades, isolamento de hardware e execução previsível.

5.1 Layered Architecture (Arquitetura em Camadas)

Problema resolvido:
Firmware “espaguete”, onde qualquer módulo acessa diretamente registradores, RTOS e aplicação.

Ideia do padrão:
Organizar o sistema em camadas bem definidas, com dependências unidirecionais.

Camadas típicas em FreeRTOS

Exemplo de separação correta

Driver (HAL):

void UartHw_SendByte(uint8_t b);

void UartHw_SendByte(uint8_t b);

Serviço:

void UartService_Send(const uint8_t *data, size_t len);

void UartService_Send(const uint8_t *data, size_t len);

Aplicação:

UartService_Send((uint8_t*)"OK\n", 3);

UartService_Send((uint8_t*)"OK\n", 3);

Vantagens:

• Portabilidade de MCU
• Testes unitários viáveis
• Evolução controlada

Regra prática:
Camadas superiores não conhecem detalhes das inferiores.

5.2 Hardware Abstraction Layer (HAL) como Padrão

Problema resolvido:
Dependência direta de registradores ou SDK do fabricante.

Ideia do padrão:
Isolar acesso ao hardware atrás de uma API mínima e estável.

typedef struct {
    void (*init)(void);
    void (*write)(const uint8_t *buf, size_t len);
} UartDriver;

typedef struct {
    void (*init)(void);
    void (*write)(const uint8_t *buf, size_t len);
} UartDriver;

static UartDriver uart0 = {
    .init  = STM32_UartInit,
    .write = STM32_UartWrite
};

static UartDriver uart0 = {
    .init  = STM32_UartInit,
    .write = STM32_UartWrite
};

Benefício crítico:
Permite trocar STM32 → NXP → RP2040 sem reescrever aplicação.

5.3 Service Layer (Camada de Serviços)

Problema resolvido:
Drivers não devem conter lógica de negócio nem política de concorrência.

Ideia do padrão:
Serviços encapsulam:

• Sincronização
• Filas
• Retries
• Timeout
• Políticas de acesso

Exemplo: Serviço de UART com Gatekeeper

void UartService_Send(const uint8_t *data, size_t len)
{
    UartRequest req = {
        .data = data,
        .len  = len
    };

    xQueueSend(UartQueue, &req, portMAX_DELAY);
}

void UartService_Send(const uint8_t *data, size_t len)
{
    UartRequest req = {
        .data = data,
        .len  = len
    };

    xQueueSend(UartQueue, &req, portMAX_DELAY);
}

Vantagens:

• Aplicação fica limpa
• Política centralizada
• Drivers permanecem simples

5.4 Active Object Pattern

Problema resolvido:
Misturar lógica de controle com concorrência explícita.

Ideia do padrão:
Cada objeto ativo possui:

• Estado interno
• Fila própria
• Tarefa dedicada

Estrutura conceitual

Active Object
 ├── Queue
 ├── Task
 └── State Machine

Active Object
 ├── Queue
 ├── Task
 └── State Machine

Exemplo simplificado

typedef struct {
    QueueHandle_t queue;
} MotorController;

typedef struct {
    QueueHandle_t queue;
} MotorController;

void MotorTask(void *pvParameters)
{
    MotorCommand cmd;

    for (;;)
    {
        xQueueReceive(motor.queue, &cmd, portMAX_DELAY);
        ExecuteMotorCommand(&cmd);
    }
}

void MotorTask(void *pvParameters)
{
    MotorCommand cmd;

    for (;;)
    {
        xQueueReceive(motor.queue, &cmd, portMAX_DELAY);
        ExecuteMotorCommand(&cmd);
    }
}

Vantagens:

• Forte encapsulamento
• Ideal para controle, comunicação e I/O
• Elimina mutexes internos

Custo:
Uso maior de RAM (1 task + 1 fila por objeto)

5.5 Deferred Interrupt Processing

Problema resolvido:
ISR longa causa jitter e perda de deadlines.

Ideia do padrão:
ISR apenas sinaliza → processamento pesado ocorre em task.

void ADC_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    xTaskNotifyFromISR(AdcTaskHandle, 0, eNoAction, &xHigherPriorityTaskWoken);
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

void ADC_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    xTaskNotifyFromISR(AdcTaskHandle, 0, eNoAction, &xHigherPriorityTaskWoken);
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

void AdcTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        ProcessAdcData();
    }
}

void AdcTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        ProcessAdcData();
    }
}

Vantagens:

• ISR mínima
• Melhor escalonamento
• Sistema mais previsível

6 – Padrões de Inicialização, Startup Sequencial e Monitoramento de Saúde

Em sistemas com FreeRTOS, o boot é o momento mais frágil do sistema. Muitos firmwares falham não durante a operação normal, mas durante inicialização parcial, falhas de periféricos, ordem incorreta de dependências ou estados indefinidos.

Os padrões desta seção tornam o startup determinístico, auditável e recuperável.

6.1 Startup Task (Task de Inicialização)

Problema resolvido:
Inicialização espalhada entre main(), ISRs e tarefas diversas.

Ideia do padrão:
Criar uma tarefa exclusiva de startup, responsável por inicializar tudo em ordem controlada, antes do sistema entrar em operação normal.

Estrutura típica

int main(void)
{
    HardwareInit();

    xTaskCreate(StartupTask, "Startup", 1024, NULL, tskIDLE_PRIORITY + 3, NULL);

    vTaskStartScheduler();
}

int main(void)
{
    HardwareInit();

    xTaskCreate(StartupTask, "Startup", 1024, NULL, tskIDLE_PRIORITY + 3, NULL);

    vTaskStartScheduler();
}

void StartupTask(void *pvParameters)
{
    InitDrivers();
    InitServices();
    InitApplication();

    xTaskCreate(AppTask, "App", 1024, NULL, tskIDLE_PRIORITY + 1, NULL);

    vTaskDelete(NULL);
}

void StartupTask(void *pvParameters)
{
    InitDrivers();
    InitServices();
    InitApplication();

    xTaskCreate(AppTask, "App", 1024, NULL, tskIDLE_PRIORITY + 1, NULL);

    vTaskDelete(NULL);
}

Vantagens:

• Ordem explícita
• Inicialização rastreável
• Elimina “efeitos colaterais” no main()

Boa prática:
Startup task deve se autodestruir após cumprir sua função.

6.2 Init Sequencing (Sequenciamento de Inicialização)

Problema resolvido:
Tarefas começam a rodar antes de suas dependências estarem prontas.

Ideia do padrão:
Inicialização ocorre em fases bem definidas, com sincronização explícita.

Exemplo com Event Groups

#define EVT_DRIVERS_READY   (1 << 0)
#define EVT_SERVICES_READY  (1 << 1)

#define EVT_DRIVERS_READY   (1 << 0)
#define EVT_SERVICES_READY  (1 << 1)

void StartupTask(void *pvParameters)
{
    InitDrivers();
    xEventGroupSetBits(systemEvents, EVT_DRIVERS_READY);

    InitServices();
    xEventGroupSetBits(systemEvents, EVT_SERVICES_READY);

    vTaskDelete(NULL);
}

void StartupTask(void *pvParameters)
{
    InitDrivers();
    xEventGroupSetBits(systemEvents, EVT_DRIVERS_READY);

    InitServices();
    xEventGroupSetBits(systemEvents, EVT_SERVICES_READY);

    vTaskDelete(NULL);
}

void AppTask(void *pvParameters)
{
    xEventGroupWaitBits(
        systemEvents,
        EVT_DRIVERS_READY | EVT_SERVICES_READY,
        pdFALSE,
        pdTRUE,
        portMAX_DELAY
    );

    RunApplication();
}

void AppTask(void *pvParameters)
{
    xEventGroupWaitBits(
        systemEvents,
        EVT_DRIVERS_READY | EVT_SERVICES_READY,
        pdFALSE,
        pdTRUE,
        portMAX_DELAY
    );

    RunApplication();
}

Vantagem:
Dependências explícitas → menos bugs “fantasma”.

6.3 Dependency Ordering Pattern

Problema resolvido:
Serviços que dependem implicitamente uns dos outros.

Ideia do padrão:
Cada serviço declara o que precisa antes de operar.

Exemplo conceitual

bool Network_IsReady(void);
bool Storage_IsReady(void);

bool Network_IsReady(void);
bool Storage_IsReady(void);

void TelemetryTask(void *pvParameters)
{
    while (!Network_IsReady() || !Storage_IsReady())
    {
        vTaskDelay(pdMS_TO_TICKS(100));
    }

    StartTelemetry();
}

void TelemetryTask(void *pvParameters)
{
    while (!Network_IsReady() || !Storage_IsReady())
    {
        vTaskDelay(pdMS_TO_TICKS(100));
    }

    StartTelemetry();
}

Melhoria recomendada:
Substituir polling por eventos ou notificações.

6.4 Health Monitoring Pattern (Monitoramento de Saúde)

Problema resolvido:
Tarefas travam silenciosamente.

Ideia do padrão:
Cada tarefa reporta periodicamente seu estado para um supervisor central.

Estrutura básica

typedef struct {
    uint32_t taskId;
    TickType_t lastAlive;
} TaskHealth;

typedef struct {
    uint32_t taskId;
    TickType_t lastAlive;
} TaskHealth;

void HealthReport(uint32_t id)
{
    healthTable[id].lastAlive = xTaskGetTickCount();
}

void HealthReport(uint32_t id)
{
    healthTable[id].lastAlive = xTaskGetTickCount();
}

void SupervisorTask(void *pvParameters)
{
    for (;;)
    {
        if (TaskTimeoutDetected())
            EnterRecoveryMode();

        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

void SupervisorTask(void *pvParameters)
{
    for (;;)
    {
        if (TaskTimeoutDetected())
            EnterRecoveryMode();

        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

Vantagens:

• Detecção precoce de falhas
• Integração natural com watchdog
• Essencial em sistemas remotos

6.5 Fail-Safe State Pattern

Problema resolvido:
Sistema entra em estado indefinido após falha grave.

Ideia do padrão:
Definir explicitamente um estado seguro, conhecido e controlado.

void EnterSafeState(void)
{
    DisableOutputs();
    StopMotors();
    SignalErrorLED();
}

void EnterSafeState(void)
{
    DisableOutputs();
    StopMotors();
    SignalErrorLED();
}

Importante:
Fail-safe não é reset. É sobrevivência controlada.

6.6 Warm Restart vs Cold Restart

Problema resolvido:
Reset total desnecessário causa perda de estado e latência.

Ideia do padrão:
Diferenciar:

• Cold restart → reboot completo
• Warm restart → reinicialização parcial de serviços

if (RecoverableFault())
    RestartServices();
else
    SystemReset();

if (RecoverableFault())
    RestartServices();
else
    SystemReset();

7 – Síntese Geral e Checklist Arquitetural de Padrões para FreeRTOS

Após percorrer os principais grupos de padrões aplicáveis a sistemas com RTOS, fica claro que FreeRTOS não é apenas um escalonador, mas uma plataforma arquitetural que exige decisões conscientes desde o primeiro xTaskCreate().

Esta seção final transforma o conteúdo técnico em instrumento de uso real, algo que pode ser consultado durante o desenho ou revisão de um firmware.

7.1 Mapa Conceitual dos Padrões em RTOS

Podemos organizar os padrões apresentados em camadas de decisão, do mais fundamental ao mais sistêmico:

Estrutura Básica

• Superloop + Tasks
• One Task per Responsibility
• Cyclic Executive
• Idle Task Pattern

Define como o sistema respira

Comunicação e Sincronização

• Event Queue
• Mailbox
• Publish–Subscribe
• Task Notifications
• Stream Buffer / Message Buffer

Define como a informação flui

Proteção de Recursos

• Mutex com Priority Inheritance
• Gatekeeper Task
• Critical Sections
• Event Groups
• Deadlock Avoidance

Define como o sistema se protege

Controle de Comportamento

• Finite State Machine (FSM)
• Hierarchical State Machine (HSM)
• Mode Manager
• Recovery Pattern
• Watchdog Pattern

Define como o sistema se comporta e reage

Arquitetura Interna

• Layered Architecture
• HAL
• Service Layer
• Active Object
• Deferred Interrupt Processing

Define como o sistema é construído

Inicialização e Robustez

• Startup Task
• Init Sequencing
• Dependency Ordering
• Health Monitoring
• Fail-Safe State
• Warm vs Cold Restart

Define como o sistema nasce e sobrevive

7.2 Checklist Arquitetural para Projetos com FreeRTOS

Use este checklist como ferramenta de revisão técnica:

Estrutura

• Cada tarefa tem uma responsabilidade clara?
• Existe uma política clara de prioridades?
• Tarefas críticas têm WCET conhecido?

Comunicação

• Variáveis globais foram substituídas por filas/eventos?
• ISR apenas sinalizam, nunca processam?
• Fluxos contínuos usam buffers, não filas?

Proteção

• Mutexes são usados apenas para recursos?
• Existe Gatekeeper para periféricos compartilhados?
• Ordem de aquisição de recursos é consistente?

Estados e Modos

• O comportamento está modelado em FSM ou HSM?
• Modos globais são explícitos?
• Falhas são estados, não exceções implícitas?

Arquitetura

• Aplicação não conhece registradores?
• Drivers não conhecem RTOS?
• Serviços encapsulam política e sincronização?

Inicialização e Saúde

• Startup ocorre em task dedicada?
• Dependências são explícitas?
• Existe supervisão de tarefas?
• Fail-safe é definido?

7.3 Erros Clássicos que Esses Padrões Evitam

• “Só mais um volatile resolve”
• “Vamos proteger tudo com mutex”
• “ISR rápida não precisa de cuidado”
• “Reset resolve qualquer coisa”
• “Depois a gente organiza a arquitetura”

Todos esses erros são sintomas da ausência de padrões, não de falta de RTOS.

Conclusão Geral do Artigo

A maturidade em sistemas embarcados com FreeRTOS não está em quantas tasks você cria, mas em como você estrutura comportamento, comunicação e recuperação.

RTOS sem padrões é apenas concorrência.
RTOS com padrões é engenharia.

Os padrões apresentados aqui não são teóricos: eles surgiram de sistemas industriais, médicos, automotivos e aeroespaciais, e quando aplicados corretamente, reduzem drasticamente:

• Bugs intermitentes
• Tempo de depuração
• Retrabalho arquitetural
• Risco em produção

The post Padrões de Projeto Aplicados a RTOS (FreeRTOS) first appeared on MCU & FPGA.

Introdução geral

Em sistemas embarcados com RTOS, especialmente em aplicações industriais, automotivas e IoT crítico, o maior desafio não é apenas “fazer funcionar”, mas manter previsibilidade temporal, escalabilidade e manutenibilidade. É nesse ponto que os padrões de projeto aplicados a RTOS se tornam fundamentais.

Diferente de aplicações desktop, padrões em RTOS precisam respeitar restrições de tempo real, uso determinístico de memória, prioridades, latência de interrupções e sincronização segura entre contexto de ISR e tarefas. Muitos padrões clássicos de software são adaptados ou reinterpretados nesse contexto.

Neste artigo, começaremos pelos padrões estruturais básicos de tarefas, que formam a fundação de praticamente qualquer sistema com FreeRTOS.

Padrões Fundamentais de Estruturação de Tarefas

1.1 Superloop + Tasks (Incremental RTOS Adoption)

Problema resolvido:
Projetos legados em superloop (while(1)) tornam-se difíceis de manter à medida que crescem. Migrar tudo de uma vez para RTOS é arriscado.

Ideia do padrão:
Manter o superloop como uma tarefa principal, introduzindo gradualmente novas tarefas RTOS.

Quando usar:

• Migração de firmware bare-metal para FreeRTOS
• Sistemas simples que estão crescendo
• Prototipação controlada

Estrutura típica:

void LegacySuperloopTask(void *pvParameters)
{
    for (;;)
    {
        ReadSensors();
        ProcessData();
        UpdateOutputs();

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

void LegacySuperloopTask(void *pvParameters)
{
    for (;;)
    {
        ReadSensors();
        ProcessData();
        UpdateOutputs();

        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

xTaskCreate(
    LegacySuperloopTask,
    "Legacy",
    1024,
    NULL,
    tskIDLE_PRIORITY + 1,
    NULL
);

xTaskCreate(
    LegacySuperloopTask,
    "Legacy",
    1024,
    NULL,
    tskIDLE_PRIORITY + 1,
    NULL
);

Vantagens:

• Baixo risco na migração
• Preserva código validado
• Facilita testes incrementais

Risco comum:
Transformar essa tarefa em um “monstro” que ignora o espírito do RTOS. Este padrão deve ser transitório, não permanente.

1.2 One Task Per Responsibility (Uma tarefa por responsabilidade)

Problema resolvido:
Tarefas que fazem “de tudo” dificultam análise temporal, debugging e escalonamento.

Ideia do padrão:
Cada tarefa possui uma única responsabilidade funcional bem definida.

Exemplo típico em FreeRTOS:

• Task de aquisição
• Task de processamento
• Task de comunicação

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        ReadADC();
        xTaskNotify(ProcessTaskHandle, 0, eNoAction);
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

void SensorTask(void *pvParameters)
{
    for (;;)
    {
        ReadADC();
        xTaskNotify(ProcessTaskHandle, 0, eNoAction);
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

void ProcessTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        FilterData();
        ComputeResults();
    }
}

void ProcessTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        FilterData();
        ComputeResults();
    }
}

Vantagens:

• Facilita análise de prioridades
• Reduz acoplamento
• Favorece paralelismo real

Boas práticas:

• Nomear tarefas claramente
• Documentar WCET (Worst Case Execution Time)
• Evitar bloqueios longos

1.3 Cyclic Executive com RTOS

Problema resolvido:
Algumas aplicações precisam de periodicidade rígida, mesmo usando RTOS.

Ideia do padrão:
Uma tarefa de alta prioridade atua como orquestrador temporal, liberando outras tarefas de forma cíclica.

Estrutura conceitual:

• Task cíclica principal
• Subtarefas acionadas por notificações

void CyclicTask(void *pvParameters)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();

    for (;;)
    {
        xTaskNotify(TaskAHandle, 0, eNoAction);
        xTaskNotify(TaskBHandle, 0, eNoAction);

        vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(10));
    }
}

void CyclicTask(void *pvParameters)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();

    for (;;)
    {
        xTaskNotify(TaskAHandle, 0, eNoAction);
        xTaskNotify(TaskBHandle, 0, eNoAction);

        vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(10));
    }
}

Vantagens:

• Controle temporal explícito
• Previsibilidade elevada
• Útil em controle e automação

Limitação:
Menos flexível que arquiteturas puramente orientadas a eventos.

1.4 Idle Task como Padrão Arquitetural

Problema resolvido:
Desperdício de CPU e energia quando o sistema está ocioso.

Ideia do padrão:
Usar a Idle Task como ponto central para:

• Economia de energia
• Limpeza de recursos
• Instrumentação

void vApplicationIdleHook(void)
{
    EnterLowPowerMode();
}

void vApplicationIdleHook(void)
{
    EnterLowPowerMode();
}

Uso típico:

• __WFI() em Cortex-M
• Estatísticas de CPU
• Monitoramento de heap

Importante:
Nunca bloquear, nunca usar delays e nunca acessar recursos não protegidos.

The post Padrões de Projeto Aplicados a RTOS (FreeRTOS) first appeared on MCU & FPGA.

A combinação do FreeRTOS com a pilha de rede lwIP (Lightweight IP) é hoje uma das arquiteturas mais comuns em sistemas embarcados conectados, especialmente em microcontroladores Cortex-M (STM32, NXP, RP2040 com stack externa, ESP32 quando abstraído), onde há restrição severa de memória, tempo real e consumo energético. O FreeRTOS fornece o modelo concorrente determinístico (tarefas, prioridades, sincronização), enquanto o lwIP entrega uma implementação enxuta da pilha TCP/IP, compatível com IPv4, IPv6, TCP, UDP, ICMP, ARP, DHCP, DNS e HTTP, entre outros protocolos.

O ponto crítico — e frequentemente negligenciado — é que o lwIP não é apenas uma biblioteca de rede, mas sim um framework cooperativo que precisa ser corretamente integrado ao modelo de execução do RTOS. Dependendo da configuração (RAW API, Netconn API ou BSD Sockets API), o lwIP pode operar de forma event-driven, thread-safe ou thread-aware, exigindo decisões arquiteturais bem fundamentadas. Uma escolha inadequada costuma resultar em deadlocks, stack overflow, perda de pacotes, latências imprevisíveis ou até hard faults difíceis de diagnosticar.

Em sistemas com FreeRTOS, o lwIP normalmente é encapsulado em uma ou mais tarefas dedicadas, além de callbacks executados a partir de interrupções (ETH IRQ, DMA RX/TX) ou timers de software. Isso cria um ambiente híbrido onde código de interrupção, tarefas e a pilha TCP/IP precisam cooperar com rigor: uso correto de semáforos, mutexes, mailboxes (queues), buffers e prioridades. O entendimento dessa interação é essencial para construir aplicações robustas como servidores HTTP, MQTT brokers/clients, WebSockets, OTA, Modbus/TCP, Profinet sobre TCP/IP, entre outras.

Nesta série de artigos, este material assume um cenário típico e realista:

• FreeRTOS rodando como sistema operacional principal
• lwIP configurado com TCP/IP thread dedicada
• Interface Ethernet (MAC + PHY) ou driver de rede equivalente
• Comunicação entre tarefas da aplicação e a pilha de rede
• Ênfase em boas práticas, arquitetura correta e exemplos práticos em C

Nas próximas seções, vamos avançar progressivamente, começando pela arquitetura interna do lwIP quando integrado ao FreeRTOS, passando pelas formas de integração (RAW, Netconn e Sockets), até chegar a exemplos completos como servidor HTTP, cliente TCP e sincronização entre tarefas da aplicação e a pilha de rede.

Arquitetura do lwIP em sistemas com FreeRTOS

Quando o lwIP é integrado a um sistema com FreeRTOS, ele deixa de ser apenas uma pilha TCP/IP “passiva” e passa a fazer parte ativa do modelo concorrente do sistema. O ponto central dessa arquitetura é a chamada TCP/IP thread (normalmente criada por tcpip_init()), que se torna o contexto exclusivo e soberano para quase todas as operações internas do lwIP. Isso significa que estruturas críticas como PCB (Protocol Control Blocks), buffers pbuf, timers TCP e estados de conexão não são thread-safe por padrão e devem ser manipulados apenas dentro desse contexto controlado.

Na prática, o lwIP organiza seu funcionamento em três grandes domínios de execução: interrupções de hardware, TCP/IP thread e tarefas da aplicação. As interrupções normalmente vêm do driver Ethernet (IRQ do MAC ou DMA RX/TX), cujo papel é mínimo: sinalizar que há pacotes recebidos ou buffers liberados, evitando qualquer processamento pesado. Essas interrupções acordam a TCP/IP thread por meio de semaphores ou mailboxes, garantindo que todo o processamento de protocolos ocorra fora do contexto de ISR, preservando determinismo e estabilidade do sistema.

A TCP/IP thread funciona como um dispatcher de eventos de rede. Ela processa pacotes recebidos, executa timers periódicos (TCP retransmission, ARP aging, DHCP renewal), gerencia conexões e chama callbacks registrados pela aplicação. É aqui que reside uma armadilha comum: callbacks do lwIP não executam no contexto da task da aplicação, mas sim dentro da TCP/IP thread. Isso exige extremo cuidado ao acessar recursos compartilhados, como filas do FreeRTOS, buffers globais ou drivers de periféricos, sob pena de criar condições de corrida difíceis de rastrear.

As tarefas da aplicação, por sua vez, nunca devem acessar diretamente estruturas internas do lwIP, exceto quando se utiliza APIs explicitamente thread-safe (como Netconn ou Sockets). Quando a arquitetura é bem desenhada, as tasks da aplicação se comunicam com a TCP/IP thread usando mensagens, filas ou chamadas assíncronas, mantendo uma separação clara entre lógica de negócio e infraestrutura de rede. Esse desacoplamento é um dos fatores-chave para escalabilidade e manutenibilidade do firmware.

Do ponto de vista conceitual, pense no lwIP como um ator central que serializa todo o tráfego de rede, enquanto o FreeRTOS fornece o orquestrador de concorrência ao redor dele. Quando esse modelo é respeitado, o sistema se comporta de forma previsível mesmo sob carga elevada de rede. Quando é violado — por exemplo, chamando funções RAW do lwIP a partir de tasks arbitrárias — os sintomas surgem como bugs intermitentes, travamentos aleatórios ou degradação severa de desempenho.

Na próxima seção, vamos entrar em um dos pontos mais críticos e confusos para quem trabalha com lwIP:
as três APIs disponíveis (RAW API, Netconn API e BSD Sockets API), explicando quando usar cada uma, suas vantagens, limitações e impactos diretos na arquitetura FreeRTOS.

As APIs do lwIP no contexto do FreeRTOS: RAW, Netconn e Sockets

Um dos pontos que mais geram confusão — e erros arquiteturais — no uso do lwIP com FreeRTOS é a existência de três APIs distintas, cada uma com modelos mentais, custos e implicações completamente diferentes. A escolha da API não é apenas uma questão de preferência sintática; ela define como as tasks interagem com a pilha TCP/IP, quais garantias de thread-safety existem e qual será o impacto em latência, uso de memória e complexidade do sistema.

A RAW API é a forma mais direta e eficiente de usar o lwIP. Ela é totalmente event-driven, baseada em callbacks, e opera exclusivamente no contexto da TCP/IP thread. Não existe bloqueio, não existem semáforos implícitos, nem cópia adicional de buffers. Cada evento de rede — conexão estabelecida, dados recebidos, erro ou fechamento — dispara uma função de callback registrada previamente. Isso torna a RAW API ideal para sistemas com restrições severas de RAM e tempo real rígido, mas ao custo de maior complexidade cognitiva. Em sistemas FreeRTOS, a RAW API não deve ser chamada diretamente a partir de tasks da aplicação; qualquer interação precisa ser mediada por mensagens ou funções como tcpip_callback().

Já a Netconn API atua como uma camada intermediária entre a RAW API e o modelo tradicional de threads. Ela encapsula a lógica baseada em callbacks dentro de uma API bloqueante e thread-safe, usando mailboxes e semaphores internos. Para o desenvolvedor FreeRTOS, isso significa poder escrever código sequencial — netconn_accept(), netconn_recv(), netconn_write() — dentro de uma task, sem violar as regras internas do lwIP. O custo disso é um pequeno aumento de consumo de memória e latência, além de menos controle fino sobre eventos de baixo nível. Em projetos industriais, a Netconn API costuma ser um equilíbrio muito saudável entre robustez e simplicidade.

A BSD Sockets API, por sua vez, é a mais familiar para quem vem do mundo Linux ou POSIX. Ela oferece funções como socket(), bind(), listen(), accept(), recv() e send(), com semântica muito próxima à de sistemas operacionais completos. Internamente, ela é construída sobre a Netconn API, herdando suas características e custos. Em FreeRTOS, a Sockets API facilita a portabilidade de código legado e acelera o desenvolvimento inicial, mas frequentemente induz a arquiteturas pobres, com tasks bloqueantes demais, pilha grande e baixa previsibilidade temporal se não for bem planejada.

A decisão correta normalmente segue este raciocínio: se o sistema é altamente restrito e orientado a eventos, use RAW API; se precisa de clareza, robustez e integração limpa com FreeRTOS, use Netconn; se o foco é portabilidade e velocidade de desenvolvimento, a Sockets API pode ser aceitável — desde que o impacto em recursos seja cuidadosamente controlado. Em sistemas críticos, misturar APIs sem critério é uma receita certa para problemas difíceis de depurar.

Na próxima seção, vamos aprofundar exatamente como o FreeRTOS e o lwIP se comunicam internamente, explorando mailboxes, semaphores, timers e a função tcpip_init(), com diagramas conceituais e exemplos práticos em C.

Integração interna entre FreeRTOS e lwIP: mailboxes, semáforos e tcpip_init()

A espinha dorsal da integração entre FreeRTOS e lwIP é o mecanismo de mensagens assíncronas que garante que todo o processamento da pilha TCP/IP ocorra em um único contexto controlado. Esse contexto é criado pela chamada a tcpip_init(), responsável por inicializar o lwIP e criar a TCP/IP thread, além de suas estruturas de sincronização internas. Entender exatamente o que acontece aqui é essencial para evitar violações de thread-safety e erros sutis de concorrência.

Quando tcpip_init() é chamada, o lwIP cria internamente uma task do FreeRTOS (normalmente chamada de tcpip_thread) e associa a ela uma mailbox principal. Essa mailbox funciona como uma fila de mensagens do RTOS, por onde chegam eventos como pacotes recebidos, timers expirados ou callbacks solicitados por outras tasks. O modelo é deliberadamente serial: a TCP/IP thread processa uma mensagem por vez, garantindo que as estruturas internas do lwIP nunca sejam acessadas concorrentemente.

As interrupções de rede (por exemplo, RX DMA do Ethernet MAC) não processam protocolos diretamente. Em vez disso, elas apenas notificam o sistema — geralmente liberando um semáforo ou enviando um ponteiro de buffer para uma mailbox. O driver Ethernet, então, acorda a TCP/IP thread, que passa a processar os pacotes no contexto correto. Esse desenho é fundamental para manter latência previsível e evitar execução de código pesado em ISR, algo especialmente crítico em sistemas com FreeRTOS.

Para permitir que tasks da aplicação interajam com o lwIP sem violar esse modelo, o lwIP fornece funções como tcpip_callback() e tcpip_try_callback(). Essas funções permitem que uma task qualquer solicite a execução de uma função dentro da TCP/IP thread, de forma assíncrona. Esse padrão é a base de arquiteturas seguras quando se utiliza a RAW API, pois impede acessos diretos às estruturas internas da pilha a partir de múltiplos contextos.

A Netconn e a Sockets API se apoiam nesse mesmo mecanismo, mas encapsulam toda essa complexidade. Quando uma task chama netconn_recv(), por exemplo, o que acontece por baixo dos panos é um diálogo entre mailboxes internas, semáforos e a TCP/IP thread. A task da aplicação fica bloqueada de forma controlada, enquanto o lwIP continua operando normalmente. Isso explica por que essas APIs são thread-safe, mas também por que consomem mais RAM e stack.

Um erro clássico em projetos é tentar “otimizar” esse fluxo acessando diretamente buffers, chamando funções RAW a partir de tasks comuns ou usando mutexes do FreeRTOS para proteger estruturas do lwIP. Essa abordagem não funciona e quebra premissas internas do stack. O modelo correto não é proteger o lwIP com mutexes, mas respeitar o confinamento de contexto imposto pela TCP/IP thread.

Na próxima seção, vamos aplicar esses conceitos de forma concreta, construindo um exemplo prático de inicialização do lwIP com FreeRTOS, incluindo criação de tarefas, configuração do driver Ethernet e verificação do fluxo de dados.

Exemplo prático: inicialização do lwIP em um sistema FreeRTOS

Nesta seção vamos sair do plano conceitual e entrar no código real, mostrando como um sistema típico FreeRTOS + lwIP é inicializado. O objetivo aqui não é apenas “fazer funcionar”, mas entender por que cada passo existe, qual o contexto de execução envolvido e quais são os erros clássicos que devem ser evitados.

Assumiremos um cenário bastante comum em projetos industriais:

• FreeRTOS já inicializado
• Interface Ethernet com driver próprio (MAC + PHY)
• lwIP configurado para uso com TCP/IP thread dedicada
• Uso futuro de Netconn ou Sockets API

5.1 Ordem correta de inicialização

A ordem de inicialização é crítica. Um erro frequente é criar tasks de aplicação que usam rede antes do lwIP estar totalmente operacional.

A sequência correta, em alto nível, é:

1. Inicializar hardware básico (clock, GPIO, PHY, MAC)
2. Inicializar o lwIP (tcpip_init)
3. Configurar interface de rede (netif)
4. Subir a interface (netif_set_up)
5. Só então criar tasks da aplicação que usam rede
6. Iniciar o scheduler do FreeRTOS

Essa ordem garante que nenhuma task tente acessar a pilha TCP/IP fora do contexto correto.

5.2 Inicializando o lwIP (tcpip_init)

O primeiro ponto de integração direta entre FreeRTOS e lwIP é a chamada a tcpip_init():

#include "lwip/tcpip.h"

static void lwip_init_done(void *arg)
{
    /* Callback chamado quando a TCP/IP thread está pronta */
    (void)arg;
}

void lwip_stack_init(void)
{
    tcpip_init(lwip_init_done, NULL);
}

#include "lwip/tcpip.h"

static void lwip_init_done(void *arg)
{
    /* Callback chamado quando a TCP/IP thread está pronta */
    (void)arg;
}

void lwip_stack_init(void)
{
    tcpip_init(lwip_init_done, NULL);
}

O que acontece aqui, de fato:

• O lwIP cria internamente a TCP/IP thread como uma task do FreeRTOS
• São criadas mailboxes internas para troca de mensagens
• Timers internos do TCP/IP são registrados
• O callback lwip_init_done() é executado no contexto da TCP/IP thread, não na task chamadora

Esse detalhe é importante: qualquer código executado nesse callback já está em um contexto seguro para chamadas RAW, caso necessário.

5.3 Configuração da interface de rede (netif)

Após a inicialização do lwIP, precisamos registrar a interface de rede:

#include "lwip/netif.h"
#include "lwip/ip_addr.h"
#include "lwip/dhcp.h"

static struct netif netif_eth;

void netif_config(void)
{
    ip4_addr_t ipaddr;
    ip4_addr_t netmask;
    ip4_addr_t gw;

    IP4_ADDR(&ipaddr, 0, 0, 0, 0);   /* DHCP */
    IP4_ADDR(&netmask, 0, 0, 0, 0);
    IP4_ADDR(&gw, 0, 0, 0, 0);

    netif_add(&netif_eth,
              &ipaddr,
              &netmask,
              &gw,
              NULL,
              ethernetif_init,
              tcpip_input);

    netif_set_default(&netif_eth);
    netif_set_up(&netif_eth);

    dhcp_start(&netif_eth);
}

#include "lwip/netif.h"
#include "lwip/ip_addr.h"
#include "lwip/dhcp.h"

static struct netif netif_eth;

void netif_config(void)
{
    ip4_addr_t ipaddr;
    ip4_addr_t netmask;
    ip4_addr_t gw;

    IP4_ADDR(&ipaddr, 0, 0, 0, 0);   /* DHCP */
    IP4_ADDR(&netmask, 0, 0, 0, 0);
    IP4_ADDR(&gw, 0, 0, 0, 0);

    netif_add(&netif_eth,
              &ipaddr,
              &netmask,
              &gw,
              NULL,
              ethernetif_init,
              tcpip_input);

    netif_set_default(&netif_eth);
    netif_set_up(&netif_eth);

    dhcp_start(&netif_eth);
}

Aqui aparecem alguns pontos arquiteturais importantes:

• ethernetif_init é o driver de baixo nível, responsável por integrar MAC/PHY ao lwIP
• tcpip_input garante que pacotes recebidos sejam entregues à TCP/IP thread, e não processados no contexto errado
• O uso de DHCP é opcional, mas comum em sistemas conectados

Essa função normalmente é chamada após tcpip_init() e antes da criação das tasks de aplicação.

5.4 Criação das tasks da aplicação

Somente depois que a pilha está pronta é que criamos tasks que usam rede:

void network_task(void *argument)
{
    /* A partir daqui, é seguro usar Netconn ou Sockets API */
    for (;;)
    {
        /* Lógica de rede */
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void app_start(void)
{
    xTaskCreate(network_task,
                "NetTask",
                1024,
                NULL,
                tskIDLE_PRIORITY + 2,
                NULL);
}

void network_task(void *argument)
{
    /* A partir daqui, é seguro usar Netconn ou Sockets API */
    for (;;)
    {
        /* Lógica de rede */
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void app_start(void)
{
    xTaskCreate(network_task,
                "NetTask",
                1024,
                NULL,
                tskIDLE_PRIORITY + 2,
                NULL);
}

Note que:

• A task não interage diretamente com estruturas RAW
• O tamanho da stack já precisa considerar buffers de rede
• A prioridade deve ser pensada em conjunto com a TCP/IP thread

Um erro comum é dar prioridade muito baixa para a TCP/IP thread e alta para tasks de aplicação, o que resulta em timeouts, perda de pacotes e conexões instáveis.

5.5 Erros clássicos nesta fase

Alguns problemas recorrentes que surgem exatamente nesse ponto:

• Criar sockets antes do netif_set_up
• Chamar funções RAW a partir de tasks comuns
• Executar processamento pesado no driver Ethernet (ISR)
• Stack insuficiente para tasks de rede
• Prioridade inadequada da TCP/IP thread

Todos esses erros levam a sintomas difíceis de diagnosticar, como travamentos aleatórios ou falhas intermitentes de comunicação.

Na próxima seção, vamos construir um exemplo completo de servidor TCP/HTTP, mostrando como uma task FreeRTOS usa a Netconn ou Sockets API corretamente, com explicação detalhada de cada chamada.

Exemplo completo: servidor TCP usando Sockets API em uma task FreeRTOS

Aqui vamos montar um servidor TCP simples (estilo “echo server” + base para HTTP) rodando em uma task do FreeRTOS usando a BSD Sockets API do lwIP. A ideia é te dar um esqueleto real que funciona em 80% dos firmwares conectados: uma task aceita conexões, recebe dados, responde e fecha. Em seguida, vou apontar onde normalmente você evolui para HTTP, MQTT, Modbus/TCP etc.

6.1 Requisitos e premissas

Para usar Sockets no lwIP você normalmente precisa ter (no lwipopts.h):

• LWIP_SOCKET=1
• LWIP_NETCONN=1 (sockets geralmente dependem dela)
• LWIP_TCP=1
• LWIP_DNS=1 (se quiser resolver nomes)
• LWIP_DHCP=1 (se usar DHCP)

E lembrar do modelo: a task de sockets é sua, mas o lwIP continua processando rede na TCP/IP thread.

6.2 Código do servidor TCP (com comentários didáticos)

#include "FreeRTOS.h"
#include "task.h"

#include "lwip/sockets.h"
#include "lwip/inet.h"
#include <string.h>
#include <stdio.h>

/* Ajuste conforme sua aplicação */
#define SERVER_PORT     5000
#define RX_BUF_SIZE     1024
#define LISTEN_BACKLOG  4

static void tcp_server_task(void *arg)
{
    (void)arg;

    int listen_fd = -1;
    int client_fd = -1;

    struct sockaddr_in addr;
    struct sockaddr_in client_addr;
    socklen_t client_len = sizeof(client_addr);

    /* Buffer local: cuidado com stack! */
    char rx_buf[RX_BUF_SIZE];

    /* 1) Criar socket TCP */
    listen_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (listen_fd < 0) {
        /* Em sistemas embarcados: logue e reinicie a task ou sinalize falha */
        vTaskDelete(NULL);
    }

    /* 2) Preencher estrutura de endereço */
    memset(&addr, 0, sizeof(addr));
    addr.sin_family = AF_INET;
    addr.sin_port = htons(SERVER_PORT);
    addr.sin_addr.s_addr = htonl(INADDR_ANY); /* escuta em todas interfaces */

    /* 3) Bind: amarra o socket à porta */
    if (bind(listen_fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    /* 4) Listen: coloca em modo servidor */
    if (listen(listen_fd, LISTEN_BACKLOG) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    for (;;)
    {
        /* 5) Accept: bloqueia esperando cliente */
        client_fd = accept(listen_fd, (struct sockaddr *)&client_addr, &client_len);
        if (client_fd < 0) {
            /* Se accept falhar, normalmente você continua tentando */
            vTaskDelay(pdMS_TO_TICKS(100));
            continue;
        }

        /* 6) Loop de recepção */
        for (;;)
        {
            int n = recv(client_fd, rx_buf, sizeof(rx_buf) - 1, 0);
            if (n <= 0) {
                /* n == 0 -> cliente fechou; n < 0 -> erro */
                break;
            }

            rx_buf[n] = '\0';

            /* 7) Aqui entra a lógica da aplicação.
                  Para um echo server: devolve os bytes recebidos. */
            send(client_fd, rx_buf, n, 0);

            /* Exemplo: se quiser encerrar ao receber "quit" */
            if (strncmp(rx_buf, "quit", 4) == 0) {
                break;
            }
        }

        /* 8) Fecha conexão do cliente */
        closesocket(client_fd);
        client_fd = -1;
    }
}

/* Função de arranque */
void start_tcp_server(void)
{
    /* Stack precisa ser dimensionada: sockets + buffer local */
    xTaskCreate(tcp_server_task,
                "TCPServer",
                2048,                  /* ajuste real conforme seu MCU/heap */
                NULL,
                tskIDLE_PRIORITY + 2,  /* prioridade média */
                NULL);
}

#include "FreeRTOS.h"
#include "task.h"

#include "lwip/sockets.h"
#include "lwip/inet.h"
#include <string.h>
#include <stdio.h>

/* Ajuste conforme sua aplicação */
#define SERVER_PORT     5000
#define RX_BUF_SIZE     1024
#define LISTEN_BACKLOG  4

static void tcp_server_task(void *arg)
{
    (void)arg;

    int listen_fd = -1;
    int client_fd = -1;

    struct sockaddr_in addr;
    struct sockaddr_in client_addr;
    socklen_t client_len = sizeof(client_addr);

    /* Buffer local: cuidado com stack! */
    char rx_buf[RX_BUF_SIZE];

    /* 1) Criar socket TCP */
    listen_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (listen_fd < 0) {
        /* Em sistemas embarcados: logue e reinicie a task ou sinalize falha */
        vTaskDelete(NULL);
    }

    /* 2) Preencher estrutura de endereço */
    memset(&addr, 0, sizeof(addr));
    addr.sin_family = AF_INET;
    addr.sin_port = htons(SERVER_PORT);
    addr.sin_addr.s_addr = htonl(INADDR_ANY); /* escuta em todas interfaces */

    /* 3) Bind: amarra o socket à porta */
    if (bind(listen_fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    /* 4) Listen: coloca em modo servidor */
    if (listen(listen_fd, LISTEN_BACKLOG) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    for (;;)
    {
        /* 5) Accept: bloqueia esperando cliente */
        client_fd = accept(listen_fd, (struct sockaddr *)&client_addr, &client_len);
        if (client_fd < 0) {
            /* Se accept falhar, normalmente você continua tentando */
            vTaskDelay(pdMS_TO_TICKS(100));
            continue;
        }

        /* 6) Loop de recepção */
        for (;;)
        {
            int n = recv(client_fd, rx_buf, sizeof(rx_buf) - 1, 0);
            if (n <= 0) {
                /* n == 0 -> cliente fechou; n < 0 -> erro */
                break;
            }

            rx_buf[n] = '\0';

            /* 7) Aqui entra a lógica da aplicação.
                  Para um echo server: devolve os bytes recebidos. */
            send(client_fd, rx_buf, n, 0);

            /* Exemplo: se quiser encerrar ao receber "quit" */
            if (strncmp(rx_buf, "quit", 4) == 0) {
                break;
            }
        }

        /* 8) Fecha conexão do cliente */
        closesocket(client_fd);
        client_fd = -1;
    }
}

/* Função de arranque */
void start_tcp_server(void)
{
    /* Stack precisa ser dimensionada: sockets + buffer local */
    xTaskCreate(tcp_server_task,
                "TCPServer",
                2048,                  /* ajuste real conforme seu MCU/heap */
                NULL,
                tskIDLE_PRIORITY + 2,  /* prioridade média */
                NULL);
}

6.3 Pontos críticos (onde a maioria erra)

A primeira armadilha é stack. Repare que rx_buf[1024] está na stack da task. Em Cortex-M, 2 KB de stack pode ficar apertado se você começar a montar respostas HTTP grandes, fazer parsing pesado ou usar printf. Uma prática robusta é mover buffers grandes para heap/estático e deixar stack para variáveis pequenas.

A segunda armadilha é bloqueio infinito. accept() e recv() bloqueiam. Isso pode ser OK em um servidor dedicado, mas se você precisa de shutdown limpo, watchdog cooperativo ou multiplexar atividades, você vai querer timeouts via setsockopt() com SO_RCVTIMEO e SO_SNDTIMEO, ou usar select() para multiplexar.

A terceira armadilha é “fazer tudo nessa task”. Em firmware sério, o servidor de sockets vira um front-end que entrega payloads para outras tasks via queues (produtor/consumidor), mantendo o servidor leve e previsível. Caso contrário, você mistura rede + lógica de negócio + acesso a periféricos no mesmo contexto e cria latência ruim e travamentos em cascata.

6.4 Melhorando com timeouts (essencial para robustez)

Um exemplo direto para evitar travar em recv():

struct timeval tv;
tv.tv_sec = 5;
tv.tv_usec = 0;
setsockopt(client_fd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));

struct timeval tv;
tv.tv_sec = 5;
tv.tv_usec = 0;
setsockopt(client_fd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));

Com isso, recv() retorna erro após 5 s sem dados, e você pode encerrar a conexão ou apenas continuar.

Na próxima seção, vamos fazer exatamente o que transforma esse exemplo em arquitetura “de produção”:

• Task de sockets como Gatekeeper
• Entrega de dados para uma fila FreeRTOS
• Um ou mais consumidores processando requisições
• Resposta retornando ao cliente de forma segura

Arquitetura de produção: servidor de sockets como Gatekeeper + filas FreeRTOS (produtor/consumidor)

Quando você coloca lwIP + FreeRTOS em um produto real, a pergunta não é “como abrir um socket”, mas sim: como garantir previsibilidade, isolamento de falhas e escalabilidade quando há múltiplas conexões, parsing de protocolo, acesso a periféricos e regras de negócio rodando ao mesmo tempo. O padrão mais sólido aqui é tratar a task de rede como um Gatekeeper (porteiro): ela faz o mínimo necessário (I/O de rede e framing básico), empacota mensagens e entrega para a aplicação via Queue. As tasks de aplicação, por sua vez, consomem essas mensagens e devolvem respostas por um caminho igualmente controlado.

A razão técnica é simples: a pilha de rede precisa de tempo de CPU para manter conexões (ACKs, retransmissões, janelas TCP), e isso pode ser prejudicado se você faz parsing pesado, acesso a flash, escrita em SD, controle de motores ou logs complexos dentro da mesma task que está segurando o socket. Além disso, erros na lógica de negócio não podem derrubar a infraestrutura de rede. Com Gatekeeper + filas, você desacopla os domínios: rede continua estável, aplicação pode reiniciar tasks de processamento, e o sistema ganha uma arquitetura “defensiva”.

A seguir, vamos montar um exemplo funcional e didático. Ele não é “o menor possível”: ele é “o mais correto possível” para firmware.

7.1 Estruturas de mensagem e filas

Vamos definir duas filas:

• rxQueue: mensagens recebidas da rede para a aplicação
• txQueue: respostas da aplicação para serem transmitidas pela task de rede

Cada mensagem precisa carregar, no mínimo:

• identificador da conexão (socket do cliente ou um handle abstrato)
• payload (bytes recebidos)
• tamanho
• metadados (opcional: IP/porta, timestamp etc.)

#include "FreeRTOS.h"
#include "queue.h"
#include <stdint.h>

#define MAX_PAYLOAD 512

typedef struct
{
    int client_fd;                 /* Identifica a conexão */
    uint16_t len;
    uint8_t payload[MAX_PAYLOAD];  /* Mensagem "copiada" para trânsito seguro */
} NetMessage_t;

static QueueHandle_t rxQueue;
static QueueHandle_t txQueue;

void net_queues_init(void)
{
    rxQueue = xQueueCreate(8, sizeof(NetMessage_t));
    txQueue = xQueueCreate(8, sizeof(NetMessage_t));
}

#include "FreeRTOS.h"
#include "queue.h"
#include <stdint.h>

#define MAX_PAYLOAD 512

typedef struct
{
    int client_fd;                 /* Identifica a conexão */
    uint16_t len;
    uint8_t payload[MAX_PAYLOAD];  /* Mensagem "copiada" para trânsito seguro */
} NetMessage_t;

static QueueHandle_t rxQueue;
static QueueHandle_t txQueue;

void net_queues_init(void)
{
    rxQueue = xQueueCreate(8, sizeof(NetMessage_t));
    txQueue = xQueueCreate(8, sizeof(NetMessage_t));
}

Observação crítica: aqui estamos usando cópia de payload. Em sistemas mais exigentes, você pode migrar para zero-copy com pbuf (RAW API) ou pool de buffers. Mas começar com cópia é geralmente a forma mais estável de construir algo robusto e debugar rápido.

7.2 Task Gatekeeper: recebe do socket e entrega na rxQueue

A task de rede agora vira uma “central de I/O”: aceita conexões, recebe dados e empacota mensagens para a fila.

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"

#include "lwip/sockets.h"
#include "lwip/inet.h"
#include <string.h>

#define SERVER_PORT 5000

static void socket_gatekeeper_task(void *arg)
{
    (void)arg;

    int listen_fd;
    struct sockaddr_in addr;

    listen_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (listen_fd < 0) vTaskDelete(NULL);

    memset(&addr, 0, sizeof(addr));
    addr.sin_family = AF_INET;
    addr.sin_port = htons(SERVER_PORT);
    addr.sin_addr.s_addr = htonl(INADDR_ANY);

    if (bind(listen_fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    if (listen(listen_fd, 4) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    for (;;)
    {
        int client_fd = accept(listen_fd, NULL, NULL);
        if (client_fd < 0) {
            vTaskDelay(pdMS_TO_TICKS(50));
            continue;
        }

        /* Exemplo simples: atende 1 cliente por vez.
           Em produção você pode criar uma task por cliente OU usar select(). */
        for (;;)
        {
            NetMessage_t msg;
            int n = recv(client_fd, msg.payload, MAX_PAYLOAD, 0);
            if (n <= 0) break;

            msg.client_fd = client_fd;
            msg.len = (uint16_t)n;

            /* Entrega para aplicação: se a fila estiver cheia, você precisa decidir política:
               - descartar
               - bloquear por tempo limitado
               - desconectar cliente
            */
            if (xQueueSend(rxQueue, &msg, pdMS_TO_TICKS(20)) != pdPASS) {
                /* Política simples: descarta e segue */
            }

            /* Antes de receber mais, veja se há resposta pronta para este cliente */
            NetMessage_t out;
            if (xQueueReceive(txQueue, &out, 0) == pdPASS) {
                if (out.client_fd == client_fd && out.len > 0) {
                    send(client_fd, out.payload, out.len, 0);
                } else {
                    /* Se veio resposta de outro cliente, em produção você
                       rotearia corretamente (mapa de conexões, etc.) */
                }
            }
        }

        closesocket(client_fd);
    }
}

void start_socket_gatekeeper(void)
{
    xTaskCreate(socket_gatekeeper_task,
                "NetGate",
                2048,
                NULL,
                tskIDLE_PRIORITY + 3, /* Um pouco acima da aplicação */
                NULL);
}

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"

#include "lwip/sockets.h"
#include "lwip/inet.h"
#include <string.h>

#define SERVER_PORT 5000

static void socket_gatekeeper_task(void *arg)
{
    (void)arg;

    int listen_fd;
    struct sockaddr_in addr;

    listen_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (listen_fd < 0) vTaskDelete(NULL);

    memset(&addr, 0, sizeof(addr));
    addr.sin_family = AF_INET;
    addr.sin_port = htons(SERVER_PORT);
    addr.sin_addr.s_addr = htonl(INADDR_ANY);

    if (bind(listen_fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    if (listen(listen_fd, 4) < 0) {
        closesocket(listen_fd);
        vTaskDelete(NULL);
    }

    for (;;)
    {
        int client_fd = accept(listen_fd, NULL, NULL);
        if (client_fd < 0) {
            vTaskDelay(pdMS_TO_TICKS(50));
            continue;
        }

        /* Exemplo simples: atende 1 cliente por vez.
           Em produção você pode criar uma task por cliente OU usar select(). */
        for (;;)
        {
            NetMessage_t msg;
            int n = recv(client_fd, msg.payload, MAX_PAYLOAD, 0);
            if (n <= 0) break;

            msg.client_fd = client_fd;
            msg.len = (uint16_t)n;

            /* Entrega para aplicação: se a fila estiver cheia, você precisa decidir política:
               - descartar
               - bloquear por tempo limitado
               - desconectar cliente
            */
            if (xQueueSend(rxQueue, &msg, pdMS_TO_TICKS(20)) != pdPASS) {
                /* Política simples: descarta e segue */
            }

            /* Antes de receber mais, veja se há resposta pronta para este cliente */
            NetMessage_t out;
            if (xQueueReceive(txQueue, &out, 0) == pdPASS) {
                if (out.client_fd == client_fd && out.len > 0) {
                    send(client_fd, out.payload, out.len, 0);
                } else {
                    /* Se veio resposta de outro cliente, em produção você
                       rotearia corretamente (mapa de conexões, etc.) */
                }
            }
        }

        closesocket(client_fd);
    }
}

void start_socket_gatekeeper(void)
{
    xTaskCreate(socket_gatekeeper_task,
                "NetGate",
                2048,
                NULL,
                tskIDLE_PRIORITY + 3, /* Um pouco acima da aplicação */
                NULL);
}