Waiting for event bits (AND/OR) in FreeRTOS

Introduction

Waiting for event bits lets a program pause until certain signals happen. It helps tasks wait for one or more events before continuing.

When a task needs to wait for multiple conditions to be true before running.

When a task should continue after any one of several events happens.

When coordinating between tasks using flags to signal events.

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

When you want to synchronize tasks based on multiple signals.

Syntax

FreeRTOS

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

xEventGroup is the event group handle to wait on.

uxBitsToWaitFor is the bit mask of bits to wait for.

xClearOnExit clears bits when returned if set to pdTRUE.

xWaitForAllBits chooses AND (pdTRUE) or OR (pdFALSE) waiting.

xTicksToWait is how long to wait before timeout.

Examples

Waits until both BIT_1 and BIT_2 are set (AND). Clears bits on exit. Waits forever.

FreeRTOS

bits = xEventGroupWaitBits(
    myEventGroup,
    BIT_1 | BIT_2,
    pdTRUE,
    pdTRUE,
    portMAX_DELAY
);

Waits until either BIT_1 or BIT_2 is set (OR). Does not clear bits. Waits 100 ms max.

FreeRTOS

bits = xEventGroupWaitBits(
    myEventGroup,
    BIT_1 | BIT_2,
    pdFALSE,
    pdFALSE,
    100 / portTICK_PERIOD_MS
);

Sample Program

This program creates an event group and two tasks. Task1 waits until both BIT_0 and BIT_1 are set. Task2 sets BIT_0 after 1 second, then BIT_1 after another second. Task1 prints messages before and after waiting.

FreeRTOS

#include "FreeRTOS.h"
#include "event_groups.h"
#include "task.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 and BIT_1\n");
    EventBits_t bits = xEventGroupWaitBits(
        xEventGroup,
        BIT_0 | BIT_1,
        pdTRUE,
        pdTRUE,
        portMAX_DELAY
    );
    if ((bits & (BIT_0 | BIT_1)) == (BIT_0 | BIT_1)) {
        printf("Task1: Both bits received!\n");
    }
    vTaskDelete(NULL);
}

void vTask2(void *pvParameters) {
    vTaskDelay(1000 / portTICK_PERIOD_MS);
    printf("Task2: Setting BIT_0\n");
    xEventGroupSetBits(xEventGroup, BIT_0);
    vTaskDelay(1000 / portTICK_PERIOD_MS);
    printf("Task2: Setting BIT_1\n");
    xEventGroupSetBits(xEventGroup, BIT_1);
    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);
    vTaskStartScheduler();
    return 0;
}

Important Notes

Use pdTRUE for xWaitForAllBits to wait for all bits (AND).

Use pdFALSE for xWaitForAllBits to wait for any bit (OR).

Setting xClearOnExit to pdTRUE clears the bits when the function returns.

Summary

Waiting for event bits lets tasks pause until specific signals happen.

Use AND mode to wait for all bits, OR mode to wait for any bit.

Clearing bits on exit helps avoid repeated triggers.

Practice

1. What does waiting for event bits in FreeRTOS allow a task to do?

easy

A. Pause execution until specific event bits are set

B. Run continuously without interruption

C. Automatically clear all event bits on start

D. Create new event bits dynamically

Solution

1. Step 1: Understand event bits purpose

   Event bits are signals that tasks can wait for to synchronize actions.

2. Step 2: Identify what waiting means

   Waiting means the task pauses until the required bits are set.

3. Final Answer:

   Pause execution until specific event bits are set -> Option A

4. Quick Check:

   Waiting for event bits = pause task until bits set [OK]

Hint: Waiting means pausing until bits signal event [OK]

Common Mistakes:

• Thinking waiting means running continuously
• Confusing event bits with task creation
• Assuming bits clear automatically on start

2. Which of the following is the correct syntax to wait for event bits using AND mode in FreeRTOS?

easy

A. xEventGroupClearBits(eventGroup, bitsToWaitFor);

B. xEventGroupWaitBits(eventGroup, bitsToWaitFor, clearOnExit, pdFALSE, timeout);

C. xEventGroupWaitBits(eventGroup, bitsToWaitFor, clearOnExit, pdTRUE, timeout);

D. xEventGroupSetBits(eventGroup, bitsToWaitFor);

Solution

1. Step 1: Identify the AND mode parameter

   The fourth parameter is pdTRUE to wait for all bits (AND mode).

