CMSIS-RTOS RTX: Timer Management

| CMSIS-RTOS RTX Version 4.80 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Enumerations | Functions
Timer Management
CMSIS-RTOS API (RTX)

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

## Macros
#define | osTimerDef(name, function)
| Define a Timer object.
#define | osTimer(name) &os_timer_def_##name
| Access a Timer definition.

## 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.
osStatus | osTimerStart (osTimerId timer_id, uint32_t millisec)
| Start or restart a timer.
osStatus | osTimerStop (osTimerId timer_id)
| Stop the timer.
osStatus | osTimerDelete (osTimerId timer_id)
| Delete a timer that was created by osTimerCreate.

## 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.

#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.

## Enumeration Type Documentation

enum os_timer_type

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.

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
  - In RTX, this function is only available if you have set `OS_TIMERS` to 1 in the RTX_Conf_CM.c configuration file (User Timers enabled).
  - Cannot be called from Interrupt Service Routines.

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.

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.

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.

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.

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.

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.

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