RTC

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

功能概述

RTC（Real-Time Clock，实时时钟）芯片是一种集成时钟计时功能的电路模块，支持对年、月、日、星期、时、分、秒进行精确计时，并具备闰年自动补偿功能。

RTC的工作原理

RTC的基本结构

  • 低频时钟源：通常为32.768 kHz外部晶振（LSE）或内部低速RC振荡器（LSI），为RTC提供高稳定性的时间基准。

  • 预分频器（Prescaler）：将输入时钟分频至1 Hz，产生精确的秒脉冲。

  • 时间/日期寄存器：以BCD或二进制格式存储当前时间与日期。

  • 备份域（Backup Domain）：包含一组由备用电源（如VBAT）供电的寄存器，主电源掉电后内容不丢失，用于保存RTC配置和用户数据。

  • 闹钟（Alarm）单元：可编程设置特定时间点触发中断或唤醒系统。

  • 周期性唤醒定时器（Wakeup Timer）：支持毫秒级到秒级的周期性事件。

  • 控制与状态寄存器：用于配置RTC功能、使能中断、检查标志位等。

  • 中断输出机制：支持秒更新、闹钟、唤醒等事件的中断或事件信号输出。

RTC的工作流程

  1. 输入/输出端口

RTC芯片可通过输入/输出端口接收外部信号，据此调整系统时间。例如，通过串行通信接口（UART、I2C、SPI等）接收计算机或其他设备下发的时间信息，或通过网络协议（如NTP）同步网络时间。

  1. 定时器/计数器

RTC芯片内部通常集成一个或多个定时器/计数器，用于产生时间基准。定时器/计数器由预分频器和计数器构成：预分频器将系统时钟分频至合适的计数频率，计数器在该频率下累计经过的时间。当计数值达到设定值时，会触发中断事件，通知系统更新时间。

  1. 中断控制器

RTC芯片还包含中断控制器，用于处理定时器的溢出事件。当定时器/计数器的计数值达到设定值时，会向中断控制器发出中断请求；中断控制器识别该请求后，触发相应的中断服务程序（ISR）执行，如更新系统时间、唤醒等待处理的任务等。

  1. 系统时间的更新

需要校准系统时间时，RTC芯片会执行一系列操作：首先，通过输入/输出端口接收新的时间信息；然后，使用定时器/计数器计算经过的时间差；接着，将该时间差累加到当前系统时间上；最后，通过中断控制器通知系统其他部分时间已更新。

RTC API

头文件

qosa_rtc.h

函数概览

函数

说明

qosa_rtc_set_time()

设置系统RTC时间

qosa_rtc_get_time()

获取系统RTC时间

qosa_rtc_get_localtime()

获取本地时间（UTC时间 + 时区偏移）

qosa_rtc_get_timezone()

获取系统的时区偏移量

qosa_rtc_set_timezone()

设置系统的时区偏移量

qosa_rtc_gmtime_r()

将Unix时间戳转换为分解时间（struct tm 格式）

qosa_rtc_mktime()

将分解时间（struct tm 格式）转换为Unix时间戳

qosa_rtc_set_alarm()

设置RTC闹钟时间

qosa_rtc_get_alarm()

获取RTC闹钟时间

qosa_rtc_enable_alarm()

启用或禁用RTC闹钟

qosa_rtc_register_cb()

注册RTC回调函数

qosa_rtc_set_cfg()

设置RTC配置

qosa_rtc_get_cfg()

获取RTC配置

qosa_rtc_print_time()

打印RTC时间到指定输出设备

函数详解

qosa_rtc_set_time

  • 功能描述
    设置系统RTC时间。

  • 函数原型

int qosa_rtc_set_time(qosa_time_t time);

  • 参数说明

参数名

输入/输出

类型

说明

time

输入

qosa_time_t

Unix时间戳

  • 返回值说明
    0：函数执行成功
    -1：函数执行失败

qosa_rtc_get_time

  • 功能描述
    获取系统RTC时间。

  • 函数原型

int qosa_rtc_get_time(qosa_time_t *time);

  • 参数说明

参数名

输入/输出

类型

说明

time

输出

qosa_time_t *

指向 qosa_time_t 的指针，用于存储获取到的Unix时间戳

  • 返回值说明
    0：函数执行成功
    -1：函数执行失败

qosa_rtc_get_localtime

  • 功能描述
    获取本地时间（UTC时间 + 时区偏移）。

  • 函数原型

int qosa_rtc_get_localtime(qosa_time_t *time);

  • 参数说明

参数名

输入/输出

类型

说明

time

输出

qosa_time_t *

指向 qosa_time_t 的指针，用于存储获取到的本地时间戳

  • 返回值说明
    0：函数执行成功
    -1：函数执行失败

qosa_rtc_get_timezone

  • 功能描述
    获取系统的时区偏移量。

  • 函数原型

