Event group for task synchronization in FreeRTOS

Introduction

Event groups help tasks wait for or signal multiple events easily. They let tasks work together by sharing simple flags.

When multiple tasks need to wait for one or more events before continuing.

When a task must signal other tasks that some work is done.

When you want to combine several conditions into one wait operation.

When you want to avoid busy waiting and save CPU time.

When tasks need to synchronize without complex message passing.

Syntax

FreeRTOS

EventGroupHandle_t xEventGroupCreate(void);

EventBits_t xEventGroupWaitBits(
    EventGroupHandle_t xEventGroup,
    const EventBits_t uxBitsToWaitFor,
    const BaseType_t xClearOnExit,
    const BaseType_t xWaitForAllBits,
    TickType_t xTicksToWait
);

EventBits_t xEventGroupSetBits(
    EventGroupHandle_t xEventGroup,
    const EventBits_t uxBitsToSet
);

xEventGroupCreate() creates a new event group and returns its handle.

xEventGroupWaitBits() waits for specified bits to be set in the event group.

Examples

Create an event group to hold event bits.

FreeRTOS

EventGroupHandle_t xEventGroup = xEventGroupCreate();
// Create an event group

Wait for either BIT_0 or BIT_1 to be set. Clear bits after waiting.

FreeRTOS

EventBits_t uxBits = xEventGroupWaitBits(
    xEventGroup,
    BIT_0 | BIT_1,
    pdTRUE,
    pdFALSE,
    portMAX_DELAY
);
// Wait for BIT_0 or BIT_1 to be set, clear bits on exit, wait forever

Set BIT_0 to notify waiting tasks.

FreeRTOS

xEventGroupSetBits(xEventGroup, BIT_0);
// Set BIT_0 in the event group to signal an event

Sample Program

This program creates an event group and three tasks. Task1 waits for BIT_0, Task2 waits for BIT_1, and Task3 sets both bits after 1 second. Tasks 1 and 2 print messages when their bits are received.

FreeRTOS

#include "FreeRTOS.h"
#include "task.h"
#include "event_groups.h"
#include <stdio.h>

#define BIT_0 (1 << 0)
#define BIT_1 (1 << 1)

EventGroupHandle_t xEventGroup;

void vTask1(void *pvParameters) {
    printf("Task1: Waiting for BIT_0...\n");
    xEventGroupWaitBits(xEventGroup, BIT_0, pdTRUE, pdFALSE, portMAX_DELAY);
    printf("Task1: BIT_0 received!\n");
    vTaskDelete(NULL);
}

void vTask2(void *pvParameters) {
    printf("Task2: Waiting for BIT_1...\n");
    xEventGroupWaitBits(xEventGroup, BIT_1, pdTRUE, pdFALSE, portMAX_DELAY);
    printf("Task2: BIT_1 received!\n");
    vTaskDelete(NULL);
}

void vTask3(void *pvParameters) {
    printf("Task3: Setting BIT_0 and BIT_1 after delay...\n");
    vTaskDelay(pdMS_TO_TICKS(1000));
    xEventGroupSetBits(xEventGroup, BIT_0 | BIT_1);
    printf("Task3: Bits set!\n");
    vTaskDelete(NULL);
}

int main(void) {
    xEventGroup = xEventGroupCreate();
    if (xEventGroup == NULL) {
        printf("Failed to create event group\n");
        return 1;
    }

    xTaskCreate(vTask1, "Task1", 1000, NULL, 1, NULL);
    xTaskCreate(vTask2, "Task2", 1000, NULL, 1, NULL);
    xTaskCreate(vTask3, "Task3", 1000, NULL, 1, NULL);

    vTaskStartScheduler();

    // Should never reach here
    for(;;);
    return 0;
}

Important Notes

Always check if xEventGroupCreate() returns NULL, which means creation failed.

Use pdTRUE for xClearOnExit if you want bits cleared after a task wakes up.

Event bits are limited to 24 bits in FreeRTOS.

Summary

Event groups let tasks wait for or signal multiple events using bits.

They help tasks synchronize without busy waiting.

Use xEventGroupWaitBits() to wait and xEventGroupSetBits() to signal.

Practice

1. What is the primary purpose of an event group in FreeRTOS for task synchronization?

easy

A. To allocate memory dynamically for tasks

B. To allow tasks to wait for multiple events using bits

C. To create queues for message passing

D. To manage task priorities automatically

Solution

1. Step 1: Understand event groups in FreeRTOS

   Event groups use bits to represent events that tasks can wait for or signal.

2. Step 2: Identify the main use of event groups

   They help tasks synchronize by waiting on or setting bits representing events.

3. Final Answer:

   To allow tasks to wait for multiple events using bits -> Option B

4. Quick Check:

   Event groups = wait for multiple events [OK]

Hint: Event groups use bits to sync tasks, not memory or priorities [OK]

Common Mistakes:

• Confusing event groups with queues
• Thinking event groups manage memory
• Assuming event groups change task priorities

