Realtime Clock (r_rtc_c)

Functions
fsp_err_t	R_RTC_C_Open (rtc_ctrl_t *const p_ctrl, rtc_cfg_t const *const p_cfg)
fsp_err_t	R_RTC_C_Close (rtc_ctrl_t *const p_ctrl)
fsp_err_t	R_RTC_C_ClockSourceSet (rtc_ctrl_t *const p_ctrl)
fsp_err_t	R_RTC_C_CalendarTimeSet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t	R_RTC_C_CalendarTimeGet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t	R_RTC_C_CalendarAlarmSet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t	R_RTC_C_CalendarAlarmGet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t	R_RTC_C_PeriodicIrqRateSet (rtc_ctrl_t *const p_ctrl, rtc_periodic_irq_select_t const rate)
fsp_err_t	R_RTC_C_InfoGet (rtc_ctrl_t *const p_ctrl, rtc_info_t *const p_rtc_info)
fsp_err_t	R_RTC_C_ErrorAdjustmentSet (rtc_ctrl_t *const p_ctrl, rtc_error_adjustment_cfg_t const *const err_adj_cfg)
fsp_err_t	R_RTC_C_CallbackSet (rtc_ctrl_t *const p_ctrl, void(*p_callback)(rtc_callback_args_t *), void const *const p_context, rtc_callback_args_t *const p_callback_memory)
fsp_err_t	R_RTC_C_TimeCaptureSet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)
fsp_err_t	R_RTC_C_TimeCaptureGet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)

Detailed Description

Driver for the RTC peripheral on RA MCUs. This module implements the RTC Interface.

Overview

The RTC HAL module configures the RTC module and controls clock, calendar and alarm functions. A callback can be used to respond to the alarm and periodic interrupt.

Features

• RTC_C time and date get and set.
• RTC_C time and date alarm get and set.
• RTC_C alarm and periodic event notification.

The RTC HAL module supports two different interrupt types:

• An alarm interrupt generated on a match of any combination of minute, hour and day of the week.
• A periodic interrupt generated every 1 month, 1 day, 1 hour, 1 minute, 1 second and 1/2 second.

A user-defined callback function can be registered (in the rtc_api_t::open API call) and will be called from the interrupt service routine (ISR) for alarm and periodic interrupt. When called, it is passed a pointer to a structure (rtc_callback_args_t) that holds a user-defined context pointer and an indication of which type of interrupt was fired.

Date and Time validation

"Parameter Checking" needs to be enabled if date and time validation is required for calendarTimeSet and calendarAlarmSet APIs. When using the calendarAlarmSet API, minute, hour and day of the week are written to the related registers.

Sub-Clock error adjustment (Time Error Adjustment Function)

The time error adjustment function is used to correct errors, running fast or slow, in the time caused by variation in the precision of oscillation by the sub-clock oscillator. Because 32,768 cycles of the sub-clock oscillator constitute 1 second of operation when the sub-clock oscillator is selected, the clock runs fast if the sub-clock frequency is high and slow if the sub-clock frequency is low.

The error adjustment is reset every time RTC is reconfigured or time is set.

Note

RTC driver configurations do not do error adjustment internally while initializing the driver. Application must make calls to the error adjustment api's for desired adjustment.

Configuration

Build Time Configurations for r_rtc_c

The following build time configurations are defined in fsp_cfg/r_rtc_c_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Timers > Realtime Clock (r_rtc_c)

This module can be added to the Stacks tab via New Stack > Timers > Realtime Clock (r_rtc_c).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rtc0	Module name.
Operation clock	FSXP SOSC/256 (128 Hz)	FSXP	Select the RTC operation clock. If using 'SOSC/256' as the source for RTCCLK, the FSXP source cannot be LOCO in Clock tab.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Interrupt Priority	MCU Specific Options		Select the period or alarm interrupt priority.

Interrupt Configuration

To activate interrupts for the RTC module, the desired interrupts must be enabled, The underlying implementation will be expected to handle any interrupts it can support and notify higher layers via callback.

Clock Configuration

The RTC HAL module can use the following clock sources(setting in clock page):

• Sub-Clock: SOSC (32.768 kHz)
• SOSC/256 (128 Hz)
• LOCO (32.768 kHz)

Users have to select the right source for their application. Sub-Clock is the default during configuration when it is available.

Pin Configuration

This module does not use I/O pins.

Usage Notes

System Initialization

• RTC driver does not start the sub-clock. The application is responsible for ensuring required clocks are started and stable before accessing MCU peripheral registers.

Warning

The subclock can take seconds to stabilize. The RA startup code does not wait for subclock stabilization unless the subclock is the main clock source. When running AGT or RTC off the subclock, the application must ensure the subclock is stable before starting operation.

• Even when only running in Periodic Interrupt mode R_RTC_C_CalendarTimeSet must be called successfully to start the RTC.

Limitations

Developers should be aware of the following limitations when using the RTC_C:

