25 rtc 实时时钟

作者：王城钧　|　最后修改：2026-04-14

一、rtc(实时时钟)概述

rtc（实时时钟）是一种能独立于主系统电源持续运行的电子组件，经分频计数实现年、月、日、时、分、秒的精准计量，可与主系统实现时间读取、校准、闹钟触发等交互，具备高稳定性的特点，广泛应用于消费电子、物联网、工业控制、汽车电子等领域，为设备提供可靠的时间戳和时序基准，是保障系统时间同步的关键组件。

1.1 LuatOS 的 rtc 核心库有什么用？

rtc 核心库提供对 rtc 功能的设置以及获取能力，主要功能包括：

设置 rtc 时钟初始时间，读取 rtc 时钟时间
设置 rtc 的时区以及基准年

二、演示功能概述

本教程将使用 Air780EGH 核心板演示 rtc 核心库的核心功能，主要包括：

场景 1(无网络环境下的 rtc 功能演示)

设置基准年和时区信息初始化 rtc
通过时间戳设置具体时间后，每秒循环打印基于 rtc 的本地时间

场景 2(获取基站和 ntp 授时成功后的 rtc 时间和实时时间)

设置基准年和时区信息初始化 rtc
等待基站和 ntp 授时成功，随后每秒循环打印实时时间和 rtc 时钟时间

三、准备硬件环境

1.Air780EGH 核心板 +SIM 卡(若选择的是 demo 中获取实时时间的协程需要插入 SIM 卡)

2.TYPE-C USB 数据线一根，Air780EGH 核心板和数据线的硬件接线方式为：

Air780EGH 核心板通过 TYPE-C USB 口供电；（外部供电/USB 供电拨动开关拨到 USB 供电一端）
TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

四、软件环境

在开始实践本示例之前，先筹备一下软件环境：

1.烧录工具： Luatools 工具；

2.内核固件：本demo开发测试时使用的固件为Air780EGH V2016 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；

3.LuatOS 需要的脚本和资源文件

脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/rtc

准备好软件环境之后，接下来查看如何烧录项目文件到 Air780EGH 核心板，将本篇文章中演示使用的项目文件烧录到 Air780EGH 核心板中。

五、API 接口说明

详细 API 文档请参考：https://docs.openluat.com/osapi/core/rtc/

六、代码示例介绍

6.1 功能测试核心代码

注意：以下两个任务每次测试时只能选择其一进行测试

-- RTC时钟演示(测试环境为无网络环境)
local function rtc_task1()
    rtc.setBaseYear(1900) -- 设置基准年为1900年
    local result = rtc.timezone(32) -- 设置时区为东八区
    log.info("rtc.timezone()", result) -- 打印时区信息
    -- rtc.set({ year = 2025, mon = 10, day = 28, hour = 8, min = 10, sec = 53 }) -- 设置日期和时间
    rtc.set(1761639053) -- 设置时间戳(与上一行的设置效果相同，二选一即可)
    local t1 = rtc.get()
    log.info("rtc初始时间", json.encode(t1)) -- 打印当前日期和时间
    log.info("rtc设置后的本地时间", os.date()) -- 打印当前日期和时间    
    while true do
        log.info("os.date()", os.date()) -- 打印RTC时钟时间
        local t = rtc.get() -- 获取rtc时间
        log.info("循环rtc时间", json.encode(t)) -- 打印当前rtc时间
        sys.wait(1000) -- 等待1s，然后再次获取rtc时间和实时时间
    end
end

-- 获取基站和 NTP授时成功后的rtc时间
local function rtc_task2()
    rtc.setBaseYear(1900) -- 设置基准年为1900年
    local result = rtc.timezone(32) -- 设置时区为东八区
    log.info("rtc.timezone()", result) -- 打印时区信息
    -- rtc.set({ year = 2025, mon = 10, day = 28, hour = 19, min = 10, sec = 53 }) -- 设置日期和时间
    rtc.set(1761678653) -- 设置时间戳(与上一行的设置效果相同，二选一即可)
    log.info("rtc设置后时间", os.date()) -- 打印当前日期和时间
    while not socket.adapter(socket.dft()) do
        log.warn("sntp_task_func", "wait IP_READY", socket.dft())
        -- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
        -- 或者等待1秒超时退出阻塞等待状态;
        -- 注意：此处的1000毫秒超时不要修改的更长；
        -- 因为当使用exnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
        -- 当exnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
        -- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
        sys.waitUntil("IP_READY", 1000)
    end
    socket.sntp()
    sys.waitUntil("NTP_UPDATE", 5000)
    while true do
        log.info("os.date()", os.date()) -- 打印实时时间
        local t = rtc.get()              -- 获取rtc时间
        log.info("循环rtc时间", json.encode(t))
        -- 打印当前rtc时间,当收到基站和 NTP授时的时候,rtc时间会自动更新为当前UTC时间(零时区)，于北京时间(东八区)相差8小时
        sys.wait(1000) -- 等待1s,然后再次获取rtc时间和实时时间
    end
end

-- 注意：以下两个任务每次测试时只能选择其一进行测试

-- 无网络情况下的rtc时间演示
sys.taskInit(rtc_task1)

-- 获取基站和 NTP授时成功后的rtc时间
-- sys.taskInit(rtc_task2)

6.2 功能验证

通过 luatools 工具查看相关日志：

任务 1：

任务 2：

七、总结

至此，本示例详细介绍了如何使用 rtc 核心库进行功能测试开发。