RTC 开发指导_Rev1.4

修订记录

版本	日期	作者	修订内容
Rev1.0	23-09-19	LJZ	创建文档
Rev1.1	24-03-25	sxx	更改文档名称
Rev1.2	25-04-18	ZH	增加系列常见问题
Rev1.3	25-05-14	LJZ	1. 优化文档格式 2. 增加系列常见问题
Rev1.4	26-01-27	LJZ	新增接口Liot_GetTimestamp()

1 简介

本文档介绍 LTE-EC71X RTC 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_rtc/liot_rtc.h 文件声明。

2 API 函数概览

函数	说明
`liot_rtc_set_time()`	设置rtc时间
`liot_rtc_get_time()`	获取rtc时间
`liot_rtc_get_time_s()`	获取rtc时间转换成秒数
`liot_rtc_get_localtime()`	获取本地rtc时间
`liot_rtc_set_timezone()`	设置时区，以15分钟为单位
`liot_rtc_get_timezone()`	获取时区，以15分钟为单位
`liot_rtc_print_time()`	打印rtc时间
`liot_rtc_set_alarm()`	设置rtc alarm时间
`liot_rtc_get_alarm()`	获取rtc alarm时间
`liot_rtc_enable_alarm()`	打开和关闭rtc alarm
`liot_rtc_register_cb()`	注册rtc alarm 回调函数
`Liot_GetTimestamp()`	获取rtc时间转换成毫秒数

3 类型说明

3.1 liot_errcode_rtc_e

RTC API 执行结果错误码。

定义

typedef enum
{
    LIOT_RTC_SUCCESS = LIOT_SUCCESS,

    LIOT_RTC_INVALID_PARAM_ERR = 1 | LIOT_RTC_ERRCODE_BASE,
    LIOT_RTC_SET_TIME_ERROR,
    LIOT_RTC_GET_TIME_ERROR,
    LIOT_RTC_SET_CB_ERR,
    LIOT_RTC_ENABLE_ALARM_ERR,
    LIOT_RTC_REMOVE_ALARM_ERR,
    LIOT_RTC_GET_FUNC_ERR,
} liot_errcode_rtc_e;

参数

LIOT_RTC_SUCCESS：函数执行成功。
LIOT_RTC_INVALID_PARAM_ERR ：输入无效参数。
LIOT_RTC_SET_TIME_ERROR：设置 RTC 时间错误。
LIOT_RTC_GET_TIME_ERROR：获取 RTC 时间错误。
LIOT_RTC_SET_CB_ERR：注册回调函数错误。
LIOT_RTC_ENABLE_ALARM_ERR：启用警报错误。
LIOT_RTC_REMOVE_ALARM_ERR：删除警报错误。
LIOT_RTC_GET_FUNC_ERR：RTC API 函数无法识别。

3.2 liot_rtc_time_s

rtc时间结构体定义如下

定义

typedef struct liot_rtc_time_struct
{
    int tm_sec;  // seconds [0,59]
    int tm_min;  // minutes [0,59]
    int tm_hour; // hour [0,23]
    int tm_mday; // day of month [1,31]
    int tm_mon;  // month of year [1,12]
    int tm_year; // year [2000-2100]
    int tm_wday; // wday [0-6],sunday = 0,this value has no effect when setting the time
} liot_rtc_time_s;

参数

类型	参数	描述
int	tm_sec	秒。范围：0 ~ 59。
int	tm_min	分。范围：0 ~ 59。
int	tm_hour	时。范围：0 ~ 23。
int	tm_mday	日。范围：1 ~ 31。
int	tm_mon	月。范围：1 ~ 12。
int	tm_year	年。范围：2000 ~ 2100。
int	tm_wday	一周中的第几天。范围：0 ~ 6，0 为周日。

4 API 函数详解

4.1 liot_rtc_set_time

该函数用于设置rtc时间

声明

liot_errcode_rtc_e liot_rtc_set_time(liot_rtc_time_s *tm);

参数

tm：[In] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.2 liot_rtc_get_time

该函数用于获取rtc时间。

声明