int qosa_rtc_get_timezone(void);

  • 参数说明
    无

  • 返回值说明
    时区偏移量（单位：15分钟）

qosa_rtc_set_timezone

  • 功能描述
    设置系统的时区偏移量。

  • 函数原型

int qosa_rtc_set_timezone(int time_zone);

  • 参数说明

参数名

输入/输出

类型

说明

time_zone

输入

int

时区偏移量；范围：-48~56；单位：15分钟

  • 返回值说明
    当前始终返回 0，无论操作成功还是失败

qosa_rtc_gmtime_r

  • 功能描述
    将Unix时间戳转换为分解时间（struct tm 格式）。

  • 函数原型

qosa_rtc_time_t *qosa_rtc_gmtime_r(const qosa_time_t *timer, qosa_rtc_time_t *result);

  • 参数说明

参数名

输入/输出

类型

说明

timer

输入

const qosa_time_t *

指向Unix时间戳的指针

result

输出

qosa_rtc_time_t*

指向 qosa_rtc_time_t 的指针，用于存储转换后的分解时间；详见 qosa_rtc_time_t

  • 返回值说明
    result 指针：函数执行成功
    NULL：函数执行失败

qosa_rtc_mktime

  • 功能描述
    将分解时间（struct tm 格式）转换为Unix时间戳。

  • 函数原型

int qosa_rtc_mktime(qosa_rtc_time_t *rtc_time, qosa_time_t *timer);

  • 参数说明

参数名

输入/输出

类型

说明

rtc_time

输入

qosa_rtc_time_t*

指向 qosa_rtc_time_t 的指针，表示分解时间；详见 qosa_rtc_time_t

timer

输出

qosa_time_t *

指向 qosa_time_t 的指针，用于存储转换后的时间戳

  • 返回值说明
    当前始终返回 QOSA_OK，无论操作成功还是失败

qosa_rtc_set_alarm

  • 功能描述
    设置RTC闹钟时间。

  • 函数原型

qosa_rtc_error_e qosa_rtc_set_alarm(qosa_rtc_time_t *rtc_time);

  • 参数说明

参数名

输入/输出

类型

说明

rtc_time

输入

qosa_rtc_time_t*

指向 qosa_rtc_time_t 的指针，表示闹钟时间；详见 qosa_rtc_time_t

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_get_alarm

  • 功能描述
    获取RTC闹钟时间。

  • 函数原型

qosa_rtc_error_e qosa_rtc_get_alarm(qosa_rtc_time_t *rtc_time);

  • 参数说明

参数名

输入/输出

类型

说明

rtc_time

输出

qosa_rtc_time_t*

指向 qosa_rtc_time_t 的指针，用于存储获取到的闹钟时间；详见 qosa_rtc_time_t

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_enable_alarm

  • 功能描述
    启用或禁用RTC闹钟。

  • 函数原型

qosa_rtc_error_e qosa_rtc_enable_alarm(qosa_uint8_t on_off);

  • 参数说明

参数名

输入/输出

类型

说明

on_off

输入

qosa_uint8_t

启用或禁用闹钟
1：启用闹钟
0：禁用闹钟

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_register_cb

  • 功能描述
    注册RTC事件回调函数。

  • 函数原型

qosa_rtc_error_e qosa_rtc_register_cb(qosa_rtc_cb_ptr cb);

  • 参数说明

参数名

输入/输出

类型

说明

cb

输入

qosa_rtc_cb_ptr

指向回调函数的指针；详见 qosa_rtc_cb_ptr

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_cb_ptr

  • 功能描述
    接收闹钟到期通知的回调函数原型。

  • 函数原型

typedef void (*qosa_rtc_cb_ptr)(void);

qosa_rtc_set_cfg

  • 功能描述
    设置RTC配置。

  • 函数原型

qosa_rtc_error_e qosa_rtc_set_cfg(qosa_rtc_cfg_t *cfg);

  • 参数说明

参数名

输入/输出

类型

说明

cfg

输入

qosa_rtc_cfg_t*

指向 qosa_rtc_cfg_t 的指针，表示配置信息；详见 qosa_rtc_cfg_t

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_get_cfg

  • 功能描述
    获取RTC配置。

  • 函数原型

qosa_rtc_error_e qosa_rtc_get_cfg(qosa_rtc_cfg_t *cfg);

  • 参数说明

参数名

输入/输出

类型

说明

cfg

输出

qosa_rtc_cfg_t*

指向 qosa_rtc_cfg_t 的指针，用于存储获取到的配置信息；详见 qosa_rtc_cfg_t

  • 返回值说明
    QOSA_RTC_ERR_OK：函数执行成功
    其他值（详见 qosa_rtc_error_e）：函数执行失败

qosa_rtc_print_time

  • 功能描述
    打印RTC时间到指定输出设备。

  • 函数原型

qosa_rtc_error_e qosa_rtc_print_time(qosa_rtc_time_t *rtc_time);

  • 参数说明

参数名

输入/输出

类型

