Real-Time Clock (RTC)
Overview
Word |
Definition |
|---|---|
Real-time clock |
Low power device tracking time using broken-down time |
Real-time counter |
Low power counter which can be used to track time |
RTC |
Acronym for real-time clock |
An RTC is a low power device which tracks time using broken-down time. It should not be confused with low-power counters which sometimes share the same name, acronym, or both.
RTCs are usually optimized for low energy consumption and are usually kept running even when the system is in a low power state.
RTCs usually contain one or more alarms which can be configured to trigger at a given time. These alarms are commonly used to wake up the system from a low power state.
History of RTCs in Zephyr
RTCs have been supported before this API was created, using the Counter API. The unix timestamp was used to convert between broken-down time and the unix timestamp within the RTC drivers, which internally used the broken-down time representation.
The disadvantages of this approach where that hardware counters can not be set to a specific count, requiring all RTCs to use device specific APIs to set the time, converting from unix time to broken-down time, unnecessarily in some cases, and some common features missing, like input clock calibration and the update callback.
Configuration Options
Related configuration options:
API Reference
- group rtc_interface
RTC Interface.
Unnamed Group
Typedefs
-
typedef void (*rtc_update_callback)(const struct device *dev, void *user_data)
RTC update event callback.
- Param dev:
Device instance invoking the handler
- Param user_data:
Optional user data provided when update irq callback is set
-
typedef void (*rtc_alarm_callback)(const struct device *dev, uint16_t id, void *user_data)
RTC alarm triggered callback.
- Param dev:
Device instance invoking the handler
- Param id:
Alarm id
- Param user_data:
Optional user data passed with the alarm configuration
-
typedef int (*rtc_api_set_time)(const struct device *dev, const struct rtc_time *timeptr)
API for setting RTC time.
-
typedef int (*rtc_api_get_time)(const struct device *dev, struct rtc_time *timeptr)
API for getting RTC time.
-
typedef int (*rtc_api_alarm_get_supported_fields)(const struct device *dev, uint16_t id, uint16_t *mask)
API for getting the supported fields of the RTC alarm time.
-
typedef int (*rtc_api_alarm_set_time)(const struct device *dev, uint16_t id, uint16_t mask, const struct rtc_time *timeptr)
API for setting RTC alarm time.
-
typedef int (*rtc_api_alarm_get_time)(const struct device *dev, uint16_t id, uint16_t *mask, struct rtc_time *timeptr)
API for getting RTC alarm time.
-
typedef int (*rtc_api_alarm_is_pending)(const struct device *dev, uint16_t id)
API for testing if RTC alarm is pending.
-
typedef int (*rtc_api_alarm_set_callback)(const struct device *dev, uint16_t id, rtc_alarm_callback callback, void *user_data)
API for setting RTC alarm callback.
-
typedef int (*rtc_api_update_set_callback)(const struct device *dev, rtc_update_callback callback, void *user_data)
API for setting RTC update callback.
Functions
-
struct rtc_time
- #include <rtc.h>
Structure for storing date and time values with sub-second precision.
The structure is 1-1 mapped to the struct tm for the members
tm_sectotm_isdstmaking it compatible with the standard time library.Note
Use rtc_time_to_tm() to safely cast from a rtc_time pointer to a tm pointer.
Public Members
-
int tm_sec
Seconds [0, 59]
-
int tm_min
Minutes [0, 59]
-
int tm_hour
Hours [0, 23]
-
int tm_mday
Day of the month [1, 31]
-
int tm_mon
Month [0, 11]
-
int tm_year
Year - 1900
-
int tm_wday
Day of the week [0, 6] (Sunday = 0) (Unknown = -1)
-
int tm_yday
Day of the year [0, 365] (Unknown = -1)
-
int tm_isdst
Daylight saving time flag [-1] (Unknown = -1)
-
int tm_nsec
Nanoseconds [0, 999999999] (Unknown = 0)
-
int tm_sec
-
struct rtc_driver_api
- #include <rtc.h>
RTC driver API.
-
typedef void (*rtc_update_callback)(const struct device *dev, void *user_data)
RTC device driver test suite
The test suite validates the behavior of the RTC device driver. It
is designed to be portable between boards. It uses the device tree
alias rtc to designate the RTC device to test.
This test suite tests the following:
Setting and getting the time.
RTC Time incrementing correctly.
Alarms if supported by hardware, with and without callback enabled
Calibration if supported by hardware.
The calibration test tests a range of values which are printed to the console to be manually compared. The user must review the set and gotten values to ensure they are valid.
By default, only the mandatory Setting and getting time is enabled
for testing. To test the optional alarms, update event callback
and clock calibration, these must be enabled by selecting
CONFIG_RTC_ALARM, CONFIG_RTC_UPDATE and
CONFIG_RTC_CALIBRATION.
To build the test application with default settings for a board which
contains the device tree alias rtc, the following command can be used
for reference:
$ west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/
To build the test with additional RTC features enabled, use menuconfig to enable the additional features. The following command can be used for reference:
$ west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/
Then build the test application using the following command
$ west build
To run the test suite, flash and run the application on your board, the output will be printed to the console.
Note
The tests take up to 30 seconds each if they are testing real hardware.