Chapter 2. API Reference
• xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the con-
stant portTICK_PERIOD_MS can be used to convert a time that has been specified in millisec-
onds. For example, if the timer must expire after 100 ticks, then xTimerPeriodInTicks should be
set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 /
portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. Time
timer period must be greater than 0.
• uxAutoReload: If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a
frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the
timer will be a one-shot timer and enter the dormant state after it expires.
• pvTimerID: An identifier that is assigned to the timer being created. Typically this would be used
in the timer callback function to identify which timer expired when the same callback function is
assigned to more than one timer.
• pxCallbackFunction: The function to call when the timer expires. Callback functions must
have the prototype defined by TimerCallbackFunction_t, which is“void vCallbackFunction( Timer-
Handle_t xTimer );”.
TimerHandle_t xTimerCreateStatic(const char *const pcTimerName, const TickType_t
xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void
*const pvTimerID, TimerCallbackFunction_t pxCallbackFunc-
tion, StaticTimer_t *pxTimerBuffer)
TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, TickType_t xTimerPeriodInTicks,
UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction, Static-
Timer_t *pxTimerBuffer );
Creates a new software timer instance, and returns a handle by which the created software timer can be refer-
enced.
Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer
data structure is stored. If a software timer is created using xTimerCreate() then the required memory is auto-
matically dynamically allocated inside the xTimerCreate() function. (see https://www.FreeRTOS.org/a00111.
html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the
memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be
created without using any dynamic memory allocation.
Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimer-
ResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used
to transition a timer into the active state.
Example usage:
*
* // The buffer used to hold the software timer's data structure.
* static StaticTimer_t xTimerBuffer;
*
* // A variable that will be incremented by the software timer's callback
* // function.
* UBaseType_t uxVariableToIncrement = 0;
*
* // A software timer callback function that increments a variable passed to
* // it when the software timer was created. After the 5th increment the
* // callback function stops the software timer.
* static void prvTimerCallback( TimerHandle_t xExpiredTimer )
* {
* UBaseType_t *puxVariableToIncrement;
* BaseType_t xReturned;
*
* // Obtain the address of the variable to increment from the timer ID.
* puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID(␣
,→xExpiredTimer );
*
* // Increment the variable to show the timer callback has executed.
* ( *puxVariableToIncrement )++;
*
(continues on next page)
Espressif Systems 916
Submit Document Feedback
Release v4.4
To Next Page
Loading...