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

O Git tornou-se o sistema de controle de versão mais utilizado no desenvolvimento de software moderno. Ele permite que desenvolvedores acompanhem alterações no código, trabalhem em equipe de forma organizada e mantenham histórico detalhado de todas as modificações realizadas em um projeto. No entanto, embora o Git ofereça um conjunto poderoso de ferramentas, seu uso eficaz depende muito da estratégia adotada pela equipe ou pelo desenvolvedor.

Em muitos projetos, especialmente aqueles relacionados a sistemas embarcados, firmware e aplicações críticas, como os que envolvem microcontroladores, RTOS ou arquiteturas distribuídas, a forma como o código é organizado dentro do Git pode impactar diretamente na qualidade do software, na rastreabilidade das mudanças e na capacidade de manutenção do projeto ao longo do tempo.

Uma estratégia bem definida de uso do Git permite resolver diversos problemas comuns no desenvolvimento colaborativo. Entre esses problemas estão conflitos frequentes de código, dificuldade em identificar quando uma funcionalidade foi introduzida, ausência de rastreabilidade entre commits e tarefas de desenvolvimento, e dificuldades para manter versões estáveis do software enquanto novas funcionalidades continuam sendo implementadas.

Ao longo da experiência prática em projetos individuais e também em equipes dentro de empresas, desenvolvi uma abordagem de organização baseada em branches de versões, branches de funcionalidades, uso disciplinado de tags e integração com sistemas de issues, especialmente no GitHub. Essa abordagem busca equilibrar três aspectos fundamentais do desenvolvimento moderno: estabilidade da versão em produção, evolução contínua do software e rastreabilidade completa das alterações realizadas.

Além disso, essa estratégia também considera cenários mais complexos de desenvolvimento, como ambientes onde existem dois repositórios distintos — um para desenvolvimento e outro para produção — e também a necessidade de manter simultaneamente múltiplas versões do software, algo comum em produtos embarcados que permanecem anos no mercado recebendo atualizações incrementais.

Neste artigo será apresentada, de forma didática e detalhada, uma estratégia prática de organização de projetos com Git, incluindo o uso de branches, tags, commits estruturados, integração com issues e organização arquitetural do código. Também serão apresentados os comandos fundamentais do Git necessários para implementar essa estratégia no dia a dia do desenvolvimento.

O objetivo não é apenas explicar os comandos, mas mostrar como construir um fluxo de trabalho que permita manter o projeto organizado, escalável e rastreável, mesmo em projetos grandes ou em equipes distribuídas.

Na próxima seção será apresentada a base dessa estratégia: a organização do repositório a partir do branch principal (Main) e a criação de branches para versões e funcionalidades.

The post Estratégia Profissional de Gestão de Código com Git em Projetos Individuais e em Equipe 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);
}

Por que esse desenho é bom? Porque o Gatekeeper mantém I/O simples e previsível: ele não interpreta protocolo nem acessa hardware. Ele apenas “empurra bytes”.

Crítica (importante): este exemplo atende um cliente por vez. Para múltiplos clientes, as duas opções típicas são:

1. uma task por conexão (mais simples, mas consome RAM/stack)
2. select() com um loop único multiplexando sockets (mais eficiente, mais complexo)

Na próxima seção eu te mostro os dois modelos, mas antes precisamos fechar o ciclo com o consumidor.

7.3 Task consumidora: processa mensagem e devolve resposta

Agora a lógica de aplicação recebe mensagens da rxQueue, interpreta e devolve uma resposta pela txQueue.

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include <string.h>

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

    for (;;)
    {
        NetMessage_t in;
        if (xQueueReceive(rxQueue, &in, portMAX_DELAY) == pdPASS)
        {
            NetMessage_t out;
            memset(&out, 0, sizeof(out));

            out.client_fd = in.client_fd;

            /* Exemplo de "protocolo": comandos ASCII */
            if (in.len >= 4 && memcmp(in.payload, "ping", 4) == 0) {
                const char *resp = "pong\n";
                out.len = (uint16_t)strlen(resp);
                memcpy(out.payload, resp, out.len);
            } else {
                const char *resp = "unknown\n";
                out.len = (uint16_t)strlen(resp);
                memcpy(out.payload, resp, out.len);
            }

            /* Envia resposta para o Gatekeeper transmitir */
            (void)xQueueSend(txQueue, &out, pdMS_TO_TICKS(50));
        }
    }
}

