| 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
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
RTC driver
RTC HAL and driver

Real timer counter (RTC) driver. More...

## Modules
| RTC peripheral driver configuration

## Data Structures
struct | nrf_drv_rtc_t
| RTC driver instance structure. More...
struct | nrf_drv_rtc_config_t
| RTC driver instance configuration structure. More...

## Macros
#define | RTC_US_TO_TICKS(us, freq) ((us * freq) / 1000000)
| Macro to convert microseconds into ticks.
#define | RTC0_INSTANCE_INDEX 0
#define | RTC1_INSTANCE_INDEX RTC0_INSTANCE_INDEX+RTC0_ENABLED
#define | RTC2_INSTANCE_INDEX RTC1_INSTANCE_INDEX+RTC1_ENABLED
#define | NRF_DRV_RTC_INSTANCE(id)
| Macro for creating RTC driver instance. More...
#define | NRF_DRV_RTC_DEFAULT_CONFIG
| RTC instance default configuration. More...

## Typedefs
typedef void(* | nrf_drv_rtc_handler_t )(nrf_drv_rtc_int_type_t int_type)
| RTC driver instance handler type.

## Enumerations
enum | nrf_drv_rtc_int_type_t { NRF_DRV_RTC_INT_COMPARE0 = 0, NRF_DRV_RTC_INT_COMPARE1 = 1, NRF_DRV_RTC_INT_COMPARE2 = 2, NRF_DRV_RTC_INT_COMPARE3 = 3, NRF_DRV_RTC_INT_TICK = 4, NRF_DRV_RTC_INT_OVERFLOW = 5 }
| RTC driver interrupt types. More...

## Functions
ret_code_t | nrf_drv_rtc_init (nrf_drv_rtc_t const *const p_instance, nrf_drv_rtc_config_t const *p_config, nrf_drv_rtc_handler_t handler)
| Function for initializing the RTC driver instance. More...
void | nrf_drv_rtc_uninit (nrf_drv_rtc_t const *const p_instance)
| Function for uninitializing the RTC driver instance. More...
void | nrf_drv_rtc_enable (nrf_drv_rtc_t const *const p_instance)
| Function for enabling the RTC driver instance. More...
void | nrf_drv_rtc_disable (nrf_drv_rtc_t const *const p_instance)
| Function for disabling the RTC driver instance. More...
ret_code_t | nrf_drv_rtc_cc_set (nrf_drv_rtc_t const *const p_instance, uint32_t channel, uint32_t val, bool enable_irq)
| Function for setting a compare channel. More...
ret_code_t | nrf_drv_rtc_cc_disable (nrf_drv_rtc_t const *const p_instance, uint32_t channel)
| Function for disabling a channel. More...
void | nrf_drv_rtc_tick_enable (nrf_drv_rtc_t const *const p_instance, bool enable_irq)
| Function for enabling tick. More...
void | nrf_drv_rtc_tick_disable (nrf_drv_rtc_t const *const p_instance)
| Function for disabling tick. More...
void | nrf_drv_rtc_overflow_enable (nrf_drv_rtc_t const *const p_instance, bool enable_irq)
| Function for enabling overflow. More...
void | nrf_drv_rtc_overflow_disable (nrf_drv_rtc_t const *const p_instance)
| Function for disabling overflow. More...
uint32_t | nrf_drv_rtc_max_ticks_get (nrf_drv_rtc_t const *const p_instance)
| Function for getting the maximum relative ticks value that can be set in the compare channel. More...
__STATIC_INLINE void | nrf_drv_rtc_int_disable (nrf_drv_rtc_t const *const p_instance, uint32_t *p_mask)
| Function for disabling all instance interrupts. More...
__STATIC_INLINE void | nrf_drv_rtc_int_enable (nrf_drv_rtc_t const *const p_instance, uint32_t mask)
| Function for enabling instance interrupts. More...
__STATIC_INLINE uint32_t | nrf_drv_rtc_counter_get (nrf_drv_rtc_t const *const p_instance)
| Function for retrieving the current counter value. More...
__STATIC_INLINE void | nrf_drv_rtc_counter_clear (nrf_drv_rtc_t const *const p_instance)
| Function for clearing the counter value. More...
__STATIC_INLINE uint32_t | nrf_drv_rtc_task_address_get (nrf_drv_rtc_t const *const p_instance, nrf_rtc_task_t task)
| Function for returning a requested task address for the RTC driver instance. More...
__STATIC_INLINE uint32_t | nrf_drv_rtc_event_address_get (nrf_drv_rtc_t const *const p_instance, nrf_rtc_event_t event)
| Function for returning a requested event address for the RTC driver instance. More...

