| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Application Timer
SDK common libraries

Application timer functionality. More...

## Modules
| Application timer functionality configuration

## Data Structures
struct | app_timer_t

## Macros
#define | APP_TIMER_CLOCK_FREQ 32768
#define | APP_TIMER_MIN_TIMEOUT_TICKS 5
#define | APP_TIMER_NODE_SIZE 32
#define | APP_TIMER_USER_OP_SIZE 24
#define | APP_TIMER_BUF_SIZE(OP_QUEUE_SIZE)
| Compute number of bytes required to hold the application timer data structures. More...
#define | APP_TIMER_TICKS(MS, PRESCALER) ((uint32_t)ROUNDED_DIV((MS) * (uint64_t)APP_TIMER_CLOCK_FREQ, ((PRESCALER) + 1) * 1000))
| Convert milliseconds to timer ticks. More...
#define | APP_TIMER_DEF(timer_id)
| Create a timer identifier and statically allocate memory for the timer. More...
#define | APP_TIMER_INIT(PRESCALER, OP_QUEUE_SIZE, SCHEDULER_FUNC)
| Initialize the application timer module. More...

## Typedefs
typedef struct app_timer_t | app_timer_t
typedef app_timer_t * | app_timer_id_t
| Timer ID type. Never declare a variable of this type, but use the macro APP_TIMER_DEF instead.
typedef void(* | app_timer_timeout_handler_t )(void *p_context)
| Application time-out handler type.
typedef uint32_t(* | app_timer_evt_schedule_func_t )(app_timer_timeout_handler_t timeout_handler, void *p_context)
| Type of function for passing events from the timer module to the scheduler.

## Enumerations
enum | app_timer_mode_t { APP_TIMER_MODE_SINGLE_SHOT, APP_TIMER_MODE_REPEATED }
| Timer modes. More...

## Functions
uint32_t | app_timer_init (uint32_t prescaler, uint8_t op_queue_size, void *p_buffer, app_timer_evt_schedule_func_t evt_schedule_func)
| Function for initializing the timer module. More...
uint32_t | app_timer_create (app_timer_id_t const *p_timer_id, app_timer_mode_t mode, app_timer_timeout_handler_t timeout_handler)
| Function for creating a timer instance. More...
uint32_t | app_timer_start (app_timer_id_t timer_id, uint32_t timeout_ticks, void *p_context)
| Function for starting a timer. More...
uint32_t | app_timer_stop (app_timer_id_t timer_id)
| Function for stopping the specified timer. More...
uint32_t | app_timer_stop_all (void)
| Function for stopping all running timers. More...
uint32_t | app_timer_cnt_get (void)
| Function for returning the current value of the RTC1 counter. More...
uint32_t | app_timer_cnt_diff_compute (uint32_t ticks_to, uint32_t ticks_from, uint32_t *p_ticks_diff)
| Function for computing the difference between two RTC1 counter values. More...
uint8_t | app_timer_op_queue_utilization_get (void)
| Function for getting the maximum observed operation queue utilization. More...

## Detailed Description

Application timer functionality.

This module enables the application to create multiple timer instances based on the RTC1 peripheral. Checking for time-outs and invocation of user time-out handlers is performed in the RTC1 interrupt handler. List handling is done using a software interrupt (SWI0). Both interrupt handlers are running in APP_LOW priority level.

When calling app_timer_start() or app_timer_stop(), the timer operation is just queued, and the software interrupt is triggered. The actual timer start/stop operation is executed by the SWI0 interrupt handler. Since the SWI0 interrupt is running in APP_LOW, if the application code calling the timer function is running in APP_LOW or APP_HIGH, the timer operation will not be performed until the application handler has returned. This will be the case, for example, when stopping a timer from a time-out handler when not using the scheduler.

Use the USE_SCHEDULER parameter of the APP_TIMER_INIT() macro to select if the Scheduler should be used or not. Even if the scheduler is not used, app_timer.h will include app_scheduler.h, so when compiling, app_scheduler.h must be available in one of the compiler include paths.

## Macro Definition Documentation

#define APP_TIMER_BUF_SIZE | ( |  | OP_QUEUE_SIZE | ) |

Value:
( \
( \
(((OP_QUEUE_SIZE) + 1) * APP_TIMER_USER_OP_SIZE) \
) \
)

Compute number of bytes required to hold the application timer data structures.

Parameters

  [in] | OP_QUEUE_SIZE | Size of the queue holding timer operations that are pending execution. Note that due to the queue implementation, this size must be one more than the size that is actually needed.

