All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
RTC: Real Time Clock

## Overview

The KSDK provides a driver for the Real Time Clock (RTC) of Kinetis devices.

# Function groups

The RTC driver supports operating the module as a time counter.

## Initialization and deinitialization

The function RTC_Init() initializes the RTC with specified configurations. The function RTC_GetDefaultConfig() gets the default configurations.

The function RTC_Deinit() disables the RTC timer and disables the module clock.

## Set & Get Datetime

The function RTC_SetDatetime() sets the timer period in seconds. User passes in the details in date & time format by using the below data structure.

typedef struct _rtc_datetime
{
uint16_t year;
uint8_t month;
uint8_t day;
uint8_t hour;
uint8_t minute;
uint8_t second;
} rtc_datetime_t;

The function RTC_GetDatetime() reads the current timer value in seconds, converts it to date & time format and stores it into a datetime structure passed in by the user.

## Set & Get Alarm

The function RTC_SetAlarm() sets the alarm time period in seconds. User passes in the details in date & time format by using the datetime data structure.

The function RTC_GetAlarm() reads the alarm time in seconds, converts it to date & time format and stores it into a datetime structure passed in by the user.

## Start & Stop timer

The function RTC_StartTimer() starts the RTC time counter.

The function RTC_StopTimer() stops the RTC time counter.

## Status

Provides functions to get and clear the RTC status.

## Interrupt

Provides functions to enable/disable RTC interrupts and get current enabled interrupts.

## RTC Oscillator

Some SoC's allow control of the RTC oscillator through the RTC module.

The function RTC_SetOscCapLoad() allows the user to modify the capacitor load configuration of the RTC oscillator.

## Monotonic Counter

Some SoC's have a 64-bit Monotonic counter available in the RTC module.

The function RTC_SetMonotonicCounter() writes a 64-bit to the counter.

The function RTC_GetMonotonicCounter() reads the monotonic counter and returns the 64-bit counter value to the user.

The function RTC_IncrementMonotonicCounter() increments the Monotonic Counter by one.

# Typical use case

## RTC tick example

Example to set the RTC current time and trigger an alarm.

int main(void)
{
uint32_t sec;
uint32_t currSeconds;
rtc_datetime_t date;
rtc_config_t rtcConfig;
/* Board pin, clock, debug console init */
BOARD_InitHardware();
/* Init RTC */
RTC_GetDefaultConfig(&rtcConfig);
RTC_Init(RTC, &rtcConfig);
/* Select RTC clock source */
BOARD_SetRtcClockSource();
PRINTF("RTC example: set up time to wake up an alarm\r\n");
/* Set a start date time and start RT */
date.year = 2014U;
date.month = 12U;
date.day = 25U;
date.hour = 19U;
date.minute = 0;
date.second = 0;
/* RTC time counter has to be stopped before setting the date & time in the TSR register */
RTC_StopTimer(RTC);
/* Set RTC time to default */
RTC_SetDatetime(RTC, &date);
/* Enable RTC alarm interrupt */
RTC_EnableInterrupts(RTC, kRTC_AlarmInterruptEnable);
/* Enable at the NVIC */
EnableIRQ(RTC_IRQn);
/* Start the RTC time counter */
RTC_StartTimer(RTC);
/* This loop will set the RTC alarm */
while (1)
{
busyWait = true;
/* Get date time */
RTC_GetDatetime(RTC, &date);
/* print default time */
PRINTF("Current datetime: %04hd-%02hd-%02hd %02hd:%02hd:%02hd\r\n", date.year, date.month, date.day, date.hour,
date.minute, date.second);
/* Get alarm time from user */
sec = 0;
PRINTF("Please input the number of second to wait for alarm \r\n");
PRINTF("The second must be positive value\r\n");
while (sec < 1)
{
SCANF("%d", &sec);
}
/* Read the RTC seconds register to get current time in seconds */
currSeconds = RTC->TSR;
/* Add alarm seconds to current time */
currSeconds += sec;
/* Set alarm time in seconds */
RTC->TAR = currSeconds;
/* Get alarm time */
RTC_GetAlarm(RTC, &date);
/* Print alarm time */
PRINTF("Alarm will occur at: %04hd-%02hd-%02hd %02hd:%02hd:%02hd\r\n", date.year, date.month, date.day,
date.hour, date.minute, date.second);
/* Wait until alarm occurs */
while (busyWait)
{
}
PRINTF("\r\n Alarm occurs !!!! ");
}
}