• R_RTC_C operates in 24-hour mode.
• If using 'SOSC/256' as the source for RTC operation clock, the FSXP source cannot be LOCO in Clock tab.
• Time error correction function can only proceed when the setting of the RTCC0.RTC128EN bit is 0.
• Alarm clock interrupt can work under LOCO clock source, but it is unstable. Please use alarm clock interrupt function under other clocks.

Examples

RTC Basic Example

This is a basic example of minimal use of the RTC_C in an application.

/* rtc_time_t is an alias for the C Standard time.h struct 'tm' */
rtc_time_t set_time =
{
    .tm_sec  = 10,
    .tm_min  = 11,
    .tm_hour = 12,
    .tm_mday = 6,
    .tm_wday = 3,
    .tm_mon  = 11,
    .tm_year = YEARS_SINCE_1900,
};

rtc_time_t get_time;

void rtc_c_example ()
{
    fsp_err_t err = FSP_SUCCESS;


    /* Open the RTC module */
    err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);


    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);


    /* Set the calendar time */
    R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);



    /* Get the calendar time */
    R_RTC_C_CalendarTimeGet(&g_rtc0_ctrl, &get_time);

}

RTC Calendar Time Set example

This is an example of setting calendar time in RTC_C.

Warning

The weekday must be set correctly even when parameter checking is disabled.

/* rtc_time_t is an alias for the C Standard time.h struct 'tm' */
rtc_time_t set_calendar_time =
{
    .tm_sec  = 10,
    .tm_min  = 11,
    .tm_hour = 12,
    .tm_mday = 6,

    /* tm_wday value must be set correctly */
    .tm_wday = 5,
    .tm_mon  = 11,
    .tm_year = YEARS_SINCE_1900,
};

void rtc_c_calendar_time_set_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the RTC module */
    err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    /* Set the calendar time and date */
    err = R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_calendar_time);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
}

RTC Periodic interrupt example

This is an example of periodic interrupt in RTC.

void rtc_c_periodic_irq_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the RTC module*/
    err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    /* R_RTC_C_CalendarTimeSet must be called at least once to start the RTC */
    R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);


    /* Set the periodic interrupt rate to 1 second */
    R_RTC_C_PeriodicIrqRateSet(&g_rtc0_ctrl, RTC_PERIODIC_IRQ_SELECT_1_SECOND);


    /* Wait for the periodic interrupt */
    while (1)
    {
        /* Wait for interrupt */
    }
}

RTC Alarm interrupt example

This is an example of alarm interrupt in RTC.

void rtc_c_alarm_irq_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /*Open the RTC module*/
    err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);


    R_RTC_C_CalendarAlarmSet(&g_rtc0_ctrl, &set_time1);


    /* Wait for the Alarm interrupt */
    while (1)
    {
        /* Wait for interrupt */
    }
}

RTC Error Adjustment example

This is an example of modifying error adjustment in RTC.

void rtc_c_erroradj_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /*Open the RTC module*/
    R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc1_cfg);

    R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);

    /* Modify Error Adjustment after RTC is running */


    err = R_RTC_C_ErrorAdjustmentSet(&g_rtc0_ctrl, &err_cfg2);
    assert(FSP_SUCCESS == err);

}

Data Structures
struct	rtc_c_extended_cfg
struct	rtc_c_instance_ctrl_t

Enumerations
enum	rtc_c_subclock_division_t

---

Data Structure Documentation

rtc_c_extended_cfg

struct rtc_c_extended_cfg

RTC extended configuration

Data Fields
rtc_c_subclock_division_t	clock_source_div	The sub clock division value.

rtc_c_instance_ctrl_t

struct rtc_c_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when rtc_api_t::open is called

Data Fields
uint32_t	open
	Whether or not driver is open.
const rtc_cfg_t *	p_cfg
	Pointer to initial configurations.

Enumeration Type Documentation

rtc_c_subclock_division_t

enum rtc_c_subclock_division_t

RTC sub_clock division

Enumerator
RTC_CLOCK_SOURCE_SUBCLOCK_DIV_BY_1	Using sub_clock for rct_c clock.
RTC_CLOCK_SOURCE_SUBCLOCK_DIV_BY_256	Using (sub_clock / 256) for rct_c clock.

Function Documentation

R_RTC_C_Open()

fsp_err_t R_RTC_C_Open	(	rtc_ctrl_t *const	p_ctrl,
		rtc_cfg_t const *const	p_cfg
	)

Opens and configures the RTC driver module. Implements rtc_api_t::open. Configuration includes clock source, and interrupt callback function.

R_RTC_Open should be called to manipulate the RTC instead of setting register directly.

Example:

    /* Open the RTC module */
    err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

Return values

FSP_SUCCESS	Initialization was successful and RTC has started.
FSP_ERR_UNSUPPORTED	Invalid clock source.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_INVALID_MODE	Subsystem clock should use SOSC before setting realtime clock to SOSC/256.
FSP_ERR_ASSERTION	Invalid time parameter field.

R_RTC_C_Close()

fsp_err_t R_RTC_C_Close

