| 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
Clock

The clock driver includes two layers: the hardware access layer (HAL) and the driver layer (DRV).

The hardware access layer provides basic APIs for accessing the registers of the clock. See the API documentation for the Clock HAL for details.

The driver layer provides APIs on a higher level than the HAL. See the API documentation for the Clock driver for details.

The clock driver is responsible for starting the high-accuracy, high-frequency clock source and the low-frequency clock (without a SoftDevice). It also performs calibration without a SoftDevice or internal RC as an LFCLK source.

# Driver configuration

Enable the driver in the configuration file `sdk_config.h` before using it in an application. The clock driver supports only the static, compile-time configuration due to the possibility of other modules attempting to initialize it. The configuration includes the high-frequency clock frequency, the low-frequency clock source, and the interrupt priority.

#define CLOCK_ENABLED 1

Enabling the clock will initialize the Clock driver to its default state:

- High-accuracy, high-frequency clock HFCLK is off
- Low-frequency clock LFCLOCK is off (without a SoftDevice)
- Calibration has not started (without a SoftDevice only)

# Using the clock driver

The Clock Example provides sample code that you can use to quickly get started.

## Controlling the HFCLK

If a module needs a high-precision clock, it can request the clock driver to start it. If a callback is provided, it will be called after the request is handled. If the requested clock was already started when nrf_drv_clock_hfclk_request is called, the callback will be called from the context of this function. Otherwise, it will be called from the context of the clock interrupt handler. To check if the HFCLK is on, call nrf_drv_clock_hfclk_is_running.

When the module is finished with the HFCLK, you should release it by calling nrf_drv_clock_hfclk_release. The clock is turned off if no other module is requesting it.

The SoftDevice API is used in the driver if a SoftDevice is present.

## Controlling the LFCLK (without a SoftDevice only)

If a module needs a low-frequency clock, it can request the clock driver to start it. If a callback is provided, it will be called after the request is handled. If the requested clock was already started when nrf_drv_clock_lfclk_request is called, the callback will be called from the context of this function. Otherwise, it will be called from the context of the clock interrupt handler. To check if the LFCLK is on, call nrf_drv_clock_lfclk_is_running.

When the module is finished with the LFCLK, you should release it by calling nrf_drv_clock_lfclk_release. The clock is turned off if no other module is requesting it.

The SoftDevice API is used in the driver if a SoftDevice is present.

## Controlling the calibration of the LFCLK (without a SoftDevice and using RC as source clock)

The internal RC can be used as source for the LFCLK, but it is not as precise as a crystal. It must be periodically calibrated against a high-frequency crystal. The clock module supports autonomous calibration. It also has a built-in low-power timer dedicated to calibration.

The calibration process consists of three phases:

- Delay (using a clock calibration timer); delay can be set to 0 to start calibration immediately
- Request the high-accuracy HFCLK
- Perform calibration

Call nrf_drv_clock_calibration_start to start the calibration process. Parameters specify the delay (given in 0.25 ms units) and an optional callback to be called once calibration is completed.

To check if there is an ongoing calibration, call nrf_drv_clock_is_calibrating.

At any time, nrf_drv_clock_calibration_abort can be called to stop calibration. If a callback was provided for nrf_drv_clock_calibration_start, the callback is executed when the process stops, with the event type set to NRF_DRV_CLOCK_EVT_CAL_ABORTED.

Periodic calibration can be achieved by calling nrf_drv_clock_calibration_start from the calibration completion handler:

void clock_handler(nrf_drv_clock_evt_type_t event)
{
if (event == NRF_DRV_CLOCK_EVT_CAL_DONE)
{ ret = nrf_drv_clock_calibration_start(10, clock_handler); }
}