跳转至

rtc

作者:王城钧

一、概述

rtc 库提供实时时钟设置与获取功能:rtc.set 以表或时间戳形式设置时钟,返回操作状态;rtc.get 获取当前时钟信息并返回表;同时支持设置与取消 RTC 唤醒时间,以及设置 RTC 基准年和读取或设置时区。

(1)硬件完全掉电(vbat 断电),再上电(vbat 上电),开机后的时间默认是什么?

此种情况上电开机默认时间为{"year":36804,"min":0,"hour":0,"mon":15,"sec":0,"day":12}

(2)硬件没有掉电(vbat 一直有电),软件关机,再开机后的时间默认是什么?

此种情况上电开机默认时间为实时时间

(3)硬件没有掉电(vbat 一直有电),软件重启,重启后的时间默认是什么?

此种情况上电开机默认时间为{"year":36804,"min":0,"hour":0,"mon":15,"sec":0,"day":12}

(4)内部硬件看门狗重启,重启后的时间默认是什么?

此种情况上电开机默认时间为 {"year":36804,"min":0,"hour":0,"mon":15,"sec":0,"day":12}

二、核心示例

1、核心示例是指:使用本库文件提供的核心 API,开发的基础业务逻辑的演示代码;

2、核心示例的作用是:帮助开发者快速理解如何使用本库,所以核心示例的逻辑都比较简单;

3、更加完整和详细的 demo,请参考 LuatOS 仓库 中各个产品目录下的 demo/rtc

-- LuaTools需要PROJECT和VERSION这两个信息
PROJECT = "rtcdemo"
VERSION = "000.000.001"

log.info("main", PROJECT, VERSION)

--添加硬狗防止程序卡死
if wdt then
    wdt.init(9000)--初始化watchdog设置为9s
    sys.timerLoopStart(wdt.feed, 3000)--3s喂一次狗
end

local function rtc_task()
    log.info("os.date()", os.date())
    local t = rtc.get()
    log.info("rtc", json.encode(t))
    rtc.set({year=2021,mon=8,day=31,hour=17,min=8,sec=43})
    log.info("os.date()", os.date())
    while 1 do
        log.info("os.date()", os.date())
        local t = rtc.get()
        log.info("rtc", json.encode(t))
        sys.wait(1000)
    end
end

sys.taskInit(rtc_task)

-- 主循环, 必须加
sys.run()

三、常量详解

核心库常量,顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值,在脚本代码中不需要声明,可直接调用;

每个常量对应的常量取值仅做日志打印时查询使用,不要将这个常量取值用做具体的业务逻辑判断,因为LuatOS内核固件可能会变更每个常量对应的常量取值;

如果用做具体的业务逻辑判断,一旦常量取值发生改变,业务逻辑就会出错;

rtc 核心库没有常量。

四、函数详解

rtc.set(val)

功能

设置 RTC 时钟的时间

参数

val

参数含义:当val为table类型的参数时,表示设置时钟的参数;
         {
            -- 参数含义:时钟年份;
            -- 数据类型:number/nil;
            -- 取值范围:无特别限制;
            -- 是否必选:必须传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:2025;
            year =,

            -- 参数含义:时钟起始月份;
            -- 数据类型:number/nil;
            -- 取值范围:1-12;
            -- 是否必选:必须传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:9;
            mon =,

            -- 参数含义:时钟起始日期;
            -- 数据类型:number/nil;
            -- 取值范围:1-31;
            -- 是否必选:必须传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:29;
            day =,

            -- 参数含义:时钟起始小时;
            -- 数据类型:number/nil;
            -- 取值范围:1-23;
            -- 是否必选:必选传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:16;
            hour =,

            -- 参数含义:时钟起始分钟;
            -- 数据类型:number/nil;
            -- 取值范围:1-59;
            -- 是否必选:必选传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:37;
            min =,  

            -- 参数含义:时钟起始秒数;
            -- 数据类型:number/nil;
            -- 取值范围:1-59;
            -- 是否必选:必选传入此参数;
            -- 注意事项:暂无;
            -- 参数示例:36;
            sec =,                       
         }

         val为number类型的参数时,表示设置时钟的时间戳。