## Detailed Description

Real timer counter (RTC) driver.

## Macro Definition Documentation

#define NRF_DRV_RTC_DEFAULT_CONFIG

Value:
{ \
.prescaler = RTC_FREQ_TO_PRESCALER(RTC_DEFAULT_CONFIG_FREQUENCY), \
.interrupt_priority = RTC_DEFAULT_CONFIG_IRQ_PRIORITY, \
.reliable = RTC_DEFAULT_CONFIG_RELIABLE, \
.tick_latency = RTC_US_TO_TICKS(NRF_MAXIMUM_LATENCY_US, RTC_DEFAULT_CONFIG_FREQUENCY), \
}

RTC instance default configuration.

#define NRF_DRV_RTC_INSTANCE | ( |  | id | ) |

Value:
{ \
.p_reg = CONCAT_2(NRF_RTC, id), \
.irq = CONCAT_3(RTC, id, _IRQn), \
.instance_id = CONCAT_3(RTC, id, _INSTANCE_INDEX),\
.cc_channel_count = NRF_RTC_CC_CHANNEL_COUNT(id), \
}

Macro for creating RTC driver instance.

## Enumeration Type Documentation

enum nrf_drv_rtc_int_type_t

RTC driver interrupt types.

Enumerator
NRF_DRV_RTC_INT_COMPARE0 | Interrupt from COMPARE0 event.
NRF_DRV_RTC_INT_COMPARE1 | Interrupt from COMPARE1 event.
NRF_DRV_RTC_INT_COMPARE2 | Interrupt from COMPARE2 event.
NRF_DRV_RTC_INT_COMPARE3 | Interrupt from COMPARE3 event.
NRF_DRV_RTC_INT_TICK | Interrupt from TICK event.
NRF_DRV_RTC_INT_OVERFLOW | Interrupt from OVERFLOW event.

## Function Documentation

ret_code_t nrf_drv_rtc_cc_disable | ( | nrf_drv_rtc_t const *const | p_instance,
|  | uint32_t | channel
| ) |  |

Function for disabling a channel.

This function disables channel events and channel interrupts. The function asserts if the instance is not initialized or if the channel parameter is wrong.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | channel | One of the instance's channels.

Return values

  NRF_SUCCESS | If the procedure was successful.
  NRF_ERROR_TIMEOUT | If an interrupt was pending on the requested channel.

ret_code_t nrf_drv_rtc_cc_set | ( | nrf_drv_rtc_t const *const | p_instance,
|  | uint32_t | channel,
|  | uint32_t | val,
|  | bool | enable_irq
| ) |  |

Function for setting a compare channel.

The function asserts if the instance is not initialized or if the channel parameter is wrong. The function powers on the instance if the instance was in power off state.

The driver is not entering a critical section when configuring RTC, which means that it can be preempted for a certain amount of time. When the driver was preempted and the value to be set is short in time, there is a risk that the driver sets a compare value that is behind. If RTCn_CONFIG_RELIABLE is 1 for the given instance, the Reliable mode handles that case. However, to detect if the requested value is behind, this mode makes the following assumptions:

- The maximum preemption time in ticks (8 - bit value) is known and is less than 7.7 ms (for prescaler = 0, RTC frequency 32 kHz).
- The requested absolute compare value is not bigger than (0x00FFFFFF) - tick_latency. It is the user's responsibility to ensure that.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | channel | One of the instance's channels.
  [in] | val | Absolute value to be set in the compare register.
  [in] | enable_irq | True to enable the interrupt. False to disable the interrupt.

Return values

  NRF_SUCCESS | If the procedure was successful.
  NRF_ERROR_TIMEOUT | If the compare was not set because the request value is behind the current counter value. This error can only be reported if RTCn_CONFIG_RELIABLE = 1.

