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

Macros
#define	osTimerDef(name, function)
	Define a Timer object. More...

#define	osTimer(name) &os_timer_def_##name
	Access a Timer definition. More...

Enumerations
enum	os_timer_type { osTimerOnce = 0, osTimerPeriodic = 1 }

Functions
osTimerId	osTimerCreate (const osTimerDef_t timer_def, os_timer_type type, void argument)
	Create a timer. More...

osStatus	osTimerStart (osTimerId timer_id, uint32_t millisec)
	Start or restart a timer. More...

osStatus	osTimerStop (osTimerId timer_id)
	Stop the timer. More...

osStatus	osTimerDelete (osTimerId timer_id)
	Delete a timer that was created by osTimerCreate. 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. The timer number is passed as a parameter to the callback function. 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.

Timers are handled in the thread osTimerThread. Callback functions run under control of this thread and may use other CMSIS-RTOS API calls.

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:
osTimerDef(one_shot, start_machine); // when the timer expires, the function start_machine is called

osTimerDef(periodic, toggle_power); // when the timer expires, the function toggle_power is called

osTimerId one_shot_id, periodic_id;
Instantiate and start the timers in an RTOS thread:
one_shot_id = osTimerCreate(osTimer(one_shot), osTimerOnce, (void *)0); // creates a one-shot timer;

// (void*)0 is passed as an argument to the callback function

periodic_id = osTimerCreate(osTimer(periodic), osTimerPeriodic, (void *)5); // creates a periodic timer;

// (void*)5 is passed as an argument to the callback function

osTimerStart(one_shot_id, 500);

osTimerStart(periodic, 1500);

Macro Definition Documentation

#define osTimer ( name ) &os_timer_def_##name

Access to the timer definition for the function osTimerCreate.

Parameters

name	name of the timer object.

Note: CAN BE CHANGED: The parameter to osTimer shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

#define osTimerDef	(	name,
		function
	)

Define the attributes of a timer.

Parameters

name	name of the timer object.
function	name of the timer call back function.

Note: CAN BE CHANGED: The parameter to osTimerDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

Enumeration Type Documentation

enum os_timer_type

Note: MUST REMAIN UNCHANGED: os_timer_type shall be consistent in every CMSIS-RTOS. The os_timer_type specifies the a repeating (periodic) or one-shot timer for the function osTimerCreate.

Enumerator
osTimerOnce	one-shot timer
osTimerPeriodic	repeating timer

Function Documentation

osTimerId osTimerCreate	(	const osTimerDef_t *	timer_def,
		os_timer_type	type,
		void *	argument
	)

Parameters

[in]	timer_def	timer object referenced with osTimer.
[in]	type	osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
[in]	argument	argument to the timer call back function.

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

Note: MUST REMAIN UNCHANGED: osTimerCreate shall be consistent in every CMSIS-RTOS.

Create a one-shot or periodic timer and associate it with a callback function argument. The timer is in stopped until it is started with osTimerStart.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
 
void Timer1_Callback  (void const *arg);                   // prototypes for timer callback function
void Timer2_Callback  (void const *arg);                   
 
osTimerDef (Timer1, Timer1_Callback);                      // define timers
osTimerDef (Timer2, Timer2_Callback);
 
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 id1;                                           // timer id
  osTimerId id2;                                           // timer id
 
  // Create one-shoot timer
  exec1 = 1;
  id1 = osTimerCreate (osTimer(Timer1), osTimerOnce, &exec1);
  if (id1 != NULL)  {
    // One-shoot timer created
  }
 
  // Create periodic timer
  exec2 = 2;
  id2 = osTimerCreate (osTimer(Timer2), osTimerPeriodic, &exec2);
  if (id2 != NULL)  {
    // Periodic timer created
  }
  :
}

osStatus osTimerDelete ( osTimerId timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerCreate.

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

Note: MUST REMAIN UNCHANGED: osTimerDelete shall be consistent in every CMSIS-RTOS.

Delete the timer object.

Status and Error Codes

osOK: the specified timer has been deleted.
osErrorISR: osTimerDelete cannot be called from interrupt service routines.
osErrorParameter: timer_id is incorrect.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void Timer_Callback  (void const *arg);                    // prototype for timer callback function
osTimerDef (Timer, Timer_Callback);                        // define timer
 
void TimerDelete_example (void)  {
  osTimerId id;                                            // timer id
  osStatus status;                                         // function return status  
 
  // Create periodic timer
  exec = 1;
  id = osTimerCreate (osTimer(Timer2), osTimerPeriodic, NULL);
  osTimerStart (id, 1000UL);                               // start timer
  :
  status = osTimerDelete (id);                             // stop and delete timer
  if (status != osOK)  {
    // Timer could not be deleted
  } 
  :
}

osStatus osTimerStart	(	osTimerId	timer_id,
		uint32_t	millisec
	)

Parameters

[in]	timer_id	timer ID obtained by osTimerCreate.
[in]	millisec	time delay value of the timer.

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

Note: MUST REMAIN UNCHANGED: osTimerStart shall be consistent in every CMSIS-RTOS.

Start or restart the timer.

Status and Error Codes

osOK: the specified timer has been started or restarted.
osErrorISR: osTimerStart cannot be called from interrupt service routines.
osErrorParameter: timer_id is incorrect.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
 
void Time_Callback  (void const *arg)  {                   // timer callback function
                                                           // arg contains &exec
                                                           // called every second after osTimerStart
} 
 
osTimerDef (Timer, Time_Callback);                         // define timer
uint32_t  exec;                                            // argument for the timer call back function
 
void TimerStart_example (void)  {
  osTimerId id;                                            // timer id
  uint32_t  timerDelay;                                    // timer value
  osStatus  status;                                        // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerCreate (osTimer(Timer), osTimerPeriodic, &exec);
  if (id)  {
    timerDelay = 1000;
    status = osTimerStart (id, timerDelay);                // start timer
    if (status != osOK)  {
      // Timer could not be started
    } 
  }
  :
}

osStatus osTimerStop ( osTimerId timer_id )

Parameters

[in] timer_id timer ID obtained by osTimerCreate.

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

Note: MUST REMAIN UNCHANGED: osTimerStop shall be consistent in every CMSIS-RTOS.

Stop the timer.

Status and Error Codes

osOK: the specified timer has been stopped.
osErrorISR: osTimerStop cannot be called from interrupt service routines.
osErrorParameter: timer_id is incorrect.
osErrorResource: the timer is not started.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
 
void Timer_Callback  (void const *arg);                    // prototype for timer callback function
osTimerDef (Timer, Timer_Callback);                        // define timer
 
void TimerStop_example (void)  {
  osTimerId id;                                            // timer id
  osStatus status;                                         // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerCreate (osTimer(Timer2), osTimerPeriodic, 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
  :
}

Macros

Enumerations

Functions

Description

Working with Timers

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation