1.. _rtc_api:
2
3Real-Time Clock (RTC)
4#####################
5
6Overview
7********
8
9.. list-table:: **Glossary**
10    :widths: 30 80
11    :header-rows: 1
12
13    * - Word
14      - Definition
15    * - Real-time clock
16      - Low power device tracking time using broken-down time
17    * - Real-time counter
18      - Low power counter which can be used to track time
19    * - RTC
20      - Acronym for real-time clock
21
22An RTC is a low power device which tracks time using broken-down time.
23It should not be confused with low-power counters which sometimes share
24the same name, acronym, or both.
25
26RTCs are usually optimized for low energy consumption and are usually
27kept running even when the system is in a low power state.
28
29RTCs usually contain one or more alarms which can be configured to
30trigger at a given time. These alarms are commonly used to wake up the
31system from a low power state.
32
33History of RTCs in Zephyr
34*************************
35
36RTCs have been supported before this API was created, using the
37:ref:`counter_api` API. The unix timestamp was used to convert
38between broken-down time and the unix timestamp within the RTC
39drivers, which internally used the broken-down time representation.
40
41The disadvantages of this approach were that hardware counters could
42not be set to a specific count, requiring all RTCs to use device
43specific APIs to set the time, converting from unix time to
44broken-down time, unnecessarily in some cases, and some common
45features missing, like input clock calibration and the update
46callback.
47
48Configuration Options
49*********************
50
51Related configuration options:
52
53* :kconfig:option:`CONFIG_RTC`
54* :kconfig:option:`CONFIG_RTC_ALARM`
55* :kconfig:option:`CONFIG_RTC_UPDATE`
56* :kconfig:option:`CONFIG_RTC_CALIBRATION`
57
58API Reference
59*************
60
61.. doxygengroup:: rtc_interface
62
63RTC device driver test suite
64****************************
65
66The test suite validates the behavior of the RTC device driver. It
67is designed to be portable between boards. It uses the device tree
68alias ``rtc`` to designate the RTC device to test.
69
70This test suite tests the following:
71
72* Setting and getting the time.
73* RTC Time incrementing correctly.
74* Alarms if supported by hardware, with and without callback enabled
75* Calibration if supported by hardware.
76
77The calibration test tests a range of values which are printed to the
78console to be manually compared. The user must review the set and
79gotten values to ensure they are valid.
80
81By default, only the mandatory setting and getting of time is enabled
82for testing. To test the optional alarms, update event callback
83and clock calibration, these must be enabled by selecting
84:kconfig:option:`CONFIG_RTC_ALARM`, :kconfig:option:`CONFIG_RTC_UPDATE`
85and :kconfig:option:`CONFIG_RTC_CALIBRATION`.
86
87The following examples build the test suite for the ``native_posix``
88board. To build the test suite for a different board, replace the
89``native_posix`` board with your board.
90
91To build the test application with the default configuration, testing
92only the mandatory features, the following command can be used for
93reference:
94
95.. zephyr-app-commands::
96   :tool: west
97   :host-os: unix
98   :board: native_posix
99   :zephyr-app: tests/drivers/rtc/rtc_api
100   :goals: build
101
102To build the test with additional RTC features enabled, use menuconfig
103to enable the additional features by updating the configuration. The
104following command can be used for reference:
105
106.. zephyr-app-commands::
107   :tool: west
108   :host-os: unix
109   :board: native_posix
110   :zephyr-app: tests/drivers/rtc/rtc_api
111   :goals: menuconfig
112
113Then build the test application using the following command:
114
115.. zephyr-app-commands::
116   :tool: west
117   :host-os: unix
118   :board: native_posix
119   :zephyr-app: tests/drivers/rtc/rtc_api
120   :maybe-skip-config:
121   :goals: build
122
123To run the test suite, flash and run the application on your board, the output will
124be printed to the console.
125
126.. note::
127
128    The tests take up to 30 seconds each if they are testing real hardware.
129