2. Step 2: Confirm function usage

   xEventGroupWaitBits waits for bits with parameters: event group, bits, clear flag, wait mode, timeout.

3. Final Answer:

   xEventGroupWaitBits(eventGroup, bitsToWaitFor, clearOnExit, pdTRUE, timeout); -> Option C

4. Quick Check:

   pdTRUE means AND mode in wait bits [OK]

Hint: pdTRUE means wait for all bits (AND) [OK]

Common Mistakes:

• Using pdFALSE for AND mode
• Confusing SetBits with WaitBits
• Mixing up clearOnExit parameter

3. Given the code snippet:

EventBits_t bits = xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdTRUE, pdFALSE, 1000);

What does bits contain if only BIT_1 is set in the event group before the call?

medium

A. Only BIT_1 set in bits

B. Both BIT_1 and BIT_2 set in bits

C. Zero (no bits set)

D. Function blocks indefinitely

Solution

1. Step 1: Understand wait mode pdFALSE

   pdFALSE means OR mode: wait for any bit set.

2. Step 2: Check which bits are set before call

   Only BIT_1 is set, but the third parameter is pdTRUE (clearOnExit), and the fourth parameter is pdFALSE (waitForAll = false), so the function waits for any bit set.

3. Step 3: Analyze the code

   However, the third parameter is pdTRUE (clearOnExit), so bits are cleared on exit. But since waitForAll is pdFALSE, the function returns when any bit is set.

4. Step 4: But the question is what bits contains if only BIT_1 is set before call

   Since waitForAll is false, the function returns immediately with bits containing BIT_1 set.

5. Final Answer:

   Only BIT_1 set in bits -> Option A

6. Quick Check:

   OR mode returns bits set among requested [OK]

Hint: pdFALSE means OR mode, returns any set bits [OK]

Common Mistakes:

• Assuming both bits must be set for return
• Thinking function blocks if not all bits set
• Confusing pdTRUE and pdFALSE meanings

4. Identify the error in this code snippet:

EventBits_t bits = xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdTRUE, pdTRUE, 500);

What is wrong?

medium

A. pdTRUE for waitForAll means wait for all bits, but clearOnExit should be false to avoid clearing

B. pdTRUE for clearOnExit clears bits on exit, which is valid; no error

C. Using pdTRUE for both clearOnExit and waitForAll bits is correct

D. pdTRUE for waitForAll is invalid; must be pdFALSE

Solution

1. Step 1: Understand clearOnExit parameter

   pdTRUE means bits are cleared when function returns.

2. Step 2: Understand waitForAll parameter

   pdTRUE means wait for all bits (AND mode), which is valid.

3. Final Answer:

   pdTRUE for clearOnExit clears bits on exit, which is valid; no error -> Option B

4. Quick Check:

   clearOnExit pdTRUE is allowed and common [OK]

Hint: clearOnExit pdTRUE clears bits on return, allowed [OK]

Common Mistakes:

• Thinking clearOnExit pdTRUE is always wrong
• Confusing waitForAll with clearOnExit
• Assuming pdTRUE for waitForAll is invalid

5. You want a task to wait until both BIT_1 and BIT_2 are set, then clear those bits automatically on exit. Which call achieves this correctly?

hard

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

B. xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdFALSE, pdFALSE, portMAX_DELAY);

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

D. xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdTRUE, pdTRUE, portMAX_DELAY);

Solution

1. Step 1: Identify wait for all bits

   Fourth parameter pdTRUE means wait for all bits (AND mode).

2. Step 2: Identify clear bits on exit

   Third parameter pdTRUE means clear bits on exit.

3. Step 3: Match parameters to options

   xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdTRUE, pdTRUE, portMAX_DELAY); uses clearOnExit = pdTRUE and waitForAll = pdTRUE, correct for requirement.

4. Final Answer:

   xEventGroupWaitBits(eventGroup, BIT_1 | BIT_2, pdTRUE, pdTRUE, portMAX_DELAY); -> Option D

5. Quick Check:

   Clear bits and wait all bits = clearOnExit pdTRUE, waitForAll pdTRUE [OK]

Hint: clearOnExit and waitForAll both pdTRUE for AND + clear [OK]

Common Mistakes:

• Mixing up clearOnExit and waitForAll parameters
• Using pdFALSE for waitForAll when AND needed
• Not setting timeout to wait indefinitely