FreeRTOS

How to fix ESP32 error: ‘portTICK_PERIOD_MS’ was not declared in this scope

Problem:

While trying to compile your ESP-IDF firmware (with or without PlatformIO), you see an error message such as

src/main.cpp:13:27: error: 'portTICK_PERIOD_MS' was not declared in this scope
   13 |         vTaskDelay(1000 / portTICK_PERIOD_MS);

Solution:

Include FreeRTOS by adding the following lines to the top of the file where the error occured (src/main.cpp in this example):

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

 

Posted by Uli Köhler in ESP8266/ESP32, FreeRTOS, PlatformIO

How to fix ESP32 error: ‘vTaskDelay’ was not declared in this scope

Problem:

While trying to compile your ESP-IDF firmware (with or without PlatformIO), you see an error message such as

src/main.cpp:13:9: error: 'vTaskDelay' was not declared in this scope
   13 |         vTaskDelay(1000 / portTICK_PERIOD_MS);

Solution:

Include FreeRTOS by adding the following lines to the top of the file where the error occured (src/main.cpp in this example):

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

 

Posted by Uli Köhler in ESP8266/ESP32, FreeRTOS, PlatformIO

How to use vPortGetHeapStats() on the ESP32?

Problem:

You see an error message like the following one while compiling your ESP32 project

src/main.cpp:128:3: error: 'vPortGetHeapStats' was not declared in this scope
   vPortGetHeapStats(&heapStats);

Solution:

Although vPortGetHeapStats() is typically defined in freertos/portable.h, you can not use   vPortGetHeapStats() on the ESP32 since the frameworks do not use the FreeRTOS heap implementation.

In order to find informatio about heap usage, use the ESP heap API such as esp_get_free_heap_size().

Posted by Uli Köhler in ESP8266/ESP32, FreeRTOS

FreeRTOS task queue with static memory (xQueueCreateStatic) minimal example

Also see our previous post FreeRTOS task queue minimal example which also has examples for how to send & receive with a queue. The post you’re currently viewing is just about xQueueCreateStatic()

enum class MQTTTaskType : uint8_t {
    SendStatus = 0,
    SendInfo
};

// This struct will be inserted into the queue
struct MQTTTask {
    MQTTTaskType task; // The type of work that is requested from the received
    // TODO add your custom fields here if requred
};

constexpr size_t MQTT_TASK_QUEUE_LENGTH = 6;
static QueueHandle_t mqttTaskQueue;
static StaticQueue_t mqttTaskQueueStatic;
static uint8_t mqttTaskQueueStorageArea[ MQTT_TASK_QUEUE_LENGTH * sizeof(MQTTTask) ];

void setup() {
    // Create task queue
    mqttTaskQueue = xQueueCreateStatic( MQTT_TASK_QUEUE_LENGTH,
                                 sizeof(MQTTTask),
                                 mqttTaskQueueStorageArea,
                                 &mqttTaskQueueStatic );
}

 

Posted by Uli Köhler in C/C++, Embedded, FreeRTOS, PlatformIO

FreeRTOS task with static stack memory (xTaskCreateStatic) example

Also see our previous post which uses dynamically allocated memory using xTaskCreate()How to add FreeRTOS task (thread) to any PlatformIO project

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

constexpr size_t MY_TASK_STACK_SIZE = 1024;
static StaticTask_t myTaskBuffer;
static StackType_t myTaskStack[ MY_TASK_STACK_SIZE ];


void MyTask(void * parameter)
{
    while(true)
    {
        // TODO Your code goes here
    }
}

void setup()
{
    xTaskCreateStatic(
        MyTask, // Task function
        "MyTask", // Name
        MY_TASK_STACK_SIZE, // Stack size
        nullptr, // Parameter
        tskIDLE_PRIORITY,
        myTaskStack,
        &myTaskBuffer);
}

void loop() {
}

 

Posted by Uli Köhler in Arduino, FreeRTOS

