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)
 Initialize the RTC module. More...
 
hal_rtc_status_t hal_rtc_deinit (void)
 Deinitialize the RTC module. More...
 
hal_rtc_status_t hal_rtc_set_time (const hal_rtc_time_t *time)
 Set the RTC current time. More...
 
hal_rtc_status_t hal_rtc_get_time (hal_rtc_time_t *time)
 Get the RTC current time. More...
 
hal_rtc_status_t hal_rtc_set_alarm (const hal_rtc_time_t *time)
 Set the RTC alarm time. More...
 
hal_rtc_status_t hal_rtc_get_alarm (hal_rtc_time_t *time)
 Get the RTC alarm time. More...
 
hal_rtc_status_t hal_rtc_enable_alarm (void)
 Enable an alarm. More...
 
hal_rtc_status_t hal_rtc_disable_alarm (void)
 Disable an alarm. More...
 
hal_rtc_status_t hal_rtc_sleep (uint32_t magic)
 Set 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)
 Set the alarm callback. More...
 
hal_rtc_status_t hal_rtc_set_data (uint16_t offset, const char *buf, uint16_t len)
 Store 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)
 Read 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)
 Store 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)
 Get 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 
)

Store 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 number of data 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  )

Deinitialize the RTC module.

Returns
HAL_RTC_STATUS_OK, the operation completed successfully.
hal_rtc_status_t hal_rtc_disable_alarm ( void  )

Disable 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  )

Enable 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)

Get 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 
)

Read 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 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 received from the RTC spare registers.
[in]lenis the number of data 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)

Get 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)

Get the RTC current time.

Parameters
[out]timeis the pointer to a 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  )

Initialize 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)

Set 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 
)

Set 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 
)

Store 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 number of data store to 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)

Set the RTC current time.

Parameters
[in]timeis a pointer to the hal_rtc_time_t structure that contains the date and time settings that will be set to 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)

Set the system into sleep mode.

This function should not be called from ISR and the caller is responsible for making sure 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, the RTC hardware is not ready for use. HAL_RTC_STATUS_INVALID_PARAM, an invalid magic parameter is given. HAL_RTC_STATUS_OK, the operation completed successfully.