数据类型:table或者number
取值范围:若为number类型则取值范围最大为从1970年1月1日00:00:00
         203811903:14:07的总秒数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:
        val为table类型的参数时
        {
         year=2021,
         mon=8,
         day=31,
         hour=17,
         min=8,
         sec=43
        }
        val为number类型的参数时
        (1652230554)

返回值

local result = rtc.set(val)

result

含义说明:时钟设置成功返回true,失败会返回false
数据类型:boolean
取值范围:true或者false
注意事项:暂无;
返回示例:true

示例

local result = rtc.set({year=2021,mon=8,day=31,hour=17,min=8,sec=43})
log.info("RTC设置",result)

local result1 = rtc.set(1652230554)
log.info("RTC设置",result1)

rtc.get()

功能

获取当前系统实时时钟的时间

参数

nil

返回值

local t = rtc.get() t

含义说明:表示实时时钟的当前时间信息;
         {
            -- 含义说明:获取到的时钟年份;
            -- 数据类型:number;
            -- 取值范围:暂无;
            -- 注意事项:暂无;
            -- 返回示例:2025;
            year =,

            -- 含义说明:获取到的时钟月份;
            -- 数据类型:number;
            -- 取值范围:1-12;
            -- 注意事项:暂无;
            -- 返回示例:9;
            mon =,

            -- 含义说明:获取到的时钟日期;
            -- 数据类型:number;
            -- 取值范围:1-31;
            -- 注意事项:暂无;
            -- 返回示例:29;
            day =,

            -- 含义说明:获取到的时钟小时;
            -- 数据类型:number;
            -- 取值范围:1-31;
            -- 注意事项:暂无;
            -- 返回示例:17;
            hour =,

            -- 含义说明:获取到的时钟分钟;
            -- 数据类型:number;
            -- 取值范围:1-59;
            -- 注意事项:暂无;
            -- 返回示例:19;
            min =,  

            -- 含义说明:获取到的时钟秒数;
            -- 数据类型:number;
            -- 取值范围:1-59;
            -- 注意事项:暂无;
            -- 返回示例:29;
            sec =,                       
         }
数据类型:table
取值范围:暂无;
注意事项:暂无;
返回示例:{year=2021,mon=8,day=31,hour=17,min=8,sec=43};

示例

local t = rtc.get()
-- {year=2021,mon=8,day=31,hour=17,min=8,sec=43}
log.info("rtc", json.encode(t))

rtc.setBaseYear(Base_year)

功能

设置 RTC 基准年

参数

Base_year

参数含义:基准年Base_year,作为年份计算的偏移量,
         用于自然年份与硬件存储年份之间的双向转换,默认1900
         以下几种情况需要用这个接口:
         1.硬件RTC采用非1900基准
         某些RTC芯片可能以2000年为起始年(如存储0对应2000年)。
         2.系统需求特殊年份范围
         若系统仅需处理1970年至今的时间(如Unix时间戳兼容),减少转换计算量。
         用户需查阅硬件文档,确认RTC芯片的年份存储格式,验证系统时间行为,
         通过rtc.set设置一个测试时间,再用rtc.get读取。若返回值与预期不符,
         需调整Base_year
数据类型:number
取值范围:无特别限制;
是否必选:可选传入此参数;
注意事项:暂无;
参数示例:1900

返回值

nil

示例

rtc.setBaseYear(1900)

rtc.timezone(tz)

功能

读取或设置时区

参数

tz

参数含义:时区值,注意单位是1/4时区.例如东八区是32,而非8,西四区为-16,而非-4,默认32即东八区;
数据类型:number
取值范围:东零区到东十二区(048),西一区到西十二区(-4-48);
是否必选:可选传入此参数;
注意事项:暂无;
参数示例:32

返回值

local result = rtc.timezone(tz)

result

含义说明:当前/设置后的时区值,注意单位是1/4时区.例如东八区是32,而非8,西四区为-16,而非-4
数据类型:number
取值范围:东零区到东十二区(048),西一区到西十二区(-4-48);
注意事项:暂无;
返回示例:32

示例

-- 设置为东8区
rtc.timezone(32)
-- 设置为东3区
rtc.timezone(12)
-- 设置为西4区
rtc.timezone(-16)

五、产品支持说明

目前合宙所有主流模组都支持 rtc 核心库。