How to fix ESP32 FreeRTOS error: too few arguments to function ‘void vPortEnterCritical(portMUX_TYPE*)’

Problem:

On FreeRTOS on the ESP32, you want to use a critical zone like this:

portENTER_CRITICAL();
// Your critical code goes here!
portEXIT_CRITICAL();

but while compiling the procject, you see an error message like

src/main.cpp: In function 'void MyFunc(size_t, int16_t)':
/home/uli/.platformio/packages/framework-arduinoespressif32@src-f2ea83e2545300b10a69ff44ef9dc6cd/tools/sdk/esp32/include/freertos/port/xtensa/include/freertos/portmacro.h:476:75: error: too few arguments to function 'void vPortEnterCritical(portMUX_TYPE*)'
 #define portENTER_CRITICAL(mux)                     vPortEnterCritical(mux)

Solution:

You need to use portENTER_CRITICAL() and portEXIT_CRITICAL() with a spinlock, i.e.

portENTER_CRITICAL(&mySpinlock);
// TODO Your critical code goes here!
portEXIT_CRITICAL(&mySpinlock);

In order to see a full example on how to initialize a spinlock in FreeRTOS and use it for critical zones, see our previous post ESP32 critical zone example using FreeRTOS / PlatformIO

Posted by Uli Köhler in Arduino, ESP8266/ESP32, FreeRTOS, PlatformIO

ESP32 critical zone example using FreeRTOS / PlatformIO

In order to enter a critical zone on the ESP32 using FreeRTOS, you have to do the following:

Globally declare a spinlock:

portMUX_TYPE mySpinlock;

In setup(), initialize the spinlock:

spinlock_initialize(&mySpinlock);

Now, wherever you want to enter a critical zone, run:

portENTER_CRITICAL(&mySpinlock);
// TODO Your critical code goes here!
portEXIT_CRITICAL(&mySpinlock);

When using this in an interrupt handler, use this instead:

portENTER_CRITICAL_ISR(&mySpinlock);
// TODO Your critical code goes here!
portEXIT_CRITICAL_ISR(&mySpinlock);

 

FreeRTOS will ensure that no two threads using mySpinlock are run at the same time.

Posted by Uli Köhler in Arduino, ESP8266/ESP32, FreeRTOS, PlatformIO

How to get current task handle in FreeRTOS

Simply use xTaskGetCurrentTaskHandle()

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

TaskHandle_t myTaskHandle = xTaskGetCurrentTaskHandle();

 

Posted by Uli Köhler in Embedded, FreeRTOS

How long does portMAX_DELAY actually wait in FreeRTOS?

Although portMAX_DELAY is listed as value for waiting indefinitely, it will only actually wait indefinitely if INCLUDE_vTaskSuspend is enabled in the FreeRTOS config.

portMAX_DELAY is typically defined as 0xFFFFFFFF i.e. 2^32-1:

#define portMAX_DELAY ( TickType_t ) 0xffffffffUL

(however if 16 bit ticks are enabled using configUSE_16_BIT_TICKS it will be defined as 0xFFFF (2^16-1).

In case INCLUDE_vTaskSuspend is enabled, this is treated as a special value and will actually wait indefinitely. If INCLUDE_vTaskSuspend is not defined, it will only wait for 0xFFFFFFFF ticks (assuming 32-bit system ticks.

In other words, this will wait for only about 7 weeks if FreeRTOS is defined to tick every millisecond.

Posted by Uli Köhler in Embedded, FreeRTOS

FreeRTOS task queue minimal example

This is how you create and use a task queue in FreeRTOS:

Global declaration

Declare the structure of a task (I recommend to use a task type enum class in order to keep the flexibility of using multiple task types:

#include <freertos/queue.h>

enum class I2CTaskType : uint8_t {
    MyTaskType = 0
};

struct I2CTask {
    I2CTaskType type;
    // Parameters
    int16_t value;
};
static QueueHandle_t i2cTaskQueue;

Initialization code

Call this once, before using it:

// Create task queue
i2cTaskQueue = xQueueCreate(8 /* Number of queue slots */, sizeof(I2CTask));

In the thread processing the queue

if (xQueueReceive(i2cTaskQueue, (void *)&task, portMAX_DELAY /* Wait infinitely for new tasks */) == pdTRUE) {
    if(task.type == I2CTaskType::MyTaskType) {
        // TODO process task
        Serial.printf("My task type: %d\r\n", task.value);
    }
}

How to add a task to the queue

void AddTask(int16_t val) {
    I2CTask task;
    task.type = I2CTaskType::MyTaskType;
    task.value = val;
    xQueueSend(i2cTaskQueue, (void*)&task, 10 / portTICK_PERIOD_MS /* timeout */);
}

 

Posted by Uli Köhler in C/C++, Embedded, FreeRTOS, PlatformIO

FreeRTOS mutex minimal example

This is how you create and use a mutex in FreeRTOS:

Includes:

#include <freertos/semphr.h>

 

Global declaration

SemaphoreHandle_t myMutex;

Initialization code

Call this once, before using it:

myMutex = xSemaphoreCreateMutex();

How to lock & unlock the mutex

// Wait a maximum of 10ms to lock the mutex
if(xSemaphoreTake(myMutex, 10 / portTICK_PERIOD_MS) == pdTRUE) {
   // Success locking the mutex
   // TODO: Your code goes here!
   // Unlock the mutex!
   xSemaphoreGive(myMutex);
} else {
   // Failed to lock the mutex within timeout
   // DO NOT use the resource protected by the mutex
   // DO NOT unlock (xSemaphoreGive) !
}

 

Posted by Uli Köhler in Embedded, FreeRTOS, PlatformIO

What is the FreeRTOS equivalent to Arduino’s delay()?

Instead of Arduino’s

delay(5); // delay for five milliseconds

use this in FreeRTOS:

vTaskDelay(5 / portTICK_PERIOD_MS);
Posted by Uli Köhler in Arduino, Electronics, Embedded, FreeRTOS

How to add FreeRTOS task (“thread”) to any PlatformIO project

Most PlatformIO default configurations already have FreeRTOS enabled – they just don’t use it.

In order to start a new FreeRTOS “thread” (called task in FreeRTOS-speak), first add these includes:

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

Now add the task function and handle:

TaskHandle_t myTaskHandle;
void MyTask( void * parameter )
{
    for(;;)
    {
       // TODO Task code goes here
    }
    // if you ever exit the loop, this is here to clean up the resources
    vTaskDelete( NULL );
}

then start the task using this code once, for example in your main function:

// Start MyTask thread
xTaskCreate(
    MyTask, // Task function
    "MyTask", // Name
    10000, // Stack size
    NULL, // Parameter
    1, // Priority
    &myTaskHandle);

Also see our new post on how to use xTaskCreateStatic() to use statically allocated instead of dynamically allocated stack memory for the task: FreeRTOS task with static stack memory (xTaskCreateStatic) example

Posted by Uli Köhler in C/C++, Electronics, Embedded, FreeRTOS, PlatformIO

What is the value of portTICK_PERIOD_MS and configTICK_RATE_HZ on the ESP32 using PlatformIO?

When you use PlatformIO with the Arduino framework in its default configuration on the ESP32, configTICK_RATE_HZ is set to 1000. In other words, FreeRTOS has a default tick frequency of 1kHz. This is defined in sdkconfig.h:

#define CONFIG_FREERTOS_HZ 1000

Hence portTICK_PERIOD_MS is 1. In my opinion, a tick rate of 1kHz is a sane configuration for most usecases.

I found the value by using the following code on an ESP32:

Serial.println("Timing: ");
Serial.println(portTICK_PERIOD_MS);
Serial.println(configTICK_RATE_HZ);

 

Posted by Uli Köhler in Arduino, Electronics, Embedded, ESP8266/ESP32, FreeRTOS, PlatformIO