xTimerReset macro

BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait ); Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant. xTimerReset() re-starts a timer that was previously created using the xTimerCreate() API function. If the timer had already been started and was already in the active state, then xTimerReset() will cause the timer to re-evaluate its expiry time so that it is relative to when xTimerReset() was called. If the timer was in the dormant state then xTimerReset() has equivalent functionality to the xTimerStart() API function. Resetting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called 'n' ticks after xTimerReset() was called, where 'n' is the timers defined period. It is valid to call xTimerReset() before the scheduler has been started, but when this is done the timer will not actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is started, not relative to when xTimerReset() was called. The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset() to be available. Example usage: @verbatim // When a key is pressed, an LCD back-light is switched on. If 5 seconds pass // without a key being pressed, then the LCD back-light is switched off. In // this case, the timer is a one-shot timer. TimerHandle_t xBacklightTimer = NULL; // The callback function assigned to the one-shot timer. In this case the // parameter is not used. void vBacklightTimerCallback( TimerHandle_t pxTimer ) { // The timer expired, therefore 5 seconds must have passed since a key // was pressed. Switch off the LCD back-light. vSetBacklightState( BACKLIGHT_OFF ); } // The key press event handler. void vKeyPressEventHandler( char cKey ) { // Ensure the LCD back-light is on, then reset the timer that is // responsible for turning the back-light off after 5 seconds of // key inactivity. Wait 10 ticks for the command to be successfully sent // if it cannot be sent immediately. vSetBacklightState( BACKLIGHT_ON ); if( xTimerReset( xBacklightTimer, 100 ) != pdPASS ) { // The reset command was not executed successfully. Take appropriate // action here. } // Perform the rest of the key processing here. } void main( void ) { int32_t x; // Create then start the one-shot timer that is responsible for turning // the back-light off if no keys are pressed within a 5 second period. xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a text name, not used by the kernel. ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks. pdFALSE, // The timer is a one-shot timer. 0, // The id is not used by the callback so can take any value. vBacklightTimerCallback // The callback function that switches the LCD back-light off. ); if( xBacklightTimer == NULL ) { // The timer was not created. } else { // Start the timer. No block time is specified, and even if one was // it would be ignored because the scheduler has not yet been // started. if( xTimerStart( xBacklightTimer, 0 ) != pdPASS ) { // The timer could not be set into the Active state. } } // ... // Create tasks here. // ... // Starting the scheduler will start the timer running as it has already // been set into the active state. vTaskStartScheduler(); // Should not reach here. for( ;; ); } @endverbatim