nRF5 SDK v15.2.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Application Timer

Application timer functionality. More...

Modules

 Application timer functionality configuration
 
 RTC driver
 Real Timer Counter (RTC) peripheral driver for app_timer.
 

Data Structures

struct  app_timer_t
 
struct  app_timer_event_t
 Structure passed to app_scheduler. More...
 

Macros

#define APP_TIMER_LOG_NAME   app_timer
 Name of the module used for logger messaging.
 
#define APP_TIMER_CLOCK_FREQ   32768
 
#define APP_TIMER_MIN_TIMEOUT_TICKS   5
 
#define APP_TIMER_NODE_SIZE   32
 
#define APP_TIMER_SCHED_EVENT_DATA_SIZE   sizeof(app_timer_event_t)
 
#define APP_TIMER_MAX_CNT_VAL   RTC_COUNTER_COUNTER_Msk
 
#define APP_TIMER_TICKS(MS)
 Convert milliseconds to timer ticks. More...
 
#define APP_TIMER_DEF(timer_id)   _APP_TIMER_DEF(timer_id)
 Create a timer identifier and statically allocate memory for the timer. More...
 
#define _APP_TIMER_DEF(timer_id)
 

Typedefs

typedef void(* app_timer_timeout_handler_t )(void *p_context)
 Application time-out handler type.
 
typedef struct app_timer_t app_timer_t
 
typedef app_timer_tapp_timer_id_t
 Timer ID type. Never declare a variable of this type, but use the macro APP_TIMER_DEF instead.
 

Enumerations

enum  app_timer_mode_t {
  APP_TIMER_MODE_SINGLE_SHOT,
  APP_TIMER_MODE_REPEATED
}
 Timer modes. More...
 

Functions

ret_code_t app_timer_init (void)
 Function for initializing the timer module. More...
 
ret_code_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...
 
ret_code_t app_timer_start (app_timer_id_t timer_id, uint32_t timeout_ticks, void *p_context)
 Function for starting a timer. More...
 
ret_code_t app_timer_stop (app_timer_id_t timer_id)
 Function for stopping the specified timer. More...
 
ret_code_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)
 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...
 
void app_timer_pause (void)
 Function for pausing RTC activity which drives app_timer. More...
 
void app_timer_resume (void)
 Function for resuming RTC activity which drives app_timer. 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_DEF (   timer_id)
Value:
static app_timer_t CONCAT_2(timer_id,_data) = { {0} }; \
static const app_timer_id_t timer_id = &CONCAT_2(timer_id,_data)
#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)    _APP_TIMER_DEF(timer_id)

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

Parameters
timer_idName of the timer identifier variable that will be used to control the timer.
#define APP_TIMER_MAX_CNT_VAL   RTC_COUNTER_COUNTER_Msk

Maximum counter value that can be returned by app_timer_cnt_get.

#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_SCHED_EVENT_DATA_SIZE   sizeof(app_timer_event_t)

Size of event data when scheduler is used.

#define APP_TIMER_TICKS (   MS)
Value:
((uint32_t)ROUNDED_DIV( \
(MS) * (uint64_t)APP_TIMER_CLOCK_FREQ, \

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.

Parameters
[in]MSMilliseconds.
Returns
Number of timer ticks.

Enumeration Type Documentation

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 
)

Function for computing the difference between two RTC1 counter values.

Parameters
[in]ticks_toValue returned by app_timer_cnt_get().
[in]ticks_fromValue returned by app_timer_cnt_get().
Returns
Number of ticks from ticks_from to ticks_to.
uint32_t app_timer_cnt_get ( void  )

Function for returning the current value of the RTC1 counter.

Returns
Current value of the RTC1 counter.
ret_code_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_idPointer to timer identifier.
[in]modeTimer mode.
[in]timeout_handlerFunction to be executed when the timer expires.
Return values
NRF_SUCCESSIf the timer was successfully created.
NRF_ERROR_INVALID_PARAMIf a parameter was invalid.
NRF_ERROR_INVALID_STATEIf 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.
ret_code_t app_timer_init ( void  )

Function for initializing the timer module.

Return values
NRF_SUCCESSIf the module was initialized successfully.
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.
void app_timer_pause ( void  )

Function for pausing RTC activity which drives app_timer.

Note
This function can be used for debugging purposes to ensure that application is halted when entering a breakpoint.
void app_timer_resume ( void  )

Function for resuming RTC activity which drives app_timer.

Note
This function can be used for debugging purposes to resume application activity.
ret_code_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_idTimer identifier.
[in]timeout_ticksNumber of ticks (of RTC1, including prescaling) to time-out event (minimum 5 ticks).
[in]p_contextGeneral purpose pointer. Will be passed to the time-out handler when the timer expires.
Return values
NRF_SUCCESSIf the timer was successfully started.
NRF_ERROR_INVALID_PARAMIf a parameter was invalid.
NRF_ERROR_INVALID_STATEIf the application timer module has not been initialized or the timer has not been created.
NRF_ERROR_NO_MEMIf 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.
ret_code_t app_timer_stop ( app_timer_id_t  timer_id)

Function for stopping the specified timer.

Parameters
[in]timer_idTimer identifier.
Return values
NRF_SUCCESSIf the timer was successfully stopped.
NRF_ERROR_INVALID_PARAMIf a parameter was invalid.
NRF_ERROR_INVALID_STATEIf the application timer module has not been initialized or the timer has not been created.
NRF_ERROR_NO_MEMIf the timer operations queue was full.
ret_code_t app_timer_stop_all ( void  )

Function for stopping all running timers.

Return values
NRF_SUCCESSIf all timers were successfully stopped.
NRF_ERROR_INVALID_STATEIf the application timer module has not been initialized.
NRF_ERROR_NO_MEMIf the timer operations queue was full.

Documentation feedback | Developer Zone | Subscribe | Updated