MT7687 API Reference  LinkIt SDK v4
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

Software architecture of RTC

How to use this driver

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
 
 Struct
 
 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]offsetis the position of RTC spare registers to store data. The unit is in bytes.
[in]lenis 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
1 // Set the RTC spare registers (bytes 2 to 4) with zeros.
2 if(HAL_RTC_STATUS_OK != hal_rtc_clear_data(2, 3)) {
3  // Error handler
4 }
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]timeis 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]offsetis the position of RTC spare registers to store data. The unit is in bytes.
[in]bufis the address of buffer to store the data received from the RTC spare registers.
[in]lenis 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
1 // Read 3 bytes from the RTC spare registers byte 2~4 and store the 3 bytes data to buf
2 if(HAL_RTC_STATUS_OK != hal_rtc_get_data(2, buf, 3)) {
3  // Error handler
4 }
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]frequencyis 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]timeis 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]timeis 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_functionis the user-defined callback function.
[in]user_datais 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]offsetis the position of RTC spare registers to store data. The unit is in bytes.
[in]bufis the address of buffer to store the data write to the RTC spare registers.
[in]lenis 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
1 // Write 3 bytes from buf to RTC spare registers, bytes 2 to 4.
2 if(HAL_RTC_STATUS_OK != hal_rtc_set_data(2, buf, 3)) {
3  // Error handler
4 }
hal_rtc_status_t hal_rtc_set_time ( const hal_rtc_time_t time)

This function sets the RTC current time.

Parameters
[in]timeis 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]magicis 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.