FreeRTOS Event Groups – quick reference notes

The notes contained in this article have been compiled with reference to FreeRTOS Reference Manual v.9.0.0. The APIs are not going to change for future versions of FreeRTOS, even though new ones may be added (ensuring backward API compatibility). These APIs are very mportant for programming applications on the ESP32 because the programs may have to do a lot of waiting in real time, such as waiting for data to be sent or waiting for WiFi system to get connected to a router.

What is an event group?

You may think of an event group as a bit field where every bit is a flag that corresponds to a certain event. The event bit can be set or cleared. The state of the bits is altered to signal the status of a process to other functions.

For example, if there is a Task A that must kill itself after Task B is complete, you may use an event group with a bit indicating status of Task B, which Task A can poll to determine when Task B is done.
This is a very simple use case and event groups can serve a much more complex coordination mechanism.

Event group handles are created as static variables and are simply pointers to the event group structure (the structure must be dynamically allocated before use).

When to use event groups

When you plan on waiting for an event to occur, you should use an event group.
The event group does not notify itself of any events. The functions using the event group must signal when an event is over.

NOTES

Files to include

FreeRTOS.h
event_groups.h

Declare event group

// Declare a variablewith file-wide scope
EventGroupHandle_t xCreatedEventGroup;
// Allocate the event group
// NULL return means not allocated
xCreatedEventGroup = xEventGroupCreate();
NOTE: The event group in case of esp-idf can hold 24 bits according to the FreeeRTOS config file.

Clear event bits

EventBits_t xEventGroupClearBits
(
EventGroupHandle_t   xEventGroup,
const EventBits_t   uxBitsToClear
);
If called from an ISR, use
xEventGroupClearBitsFromISR()
A bit can be indicated by BIT_n
Multiple bits can be indicated by BIT_m|BIT_n
 

Set event bits

Same as clear event bits APIs.

xEventGroupSetBits

From an ISR:

xEventGroupSetBitsFromISR

 

Wait for event bit

EventBits_t xEventGroupWaitBits
(
const EventGroupHandle_t xEventGroup,     // Group handle
const EventBits_t uxBitsToWaitFor,       // Bits to wait for until set
const BaseType_t xClearOnExit,          // Clear bits on exit if pdTRUE
const BaseType_t xWaitForAllBits,        // Wait for all bits to set if pdTRUE
TickType_t xTicksToWait                 // Max wait time
);

Leave a Reply