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.
Files to include
Declare event group
// NULL return means not allocated
xCreatedEventGroup = xEventGroupCreate();
Clear event bits
const EventBits_t uxBitsToClear
Multiple bits can be indicated
Set event bits
Same as clear event bits APIs.
From an ISR:
Wait for event bit
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