Question

RTC 简介

RTC （Real-Time Clock）实时时钟可以提供精确的实时时间，它可以用于产生年、月、日、时、分、秒等信息。目前实时时钟芯片大多采用精度较高的晶体振荡器作为时钟源。有些时钟芯片为了在主电源掉电时还可以工作，会外加电池供电，使时间信息一直保持有效。

RT-Thread 的 RTC设备为操作系统的时间系统提供了基础服务。面对越来越多的 IoT 场景，RTC 已经成为产品的标配，甚至在诸如 SSL 的安全传输过程中，RTC 已经成为不可或缺的部分。

访问 RTC 设备

应用程序通过 RTC 设备管理接口来访问 RTC 硬件，相关接口如下所示：

函数	描述
set_date()	设置日期，年、月、日
set_time()	设置时间，时、分、秒
time()	获取当前时间

设置日期

通过如下函数设置 RTC 设备当前日期值：

rt_err_t set_date(rt_uint32_t year, rt_uint32_t month, rt_uint32_t day)

参数	描述
year	待设置生效的年份
month	待设置生效的月份
day	待设置生效的日
返回	——
RT_EOK	设置成功
-RT_ERROR	失败，没有找到 rtc 设备
其他错误码	失败

使用示例如下所示：

/* 设置日期为2018年12月3号 */
set_date(2018, 12, 3);

设置时间

通过如下函数设置 RTC 设备当前时间值：

rt_err_t set_time(rt_uint32_t hour, rt_uint32_t minute, rt_uint32_t second)

参数	描述
hour	待设置生效的时
minute	待设置生效的分
second	待设置生效的秒
返回	——
RT_EOK	设置成功
-RT_ERROR	失败，没有找到 rtc 设备
其他错误码	失败

使用示例如下所示：

/* 设置时间为11点15分50秒 */
set_time(11, 15, 50);

获取当前时间

使用到 C 标准库中的时间 API 获取时间：

time_t time(time_t *t)

参数	描述
t	时间数据指针
返回	——
当前时间值

使用示例如下所示：

time_t now;     /* 保存获取的当前时间值 */
/* 获取时间 */
now = time(RT_NULL);
/* 打印输出时间信息 */
rt_kprintf("%s\n", ctime(&now));

注意事项

目前系统内只允许存在一个 RTC 设备，且名称为 "rtc" 。

功能配置

启用 Soft RTC （软件模拟 RTC）

在 menuconfig 中可以启用使用软件模拟 RTC 的功能，这个模式非常适用于对时间精度要求不高，没有硬件 RTC 的产品。配置选项如下所示：

RT-Thread Components → 
    Device Drivers:
        -*- Using RTC device drivers                                 /* 使用 RTC 设备驱动 */
        [ ]   Using software simulation RTC device                   /* 使用软件模拟 RTC */

启用 NTP 时间自动同步

如果 RT-Thread 已接入互联网，可启用 NTP 时间自动同步功能，定期同步本地时间。

首先在 menuconfig 中按照如下选项开启 NTP 功能：

RT-Thread online packages →
    IoT - internet of things →
        netutils: Networking utilities for RT-Thread:
             [*]   Enable NTP(Network Time Protocol) client

开启 NTP 后 RTC 的自动同步功能将会自动开启，还可以设置同步周期和首次同步的延时时间：

RT-Thread Components → 
    Device Drivers:
        -*- Using RTC device drivers                                 /* 使用 RTC 设备驱动 */
        [ ]   Using software simulation RTC device                   /* 使用软件模拟 RTC */
        [*]   Using NTP auto sync RTC time                           /* 使用 NTP 自动同步 RTC 时间 */
       (30)    NTP first sync delay time(second) for network connect /* 首次执行 NTP 时间同步的延时。延时的目的在于，给网络连接预留一定的时间，尽量提高第一次执行 NTP 时间同步时的成功率。默认时间为 30S； */
       (3600)  NTP auto sync period(second)                          /* NTP 自动同步周期，单位为秒，默认一小时（即 3600S）同步一次。 */

FinSH 命令

输入 date 即可查看当前时间，大致效果如下：

msh />date
Fri Feb 16 01:11:56 2018
msh />

同样使用 date 命令，在命令后面再依次输入 年 月 日 时 分 秒 （中间空格隔开, 24H 制），设置当前时间为 2018-02-16 01:15:30，大致效果如下：

msh />date 2018 02 16 01 15 30
msh />

RTC 设备使用示例

RTC 设备的具体使用方式可以参考如下示例代码，首先设置了年月日时分秒信息，然后延时 3 秒后获取当前时间信息。

/*
 * 程序清单：这是一个 RTC 设备使用例程
 * 例程导出了 rtc_sample 命令到控制终端
 * 命令调用格式：rtc_sample
 * 程序功能：设置RTC设备的日期和时间，延时一段时间后获取当前时间并打印显示。
*/

#include <rtthread.h>
#include <rtdevice.h>

static int rtc_sample(int argc, char *argv[])
{
    rt_err_t ret = RT_EOK;
    time_t now;

    /* 设置日期 */
    ret = set_date(2018, 12, 3);
    if (ret != RT_EOK)
    {
        rt_kprintf("set RTC date failed\n");
        return ret;
    }

    /* 设置时间 */
    ret = set_time(11, 15, 50);
    if (ret != RT_EOK)
    {
        rt_kprintf("set RTC time failed\n");
        return ret;
    }

    /* 延时3秒 */
    rt_thread_mdelay(3000);

    /* 获取时间 */
    now = time(RT_NULL);
    rt_kprintf("%s\n", ctime(&now));

    return ret;
}
/* 导出到 msh 命令列表中 */
MSH_CMD_EXPORT(rtc_sample, rtc sample);