(

rtc_ctrl_t *const

p_ctrl

)

Close the RTC driver. Implements rtc_api_t::close

Return values

FSP_SUCCESS	De-Initialization was successful and RTC driver closed.
FSP_ERR_ASSERTION	Invalid p_ctrl.
FSP_ERR_NOT_OPEN	Driver not open already for close.

R_RTC_C_ClockSourceSet()

fsp_err_t R_RTC_C_ClockSourceSet

(

rtc_ctrl_t *const

p_ctrl

)

Setting clock source is not supported on the RTC_C.

Return values

FSP_ERR_UNSUPPORTED

Please set clock source in clock page.

R_RTC_C_CalendarTimeSet()

fsp_err_t R_RTC_C_CalendarTimeSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_t *const	p_time
	)

Set the calendar time.

Implements rtc_api_t::calendarTimeSet.

Return values

FSP_SUCCESS	Calendar time set operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_INVALID_ARGUMENT	Invalid parameter field.

R_RTC_C_CalendarTimeGet()

fsp_err_t R_RTC_C_CalendarTimeGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_t *const	p_time
	)

Get the calendar time.

Warning

Do not call this function from a critical section or from an interrupt with higher priority than the carry interrupt, or the time returned may be inaccurate.

Implements rtc_api_t::calendarTimeGet

Return values

FSP_SUCCESS	Calendar time get operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.

R_RTC_C_CalendarAlarmSet()

fsp_err_t R_RTC_C_CalendarAlarmSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_alarm_time_t *const	p_alarm
	)

Set the calendar alarm time. For the p_alarm, only minutes, hours and weekdays are valid. Minutes 0 to 59. Hours 0 to 23. Weekdays 0 to 127.

Implements rtc_api_t::calendarAlarmSet.

Precondition

The calendar counter must be running before the alarm can be set.

Return values

FSP_SUCCESS	Calendar alarm time set operation was successful.
FSP_ERR_INVALID_ARGUMENT	Invalid time parameter field.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLED	Interrupt must be enabled to use the alarm.

R_RTC_C_CalendarAlarmGet()

fsp_err_t R_RTC_C_CalendarAlarmGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_alarm_time_t *const	p_alarm
	)

Get the calendar alarm time. For the p_alarm, only minutes, hours and weekdays will be got.

Implements rtc_api_t::calendarAlarmGet

Return values

FSP_SUCCESS	Calendar alarm time get operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.

R_RTC_C_PeriodicIrqRateSet()

fsp_err_t R_RTC_C_PeriodicIrqRateSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_periodic_irq_select_t const	rate
	)

Set the periodic interrupt rate and enable periodic interrupt.

Implements rtc_api_t::periodicIrqRateSet

Note

To start the RTC R_RTC_C_CalendarTimeSet must be called at least once.

Example:

    /* Set the periodic interrupt rate to 1 second */
    R_RTC_C_PeriodicIrqRateSet(&g_rtc0_ctrl, RTC_PERIODIC_IRQ_SELECT_1_SECOND);

Return values

FSP_SUCCESS	The periodic interrupt rate was successfully set.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLED	User IRQ parameter not valid

R_RTC_C_InfoGet()

fsp_err_t R_RTC_C_InfoGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_info_t *const	p_rtc_info
	)

Get RTC_C running status information ad store it in provided pointer p_rtc_info

Implements rtc_api_t::infoGet

Return values

FSP_SUCCESS	Get information Successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Realtime clock module is stopped.

R_RTC_C_ErrorAdjustmentSet()

fsp_err_t R_RTC_C_ErrorAdjustmentSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_error_adjustment_cfg_t const *const	err_adj_cfg
	)

This function sets time error adjustment

Implements rtc_api_t::errorAdjustmentSet

Return values

FSP_SUCCESS	Time error adjustment successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open for operation.
FSP_ERR_INVALID_ARGUMENT	Not under sub-clock or invalid error adjustment value.

R_RTC_C_CallbackSet()

fsp_err_t R_RTC_C_CallbackSet	(	rtc_ctrl_t *const	p_ctrl,
		void(*)(rtc_callback_args_t *)	p_callback,
		void const *const	p_context,
		rtc_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements rtc_api_t::callbackSet

Return values

FSP_SUCCESS	Baud rate was successfully changed.
FSP_ERR_ASSERTION	Pointer to RTC control block is NULL or the RTC is not configured to use the internal clock.
FSP_ERR_NOT_OPEN	The control block has not been opened

R_RTC_C_TimeCaptureSet()

fsp_err_t R_RTC_C_TimeCaptureSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_capture_t *const	p_time_capture
	)

Capture is not supported on the RTC_C.

Return values

FSP_ERR_UNSUPPORTED

Function not supported in this implementation.

R_RTC_C_TimeCaptureGet()

fsp_err_t R_RTC_C_TimeCaptureGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_capture_t *const	p_time_capture
	)

Capture is not supported on the RTC_C.

Return values

FSP_ERR_UNSUPPORTED

Function not supported in this implementation.