| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs
RTC Peripheral Driver
Real Time Clock (RTC)

The section describes the programming interface of the RTC Peripheral Driver. More...

## Data Structures
struct | rtc_datetime_t
| Structure is used to hold the time in a simple "date" format. More...
struct | rtc_time_t
| Time representation: hours, minutes, second and total seconds. More...
struct | rtc_user_config_t
| RTC timer configuration structure. More...

## Macros
#define | FSL_FEATURE_RTC_INTERRUPT_COUNT (2)

## Typedefs
typedef void(* | rtc_isr_callback_t )(void)
| RTC ISR callback function typedef.

## Initialize and Shutdown
bool | rtc_init (const rtc_user_config_t *config)
| Initializes the Real Time Clock module. More...
void | rtc_shutdown (void)
| disable RTC module clock gate control. More...

## RTC interrupt configuration and status
void | rtc_configure_int (hw_rtc_ier_t *bitfields)
| Enables/disables RTC interrupts. More...
void | rtc_get_int_status (hw_rtc_sr_t *int_status_flags)
| Returns the RTC interrupt status flags. More...

## RTC datetime set and get
bool | rtc_set_datetime (const rtc_datetime_t *datetime, bool start_after_set)
| Sets the RTC date and time according to the given time structure, if indicated in the corresponding parameter. More...
void | rtc_get_datetime (rtc_datetime_t *datetime)
| Gets the actual RTC time and stores it in the given time structure. More...

## RTC alarm set and get
bool | rtc_set_alarm (const rtc_datetime_t *date)
| Sets the RTC alarm. More...
bool | rtc_get_alarm (rtc_datetime_t *date)
| Returns the RTC alarm time. More...

## RTC time counter start and stop
void | rtc_start_time_counter (void)
| Enables the RTC oscillator and starts time counter. More...
void | rtc_stop_time_counter (void)
| Halts running time counter. More...

## Copy time data
void | rtc_cp_datetime_time (const rtc_datetime_t *datetime, rtc_time_t *time)
| Utility to copy time data from datetime structure to a time structure. More...
void | rtc_cp_time_datetime (const rtc_time_t *time, rtc_datetime_t *datetime)
| Utility to copy time data from time structure to a datetime. More...

## ISR Callback Function
void | rtc_register_isr_callback_function (uint8_t rtc_irq_number, rtc_isr_callback_t function)
| Register RTC ISR callback function. More...

### RTC Peripheral Driver

# Overview

The RTC peripheral driver is used to set and get the RTC clock, set and read the RTC alarm time and receive notifications when an alarm is triggered.

# User configuration structures

The RTC driver uses an instantiation of the rtc_user_config_t structure to configure the RTC driver. This allows the user to configure the most common settings of the RTC driver. The rtc_user_config_t structure holds an instance of the rtc_hal_init_config_t (see RTC HAL Driver for details) and rtc_datetime_t data-types. The rtc_hal_init_config_t holds information used by the RTC HAL driver & rtc_datetime_t, which allows the user to pass in the date and time information stored in the RTC seconds register.

# Initialization

To initialize, the user calls rtc_init() with a pointer to the rtc_user_config_t structure. The driver initialization function ungates the RTC module clock. It then uses the information passed in to initialize the RTC HAL layer driver (this part is skipped if the "general_config" element is set to NULL) and the RTC time (this part is skipped if the "start_at_datetime" element is set to NULL).This is an example code to set up a user RTC configuration instantiation:
rtc_user_config_t rtc_drv_configs = {
.general_config = &rtc_init_configs,
.start_at_datetime = NULL,
};
This is an example to make the rtc_init() function.
/* init the rtc module */
rtc_init(&rtc_drv_configs);

# Setting and reading the RTC time

The RTC driver uses an instantiation of the rtc_datetime_t structure to configure or read the date & time.This is an example code to set up a user RTC configuration instantiation:
rtc_datetime_t datetimeToSet;
datetimeToSet.year = 2013;
datetimeToSet.month = 10;
datetimeToSet.day = 13;
datetimeToSet.hour = 18;
datetimeToSet.minute = 55;
datetimeToSet.second = 30;
The user can pass the date and time as part of the rtc_user_config_t structure during driver initialization or can call the rtc_set_datetime() or rtc_get_datetime() functions to configure or read the date & time at a later time. This is example to use these functions.
/* get datetime */
rtc_get_datetime(&datetime);
printf("Current datetime: %04hd-%02hd-%02hd %02hd:%02hd:%02hd\r\n",
datetime.year, datetime.month, datetime.day,
datetime.hour, datetime.minute, datetime.second);
/* set the datetime */
result = rtc_set_datetime(&datetime, true);

# Triggering an Alarm

The RTC driver uses interrupts when an alarm is triggered at a user-specified time. The user has to register a callback function that is invoked when the alarm interrupt is triggered.The user can call the rtc_set_alarm() to set the alarm time or the rtc_get_alarm() to read the configured alarm time. The user has to set the current time using the steps mentioned earlier prior to using the call to set the alarm time. This is an example of how to use these functions.
rtc_datetime_t datetimeToSet;
rtc_set_datetime(&datetimeToSet, false);
datetimeToSet.second += 5;
rtc_set_alarm(&datetimeToSet);
/*Register a callback function.*/
rtc_register_isr_callback_function(0, alarmISR);
/* Enable the Alarm interrupt */
rtc_hal_config_alarm_int_enable(true);

