RTC

This section introduces the Real-Time Clock (RTC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions. More...

Overview

This section introduces the Real-Time Clock (RTC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.

The software architecture of the RTC driver is shown in the diagram below.

Terms and acronyms

Terms	Details
RTC	Real-Time Clock. A real-time clock (RTC) is a computer clock, mostly in the form of an integrated circuit, that keeps track of the current time. For more information, please refer to an introduction to the RTC in Wikipedia .

Supported features

• Support date and time information.
  Call hal_rtc_set_time() to set the RTC current time and hal_rtc_get_time() to retrieve the RTC current time.
• Support alarm notification.
  Call hal_rtc_set_alarm() to set the RTC alarm time and hal_rtc_get_alarm() to get the RTC alarm time. To receive alarm notification, please call hal_rtc_set_alarm_callback() to register a callback function and call hal_rtc_enable_alarm() to enable the RTC alarm notification. When the RTC current time reaches the RTC alarm time, the callback function you registered will be executed. The alarm notification can be disabled by using hal_rtc_disable_alarm() function, if it's no longer required.
• Support store data during power off.
  There are several spare registers in the RTC to store data that are not cleared during a power off, except when the battery is removed.

Software architecture of RTC

• The user needs to call hal_rtc_init() to initialize the RTC hardware before using the RTC service. The user can set and get the current time or RTC alarm time at any time. RTC just supports the alarm notification. The user can use hal_rtc_set_alarm_callback(), to register callbacks for the RTC notification.
  

How to use this driver

• Set the RTC current time.
  
  • Step 1. Call hal_rtc_init() to initialize the RTC hardware, if it hasn't been called after the power went on.
  • Step 2. Call hal_rtc_set_time() to set the RTC current time.
  • sample code: Note: the base year of RTC should be 2000, there will be leap year problem if a value other than 2000 is used.

    #define BASE_YEAR 2000
    set_current_time(uint16_t year, uint8_t mon, uint8_t day, uint8_t hour, uint8_t min, uint8_t sec) {
        hal_rtc_time_t time;
    
        if(HAL_RTC_STATUS_OK != hal_rtc_init()) {
            // Error handler
        }
    
        // The user has to define the base year and the RTC year is defined
        // as an offset. For example, define the base year as 2000 and assign 15 to the RTC year to represent the year of 2015.
        time.rtc_year = year - BASE_YEAR;
        time.rtc_mon = mon;
        time.rtc_day = day;
        time.rtc_hour = hour;
        time.rtc_min = min;
        time.rtc_sec = sec;
    
        // Set the RTC current time.
        if(HAL_RTC_STATUS_OK != hal_rtc_set_time(&time)) {
            // error handle
        }
    }

• Get the RTC current time.
  
  • Step 1. Call hal_rtc_init() to initialize the RTC hardware if it has not been called after the power went on.
  • Step 2. Call hal_rtc_get_time() to get RTC current time.
  • sample code:

    #define BASE_YEAR 2000
    get_current_time(uint8_t *year, uint8_t *mon, uint8_t *day, uint8_t *hour, uint8_t *min, uint8_t *sec) {
        hal_rtc_time_t time;
    
        if(HAL_RTC_STATUS_OK != hal_rtc_init()) {
            // Error handler
        }
    
        if(HAL_RTC_STATUS_OK != hal_rtc_get_time(&time)) {
            // Error handler
        }
    
        // The user has to define the base year and the RTC year is defined
        // as an offset. For example, define the base year as 2000 and assign 15 to the RTC year to represent the year of 2015.
        *year = time.rtc_year + BASE_YEAR;
        *mon = time.rtc_mon;
        *day = time.rtc_day;
        *hour = time.rtc_hour;
        *min = time.rtc_min;
        *sec = time.rtc_sec;
    }

• Set the RTC alarm time.
  
  • Step 1. Call hal_rtc_init() to initialize the RTC hardware if it has not been called after the power went on.
  • Step 2. Call hal_rtc_set_time() to set the RTC alarm time.
  • sample code:

    #define BASE_YEAR 2000
    set_alarm_time(uint16_t year, uint8_t mon, uint8_t day, uint8_t hour, uint8_t min, uint8_t sec) {
        hal_rtc_time_t alarm;
    
        if(HAL_RTC_STATUS_OK != hal_rtc_init()) {
            // Error handler
        }
    
        // The user has to define the base year and the RTC year is defined
        // as an offset. For example, define the base year as 2000 and assign 15 to the RTC year to represent the year of 2015.
        alarm.rtc_year = year - BASE_YEAR;
        alarm.rtc_mon = mon;
        alarm.rtc_day = day;
        alarm.rtc_hour = hour;
        alarm.rtc_min = min;
        alarm.rtc_sec = sec;
    
        // Set the RTC alarm time.
        if(HAL_RTC_STATUS_OK != hal_rtc_set_alarm(&alarm)) {
            // Error handler
        }
    }

• Get the RTC alarm time.
  
  • Step 1. Call hal_rtc_init() to initialize the RTC hardware if it has not been called after the power went on.
  • Step 2. Call hal_rtc_get_alarm() to get the RTC alarm time.
  • sample code:

    get_alarm_time(uint8_t *year, uint8_t *mon, uint8_t *day, uint8_t *hour, uint8_t *min, uint8_t *sec) {
        hal_rtc_time_t alarm;
    
        if(HAL_RTC_STATUS_OK != hal_rtc_init()) {
            // Error handler
        }
    
        if(HAL_RTC_STATUS_OK != hal_rtc_get_time(&alarm)) {
            // Error handler
        }
    
        // The user has to define the base year and the RTC year is defined
        // as an offset. For example, define the base year as 2000 and assign 15 to the RTC year to represent the year of 2015.
        *year = time.rtc_year + BASE_YEAR;
        *mon = alarm.rtc_mon;
        *day = alarm.rtc_day;
        *hour = alarm.rtc_hour;
        *min = alarm.rtc_min;
        *sec = alarm.rtc_sec;
    }

• Register a user callback function to handle the RTC alarm.
  
  • Step 1. Call hal_rtc_init() to initialize the RTC hardware if it has not been called after the power went on.
  • Step 2. Call hal_rtc_set_alarm_callback() to register a user callback function to handle the RTC alarm.
  • Step 3. Call hal_rtc_enable_alarm() to enable an alarm notification. A callback function is triggered in an interrupt service routine if an alarm notification is received.
  • sample code:

    uint32_t g_user_data;
    
    set_alarm_handle_cb(hal_rtc_time_notification_period_t period) {
    
        if(HAL_RTC_STATUS_OK != hal_rtc_init()) {
            // Error handler
        }
    
        // Register a callback function to handle the RTC alarm.
        if(HAL_RTC_STATUS_OK != hal_rtc_set_alarm_callback(alarm_handle_cb, &g_user_data)) {
            // Error handler
        }
    
        // Enable an alarm notification.
        if(HAL_RTC_STATUS_OK != hal_rtc_enable_alarm()) {
            // Error handler
        }
    }

    void alarm_handle_cb(void *user_data)
    {
        // In this case, *user_data is g_user_data.
        // Apply the RTC functionality, for example, get the RTC current time and update it on the user interface.
        // Please note, that this callback runs in an interrupt service routine.
    }

• Put the system into sleep if the magic number input is as expected.
  
  • Call hal_rtc_sleep() to set the system to sleep mode.
  • sample code:

    uint32_t magic = 0xBABEBABE; // 0xBABEBABE is the expected magic number.
    hal_rtc_sleep(magic); // Set the system to sleep mode.

Functions
hal_rtc_status_t	hal_rtc_init (void)
	This function initializes the RTC module. More...
hal_rtc_status_t	hal_rtc_deinit (void)
	This function deinitializes the RTC module. More...
hal_rtc_status_t	hal_rtc_set_time (const hal_rtc_time_t *time)
	This function sets the RTC current time. More...
hal_rtc_status_t	hal_rtc_get_time (hal_rtc_time_t *time)
	This function gets the RTC current time. More...
hal_rtc_status_t	hal_rtc_set_alarm (const hal_rtc_time_t *time)
	This function sets the RTC alarm time. More...
hal_rtc_status_t	hal_rtc_get_alarm (hal_rtc_time_t *time)
	This function gets the RTC alarm time. More...
hal_rtc_status_t	hal_rtc_enable_alarm (void)
	This function enables an alarm. More...
hal_rtc_status_t	hal_rtc_disable_alarm (void)
	This function disables an alarm. More...
hal_rtc_status_t	hal_rtc_sleep (uint32_t magic)
	This function sets the system into sleep mode. More...
hal_rtc_status_t	hal_rtc_set_alarm_callback (const hal_rtc_alarm_callback_t callback_function, void *user_data)
	This function sets the alarm callback. More...
hal_rtc_status_t	hal_rtc_set_data (uint16_t offset, const char *buf, uint16_t len)
	This function stores data to the RTC registers that won't be cleared even if the system power is off, except when the battery is removed. More...
hal_rtc_status_t	hal_rtc_get_data (uint16_t offset, char *buf, uint16_t len)
	This function reads data from the RTC registers that won't be cleared even if the system power is off, except when the battery is removed. More...
hal_rtc_status_t	hal_rtc_clear_data (uint16_t offset, uint16_t len)
	This function stores zero to the RTC registers that won't be cleared even if the system power is off, except when the battery is removed. More...
hal_rtc_status_t	hal_rtc_get_f32k_frequency (uint32_t *frequency)
	This function gets the frequency value of 32.768kHz clock source, unit is in Hz. More...

Modules
	Define
	Enum
	Typedef

Function Documentation

hal_rtc_status_t hal_rtc_clear_data	(	uint16_t	offset,
		uint16_t	len
	)

This function stores zero to the RTC registers that won't be cleared even if the system power is off, except when the battery is removed.

Note, the size of the backup date is HAL_RTC_BACKUP_BYTE_NUM_MAX bytes.

Parameters

[in]	offset	is the position of RTC spare registers to store data. The unit is in bytes.
[in]	len	is the datalength read from the RTC spare registers. The unit is in bytes.

Returns

HAL_RTC_STATUS_ERROR means the RTC hardware isn't ready for use. HAL_RTC_STATUS_OK, the operation completed successfully.

See also

hal_rtc_set_data(), hal_rtc_get_data().

Example

// Set the RTC spare registers (bytes 2 to 4) with zeros.
if(HAL_RTC_STATUS_OK != hal_rtc_clear_data(2, 3)) {
    // Error handler
}

hal_rtc_status_t hal_rtc_deinit

(

void

)

This function deinitializes the RTC module.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

hal_rtc_status_t hal_rtc_disable_alarm

(

void

)

This function disables an alarm.

Call this function if the alarm notification is no longer required.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

hal_rtc_status_t hal_rtc_enable_alarm

(

void

)

This function enables an alarm.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

Example

Please refer to "Register a user callback function for handling alarm" in How to use this driver.

hal_rtc_status_t hal_rtc_get_alarm

(

hal_rtc_time_t *

time

)

This function gets the RTC alarm time.

Parameters

[out]

time

is a pointer to the hal_rtc_time_t structure to store the date and time settings received from the RTC alarm time.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

Example

Please refer to "Get RTC alarm time" in How to use this driver.

hal_rtc_status_t hal_rtc_get_data	(	uint16_t	offset,
		char *	buf,
		uint16_t	len
	)

This function reads data from the RTC registers that won't be cleared even if the system power is off, except when the battery is removed.

Note, the size of the backup data is HAL_RTC_BACKUP_BYTE_NUM_MAX bytes.

Parameters

[in]	offset	is the position of RTC spare registers to store data. The unit is in bytes.
[in]	buf	is the address of buffer to store the data received from the RTC spare registers.
[in]	len	is the datalength read from the RTC spare registers. The unit is in bytes.

Returns

HAL_RTC_STATUS_ERROR means the RTC hardware isn't ready for use. HAL_RTC_STATUS_OK, the operation completed successfully.

See also

hal_rtc_set_data(), hal_rtc_clear_data().

Example

// Read 3 bytes from the RTC spare registers byte 2~4 and store the 3 bytes data to buf
if(HAL_RTC_STATUS_OK != hal_rtc_get_data(2, buf, 3)) {
    // Error handler
}

hal_rtc_status_t hal_rtc_get_f32k_frequency

(

uint32_t *

frequency

)

This function gets the frequency value of 32.768kHz clock source, unit is in Hz.

Parameters

[in]

frequency

is a pointer to store the frequency.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

hal_rtc_status_t hal_rtc_get_time

(

hal_rtc_time_t *

time

)

This function gets the RTC current time.

Parameters

[out]

time

is a pointer to the hal_rtc_time_t structure to store the date and time settings received from the RTC current time.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

Example

Please refer to "Get RTC current time" in How to use this driver.

hal_rtc_status_t hal_rtc_init

(

void

)

This function initializes the RTC module.

This function must be called once the power is on and before using the RTC service.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

hal_rtc_status_t hal_rtc_set_alarm

(

const hal_rtc_time_t *

time

)

This function sets the RTC alarm time.

Parameters

[in]

time

is a pointer to the hal_rtc_time_t structure that contains the date and time settings to configure the RTC alarm time.

Returns

HAL_RTC_STATUS_INVALID_PARAM, an invalid alarm time parameter is given. HAL_RTC_STATUS_OK, the operation completed successfully.

Example

Please refer to "Set RTC current time" in How to use this driver.

hal_rtc_status_t hal_rtc_set_alarm_callback	(	const hal_rtc_alarm_callback_t	callback_function,
		void *	user_data
	)

This function sets the alarm callback.

This callback is executed if the RTC current and alarm times are the same.

Parameters

[in]	callback_function	is the user-defined callback function.
[in]	user_data	is a pointer to the data assigned to callback function.

Returns

HAL_RTC_STATUS_OK, the operation completed successfully.

See also

hal_rtc_set_alarm(), hal_rtc_get_alarm(), hal_rtc_enable_alarm() and hal_rtc_disable_alarm()

Example

Please refer to "Register a user callback function for handling alarm" in How to use this driver.

hal_rtc_status_t hal_rtc_set_data	(	uint16_t	offset,
		const char *	buf,
		uint16_t	len
	)

This function stores data to the RTC registers that won't be cleared even if the system power is off, except when the battery is removed.

Note, the size of the backup date is HAL_RTC_BACKUP_BYTE_NUM_MAX bytes.

Parameters

[in]	offset	is the position of RTC spare registers to store data. The unit is in bytes.
[in]	buf	is the address of buffer to store the data write to the RTC spare registers.
[in]	len	is the datalength stored in the RTC spare registers. The unit is in bytes.

Returns

HAL_RTC_STATUS_ERROR means the RTC hardware isn't ready for use. HAL_RTC_STATUS_OK, the operation completed successfully.

See also

hal_rtc_get_data(), hal_rtc_clear_data().

Example

// Write 3 bytes from buf to RTC spare registers, bytes 2 to 4.
if(HAL_RTC_STATUS_OK != hal_rtc_set_data(2, buf, 3)) {
    // Error handler
}

hal_rtc_status_t hal_rtc_set_time

(

const hal_rtc_time_t *

time

)

This function sets the RTC current time.

Parameters

[in]

time

is a pointer to the hal_rtc_time_t structure that contains the date and time settings for the RTC current time.

Returns

HAL_RTC_STATUS_INVALID_PARAM, an invalid time parameter is given. HAL_RTC_STATUS_OK, the operation completed successfully.

Example

Please refer to "Set RTC current time" in How to use this driver.

hal_rtc_status_t hal_rtc_sleep

(

uint32_t

magic

)

This function sets the system into sleep mode.

This function should not be called from ISR and the caller is responsible to ensure the ISR masks won't block the expecting ISRs, which will then set the system into sleep mode with no option to wake up.

Parameters

[in]

magic

is the magic number of this function. Please always use HAL_RTC_SLEEP_MAGIC.

Returns

HAL_RTC_STATUS_ERROR, enter RTC mode failed, due to wakeup signal is active before the chip power off. HAL_RTC_STATUS_INVALID_PARAM, an invalid magic parameter is given. HAL_RTC_STATUS_OK, the operation completed successfully.