## Data Structures

struct | rtc_datetime_t
| Structure is used to hold the date and time. More...
struct | rtc_config_t
| RTC config structure. More...

## Enumerations

enum | rtc_interrupt_enable_t { kRTC_TimeInvalidInterruptEnable = RTC_IER_TIIE_MASK, kRTC_TimeOverflowInterruptEnable = RTC_IER_TOIE_MASK, kRTC_AlarmInterruptEnable = RTC_IER_TAIE_MASK, kRTC_SecondsInterruptEnable = RTC_IER_TSIE_MASK }
| List of RTC interrupts. More...
enum | rtc_status_flags_t { kRTC_TimeInvalidFlag = RTC_SR_TIF_MASK, kRTC_TimeOverflowFlag = RTC_SR_TOF_MASK, kRTC_AlarmFlag = RTC_SR_TAF_MASK }
| List of RTC flags. More...

## Functions

static void | RTC_Reset (RTC_Type *base)
| Performs a software reset on the RTC module. More...

## Driver version

#define | FSL_RTC_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
| Version 2.0.0.

## Initialization and deinitialization

void | RTC_Init (RTC_Type *base, const rtc_config_t *config)
| Ungates the RTC clock and configures the peripheral for basic operation. More...
static void | RTC_Deinit (RTC_Type *base)
| Stop the timer and gate the RTC clock. More...
void | RTC_GetDefaultConfig (rtc_config_t *config)
| Fill in the RTC config struct with the default settings. More...

## Current Time & Alarm

status_t | RTC_SetDatetime (RTC_Type *base, const rtc_datetime_t *datetime)
| Sets the RTC date and time according to the given time structure. More...
void | RTC_GetDatetime (RTC_Type *base, rtc_datetime_t *datetime)
| Gets the RTC time and stores it in the given time structure. More...
status_t | RTC_SetAlarm (RTC_Type *base, const rtc_datetime_t *alarmTime)
| Sets the RTC alarm time. More...
void | RTC_GetAlarm (RTC_Type *base, rtc_datetime_t *datetime)
| Returns the RTC alarm time. More...

## Interrupt Interface

static void | RTC_EnableInterrupts (RTC_Type *base, uint32_t mask)
| Enables the selected RTC interrupts. More...
static void | RTC_DisableInterrupts (RTC_Type *base, uint32_t mask)
| Disables the selected RTC interrupts. More...
static uint32_t | RTC_GetEnabledInterrupts (RTC_Type *base)
| Gets the enabled RTC interrupts. More...

## Status Interface

static uint32_t | RTC_GetStatusFlags (RTC_Type *base)
| Gets the RTC status flags. More...
void | RTC_ClearStatusFlags (RTC_Type *base, uint32_t mask)
| Clears the RTC status flags. More...

## Timer Start and Stop

static void | RTC_StartTimer (RTC_Type *base)
| Starts the RTC time counter. More...
static void | RTC_StopTimer (RTC_Type *base)
| Stops the RTC time counter. More...

## Data Structure Documentation

struct rtc_datetime_t

### Data Fields

uint16_t | year
| Range from 1970 to 2099. More...
uint8_t | month
| Range from 1 to 12. More...
uint8_t | day
| Range from 1 to 31 (depending on month). More...
uint8_t | hour
| Range from 0 to 23. More...
uint8_t | minute
| Range from 0 to 59. More...
uint8_t | second
| Range from 0 to 59. More...

#### Field Documentation

uint16_t rtc_datetime_t::year

uint8_t rtc_datetime_t::month

uint8_t rtc_datetime_t::day

uint8_t rtc_datetime_t::hour

uint8_t rtc_datetime_t::minute

uint8_t rtc_datetime_t::second

struct rtc_config_t

This structure holds the configuration settings for the RTC peripheral. To initialize this structure to reasonable defaults, call the RTC_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

### Data Fields

bool | wakeupSelect
| true: Wakeup pin outputs the 32 KHz clock; false:Wakeup pin used to wakeup the chip
bool | updateMode
| true: Registers can be written even when locked under certain conditions, false: No writes allowed when registers are locked
bool | supervisorAccess
| true: Non-supervisor accesses are allowed; false: Non-supervisor accesses are not supported
uint32_t | compensationInterval
| Compensation interval that is written to the CIR field in RTC TCR Register.
uint32_t | compensationTime
| Compensation time that is written to the TCR field in RTC TCR Register.

## Enumeration Type Documentation