说明

rtc_time

输入

qosa_rtc_time_t*

指向 qosa_rtc_time_t 的指针，表示要打印的RTC时间；详见 qosa_rtc_time_t

  • 返回值说明
    当前始终返回 QOSA_RTC_ERR_OK，无论操作成功还是失败

结构体定义

qosa_time_info_t

通用时间结构体定义如下：

typedef struct
{
    qosa_uint64_t seconds;      
    qosa_uint64_t microseconds; 
} qosa_time_info_t;

参数

类型

说明

seconds

qosa_uint64_t

自1970年1月1日00:00:00 UTC起经过的整秒数

microseconds

qosa_uint64_t

当前这一秒内经过的微秒数

qosa_rtc_time_t

RTC时间结构体定义如下：

typedef struct
{
    int tm_sec;   
    int tm_min;   
    int tm_hour;  
    int tm_mday;  
    int tm_mon;   
    int tm_year;  
    int tm_wday;  
} qosa_rtc_time_t;

参数

类型

说明

tm_sec

int

秒；范围：0~59

tm_min

int

分钟；范围：0~59

tm_hour

int

小时；范围：0~23

tm_mday

int

日；范围：1~31

tm_mon

int

月；范围：0~11；0：1月，11：12月

tm_year

int

年，从1900起算；如2024年对应值为124

tm_wday

int

星期；范围：0~6；0：周日，6：周六

qosa_rtc_cfg_t

RTC配置结构体定义如下：

typedef struct
{
    qosa_rtc_enable_e nv_cfg;  
    qosa_rtc_enable_e rtc_cfg; 
    qosa_rtc_enable_e nwt_cfg; 
    qosa_rtc_tz_e     tz_cfg;  
} qosa_rtc_cfg_t;

参数

类型

说明

nv_cfg

qosa_rtc_enable_e

启动时是否读取NV中保存的时间作为RTC初始值；详见 qosa_rtc_enable_e
QOSA_RTC_CFG_ENABLE：读取
QOSA_RTC_CFG_DISABLE：不读取
默认值：QOSA_RTC_CFG_DISABLE

rtc_cfg

qosa_rtc_enable_e

启动时是否读取RTC寄存器时间作为初始值；若VBAT断电则时间重置为2000-01-01；详见 qosa_rtc_enable_e
QOSA_RTC_CFG_ENABLE：读取
QOSA_RTC_CFG_DISABLE：不读取
默认值：QOSA_RTC_CFG_DISABLE

nwt_cfg

qosa_rtc_enable_e

连接基站后是否将基站时间同步到RTC；详见 qosa_rtc_enable_e
QOSA_RTC_CFG_ENABLE：同步
QOSA_RTC_CFG_DISABLE：不同步
默认值：QOSA_RTC_CFG_DISABLE

tz_cfg

qosa_rtc_tz_e

网络注册后的时区配置；详见 qosa_rtc_tz_e
默认值：QOSA_RTC_CFG_TZ_UPDATE

枚举定义

qosa_rtc_enable_e

RTC启用配置枚举定义如下：

typedef enum
{
    QOSA_RTC_CFG_DISABLE = 0,
    QOSA_RTC_CFG_ENABLE  = 1,
} qosa_rtc_enable_e;

成员

说明

QOSA_RTC_CFG_DISABLE

禁用

QOSA_RTC_CFG_ENABLE

启用

qosa_rtc_tz_e

RTC时区配置（网络注册后）枚举定义如下：

typedef enum
{
    QOSA_RTC_CFG_TZ_UPDATE       = 0,    
    QOSA_RTC_CFG_TZ_NO_UPDATE    = 1,    
    QOSA_RTC_CFG_TZ_RESET_ZERO   = 2,    
} qosa_rtc_tz_e;

成员

说明

QOSA_RTC_CFG_TZ_UPDATE

网络注册后更新为网络时区

QOSA_RTC_CFG_TZ_NO_UPDATE

网络注册后保持原时区不变

QOSA_RTC_CFG_TZ_RESET_ZERO

网络注册后将时区重置为0

qosa_rtc_error_e

RTC结果码枚举定义如下：

#define QOSA_COMPONENT_API_RTC   (0x01 << 8)

typedef enum
{
    QOSA_RTC_ERR_OK = 0,
    QOSA_RTC_ERR_INVALID_PARAM   = 1 | QOSA_COMPONENT_API_RTC,   
    QOSA_RTC_ERR_SET_PARAM,                                      
    QOSA_RTC_ERR_GET_PARAM,                                      

} qosa_rtc_error_e;

成员

说明

QOSA_RTC_ERR_OK

函数执行成功

QOSA_RTC_ERR_INVALID_PARAM

无效参数

QOSA_RTC_ERR_SET_PARAM

配置错误

QOSA_RTC_ERR_GET_PARAM

读取错误

应用逻辑流程图

image

示例代码

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/peripheral/rtc/rtc_demo.c