Returns
  Required application timer buffer size (in bytes).

#define APP_TIMER_CLOCK_FREQ 32768

Clock frequency of the RTC timer used to implement the app timer module.

#define APP_TIMER_DEF | ( |  | timer_id | ) |

Value:
static app_timer_t timer_id##_data = { {0} }; \
static const app_timer_id_t timer_id = &timer_id##_data

Create a timer identifier and statically allocate memory for the timer.

Parameters

  timer_id | Name of the timer identifier variable that will be used to control the timer.

#define APP_TIMER_INIT | ( |  | PRESCALER,
|  |  | OP_QUEUE_SIZE,
|  |  | SCHEDULER_FUNC
| ) |  |

Value:
do \
{ \
static uint32_t APP_TIMER_BUF[CEIL_DIV(APP_TIMER_BUF_SIZE(OP_QUEUE_SIZE), \
sizeof(uint32_t))]; \
uint32_t ERR_CODE = app_timer_init((PRESCALER), \
(OP_QUEUE_SIZE) + 1, \
APP_TIMER_BUF, \
SCHEDULER_FUNC); \
APP_ERROR_CHECK(ERR_CODE); \
} while (0)

Initialize the application timer module.

This macro handles dimensioning and allocation of the memory buffer required by the timer, making sure that the buffer is correctly aligned. It will also connect the timer module to the scheduler (if specified).

Note
  This module assumes that the LFCLK is already running. If it is not, the module will be non-functional, since the RTC will not run. If you do not use a SoftDevice, you must start the LFCLK manually. See the rtc_example's lfclk_config() function for an example of how to do this. If you use a SoftDevice, the LFCLK is started on SoftDevice init.

Parameters

  [in] | PRESCALER | Value of the RTC1 PRESCALER register. This will decide the timer tick rate. Set to 0 for no prescaling.
  [in] | OP_QUEUE_SIZE | Size of the queue holding timer operations that are pending execution.
  [in] | SCHEDULER_FUNC | Pointer to scheduler event handler

Note
  Since this macro allocates a buffer, it must only be called once (it is OK to call it several times as long as it is from the same location, for example, to do a re-initialization).

#define APP_TIMER_MIN_TIMEOUT_TICKS 5

Minimum value of the timeout_ticks parameter of app_timer_start().

#define APP_TIMER_NODE_SIZE 32

Size of app_timer.timer_node_t (used to allocate data).

#define APP_TIMER_TICKS | ( |  | MS,
|  |  | PRESCALER
| ) |  | ((uint32_t)ROUNDED_DIV((MS) * (uint64_t)APP_TIMER_CLOCK_FREQ, ((PRESCALER) + 1) * 1000))

Convert milliseconds to timer ticks.

This macro uses 64-bit integer arithmetic, but as long as the macro parameters are constants (i.e. defines), the computation will be done by the preprocessor.

When using this macro, ensure that the values provided as input result in an output value that is supported by the app_timer_start function. For example, when the ticks for 1 ms is needed, the maximum possible value of PRESCALER must be 6, when APP_TIMER_CLOCK_FREQ is 32768. This will result in a ticks value as 5. Any higher value for PRESCALER will result in a ticks value that is not supported by this module.

Parameters

  [in] | MS | Milliseconds.
  [in] | PRESCALER | Value of the RTC1 PRESCALER register (must be the same value that was passed to APP_TIMER_INIT()).

Returns
  Number of timer ticks.

#define APP_TIMER_USER_OP_SIZE 24

Size of app_timer.timer_user_op_t (only for use inside APP_TIMER_BUF_SIZE()).

## Enumeration Type Documentation

enum app_timer_mode_t

Timer modes.

Enumerator
APP_TIMER_MODE_SINGLE_SHOT | The timer will expire only once.
APP_TIMER_MODE_REPEATED | The timer will restart each time it expires.

## Function Documentation

uint32_t app_timer_cnt_diff_compute | ( | uint32_t | ticks_to,
|  | uint32_t | ticks_from,
|  | uint32_t * | p_ticks_diff
| ) |  |

Function for computing the difference between two RTC1 counter values.

Parameters

  [in] | ticks_to | Value returned by app_timer_cnt_get().
  [in] | ticks_from | Value returned by app_timer_cnt_get().
  [out] | p_ticks_diff | Number of ticks from ticks_from to ticks_to.

Return values

  NRF_SUCCESS | If the counter difference was successfully computed.

