MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
RTC: Real Time Clock

Files

file  fsl_rtc.h
 

Data Structures

struct  rtc_datetime_t
 Structure is used to hold the date and time. More...
 

Enumerations

enum  rtc_interrupt_enable_t {
  kRTC_AlarmInterruptEnable = RTC_CTRL_ALARMDPD_EN_MASK,
  kRTC_WakeupInterruptEnable = RTC_CTRL_WAKEDPD_EN_MASK
}
 List of RTC interrupts. More...
 
enum  rtc_status_flags_t {
  kRTC_AlarmFlag = RTC_CTRL_ALARM1HZ_MASK,
  kRTC_WakeupFlag = RTC_CTRL_WAKE1KHZ_MASK
}
 List of RTC flags. More...
 

Functions

static void RTC_SetSecondsTimerMatch (RTC_Type *base, uint32_t matchValue)
 Set the RTC seconds timer (1HZ) MATCH value. More...
 
static uint32_t RTC_GetSecondsTimerMatch (RTC_Type *base)
 Read actual RTC seconds timer (1HZ) MATCH value. More...
 
static void RTC_SetSecondsTimerCount (RTC_Type *base, uint32_t countValue)
 Set the RTC seconds timer (1HZ) COUNT value. More...
 
static uint32_t RTC_GetSecondsTimerCount (RTC_Type *base)
 Read the actual RTC seconds timer (1HZ) COUNT value. More...
 
static void RTC_SetWakeupCount (RTC_Type *base, uint16_t wakeupValue)
 Enable the RTC wake-up timer (1KHZ) and set countdown value to the RTC WAKE register. More...
 
static uint16_t RTC_GetWakeupCount (RTC_Type *base)
 Read the actual value from the WAKE register value in RTC wake-up timer (1KHZ). More...
 
static void RTC_Reset (RTC_Type *base)
 Perform a software reset on the RTC module. More...
 

Driver version

#define FSL_RTC_DRIVER_VERSION   (MAKE_VERSION(2, 1, 1))
 Version 2.1.1.
 

Initialization and deinitialization

void RTC_Init (RTC_Type *base)
 Un-gate the RTC clock and enable the RTC oscillator. More...
 
static void RTC_Deinit (RTC_Type *base)
 Stop the timer and gate the RTC clock. More...
 

Current Time & Alarm

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

RTC wake-up timer (1KHZ) Enable

static void RTC_EnableWakeupTimer (RTC_Type *base, bool enable)
 Enable the RTC wake-up timer (1KHZ). More...
 
static uint32_t RTC_GetEnabledWakeupTimer (RTC_Type *base)
 Get the enabled status of the RTC wake-up timer (1KHZ). More...
 

Interrupt Interface

static void RTC_EnableWakeUpTimerInterruptFromDPD (RTC_Type *base, bool enable)
 Enable the wake-up timer interrupt from deep power down mode. More...
 
static void RTC_EnableAlarmTimerInterruptFromDPD (RTC_Type *base, bool enable)
 Enable the alarm timer interrupt from deep power down mode. More...
 
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)
 Get the enabled RTC interrupts. More...
 

Status Interface

static uint32_t RTC_GetStatusFlags (RTC_Type *base)
 Get the RTC status flags. More...
 
static void RTC_ClearStatusFlags (RTC_Type *base, uint32_t mask)
 Clear the RTC status flags. More...
 

Timer Enable

static void RTC_EnableTimer (RTC_Type *base, bool enable)
 Enable the RTC timer counter. More...
 
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...
 

Detailed Description

The MCUXpresso SDK provides a driver for the Real Time Clock (RTC).

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.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/rtc 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.

High resolution timer

Provides functions to enable high resolution timer and set and get the wake time.

Typical use case

RTC tick example

Example to set the RTC current time and trigger an alarm. Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/rtc


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

Enumeration Type Documentation

Enumerator
kRTC_AlarmInterruptEnable 

Alarm interrupt.

kRTC_WakeupInterruptEnable 

Wake-up interrupt.

Enumerator
kRTC_AlarmFlag 

Alarm flag.

kRTC_WakeupFlag 

1kHz wake-up timer flag

Function Documentation