## Data Structure Documentation

struct rtc_datetime_t

Warning
  If you violate the ranges, undefined behavior results.

### Data Fields
uint16_t | year
| Range from 200 to 2099. More...
uint16_t | month
| Range from 1 to 12. More...
uint16_t | day
| Range from 1 to 31 (depending on month). More...
uint16_t | hour
| Range from 0 to 23. More...
uint16_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

uint16_t rtc_datetime_t::month

uint16_t rtc_datetime_t::day

uint16_t rtc_datetime_t::hour

uint16_t rtc_datetime_t::minute

uint8_t rtc_datetime_t::second

struct rtc_time_t

### Data Fields
uint16_t | hour
| Range from 0 to 23. More...
uint16_t | minute
| Range from 0 to 59. More...
uint8_t | second
| Range from 0 to 59. More...

#### Field Documentation

uint16_t rtc_time_t::hour

uint16_t rtc_time_t::minute

uint8_t rtc_time_t::second

struct rtc_user_config_t

### Data Fields
rtc_hal_init_config_t * | general_config
| Pointer to a structure most of the configurations.
rtc_datetime_t * | start_at_datetime
| are found. More...
bool | start_counter
| Set to true to start the real time counter. More...

#### Field Documentation

rtc_datetime_t* rtc_user_config_t::start_at_datetime

Set to NULL to skip related configuration.

See the 'rtc_hal_init_config' definition for details. Initial datetime. Set to NULL to skip.

bool rtc_user_config_t::start_counter

Will

## Function Documentation

bool rtc_init | ( | const rtc_user_config_t * | config | ) |

Parameters

  Config | [in] initialization configuration details.

Returns
  True: success; false: datetime format is invalid or the counter indicated to start but it was already started.

void rtc_shutdown | ( | void |  | ) |

void rtc_configure_int | ( | hw_rtc_ier_t * | bitfields | ) |

Parameters

  bitfields | [in] set/clear respective bitfields to enabled/disabled interrupts. [out] resulting interrupt enable state. Valid bitfields: TSIE: Time Seconds Interrupt Enable TAIE: Time Alarm Interrupt Enable TOIE: Time Overflow Interrupt Enable TIIE: Time Invalid Interrupt Enable For MCUs that have the Wakeup Pin only: WPON: Wakeup Pin On (see the corresponding MCU's reference manual) For MCUs that have the Monotonic Counter only: MOIE: Monotonic Overflow Interrupt Enable

void rtc_get_int_status | ( | hw_rtc_sr_t * | int_status_flags | ) |

Parameters

  int_status_flags | [out] pointer to where to store bitfield with an actual RTC interrupt flags. ONLY valid bitfields: TIF: Time Invalid Flag TOF: Time Overflow Flag TAF: Time Alarm Flag MOF: Monotonic Overflow Flag (Not in all devices) Note: other bitfields are not to be taken in account.

bool rtc_set_datetime | ( | const rtc_datetime_t * | datetime,
|  | bool | start_after_set
| ) |  |

After, the time counter is started.

Parameters

  datetime | [in] pointer to a structure where the date and time details are stored.
  start_after_set | true: the RTC oscillator will be enabled and the counter will start. False: otherwise.

Returns
  True: success; false: error, datetime format incorrect, datetime format is invalid or unable to set the counter value because it is already enabled.

void rtc_get_datetime | ( | rtc_datetime_t * | datetime | ) |

Parameters

  datetime | [out] pointer to structure where the date and time details will be stored.

bool rtc_set_alarm | ( | const rtc_datetime_t * | date | ) |

Parameters

  date | [in] pointer to structure where the alarm date and time details will be stored.

Returns
  true: success; false: error.

bool rtc_get_alarm | ( | rtc_datetime_t * | date | ) |

Parameters

  date | [out] pointer to structure where the alarm date and time details will be stored.

Returns
  True: success; false: error.

void rtc_start_time_counter | ( | void |  | ) |

void rtc_stop_time_counter | ( | void |  | ) |

void rtc_cp_datetime_time | ( | const rtc_datetime_t * | datetime,
|  | rtc_time_t * | time
| ) |  |

Parameters

  datetime | [in] data origin
  time | [out] data destination

void rtc_cp_time_datetime | ( | const rtc_time_t * | time,
|  | rtc_datetime_t * | datetime
| ) |  |

            structure.

Parameters

  time | [in] data origin
  datetime | [out] data destination

void rtc_register_isr_callback_function | ( | uint8_t | rtc_irq_number,
|  | rtc_isr_callback_t | function
| ) |  |

System default ISR interfaces are already defined in the fsl_rtc_irq.c. Users can either edit these ISRs or use this function to register a callback function. The default ISR runs the callback function if one is installed.

Parameters

  rtc_irq_number | RTC interrupt number.
  function | Pointer to the RTC ISR callback function.