__STATIC_INLINE void nrf_drv_rtc_counter_clear | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for clearing the counter value.

This function asserts if the instance is not powered on.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

__STATIC_INLINE uint32_t nrf_drv_rtc_counter_get | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for retrieving the current counter value.

This function asserts if the instance is not powered on or if p_val is NULL.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  value | Counter value.

void nrf_drv_rtc_disable | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for disabling the RTC driver instance.

Note
  Function asserts if instance is disabled.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

void nrf_drv_rtc_enable | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for enabling the RTC driver instance.

Note
  Function asserts if instance is enabled.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

__STATIC_INLINE uint32_t nrf_drv_rtc_event_address_get | ( | nrf_drv_rtc_t const *const | p_instance,
|  | nrf_rtc_event_t | event
| ) |  |

Function for returning a requested event address for the RTC driver instance.

This function asserts if the output pointer is NULL. The event address can be used by the PPI module.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | event | One of the peripheral events.

Return values

  Address | of event register.

ret_code_t nrf_drv_rtc_init | ( | nrf_drv_rtc_t const *const | p_instance,
|  | nrf_drv_rtc_config_t const * | p_config,
|  | nrf_drv_rtc_handler_t | handler
| ) |  |

Function for initializing the RTC driver instance.

After initialization, the instance is in power off state.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_config | Initial configuration. Default configuration used if NULL.
  [in] | handler | User's event handler.

Return values

  NRF_SUCCESS | If successfully initialized.
  NRF_ERROR_INVALID_PARAM | If no handler was provided.
  NRF_ERROR_INVALID_STATE | If the instance is already initialized.

__STATIC_INLINE void nrf_drv_rtc_int_disable | ( | nrf_drv_rtc_t const *const | p_instance,
|  | uint32_t * | p_mask
| ) |  |

Function for disabling all instance interrupts.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_mask | Pointer to the location where the mask is filled.

__STATIC_INLINE void nrf_drv_rtc_int_enable | ( | nrf_drv_rtc_t const *const | p_instance,
|  | uint32_t | mask
| ) |  |

Function for enabling instance interrupts.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | mask | Mask of interrupts to enable.

uint32_t nrf_drv_rtc_max_ticks_get | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for getting the maximum relative ticks value that can be set in the compare channel.

When a SoftDevice is used, it occupies the highest level interrupt, so that the application code can be interrupted at any moment for a certain period of time. If Reliable mode is enabled, the provided maximum latency is taken into account and the return value is smaller than the RTC counter resolution. If Reliable mode is disabled, the return value equals the counter resolution.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  ticks | Maximum ticks value.

void nrf_drv_rtc_overflow_disable | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for disabling overflow.

This function disables the overflow event and interrupt.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

void nrf_drv_rtc_overflow_enable | ( | nrf_drv_rtc_t const *const | p_instance,
|  | bool | enable_irq
| ) |  |

Function for enabling overflow.

This function enables the overflow event and optionally the interrupt. The function asserts if the instance is not powered on.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | enable_irq | True to enable the interrupt. False to disable the interrupt.

__STATIC_INLINE uint32_t nrf_drv_rtc_task_address_get | ( | nrf_drv_rtc_t const *const | p_instance,
|  | nrf_rtc_task_t | task
| ) |  |

Function for returning a requested task address for the RTC driver instance.

This function asserts if the output pointer is NULL. The task address can be used by the PPI module.

Parameters

  [in] | p_instance | Pointer to the instance.
  [in] | task | One of the peripheral tasks.

Return values

  Address | of task register.

void nrf_drv_rtc_tick_disable | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for disabling tick.

This function disables the tick event and interrupt.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

void nrf_drv_rtc_tick_enable | ( | nrf_drv_rtc_t const *const | p_instance,
|  | bool | enable_irq
| ) |  |

Function for enabling tick.

This function enables the tick event and optionally the interrupt. The function asserts if the instance is not powered on.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | enable_irq | True to enable the interrupt. False to disable the interrupt.

void nrf_drv_rtc_uninit | ( | nrf_drv_rtc_t const *const | p_instance | ) |

Function for uninitializing the RTC driver instance.

After uninitialization, the instance is in idle state. The hardware should return to the state before initialization. The function asserts if the instance is in idle state.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.