Create and control timer and timer callback functions. More...

Data Structures
struct	osTimerAttr_t
	Attributes structure for timer. More...

Typedefs
typedef void *	osTimerId_t

typedef void(*	osTimerFunc_t )(void *argument)
	Entry point of a timer call back function. More...

Enumerations
enum	osTimerType_t { osTimerOnce = 0, osTimerPeriodic = 1 }
	Timer type. More...

Functions
osTimerId_t	osTimerNew (osTimerFunc_t func, osTimerType_t type, void argument, const osTimerAttr_t attr)
	Create and Initialize a timer. More...

const char *	osTimerGetName (osTimerId_t timer_id)
	Get name of a timer. More...

osStatus_t	osTimerStart (osTimerId_t timer_id, uint32_t ticks)
	Start or restart a timer. More...

osStatus_t	osTimerStop (osTimerId_t timer_id)
	Stop a timer. More...

uint32_t	osTimerIsRunning (osTimerId_t timer_id)
	Check if a timer is running. More...

osStatus_t	osTimerDelete (osTimerId_t timer_id)
	Delete a timer. More...

Description

In addition to the Generic Wait Functions CMSIS-RTOS also supports virtual timer objects. These timer objects can trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated code with the timer. Each timer can be configured as a one-shot or a periodic timer. A periodic timer repeats its operation until it is deleted or stopped. All timers can be started, restarted, or stopped.

Note: RTX handles Timers in the thread osRtxTimerThread. Callback functions run under control of this thread and may use other CMSIS-RTOS API calls. The osRtxTimerThread is configured in Timer Configuration.; Timer management functions cannot be called from Interrupt Service Routines.

The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the callback function.

Behavior of a Periodic Timer

Working with Timers

The following steps are required to use a timer:

Define the timers:
osTimerId_t one_shot_id, periodic_id;
Instantiate and start the timers:
// creates a one-shot timer:

one_shot_id = osTimerNew((osTimerFunc_t)&one_shot_Callback, osTimerOnce, (void *)0); // (void*)0 is passed as an argument

// to the callback function

// creates a periodic timer:

periodic_id = osTimerNew((osTimerFunc_t)&periodic_Callback, osTimerPeriodic, (void *)5); // (void*)5 is passed as an argument

// to the callback function

osTimerStart(one_shot_id, 500);

osTimerStart(periodic_id, 1500);

Data Structure Documentation

struct osTimerAttr_t

Data Fields
const char *	name	name of the timer
uint32_t	attr_bits	attribute bits
void *	cb_mem	memory for control block
uint32_t	cb_size	size of provided memory for control block

Typedef Documentation

osTimerId_t

Timer ID identifies the timer.

Instances of this type hold a reference to a timer object.

void(* osTimerFunc_t)(void *argument)

Enumeration Type Documentation

enum osTimerType_t

The osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function osTimerNew.

Enumerator
osTimerOnce	One-shot timer.
osTimerPeriodic	Repeating timer.

Function Documentation

osTimerId_t osTimerNew	(	osTimerFunc_t	func,
		osTimerType_t	type,
		void *	argument,
		const osTimerAttr_t *	attr
	)

Parameters

[in]	func	start address of a timer call back function.
[in]	type	osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
[in]	argument	argument to the timer call back function.
[in]	attr	timer attributes; NULL: default values.

Returns: timer ID for reference by other functions or NULL in case of error.

The function osTimerNew creates an one-shot or periodic timer and associates it with a callback function with argument. The timer is in stopped state until it is started with osTimerStart.

The parameter func specifies the start address of the timer callback function.

The parameter type specifies the type of the timer (refer to osTimerType_t).

The parameter attr sets the timer attributes (refer to osTimerAttr_t). Default attributes will be used if set to NULL.

The function osTimerNew returns the pointer to the timer object identifier or NULL in case of an error.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
 
void Timer1_Callback  (void const *arg);                   // prototypes for timer callback function
void Timer2_Callback  (void const *arg);                   
 
uint32_t  exec1;                                           // argument for the timer call back function
uint32_t  exec2;                                           // argument for the timer call back function
 
