MT2523 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_time_notification_period (hal_rtc_time_notification_period_t period)
 Set the RTC current time change notification period. 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_set_time_callback (hal_rtc_time_callback_t callback_function, void *user_data)
 Set the RTC time notification callback, and the callback execution period is set by hal_rtc_set_time_notification_period(). 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_one_shot_calibration (int16_t ticks)
 Set the tick value that will be adjusted to the RTC current time. More...
 
hal_rtc_status_t hal_rtc_get_one_shot_calibration (int16_t *ticks)
 Get the tick value that will be adjusted to the RTC current time. More...
 
hal_rtc_status_t hal_rtc_set_repeat_calibration (int16_t ticks_per_8_seconds)
 Set the ticks that are periodically adjusted to the RTC current time per 8 seconds. More...
 
hal_rtc_status_t hal_rtc_get_repeat_calibration (int16_t *ticks_per_8_seconds)
 Get the ticks that are periodically adjusted to the RTC current time per 8 seconds. 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_one_shot_calibration ( int16_t *  ticks)

Get the tick value that will be adjusted to the RTC current time.

Note, ticks will equal to zero after executing this function if one shot calibration is finished.

Parameters
[in]ticksis the ticks that are adjusted to the RTC current time. The valid value is in a range from -2048(-62.5ms) to 2045(62.4ms). The unit is about 30.52us (1s/32768).
Returns
HAL_RTC_STATUS_OK, the operation completed successfully.
See also
hal_rtc_set_one_shot_calibration()
hal_rtc_status_t hal_rtc_get_repeat_calibration ( int16_t *  ticks_per_8_seconds)

Get the ticks that are periodically adjusted to the RTC current time per 8 seconds.

Parameters
[in]ticks_per_8_secondsis the units that are adjusted to the RTC current time per 8 seconds. The valid value is from -64(-0.244ms) ~ 63(0.24ms). One unit is about 3.81us (1s/32768/8).
Returns
HAL_RTC_STATUS_OK, the operation completed successfully.
See also
hal_rtc_set_repeat_calibration().
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_one_shot_calibration ( int16_t  ticks)

Set the tick value that will be adjusted to the RTC current time.

Note, this function should be executed only once per second.

Parameters
[in]ticksis the ticks that are adjusted to the RTC current time. The valid value is in a range from -2048(-62.5ms) to 2045(62.4ms). The unit is about 30.52us (1s/32768).
Returns
HAL_RTC_STATUS_OK, the operation completed successfully.
See also
hal_rtc_get_one_shot_calibration()
hal_rtc_status_t hal_rtc_set_repeat_calibration ( int16_t  ticks_per_8_seconds)

Set the ticks that are periodically adjusted to the RTC current time per 8 seconds.

Parameters
[in]ticks_per_8_secondsis the units that are adjusted to the RTC current time per 8 seconds. The valid value is from -64(-0.244ms) ~ 63(0.24ms). One unit is about 3.81us (1s/32768/8).
Returns
HAL_RTC_STATUS_OK, the operation completed successfully.
See also
hal_rtc_get_repeat_calibration()
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_set_time_callback ( hal_rtc_time_callback_t  callback_function,
void *  user_data 
)

Set the RTC time notification callback, and the callback execution period is set by hal_rtc_set_time_notification_period().

Parameters
[in]callback_functionis a 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_time_notification_period()
Example
Please refer to "Set RTC current time" in How to use this driver.
hal_rtc_status_t hal_rtc_set_time_notification_period ( hal_rtc_time_notification_period_t  period)

Set the RTC current time change notification period.

The time notification callback function is different from a common timer or alarm callback function. The common timer or alarm callback function is only called once at a specific time, but the time notification callback function is called anytime a specific time notification condition meet. For example, the callback function runs for each second, if HAL_RTC_TIME_NOTIFICATION_EVERY_SECOND as the parameter.

Parameters
[in]periodis the expected time for the RTC current time change notification period.
Returns
HAL_RTC_STATUS_INVALID_PARAM, an invalid period parameter is given. HAL_RTC_STATUS_OK, the operation completed successfully.
See also
hal_rtc_set_time_callback()
Example
Please refer to "Register a user callback function for handling RTC current time change" in How to use this driver.