enum rtc_interrupt_enable_t

Enumerator
kRTC_TimeInvalidInterruptEnable | Time invalid interrupt.
kRTC_TimeOverflowInterruptEnable | Time overflow interrupt.
kRTC_AlarmInterruptEnable | Alarm interrupt.
kRTC_SecondsInterruptEnable | Seconds interrupt.

enum rtc_status_flags_t

Enumerator
kRTC_TimeInvalidFlag | Time invalid flag.
kRTC_TimeOverflowFlag | Time overflow flag.
kRTC_AlarmFlag | Alarm flag.

## Function Documentation

void RTC_Init | ( | RTC_Type * | base,
|  | const rtc_config_t * | config
| ) |  |

This function will issue a software reset if the timer invalid flag is set.

Note
  This API should be called at the beginning of the application using the RTC driver.

Parameters

  base | RTC peripheral base address
  config | Pointer to user's RTC config structure.

static void RTC_Deinit | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | RTC peripheral base address

void RTC_GetDefaultConfig | ( | rtc_config_t * | config | ) |

The default values are:

* config->wakeupSelect = false;
* config->updateMode = false;
* config->supervisorAccess = false;
* config->compensationInterval = 0;
* config->compensationTime = 0;
*

Parameters

  config | Pointer to user's RTC config structure.

status_t RTC_SetDatetime | ( | RTC_Type * | base,
|  | const rtc_datetime_t * | datetime
| ) |  |

The RTC counter must be stopped prior to calling this function as writes to the RTC seconds register will fail if the RTC counter is running.

Parameters

  base | RTC peripheral base address
  datetime | Pointer to structure where the date and time details to set are stored

Returns
  kStatus_Success: Success in setting the time and starting the RTC kStatus_InvalidArgument: Error because the datetime format is incorrect

void RTC_GetDatetime | ( | RTC_Type * | base,
|  | rtc_datetime_t * | datetime
| ) |  |

Parameters

  base | RTC peripheral base address
  datetime | Pointer to structure where the date and time details are stored.

status_t RTC_SetAlarm | ( | RTC_Type * | base,
|  | const rtc_datetime_t * | alarmTime
| ) |  |

The function checks whether the specified alarm time is greater than the present time. If not, the function does not set the alarm and returns an error.

Parameters

  base | RTC peripheral base address
  alarmTime | Pointer to structure where the alarm time is stored.

Returns
  kStatus_Success: success in setting the RTC alarm kStatus_InvalidArgument: Error because the alarm datetime format is incorrect kStatus_Fail: Error because the alarm time has already passed

void RTC_GetAlarm | ( | RTC_Type * | base,
|  | rtc_datetime_t * | datetime
| ) |  |

Parameters

  base | RTC peripheral base address
  datetime | Pointer to structure where the alarm date and time details are stored.

static void RTC_EnableInterrupts | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

inlinestatic

Parameters

  base | RTC peripheral base address
  mask | The interrupts to enable. This is a logical OR of members of the enumeration rtc_interrupt_enable_t

static void RTC_DisableInterrupts | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

inlinestatic

Parameters

  base | RTC peripheral base address
  mask | The interrupts to enable. This is a logical OR of members of the enumeration rtc_interrupt_enable_t

static uint32_t RTC_GetEnabledInterrupts | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | RTC peripheral base address

Returns
  The enabled interrupts. This is the logical OR of members of the enumeration rtc_interrupt_enable_t

static uint32_t RTC_GetStatusFlags | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | RTC peripheral base address

Returns
  The status flags. This is the logical OR of members of the enumeration rtc_status_flags_t

void RTC_ClearStatusFlags | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

Parameters

  base | RTC peripheral base address
  mask | The status flags to clear. This is a logical OR of members of the enumeration rtc_status_flags_t

static void RTC_StartTimer | ( | RTC_Type * | base | ) |

inlinestatic

After calling this function, the timer counter increments once a second provided SR[TOF] or SR[TIF] are not set.

Parameters

  base | RTC peripheral base address

static void RTC_StopTimer | ( | RTC_Type * | base | ) |

inlinestatic

RTC's seconds register can be written to only when the timer is stopped.

Parameters

  base | RTC peripheral base address

static void RTC_Reset | ( | RTC_Type * | base | ) |

inlinestatic

This resets all RTC registers except for the SWR bit and the RTC_WAR and RTC_RAR registers. The SWR bit is cleared by software explicitly clearing it.

Parameters

  base | RTC peripheral base address