void start_app_worker(void)
{
    xTaskCreate(app_worker_task,
                "AppWorker",
                2048,
                NULL,
                tskIDLE_PRIORITY + 2,
                NULL);
}

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include <string.h>

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

    for (;;)
    {
        NetMessage_t in;
        if (xQueueReceive(rxQueue, &in, portMAX_DELAY) == pdPASS)
        {
            NetMessage_t out;
            memset(&out, 0, sizeof(out));

            out.client_fd = in.client_fd;

            /* Exemplo de "protocolo": comandos ASCII */
            if (in.len >= 4 && memcmp(in.payload, "ping", 4) == 0) {
                const char *resp = "pong\n";
                out.len = (uint16_t)strlen(resp);
                memcpy(out.payload, resp, out.len);
            } else {
                const char *resp = "unknown\n";
                out.len = (uint16_t)strlen(resp);
                memcpy(out.payload, resp, out.len);
            }

            /* Envia resposta para o Gatekeeper transmitir */
            (void)xQueueSend(txQueue, &out, pdMS_TO_TICKS(50));
        }
    }
}

void start_app_worker(void)
{
    xTaskCreate(app_worker_task,
                "AppWorker",
                2048,
                NULL,
                tskIDLE_PRIORITY + 2,
                NULL);
}

Aqui você ganhou algo decisivo: se o parsing for pesado, você pode criar vários workers consumidores (ou uma pool) sem mexer na task de rede. E se um worker travar, você pode reiniciá-lo sem derrubar a rede (principalmente se tiver Task Monitor/Watchdog como você já vem tratando na série).

7.4 Ajustes essenciais para “produção”

O exemplo acima é a forma didática mais direta, mas em firmware real você geralmente aplica melhorias:

• Roteamento de respostas por conexão: em vez de uma txQueue única, você cria uma fila por cliente (ou um mapa de conexões).
• Política de backpressure: se rxQueue enche, você reduz leitura do socket, aplica recv com timeout, ou desconecta cliente.
• Framing: TCP é stream, não pacote. Seu “comando” pode vir partido em múltiplos recv(). Então você implementa framing (por delimitador \n, por tamanho fixo, ou por header com length).
• Stack e heap: payload copiado custa RAM; quando necessário, migra para pool de buffers.

Na próxima seção, vamos atacar exatamente o que separa “demo” de “produto”:
TCP é stream — então precisamos de framing e parser robusto, além de timeouts e manuseio de múltiplos clientes.

TCP é stream: framing robusto + múltiplos clientes (task por conexão vs select())

Se tem um erro conceitual que derruba sistemas FreeRTOS + lwIP “do nada”, é tratar recv() como se cada chamada retornasse uma mensagem completa. TCP não entrega mensagens — entrega um fluxo (stream). Isso significa que um comando ping\n pode chegar como p, depois ing\n, ou pode chegar junto com outro comando colado, ou pode vir com bytes extras. Se você não implementar framing, sua aplicação vai funcionar em bancada e falhar sob carga, ruído de rede, latência variável ou retransmissões.

A solução arquitetural é definir um protocolo com framing claro. Os dois modelos mais comuns em firmware são: (1) delimitador (por exemplo \n) e (2) length-prefix (header com tamanho). Vou te mostrar os dois, e em seguida mostro como isso muda quando você tem múltiplos clientes: ou você cria uma task por conexão (simples, mais RAM) ou usa select() (eficiente, mais complexo).

8.1 Framing por delimitador (\n)

Esse é o mais simples: você acumula bytes num buffer até achar \n. Cada linha vira um comando. É ótimo para console TCP, debug remoto, protocolos ASCII e comandos humanos. O cuidado é evitar overflow: se o cliente mandar uma linha enorme sem \n, você precisa cortar, descartar ou desconectar.

Exemplo de acumulador por conexão:

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

#define LINE_BUF_SZ 256

typedef struct
{
    uint8_t buf[LINE_BUF_SZ];
    uint16_t used;
} LineFramer_t;

/**
 * @brief Alimenta o framer com bytes recebidos e extrai 0..N linhas completas.
 *        Retorna 1 quando extraiu uma linha, 0 quando ainda não tem linha.
 */
static int framer_try_get_line(LineFramer_t *f, const uint8_t *data, uint16_t len,
                               uint8_t *out_line, uint16_t *out_len)
{
    /* Copia com proteção */
    uint16_t space = (LINE_BUF_SZ - 1) - f->used;
    if (len > space) {
        /* Política simples: reset (em produção: desconectar cliente) */
        f->used = 0;
        return 0;
    }

    memcpy(&f->buf[f->used], data, len);
    f->used += len;
    f->buf[f->used] = 0;

    /* Procura delimitador */
    uint8_t *nl = (uint8_t*)memchr(f->buf, '\n', f->used);
    if (!nl) return 0;

    uint16_t line_len = (uint16_t)(nl - f->buf) + 1; /* inclui '\n' */
    memcpy(out_line, f->buf, line_len);
    *out_len = line_len;

    /* Remove a linha do buffer (shift) */
    uint16_t remaining = f->used - line_len;
    memmove(f->buf, &f->buf[line_len], remaining);
    f->used = remaining;

    return 1;
}

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

#define LINE_BUF_SZ 256

typedef struct
{
    uint8_t buf[LINE_BUF_SZ];
    uint16_t used;
} LineFramer_t;