void RTC_Init ( RTC_Type *  base)
Note
This API should be called at the beginning of the application using the RTC driver.
Parameters
baseRTC peripheral base address
static void RTC_Deinit ( RTC_Type *  base)
inlinestatic
Parameters
baseRTC peripheral base address
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
baseRTC peripheral base address
datetimePointer 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
baseRTC peripheral base address
datetimePointer 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
baseRTC peripheral base address
alarmTimePointer 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
baseRTC peripheral base address
datetimePointer to structure where the alarm date and time details are stored.
static void RTC_EnableWakeupTimer ( RTC_Type *  base,
bool  enable 
)
inlinestatic

After calling this function, the RTC driver will use/un-use the RTC wake-up (1KHZ) at the same time.

Parameters
baseRTC peripheral base address
enableUse/Un-use the RTC wake-up timer.
  • true: Use RTC wake-up timer at the same time.
  • false: Un-use RTC wake-up timer, RTC only use the normal seconds timer by default.
static uint32_t RTC_GetEnabledWakeupTimer ( RTC_Type *  base)
inlinestatic
Parameters
baseRTC peripheral base address
Returns
The enabled status of RTC wake-up timer (1KHZ).
static void RTC_SetSecondsTimerMatch ( RTC_Type *  base,
uint32_t  matchValue 
)
inlinestatic
Parameters
baseRTC peripheral base address
matchValueThe value to be set into the RTC MATCH register
static uint32_t RTC_GetSecondsTimerMatch ( RTC_Type *  base)
inlinestatic
Parameters
baseRTC peripheral base address
Returns
The actual RTC seconds timer (1HZ) MATCH value.
static void RTC_SetSecondsTimerCount ( RTC_Type *  base,
uint32_t  countValue 
)
inlinestatic
Parameters
baseRTC peripheral base address
countValueThe value to be loaded into the RTC COUNT register
static uint32_t RTC_GetSecondsTimerCount ( RTC_Type *  base)
inlinestatic
Parameters
baseRTC peripheral base address
Returns
The actual RTC seconds timer (1HZ) COUNT value.
static void RTC_SetWakeupCount ( RTC_Type *  base,
uint16_t  wakeupValue 
)
inlinestatic
Parameters
baseRTC peripheral base address
wakeupValueThe value to be loaded into the WAKE register in RTC wake-up timer (1KHZ).
static uint16_t RTC_GetWakeupCount ( RTC_Type *  base)
inlinestatic
Parameters
baseRTC peripheral base address
Returns
The actual value of the WAKE register value in RTC wake-up timer (1HZ).
static void RTC_EnableWakeUpTimerInterruptFromDPD ( RTC_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseRTC peripheral base address
enableEnable/Disable wake-up timer interrupt from deep power down mode.
  • true: Enable wake-up timer interrupt from deep power down mode.
  • false: Disable wake-up timer interrupt from deep power down mode.
static void RTC_EnableAlarmTimerInterruptFromDPD ( RTC_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseRTC peripheral base address
enableEnable/Disable alarm timer interrupt from deep power down mode.
  • true: Enable alarm timer interrupt from deep power down mode.
  • false: Disable alarm timer interrupt from deep power down mode.
static void RTC_EnableInterrupts ( RTC_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseRTC peripheral base address
maskThe 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
baseRTC peripheral base address
maskThe 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
baseRTC 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
baseRTC peripheral base address
Returns
The status flags. This is the logical OR of members of the enumeration rtc_status_flags_t
static void RTC_ClearStatusFlags ( RTC_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseRTC peripheral base address
maskThe status flags to clear. This is a logical OR of members of the enumeration rtc_status_flags_t
static void RTC_EnableTimer ( RTC_Type *  base,
bool  enable 
)
inlinestatic

After calling this function, the RTC inner counter increments once a second when only using the RTC seconds timer (1hz), while the RTC inner wake-up timer countdown once a millisecond when using RTC wake-up timer (1KHZ) at the same time. RTC timer contain two timers, one is the RTC normal seconds timer, the other one is the RTC wake-up timer, the RTC enable bit is the master switch for the whole RTC timer, so user can use the RTC seconds (1HZ) timer independly, but they can't use the RTC wake-up timer (1KHZ) independently.

Parameters
baseRTC peripheral base address
enableEnable/Disable RTC Timer counter.
  • true: Enable RTC Timer counter.
  • false: Disable RTC Timer counter.
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
baseRTC 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
baseRTC peripheral base address
static void RTC_Reset ( RTC_Type *  base)
inlinestatic

This resets all RTC registers to their reset value. The bit is cleared by software explicitly clearing it.

Parameters
baseRTC peripheral base address