2. Which of the following is the correct function to wait for bits in an event group in FreeRTOS?

easy

A. xEventGroupClearBits()

B. xEventGroupSetBits()

C. xEventGroupWaitBits()

D. xEventGroupCreate()

Solution

1. Step 1: Recall FreeRTOS event group functions

   xEventGroupWaitBits() is used to wait for specific bits to be set.

2. Step 2: Differentiate from other functions

   xEventGroupSetBits() sets bits, ClearBits clears bits, Create creates the group.

3. Final Answer:

   xEventGroupWaitBits() -> Option C

4. Quick Check:

   Wait for bits = xEventGroupWaitBits() [OK]

Hint: Wait uses xEventGroupWaitBits(), set uses xEventGroupSetBits() [OK]

Common Mistakes:

• Using xEventGroupSetBits() to wait
• Confusing create with wait functions
• Mixing clear bits with wait bits

3. Given the following code snippet, what will be the value of bits after xEventGroupWaitBits() returns?

EventBits_t bits;
bits = xEventGroupWaitBits(eventGroup, BIT_0 | BIT_1, pdTRUE, pdFALSE, portMAX_DELAY);

Assume BIT_0 and BIT_1 are both set in eventGroup before the call.

medium

A. Only BIT_0 set

B. Only BIT_1 set

C. No bits set

D. Both BIT_0 and BIT_1 set

Solution

1. Step 1: Understand xEventGroupWaitBits parameters

   The function waits for BIT_0 or BIT_1 to be set, clears bits on exit (pdTRUE), and does not wait for all bits (pdFALSE).

2. Step 2: Analyze the bits set before call

   Both BIT_0 and BIT_1 are set, so the function returns with both bits set in the return value.

3. Final Answer:

   Both BIT_0 and BIT_1 set -> Option D

4. Quick Check:

   WaitBits returns bits set before clearing [OK]

Hint: WaitBits returns bits set before clearing them [OK]

Common Mistakes:

• Assuming only one bit is returned
• Ignoring bits cleared on exit
• Confusing wait for all bits with wait for any

4. Identify the error in the following FreeRTOS event group usage:

EventGroupHandle_t eventGroup = xEventGroupCreate();

void Task1(void *pvParameters) {
    xEventGroupWaitBits(eventGroup, BIT_0, pdFALSE, pdTRUE, portMAX_DELAY);
    // Task code
}

void Task2(void *pvParameters) {
    xEventGroupSetBits(eventGroup, BIT_0);
}

medium

A. Not checking if eventGroup creation succeeded

B. Using portMAX_DELAY as wait time

C. Using pdFALSE for clearOnExit in xEventGroupWaitBits

D. Setting bits before event group creation

Solution

1. Step 1: Check event group creation

   xEventGroupCreate() can return NULL if creation fails; code does not check this.

2. Step 2: Verify other parameters

   Using pdFALSE for clearOnExit is valid; portMAX_DELAY is valid; bits are set after creation.

3. Final Answer:

   Not checking if eventGroup creation succeeded -> Option A

4. Quick Check:

   Always check event group creation success [OK]

Hint: Always verify event group creation returned non-NULL [OK]

Common Mistakes:

• Ignoring NULL return from xEventGroupCreate
• Misusing clearOnExit parameter
• Setting bits before creating event group

5. You want two tasks to synchronize so that Task A waits until Task B signals both BIT_0 and BIT_1. Which xEventGroupWaitBits() call correctly waits for both bits before continuing?

hard

A. xEventGroupWaitBits(eventGroup, BIT_0 | BIT_1, pdTRUE, pdTRUE, portMAX_DELAY);

B. xEventGroupWaitBits(eventGroup, BIT_0 & BIT_1, pdTRUE, pdTRUE, portMAX_DELAY);

C. xEventGroupWaitBits(eventGroup, BIT_0 | BIT_1, pdTRUE, pdFALSE, portMAX_DELAY);

D. xEventGroupWaitBits(eventGroup, BIT_0 & BIT_1, pdFALSE, pdFALSE, portMAX_DELAY);

Solution

1. Step 1: Understand wait for all bits parameter

   The fourth parameter (xWaitForAllBits) must be pdTRUE to wait for both bits together.

2. Step 2: Check bit mask and parameters

   Use BIT_0 | BIT_1 to specify both bits; pdTRUE for clearOnExit clears bits after wait.

3. Final Answer:

   xEventGroupWaitBits(eventGroup, BIT_0 | BIT_1, pdTRUE, pdTRUE, portMAX_DELAY); -> Option A

4. Quick Check:

   Wait for all bits = xEventGroupWaitBits with xWaitForAllBits = pdTRUE [OK]

Hint: Set xWaitForAllBits to pdTRUE to wait for all bits [OK]

Common Mistakes:

• Using bitwise AND (&) instead of OR (|) for bit mask
• Setting xWaitForAllBits to pdFALSE when waiting for all bits
• Confusing clearOnExit with wait for all bits