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
到2038年1月19日03: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;
取值范围:东零区到东十二区(0到48),西一区到西十二区(-4到-48);
是否必选:可选传入此参数;
注意事项:暂无;
参数示例:32;
返回值
local result = rtc.timezone(tz)
result
含义说明:当前/设置后的时区值,注意单位是1/4时区.例如东八区是32,而非8,西四区为-16,而非-4;
数据类型:number;
取值范围:东零区到东十二区(0到48),西一区到西十二区(-4到-48);
注意事项:暂无;
返回示例:32;
示例
-- 设置为东8区
rtc.timezone(32)
-- 设置为东3区
rtc.timezone(12)
-- 设置为西4区
rtc.timezone(-16)
五、产品支持说明
目前合宙所有主流模组都支持 rtc 核心库。