nRF5 SDK v17.0.0
Timer library

The timer library (also referred to as app_timer) enables the application to create multiple timer instances based on the RTC1 peripheral. Start and stop requests, checking for time-outs and invoking the user time-out handlers is performed in the RTC1 interrupt handler. RTC1 interrupt priority level can be configured in sdk_config.h.

Usage

Configuration of the app_timer module is static. It is located in the sdk_config.h file. Use function app_timer_init to initialize the library.

To define a timer, use the APP_TIMER_DEF macro. This macro allocates memory for the timer instance and declares an identifier that can later on be used to refer to the specific instance. Before starting a timer, the timer must be created:

APP_TIMER_DEF(my_timer_id);
err_code = app_timer_create(&my_timer_id, mode, timeout_handler)

After the timer is created, it can be controlled using app_timer_start and app_timer_stop.

When app_timer_start() or app_timer_stop() are called, the timer operation is only queued, not executed. A RTC1 interrupt is triggered and the actual timer start/stop operation is executed by the RTC1 interrupt handler. If the application code that calls the timer function is running at the same or higher interrupt priority level, the timer operation will not be performed until the application handler has returned. This is the case, for example, when stopping a timer from a time-out handler when not using the scheduler.

To use this library with Scheduler, use the APP_TIMER_CONFIG_USE_SCHEDULER option in sdk_config.h.

Debugging

The module exposes API for pausing and resuming RTC. It can be used in debugging hooks when entering and leaving breakpoints. Such hooks are available in J-Link Monitor, see Monitor Mode Debugging - Revolutionize the way you debug BLE applications.

Migration note

When migrating from an SDK released before version 13.0.0, keep in mind that some changes have been introduced to the timer library in SDK v13.0.0. It might be necessary to adjust the code of your application to comply with these changes.

  1. Static configuration of the module has been moved to sdk_config.h and thus the APP_TIMER_INIT macro has been removed. Therefore, you must change the following code:
    APP_TIMER_INIT(PRESCALER, OP_QUEUE_SIZE, SCHEDULER_FUNC);
    to:
    err_code = app_timer_init();
  2. The PRESCALER parameter has been removed from the APP_TIMER_TICKS macro. Therefore, you must change the following code:
    ticks = APP_TIMER_TICKS(MS, PRESCALER);
    to:
    ticks = APP_TIMER_TICKS(MS);
  3. app_timer_cnt_diff_compute API change - The tick diff value is now returned by the function and not by the pointer. Therefore, you must change the following code:
    err_code = app_timer_cnt_diff_compute(ticks_to, ticks_from, &ticks_diff);
    to:
    ticks_diff = app_timer_cnt_diff_compute(ticks_to, ticks_from);

Documentation feedback | Developer Zone | Subscribe | Updated