Safe Data Sharing with FreeRTOS Queues

1. Why Not Just Use Global Variables?

With your background in C++, you might first think of using a global variable to share data between two tasks. One task writes to it, and the other reads from it. While simple, this approach is fraught with peril in a multitasking environment.

Let's watch a short video that explains the dangers of using global variables for inter-task communication and introduces queues as the robust solution.

As the video highlighted, when an operation is not atomic (meaning it can be interrupted partway through), you can get unpredictable and corrupted data. This is especially true when dealing with data larger than the processor's native word size (like a double or a struct) or when multiple tasks might write to the same variable.

Queues solve this by providing a thread-safe mechanism for passing data.

2. What is a FreeRTOS Queue?

A FreeRTOS queue is a data structure that allows you to send data from one task to another in a First-In, First-Out (FIFO) manner.

Here are the core concepts:

• Thread-Safe: The RTOS guarantees that operations on a queue are atomic. You can safely have multiple tasks sending to and receiving from the same queue without risk of data corruption.
• Data Copying (By Value): When you send an item to a queue, the RTOS copies the entire item into the queue's internal buffer. This is a crucial feature. It means the sending task can immediately reuse its local variable or let it go out of scope without affecting the data that's now safely stored in the queue.
• Blocking: Tasks can be configured to wait (block) if they try to read from an empty queue or write to a full queue. This is highly efficient, as a blocked task consumes no CPU time until data becomes available or space opens up.

Let's now turn to a practical example to see how this works in code.

3. Basic Queue Operations

The core functions you'll use to manage queues are:

• xQueueCreate(): Creates a new queue.
• xQueueSend(): Sends (copies) an item to the back of the queue.
• xQueueReceive(): Receives (copies and removes) an item from the front of the queue.

The following tutorial from Random Nerd Tutorials provides an excellent first example where one task reads a potentiometer value and sends it to another task via a queue to control an LED's brightness.

Breaking Down the Code

Let's look at those key functions from the example more closely:

1. Creation:

   potQueue = xQueueCreate(QUEUE_SIZE, sizeof(uint16_t));
   

   • The first argument, QUEUE_SIZE, defines the maximum number of items the queue can hold.
   • The second argument, sizeof(uint16_t), defines the size of each individual item. The RTOS uses this to allocate the correct amount of memory.

2. Sending:

   xQueueSend(potQueue, &potValue, portMAX_DELAY);
   

   • The first argument is the handle to the queue.
   • The second argument is a pointer to the data you want to send. The RTOS will copy sizeof(uint16_t) bytes from this memory location.
   • The third argument is the timeout. portMAX_DELAY tells the task to wait indefinitely if the queue is full. If you pass 0, the function will return immediately (pdFAIL) if the queue is full.

3. Receiving:

   if (xQueueReceive(potQueue, &potValue, portMAX_DELAY))
   

   • The second argument is a pointer to a local variable where the received data will be copied.
   • The timeout works similarly: portMAX_DELAY will block the task until an item is available. If you pass 0, the function will return immediately if the queue is empty.
   • The function returns pdTRUE on success and pdFALSE if the timeout expires before an item is received. This is why it's used in an if statement.

4. Sending Complex Data with Structs

The real power of queues becomes apparent when you need to pass more than a single number. Since queues copy a block of memory of a specified size, you can easily send an entire C++ struct.

This is incredibly useful for bundling related data. For instance, an Inertial Measurement Unit (IMU) sensor task could package accelerometer, gyroscope, and temperature readings into a single struct and send it to a processing task in one atomic operation.

The Random Nerd Tutorials guide has another excellent example that does just this.

This pattern of packaging data into structs is a clean, scalable, and highly common practice in embedded systems design.

5. Advanced Communication: Two-Way Exchange

So far, we've seen one-way communication. But you can easily establish two-way communication by using two queues. A common scenario is a "command-and-response" pattern: one task sends a command to another, and the second task sends a status or result back.

Let's look at the solution to the challenge posed in the Digi-Key video you watched earlier. It implements exactly this pattern.

• Task A (CLI): Listens for serial commands from the user. If it receives "delay xxx", it sends the number xxx to Task B via delay_queue. It also listens on msg_queue for status messages from Task B to print to the console.
• Task B (Blinker): Blinks an LED. It listens on delay_queue for new delay values. When it receives one, it sends a confirmation message ("Message received") back to Task A via msg_queue.

This example is a great demonstration of how you can build more complex, interactive systems by combining multiple tasks and queues.

Conclusion

You've now added FreeRTOS queues to your toolkit, moving beyond simple task synchronization to full-fledged, thread-safe data exchange. This ability to decouple data production from data consumption is fundamental to building robust, scalable embedded applications.

Key Takeaways:

• Queues are the preferred method for safely passing data between tasks, avoiding the pitfalls of global variables.
• Data is copied by value into a queue, ensuring the data is preserved even if the original variable goes out of scope.
• The API functions xQueueCreate, xQueueSend, and xQueueReceive are the primary tools for working with queues.
• Using blocking calls with a timeout (like portMAX_DELAY) is highly efficient, as waiting tasks do not consume CPU time.
• Queues are versatile and can be used to send any data type, including complex structs, which is a powerful pattern for bundling related information.

In this lesson, we focused on passing data between tasks. But what happens when two tasks need to access a single, shared resource, like the Serial port, an SD card, or an I2C peripheral? If one task starts a multi-step I2C transaction and gets preempted, another task could interrupt and corrupt the communication. Queues don't solve this problem of exclusive resource access. For that, we need a mutex, which will be the topic of our next lesson.