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 核心库。