uint32_t app_timer_cnt_get | ( | void |  | ) |

Function for returning the current value of the RTC1 counter.

Returns
  Current value of the RTC1 counter.

uint32_t app_timer_create | ( | app_timer_id_t const * | p_timer_id,
|  | app_timer_mode_t | mode,
|  | app_timer_timeout_handler_t | timeout_handler
| ) |  |

Function for creating a timer instance.

Parameters

  [in] | p_timer_id | Pointer to timer identifier.
  [in] | mode | Timer mode.
  [in] | timeout_handler | Function to be executed when the timer expires.

Return values

  NRF_SUCCESS | If the timer was successfully created.
  NRF_ERROR_INVALID_PARAM | If a parameter was invalid.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized or the timer is running.

Note
  This function does the timer allocation in the caller's context. It is also not protected by a critical region. Therefore care must be taken not to call it from several interrupt levels simultaneously.
  The function can be called again on the timer instance and will re-initialize the instance if the timer is not running.

Attention
  The FreeRTOS and RTX app_timer implementation does not allow app_timer_create to be called on the previously initialized instance.

uint32_t app_timer_init | ( | uint32_t | prescaler,
|  | uint8_t | op_queue_size,
|  | void * | p_buffer,
|  | app_timer_evt_schedule_func_t | evt_schedule_func
| ) |  |

Function for initializing the timer module.

Normally, initialization should be done using the APP_TIMER_INIT() macro, because that macro will both allocate the buffers needed by the timer module (including aligning the buffers correctly) and take care of connecting the timer module to the scheduler (if specified).

Parameters

  [in] | prescaler | Value of the RTC1 PRESCALER register. Set to 0 for no prescaling.
  [in] | op_queue_size | Size of the queue holding timer operations that are pending execution. Note that due to the queue implementation, this size must be one more than the size that is actually needed.
  [in] | p_buffer | Pointer to memory buffer for internal use in the app_timer module. The size of the buffer can be computed using the APP_TIMER_BUF_SIZE() macro. The buffer must be aligned to a 4 byte boundary.
  [in] | evt_schedule_func | Function for passing time-out events to the scheduler. Point to app_timer_evt_schedule() to connect to the scheduler. Set to NULL to make the timer module call the time-out handler directly from the timer interrupt handler.

Return values

  NRF_SUCCESS | If the module was initialized successfully.
  NRF_ERROR_INVALID_PARAM | If a parameter was invalid (buffer not aligned to a 4 byte boundary or NULL).

uint8_t app_timer_op_queue_utilization_get | ( | void |  | ) |

Function for getting the maximum observed operation queue utilization.

Function for tuning the module and determining OP_QUEUE_SIZE value and thus module RAM usage.

Note
  APP_TIMER_WITH_PROFILER must be enabled to use this functionality.

Returns
  Maximum number of events in queue observed so far.

uint32_t app_timer_start | ( | app_timer_id_t | timer_id,
|  | uint32_t | timeout_ticks,
|  | void * | p_context
| ) |  |

Function for starting a timer.

Parameters

  [in] | timer_id | Timer identifier.
  [in] | timeout_ticks | Number of ticks (of RTC1, including prescaling) to time-out event (minimum 5 ticks).
  [in] | p_context | General purpose pointer. Will be passed to the time-out handler when the timer expires.

Return values

  NRF_SUCCESS | If the timer was successfully started.
  NRF_ERROR_INVALID_PARAM | If a parameter was invalid.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized or the timer has not been created.
  NRF_ERROR_NO_MEM | If the timer operations queue was full.

Note
  The minimum timeout_ticks value is 5.
  For multiple active timers, time-outs occurring in close proximity to each other (in the range of 1 to 3 ticks) will have a positive jitter of maximum 3 ticks.
  When calling this method on a timer that is already running, the second start operation is ignored.

uint32_t app_timer_stop | ( | app_timer_id_t | timer_id | ) |

Function for stopping the specified timer.

Parameters

  [in] | timer_id | Timer identifier.

Return values

  NRF_SUCCESS | If the timer was successfully stopped.
  NRF_ERROR_INVALID_PARAM | If a parameter was invalid.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized or the timer has not been created.
  NRF_ERROR_NO_MEM | If the timer operations queue was full.

uint32_t app_timer_stop_all | ( | void |  | ) |

Function for stopping all running timers.

Return values

  NRF_SUCCESS | If all timers were successfully stopped.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized.
  NRF_ERROR_NO_MEM | If the timer operations queue was full.