liot_errcode_rtc_e liot_rtc_get_time(liot_rtc_time_s *tm);

参数

tm：[Out] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.3 liot_rtc_get_time_s

该函数用于将获取的rtc时间转换成秒数。时间基准为1970年1月1日 00:00:00 UTC 开始。

声明

INT32 liot_rtc_get_time_s(void);

返回值

INT32：rtc时间转换成秒数。

4.4 liot_rtc_get_localtime

该函数用于获取本地rtc时间。如当前在东八区，使用该接口获取的是经过时区偏移计算后的时间。

声明

liot_errcode_rtc_e liot_rtc_get_localtime(liot_rtc_time_s *tm);

参数

tm：[Out] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.5 liot_rtc_set_timezone

该函数用于设置时区。

声明

liot_errcode_rtc_e liot_rtc_set_timezone(int timezone);

参数

timezone：[In] 设置时区，时区参数范围：[-48，+56]。以15分钟为一个单位，例如：时区 8（东八区）对应的值是 8 x 4 = 32。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.6 liot_rtc_get_timezone

该函数用于获取时区。

声明

liot_errcode_rtc_e liot_rtc_get_timezone(int *timezone);

参数

timezone：[Out] 时区值，范围：[-48，+56]。以15分钟为一个单位，例如：时区 8（东八区）对应的值是 8 x 4 = 32。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.7 liot_rtc_print_time

该函数用于打印rtc时间至log口。

声明

liot_errcode_rtc_e liot_rtc_print_time(liot_rtc_time_s tm);

参数

tm：[In] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.8 liot_rtc_set_alarm

该函数用于设置rtc alarm时间。当前仅支持设置一个闹钟且闹钟时间掉电不保存。若需在低功耗模式下定时唤醒，请参考low-power-mode.md 使用 liot_deepslp_timer 系列接口实现。

声明

liot_errcode_rtc_e liot_rtc_set_alarm(liot_rtc_time_s *tm);

参数

tm：[In] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.9 liot_rtc_get_alarm

该函数用于获取rtc alarm时间。当前时间掉电不保存。

声明

liot_errcode_rtc_e liot_rtc_get_alarm(liot_rtc_time_s *tm);

参数

tm：[Out] 时间结构体。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.10 liot_rtc_enable_alarm

该函数用于打开和关闭rtc alarm。使能闹钟前需要通过liot_rtc_set_alarm设置时间，通过liot_rtc_register_cb注册时间到了之后的回调。

声明

liot_errcode_rtc_e liot_rtc_enable_alarm(unsigned char on_off);

参数

on_off：[In] 开关, 取值1和0, 1表示打开, 0表示关闭。

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.11 liot_rtc_register_cb

该函数用于注册rtc alarm 回调函数。

声明

liot_errcode_rtc_e liot_rtc_register_cb(liot_rtc_cb cb);

参数

cb：[In] alarm回调函数。liot_rtc_cb定义：typedef void (*liot_rtc_cb)(void);

返回值

liot_errcode_rtc_e：执行结果码，请参考 3.1。

4.12 Liot_GetTimestamp

该函数用于将获取的rtc时间转换成毫秒数。

声明

INT32 Liot_GetTimestamp(uint64_t *timestamp);

参数

timestamp：[Out] RTC时间转换的豪秒数。

返回值

INT32：0 获取成功，-1 参数错误。

5 代码示例

示例代码参考 examples/demo/src/demo_rtc.c 文件。如下运行结果则说明获取所有信息正常：

6 常见问题

6.1 EC718 32K 时钟精度如何？

只有内部 RTC 工作时，不校准的情况下，误差较大，24H 大概会误差几分钟。32K RTC 需要校准，想要获取准确的时间需要和网络同步，可通过liot_nw_set_ctzu_switch来打开基站的时间同步功能或使用liot_ntp_sync来主动进行时间同步。

6.2 低功耗模式下的闹钟支持

目前低功耗（如 PSM, HIBERNATE）下不支持闹钟唤醒。若需在低功耗模式下定时唤醒，请参考low-power-mode.md 使用 liot_deepslp_timer 系列接口实现。