Chapter 2. API Reference
vTaskDelay() specifies a time at which the task wishes to unblock relative to the time at which vTaskDelay()
is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after
vTaskDelay() is called. vTaskDelay() does not therefore provide a good method of controlling the frequency
of a periodic task as the path taken through the code, as well as other task and interrupt activity, will effect
the frequency at which vTaskDelay() gets called and therefore the time at which the task next executes. See
xTaskDelayUntil() for an alternative API function designed to facilitate fixed frequency execution. It does this
by specifying an absolute time (rather than a relative time) at which the calling task should unblock.
Example usage:
void vTaskFunction( void * pvParameters )
{
// Block for 500ms.
const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
for( ;; )
{
// Simply toggle the LED every 500ms, blocking between each toggle.
vToggleLED();
vTaskDelay( xDelay );
}
}
Parameters
• xTicksToDelay: The amount of time, in tick periods, that the calling task should block.
BaseType_t xTaskDelayUntil(TickType_t *const pxPreviousWakeTime, const TickType_t
xTimeIncrement)
INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. See the configuration
section for more information.
Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution
frequency.
This function differs from vTaskDelay () in one important aspect: vTaskDelay () will cause a task to block for
the specified number of ticks from the time vTaskDelay () is called. It is therefore difficult to use vTaskDelay
() by itself to generate a fixed execution frequency as the time between a task starting to execute and that task
calling vTaskDelay () may not be fixed [the task may take a different path though the code between calls, or
may get interrupted or preempted a different number of times each time it executes].
Whereas vTaskDelay () specifies a wake time relative to the time at which the function is called, xTaskDe-
layUntil () specifies the absolute (exact) time at which it wishes to unblock.
The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a time specified in millisec-
onds with a resolution of one tick period.
Example usage:
// Perform an action every 10 ticks.
void vTaskFunction( void * pvParameters )
{
TickType_t xLastWakeTime;
const TickType_t xFrequency = 10;
BaseType_t xWasDelayed;
// Initialise the xLastWakeTime variable with the current time.
xLastWakeTime = xTaskGetTickCount ();
for( ;; )
{
// Wait for the next cycle.
xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
// Perform action here. xWasDelayed value can be used to determine
// whether a deadline was missed if the code here took too long.
(continues on next page)
Espressif Systems 859
Submit Document Feedback
Release v4.4