Application timer functionality. More...

Modules
	Application timer functionality configuration

Data Structures
struct	app_timer_t

struct	app_timer_event_t
	Structure passed to app_scheduler. More...

Macros
#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_TICKS (MS)
	Convert milliseconds to timer ticks. More...

#define	APP_TIMER_DEF (timer_id)
	Create a timer identifier and statically allocate memory for the timer. 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.

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_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_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
         
         ,         \
        
         1000 * (
         
          APP_TIMER_CONFIG_RTC_FREQUENCY
         
         + 1)))

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] MS Milliseconds.

Returns: Number of timer ticks.

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
	)

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() .

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

ret_code_t app_timer_init ( void )

Function for initializing the timer module.

Return values

NRF_SUCCESS If 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_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.

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

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

Application Timer

nRF5 SDK v13.0.0

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation