Application timer functionality. More...

Macros
#define	APP_TIMER_CLOCK_FREQ 32768

#define	APP_TIMER_MIN_TIMEOUT_TICKS 5

#define	APP_TIMER_NODE_SIZE 40

#define	APP_TIMER_USER_OP_SIZE 24

#define	APP_TIMER_USER_SIZE 8

#define	APP_TIMER_INT_LEVELS 3

#define	APP_TIMER_BUF_SIZE(MAX_TIMERS, 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_INIT(PRESCALER, MAX_TIMERS, OP_QUEUES_SIZE, SCHEDULER_FUNC)
	Macro for initializing the application timer module. More...

Typedefs
typedef uint32_t	app_timer_id_t
	Timer id type.

typedef void(*	app_timer_timeout_handler_t )(void *p_context)
	Application timeout 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 max_timers, uint8_t op_queues_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 *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 (uint32_t *p_ticks)
	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...

Detailed Description

Application timer functionality.

It enables the application to create multiple timer instances based on the RTC1 peripheral. Checking for timeouts and invokation of user timeout 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.

Note: 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 e.g. when stopping a timer from a timeout handler when not using the scheduler.

Use the USE_SCHEDULER parameter of the APP_TIMER_INIT() macro to select if the Scheduler is to be used or not.

Note: 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	(	MAX_TIMERS,
		OP_QUEUE_SIZE
	)

Value:

(                                                                                              \
        ((MAX_TIMERS) * APP_TIMER_NODE_SIZE)                                                       \
        +                                                                                          \
        (                                                                                          \
            APP_TIMER_INT_LEVELS                                                                   \
            *                                                                                      \
            (APP_TIMER_USER_SIZE + ((OP_QUEUE_SIZE) + 1) * APP_TIMER_USER_OP_SIZE)                 \
        )                                                                                          \
    )

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

Parameters

[in]	MAX_TIMERS	Maximum number of timers that can be created at any given time.
[in]	OP_QUEUE_SIZE	Size of queues holding timer operations that are pending execution. NOTE: 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_INIT	(	PRESCALER,
		MAX_TIMERS,
		OP_QUEUES_SIZE,
		SCHEDULER_FUNC
	)

Value:

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

Macro for initializing the application timer module.

It will handle 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 isn't, the module will be non-functional, since the RTC will not run. If you don't use a softdevice, you'll have to 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]	MAX_TIMERS	Maximum number of timers that can be created at any given time.
[in]	OP_QUEUES_SIZE	Size of queues 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, e.g. to do a reinitialization).

#define APP_TIMER_INT_LEVELS 3

Number of interrupt levels from where timer operations may be initiated (only for use inside APP_TIMER_BUF_SIZE()).

#define APP_TIMER_MIN_TIMEOUT_TICKS 5

Minimum value of the timeout_ticks parameter of app_timer_start().

#define APP_TIMER_NODE_SIZE 40

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

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

Note: 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.
[in]	PRESCALER	Value of the RTC1 PRESCALER register (must be the same value that was passed to APP_TIMER_INIT()).

Note: When using this macro, it is the responsibility of the developer to 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.

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

#define APP_TIMER_USER_SIZE 8

Size of app_timer.timer_user_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 Counter difference was successfully computed.

uint32_t app_timer_cnt_get ( uint32_t * p_ticks )

Function for returning the current value of the RTC1 counter.

Parameters

[out] p_ticks Current value of the RTC1 counter.

Return values

NRF_SUCCESS Counter was successfully read.

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

Function for creating a timer instance.

Parameters

[out]	p_timer_id	Id of the newly created timer.
[in]	mode	Timer mode.
[in]	timeout_handler	Function to be executed when the timer expires.

Return values

NRF_SUCCESS	Timer was successfully created.
NRF_ERROR_INVALID_PARAM	Invalid parameter.
NRF_ERROR_INVALID_STATE	Application timer module has not been initialized.
NRF_ERROR_NO_MEM	Maximum number of timers has already been reached.

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.

uint32_t app_timer_init	(	uint32_t	prescaler,
		uint8_t	max_timers,
		uint8_t	op_queues_size,
		void *	p_buffer,
		app_timer_evt_schedule_func_t	evt_schedule_func
	)

Function for initializing the timer module.

Note: Normally initialization should be done using the APP_TIMER_INIT() macro, as that will both allocate the buffers needed by the timer module (including aligning the buffers correctly, and also 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]	max_timers	Maximum number of timers that can be created at any given time.
[in]	op_queues_size	Size of queues holding timer operations that are pending execution. NOTE: 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 timeout 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 timeout handler directly from the timer interrupt handler.

Return values

NRF_SUCCESS	Successful initialization.
NRF_ERROR_INVALID_PARAM	Invalid parameter (buffer not aligned to a 4 byte boundary or NULL).

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	Id of timer to start.
[in]	timeout_ticks	Number of ticks (of RTC1, including prescaling) to timeout event (minimum 5 ticks).
[in]	p_context	General purpose pointer. Will be passed to the timeout handler when the timer expires.

Return values

NRF_SUCCESS	Timer was successfully started.
NRF_ERROR_INVALID_PARAM	Invalid parameter.
NRF_ERROR_INVALID_STATE	Application timer module has not been initialized, or timer has not been created.
NRF_ERROR_NO_MEM	Timer operations queue was full.

Note: The minimum timeout_ticks value is 5.; For multiple active timers, timeouts 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 which is already running, the second start operation will be ignored.

uint32_t app_timer_stop ( app_timer_id_t timer_id )

Function for stopping the specified timer.

Parameters

[in] timer_id Id of timer to stop.

Return values

NRF_SUCCESS	Timer was successfully stopped.
NRF_ERROR_INVALID_PARAM	Invalid parameter.
NRF_ERROR_INVALID_STATE	Application timer module has not been initialized, or timer has not been created.
NRF_ERROR_NO_MEM	Timer operations queue was full.

uint32_t app_timer_stop_all ( void )

Function for stopping all running timers.

Return values

NRF_SUCCESS	All timers were successfully stopped.
NRF_ERROR_INVALID_STATE	Application timer module has not been initialized.
NRF_ERROR_NO_MEM	Timer operations queue was full.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation