Timer Management

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

The Timer Management function group allow creating and controlling of timers and callback functions in the system. A callback function is called when a time period expires whereby both one-shot and periodic timers are possible. A timer 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

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.

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.

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.

Example

#include "cmsis_os.h"
 
void Time_Callback  (void const *arg)  {                   // timer callback function
                                                           // arg contains &exec
                                                           // called every second after osTimerStart
} 

osTimerDef (Timer, Timer_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.

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
  :
}