1@page page_device_rtc RTC Device
2
3# Introduction of RTC
4
5The RTC (Real-Time Clock) provides accurate real-time clock time, which can be used to generate information such as year, month, day, hour, minute, and second. At present, most real-time clock chips use a higher precision crystal oscillator as a clock source. In order to work when the main power supply is powered down, some clock chips will be powered by a battery to keep the time information valid.
6
7The RT-Thread RTC device provides the basic services for the operating system's time system. RTCs find many uses in IoT scenarios, and even in secure transmission processes such as SSL, RTC has become an indispensable part.
8
9
10# Access RTC Devices
11
12The application accesses the RTC hardware through the RTC device management interface, and the relevant interfaces are as follows:
13
14| **Function** | Description                |
15| ------------- | ---------------------------------- |
16| set_date()  | Set date, year, month, day |
17| set_time()     | Set time, hour, minute, second |
18| time()   | Obtain current time |
19
20## Set Date
21
22Set the current date value of the RTC device by the following functions:
23
24```c
25rt_err_t set_date(rt_uint32_t year, rt_uint32_t month, rt_uint32_t day)
26```
27
28| **Parameter** | **Description**                |
29| -------- | ---------------------------------- |
30|year      |The year to be set to take effect|
31|month     |The month to be set to take effect|
32|day       | The date to be set to take effect  |
33| **return** | ——                                 |
34| RT_EOK   | Set-up succeeded |
35| -RT_ERROR | Set-up failed, no rtc device found |
36| other error code | Set-up failed  |
37
38An example of use is as follows:
39
40```c
41/* Set the date to December 3, 2018 */
42set_date(2018, 12, 3);
43```
44
45## Set Time
46
47Set the current time value of the RTC device by the following function:
48
49```c
50rt_err_t set_time(rt_uint32_t hour, rt_uint32_t minute, rt_uint32_t second)
51```
52
53| **Parameter** | **Description**              |
54| ---------- | ------------------------------- |
55|hour         |The hour to be set to take effect|
56|minute        |The minute to be set to take effect|
57|second        |The second to be set to take effect|
58| **return** | ——                             |
59| RT_EOK   | Set-up succeeded |
60| -RT_ERROR | Set-up failed, no rtc device found |
61| other error code | Set-up failed   |
62
63An example of use is as follows:
64
65```c
66/* Set the time to 11:15:50 */
67set_time(11, 15, 50);
68```
69
70## Obtain Current Time
71
72Obtain time using the time API in the C standard library:
73
74```c
75time_t time(time_t *t)
76```
77
78| **Parameter** | **Description**              |
79| ---------- | ------------------------------- |
80|t          |Time data pointer      |
81| **return** | ——                             |
82| Current time value |  |
83
84Examples of use are as follows:
85
86```c
87time_t now;     /* Save the current time value obtained */
88/* Obtain Time */
89now = time(RT_NULL);
90/* Printout time information */
91rt_kprintf("%s\n", ctime(&now));
92```
93
94>Currently only one RTC device is allowed in the system and the name is `"rtc"`.
95
96# Functional Configuration
97
98## Enable Soft RTC (Software Emulation RTC)
99
100You can use the function of enabling RTC software emulation, which is ideal for products that do not require high time precision and have no hardware RTC. The configuration options of menuconfig are as follows:
101
102```c
103RT-Thread Components →
104    Device Drivers:
105        -*- Using RTC device drivers                                 /* Use RTC device driver */
106        [ ]   Using software simulation RTC device                   /* Use software simulation RTC device */
107```
108
109## Enable NTP Time Automatic Synchronization
110
111If the RT-Thread is connected to the Internet, you can enable automatic NTP time synchronization to synchronize local time periodically.
112
113First open the NTP function in menuconfig as follows:
114
115```c
116RT-Thread online packages →
117    IoT - internet of things →
118        netutils: Networking utilities for RT-Thread:
119             [*]   Enable NTP(Network Time Protocol) client
120```
121
122After NTP is turned on, the RTC's automatic synchronization function will be automatically turned on, and the synchronization period and the delay time of the first synchronization can also be set:
123
124```c
125RT-Thread Components →
126    Device Drivers:
127        -*- Using RTC device drivers                                 /* Use RTC device driver */
128        [ ]   Using software simulation RTC device                   /* Use software simulation RTC device */
129        [*]   Using NTP auto sync RTC time                           /* Automatically synchronize RTC time with NTP */
130       (30)    NTP first sync delay time(second) for network connect /* The delay for performing NTP time synchronization for the first time. The purpose of the delay is to reserve a certain amount of time for the network connection and try to increase the success rate of the first NTP time synchronization. The default time is 30S； */
131       (3600)  NTP auto sync period(second)                          /* NTP The synchronization period is automatically synchronized in seconds, and the default period is one hour (ie 3600S). */
132```
133
134# FinSH Command
135
136Enter `date` to view the current time.
137
138```c
139msh />date
140Fri Feb 16 01:11:56 2018
141msh />
142```
143
144Also use the `date` command, after the command, enter `year` `month` `date` `hour ` ` minute ` ` second ` (between spaces, 24H system), and set the current time to 2018-02-16 01:15:30. The approximate effect is as follows:
145
146```c
147msh />date 2018 02 16 01 15 30
148msh />
149```
150
151# RTC Device Usage Examples
152
153For the specific usage of the RTC device, refer to the following example code. First, set the year, month, date, hour, minute and second information, and then delay the data for 3 seconds to get the current time information.
154
155```c
156/*
157 * Program listing: This is an RTC device usage routine
158 * The routine exports the rtc_sample command to the control terminal
159 * Command call format：rtc_sample
160 * Program function: Set the date and time of the RTC device. After a delay, obtain the current time and print the display.
161*/
162
163#include <rtthread.h>
164#include <rtdevice.h>
165
166static int rtc_sample(int argc, char *argv[])
167{
168    rt_err_t ret = RT_EOK;
169    time_t now;
170
171    /* Set date */
172    ret = set_date(2018, 12, 3);
173    if (ret != RT_EOK)
174    {
175        rt_kprintf("set RTC date failed\n");
176        return ret;
177    }
178
179    /* Set time */
180    ret = set_time(11, 15, 50);
181    if (ret != RT_EOK)
182    {
183        rt_kprintf("set RTC time failed\n");
184        return ret;
185    }
186
187    /* Delay 3 seconds */
188    rt_thread_mdelay(3000);
189
190    /* Obtain Time */
191    now = time(RT_NULL);
192    rt_kprintf("%s\n", ctime(&now));
193
194    return ret;
195}
196/* Export to the msh command list */
197MSH_CMD_EXPORT(rtc_sample, rtc sample);
198```
199