RTC
Introduction
The Real-Time Clock (RTC) is a special timing device that is typically designed for low-power operation and provides time and calendar functions. The RTC also offers an alarm function, which can be used to wake up the device.
Function List
Function Overview
Calendar Function: The RTC module supports setting and querying the calendar, including: year, month, day, hour, minute, and second.
Alarm Function: The RTC module supports configuring alarms and registering alarm callbacks; when the alarm expires, it will notify the user through a callback.
Main Functions
RTC Initialization
Use the RTC by first calling wm_drv_rtc_init("rtc") to initialize the RTC.
If the RTC has already been initialized by another module, you can call wm_dt_get_device_by_name("rtc") to query the RTC device pointer.
wm_device_t *rtc_dev;
/** Initialize the RTC */
rtc_dev = wm_drv_rtc_init("rtc");
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
RTC Calendar Function
The RTC provides calendar query and setting functions. The WM800 supports calendar functions within the range of 2000-01-01 00:00:00 to 2127-12-31 23:59:59. The current time should be configured when the device is powered on for the first time.
Setting the RTC Calendar
wm_device_t *rtc_dev;
struct tm tm = { 0 };
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Set the calendar time to: 2024-07-01 12:00:00 */
tm.tm_year = 124; // Years since 1900
tm.tm_mon = 6; // 0-based month (July)
tm.tm_mday = 1;
tm.tm_hour = 12;
tm.tm_min = 0;
tm.tm_sec = 0;
/** Set the RTC calendar */
wm_drv_rtc_set_time(rtc_dev, &tm);
Querying the RTC Calendar
char buffer[32];
wm_device_t *rtc_dev;
struct tm tm = { 0 };
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Query the RTC calendar */
wm_drv_rtc_get_time(rtc_dev, &tm);
/** Serialize the retrieved calendar, depends on the C standard library <time.h> */
strftime(buffer, sizeof(buffer), "%Y-%m-%d %H:%M:%S", &tm);
/** Display the current time */
printf("%s\n", buffer);
RTC Alarm Function
Querying RTC Alarm ID
Depending on the device model, the RTC can provide one or multiple alarms for user use. Pay attention to the return value of the function.
Note: The W800 has only one RTC alarm.
wm_device_t *rtc_dev;
int id;
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Query the available RTC alarm */
wm_drv_rtc_get_alarm_available_id(rtc_dev, &id);
Querying RTC Alarm Mask
The RTC provides an alarm mask query function. The result can be used to set up recurring alarms according to the types in wm_rtc_alarm_mask_e.
Note: The W800 does not currently support recurring RTC alarms, so the queried mask should be 0.
wm_device_t *rtc_dev;
int mask;
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Query the alarm mask for ID 0 */
wm_drv_rtc_get_alarm_mask(rtc_dev, 0, &mask);
Registering RTC Alarm Callback
Users can register an alarm callback with the RTC. When the alarm expires, the RTC will callback the user’s registered function. Additionally, you can register the private pointer of the application with the RTC. When the RTC calls the user’s callback, it will pass this pointer to the user’s callback for use.
/** User-defined callback function */
static void wm_rtc_alarm_callback_handle(void *user_data) {
/** RTC alarm has expired */
}
/** Register the RTC alarm callback */
wm_device_t *rtc_dev;
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
wm_drv_rtc_register_alarm_callback(rtc_dev, 0, wm_rtc_alarm_callback_handle, NULL);
Setting the RTC Alarm
Users can set the RTC alarm time. When the alarm expires, the device will trigger an RTC alarm interrupt and call back the user’s registered function.
struct tm tm = { 0 };
wm_device_t *rtc_dev;
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Set the alarm to expire on 2024-08-01 12:00:00 */
tm.tm_year = 124; // Years since 1900
tm.tm_mon = 7; // 0-based month (August)
tm.tm_mday = 1;
tm.tm_hour = 12;
tm.tm_min = 0;
tm.tm_sec = 0;
wm_drv_rtc_set_alarm(rtc_dev, 0, 0, &tm);
Canceling the RTC Alarm
According to user business logic, the RTC also provides an interface to cancel the RTC alarm.
struct tm tm = { 0 };
wm_device_t *rtc_dev;
/** The RTC has been initialized */
/** Query the RTC device pointer */
rtc_dev = wm_dt_get_device_by_name("rtc");
/** Cancel the RTC alarm */
wm_drv_rtc_abort_alarm(rtc_dev, 0);
Application Example
For a basic example of using ADC, please refer to: examples/peripheral/rtc