/**
 * @brief Alimenta o framer com bytes recebidos e extrai 0..N linhas completas.
 *        Retorna 1 quando extraiu uma linha, 0 quando ainda não tem linha.
 */
static int framer_try_get_line(LineFramer_t *f, const uint8_t *data, uint16_t len,
                               uint8_t *out_line, uint16_t *out_len)
{
    /* Copia com proteção */
    uint16_t space = (LINE_BUF_SZ - 1) - f->used;
    if (len > space) {
        /* Política simples: reset (em produção: desconectar cliente) */
        f->used = 0;
        return 0;
    }

    memcpy(&f->buf[f->used], data, len);
    f->used += len;
    f->buf[f->used] = 0;

    /* Procura delimitador */
    uint8_t *nl = (uint8_t*)memchr(f->buf, '\n', f->used);
    if (!nl) return 0;

    uint16_t line_len = (uint16_t)(nl - f->buf) + 1; /* inclui '\n' */
    memcpy(out_line, f->buf, line_len);
    *out_len = line_len;

    /* Remove a linha do buffer (shift) */
    uint16_t remaining = f->used - line_len;
    memmove(f->buf, &f->buf[line_len], remaining);
    f->used = remaining;

    return 1;
}

Uso típico no loop do socket: você chama recv(), joga os bytes no framer e enquanto ele conseguir extrair linhas você envia para a fila (rxQueue).

8.2 Framing por header com tamanho (length-prefix)

Esse é o padrão de protocolos binários robustos. Você define, por exemplo:

• 2 bytes: len (big-endian)
• len bytes: payload

Vantagem: não depende de delimitador e funciona bem com binário. Desvantagem: você precisa validar tamanho, lidar com endianess e limites.

Estrutura de parsing por estados:

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

#define MAX_FRAME 512

typedef enum { ST_LEN1, ST_LEN2, ST_PAYLOAD } ParseState_t;

typedef struct
{
    ParseState_t st;
    uint16_t expected;
    uint16_t got;
    uint8_t payload[MAX_FRAME];
} LenFramer_t;

static void lenframer_init(LenFramer_t *f)
{
    f->st = ST_LEN1;
    f->expected = 0;
    f->got = 0;
}

/**
 * @brief Consome bytes e extrai frames completos. Retorna 1 quando extrai um frame.
 */
static int lenframer_feed(LenFramer_t *f, const uint8_t *data, uint16_t len,
                          uint8_t *out_payload, uint16_t *out_len)
{
    for (uint16_t i = 0; i < len; i++)
    {
        uint8_t b = data[i];

        switch (f->st)
        {
            case ST_LEN1:
                f->expected = ((uint16_t)b) << 8;
                f->st = ST_LEN2;
                break;

            case ST_LEN2:
                f->expected |= b;
                if (f->expected == 0 || f->expected > MAX_FRAME) {
                    /* Frame inválido: reset (em produção: desconectar) */
                    lenframer_init(f);
                    break;
                }
                f->got = 0;
                f->st = ST_PAYLOAD;
                break;

            case ST_PAYLOAD:
                f->payload[f->got++] = b;
                if (f->got >= f->expected) {
                    memcpy(out_payload, f->payload, f->expected);
                    *out_len = f->expected;
                    lenframer_init(f);
                    return 1; /* extraiu 1 frame */
                }
                break;
        }
    }
    return 0;
}

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

#define MAX_FRAME 512

typedef enum { ST_LEN1, ST_LEN2, ST_PAYLOAD } ParseState_t;

typedef struct
{
    ParseState_t st;
    uint16_t expected;
    uint16_t got;
    uint8_t payload[MAX_FRAME];
} LenFramer_t;

static void lenframer_init(LenFramer_t *f)
{
    f->st = ST_LEN1;
    f->expected = 0;
    f->got = 0;
}

/**
 * @brief Consome bytes e extrai frames completos. Retorna 1 quando extrai um frame.
 */
static int lenframer_feed(LenFramer_t *f, const uint8_t *data, uint16_t len,
                          uint8_t *out_payload, uint16_t *out_len)
{
    for (uint16_t i = 0; i < len; i++)
    {
        uint8_t b = data[i];

        switch (f->st)
        {
            case ST_LEN1:
                f->expected = ((uint16_t)b) << 8;
                f->st = ST_LEN2;
                break;

            case ST_LEN2:
                f->expected |= b;
                if (f->expected == 0 || f->expected > MAX_FRAME) {
                    /* Frame inválido: reset (em produção: desconectar) */
                    lenframer_init(f);
                    break;
                }
                f->got = 0;
                f->st = ST_PAYLOAD;
                break;

            case ST_PAYLOAD:
                f->payload[f->got++] = b;
                if (f->got >= f->expected) {
                    memcpy(out_payload, f->payload, f->expected);
                    *out_len = f->expected;
                    lenframer_init(f);
                    return 1; /* extraiu 1 frame */
                }
                break;
        }
    }
    return 0;
}