void TimerCreate_example (void)  {
  osTimerId_t id1;                                         // timer id
  osTimerId_t id2;                                         // timer id
 
  // Create one-shoot timer
  exec1 = 1;
  id1 = osTimerNew ((osTimerFunc_t)&Timer1_Callback, osTimerOnce, &exec1, NULL);
  if (id1 != NULL)  {
    // One-shoot timer created
  }
 
  // Create periodic timer
  exec2 = 2;
  id2 = osTimerNew ((osTimerFunc_t)&Timer2_Callback, osTimerPeriodic, &exec2, NULL);
  if (id2 != NULL)  {
    // Periodic timer created
  }
  :
}

*const char * osTimerGetName ( osTimerId_t timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerNew.

Returns: name as NULL terminated string.

The function osTimerGetName returns the pointer to the name string of the timer identified by parameter timer_id or NULL in case of an error.

Note: This function cannot be called from Interrupt Service Routines.

osStatus_t osTimerStart	(	osTimerId_t	timer_id,
		uint32_t	ticks
	)

Parameters

[in]	timer_id	timer ID obtained by osTimerNew.
[in]	ticks	time ticks value of the timer.

Returns: status code that indicates the execution status of the function.

The function osTimerStart starts or restarts a timer specified by the parameter timer_id. The parameter ticks specifies the value of the timer in time ticks.

Possible osStatus_t return values:

osOK: the specified timer has been started or restarted.
osErrorISR: osTimerStart cannot be called from interrupt service routines.
osErrorParameter: parameter timer_id is either NULL or invalid or ticks is incorrect.
osErrorResource: the timer specified by parameter timer_id is in an invalid timer state.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
  
void Timer_Callback  (void const *arg)  {                   // timer callback function
                                                            // arg contains &exec
                                                            // called every second after osTimerStart
} 
 
uint32_t  exec;                                             // argument for the timer call back function
 
void TimerStart_example (void)  {
  osTimerId_t id;                                           // timer id
  uint32_t    timerDelay;                                   // timer value
  osStatus_t  status;                                       // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
  if (id)  {
    timerDelay = 1000;
    status = osTimerStart (id, timerDelay);                 // start timer
    if (status != osOK)  {
      // Timer could not be started
    } 
  }
  ;
}

osStatus_t osTimerStop ( osTimerId_t timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerNew.

Returns: status code that indicates the execution status of the function.

The function osTimerStop stops a timer specified by the parameter timer_id.

Possible osStatus_t return values:

osOK: the specified timer has been stopped.
osErrorISR: osTimerStop cannot be called from interrupt service routines.
osErrorParameter: parameter timer_id is either NULL or invalid.
osErrorResource: the timer specified by parameter timer_id is not running (you can only stop a running timer).

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
 
void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function
void TimerStop_example (void)  {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000);                                 // start timer
  :
  status = osTimerStop (id);                               // stop timer
  if (status != osOK)  {
    // Timer could not be stopped
  } 
  ;
  osTimerStart (id, 1000);                                 // start timer again
  ;
}

uint32_t osTimerIsRunning ( osTimerId_t timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerNew.

Returns: 0 not running, 1 running.

the function osTimerIsRunning checks whether a timer specified by parameter timer_id is running. It returns 1 if the timer is running and 0 if the timer is stopped or an error occurred.

Note: This function cannot be called from Interrupt Service Routines.

osStatus_t osTimerDelete ( osTimerId_t timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerNew.

Returns: status code that indicates the execution status of the function.

The function osTimerDelete deletes the timer specified by parameter timer_id.

Possible osStatus_t return values:

osOK: the specified timer has been deleted.
osErrorISR: osTimerDelete cannot be called from interrupt service routines.
osErrorParameter: parameter timer_id is either NULL or invalid.
osErrorResource: the timer specified by parameter timer_id is in an invalid timer state.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function
void TimerDelete_example (void)  {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status  
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000UL);                               // start timer
  ;
  status = osTimerDelete (id);                             // stop and delete timer
  if (status != osOK)  {
    // Timer could not be deleted
  } 
  ;
}

Data Structures

Typedefs

Enumerations

Functions

Description

Working with Timers

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation