The 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.
The 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.
| -RT_ERROR | Set-up failed, no rtc device found |
| other error code | Set-up failed |
An example of use is as follows:
```c
/* Set the time to 11:15:50 */
set_time(11, 15, 50);
```
### Obtain Current Time
Obtain time using the time API in the C standard library:
```c
time_t time(time_t *t)
```
| **Parameter** | **Description** |
| ---------- | ------------------------------- |
|t |Time data pointer |
| **return** | —— |
| Current time value | |
Examples of use are as follows:
```c
time_t now; /* Save the current time value obtained */
/* Obtain Time */
now = time(RT_NULL);
/* Printout time information */
rt_kprintf("%s\n", ctime(&now));
```
>Currently only one RTC device is allowed in the system and the name is `"rtc"`.
## Functional Configuration
### Enable Soft RTC (Software Emulation RTC)
You 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:
```c
RT-Thread Components →
Device Drivers:
-*- Using RTC device drivers /* Use RTC device driver */
[ ] Using software simulation RTC device /* Use software simulation RTC device */
```
### Enable NTP Time Automatic Synchronization
If the RT-Thread is connected to the Internet, you can enable automatic NTP time synchronization to synchronize local time periodically.
First open the NTP function in menuconfig as follows:
After 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:
-*- Using RTC device drivers /* Use RTC device driver */
[ ] Using software simulation RTC device /* Use software simulation RTC device */
[*] Using NTP auto sync RTC time /* Automatically synchronize RTC time with NTP */
(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； */
(3600) NTP auto sync period(second) /* NTP The synchronization period is automatically synchronized in seconds, and the default period is one hour (ie 3600S). */
```
## FinSH Command
Enter `date` to view the current time.
```c
msh />date
Fri Feb 16 01:11:56 2018
msh />
```
Also 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:
```c
msh />date 2018 02 16 01 15 30
msh />
```
## RTC Device Usage Examples
For 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.
```c
/*
* Program listing: This is an RTC device usage routine
* The routine exports the rtc_sample command to the control terminal
* Command call format：rtc_sample
* Program function: Set the date and time of the RTC device. After a delay, obtain the current time and print the display.
