跳至主要內容

Rtc模块用户手册

大约 10 分钟约 2983 字2025/12/26

Rtc模块用户手册

目录

1. 简介

本模块提供了对 RTC (Real-Time Clock) 的抽象接口，用于实现精确的时间日期跟踪、闹钟功能和周期性节拍中断。

主要功能包括：

  • 初始化与反初始化: 通过 HLI_Rtc_Init 和 HLI_Rtc_DeInit 对RTC模块进行配置和资源释放。
  • 时间日期设置与获取: 支持在运行时通过 HLI_Rtc_SetTime、HLI_Rtc_SetDate、HLI_Rtc_GetTime 和 HLI_Rtc_GetDate 动态管理当前时间和日期。
  • 闹钟功能: 可配置两个独立的闹钟（A和B），支持按天或按周重复，并在到达设定时间时触发中断回调。
  • 节拍中断: 可配置周期性的节拍中断，用于需要固定时间间隔触发的系统任务。
  • 使能/禁止: 提供 HLI_Rtc_Enable 和 HLI_Rtc_Disable 函数来控制RTC模块的运行。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
MCU微控制器
RTC实时时钟
ISR中断服务例程

2. 文件结构

文件名称描述
kf32axxx_hli_rtc.c此文件包含RTC驱动程序的通用功能
kf32axxx_hli_rtc.h此头文件输出RTC驱动程序的宏、类型定义和函数原型
kf32axxx_hli_rtc_cfg.h此文件包含RTC模块相关配置及宏定义
kf32axxx_hli_rtc_Lcfg.c此文件包含RTC配置变量
kf32axxx_hli_rtc_Lcfg.h此文件包含RTC配置变量声明
__irq_rtc.c此文件包含RTC模块中断服务函数

3. 数据结构

3.1 数据类型

3.1.1 宏定义

无。

3.1.2 枚举

  1. RTC时钟源 (HLI_Rtc_ClockType)

    枚举值解释
    HLI_RTC_EXTLF使用外部低频作为RTC时钟源
    HLI_RTC_INTLF使用内部低频作为RTC时钟源

  2. 闹钟序号 (HLI_Rtc_IndexType)

    枚举值解释
    HLI_RTC_ALARM_A使用闹钟A
    HLI_RTC_ALARM_B使用闹钟B

  3. 节拍时间 (HLI_Rtc_TickTimeType)

    枚举值解释
    HLI_RTC_TICK_TIME_1S时间节拍为1s
    HLI_RTC_TICK_TIME_1S_DIV_2时间节拍为 1/2 秒
    HLI_RTC_TICK_TIME_1S_DIV_4时间节拍为 1/4 秒
    HLI_RTC_TICK_TIME_1S_DIV_8时间节拍为 1/8 秒
    HLI_RTC_TICK_TIME_1S_DIV_16时间节拍为 1/16 秒
    HLI_RTC_TICK_TIME_1S_DIV_32时间节拍为 1/32 秒
    HLI_RTC_TICK_TIME_1S_DIV_64时间节拍为 1/64 秒
    HLI_RTC_TICK_TIME_1S_DIV_128时间节拍为 1/128 秒

  4. 闹钟重复模式 (HLI_Rtc_AlarmRepeatType)

    枚举值解释
    HLI_RTC_ALARM_REPEAT_DAY闹钟每天重复
    HLI_RTC_ALARM_REPEAT_WEEK闹钟每周重复

  5. RTC函数执行结果 (HLI_Rtc_StatusType)

    枚举值解释
    HLI_RTC_STATUS_OK函数执行成功
    HLI_RTC_STATUS_ERROR通用错误
    HLI_RTC_STATUS_INVALID_PARAM无效参数错误
    HLI_RTC_STATUS_INVALID_TIME无效时间错误
    HLI_RTC_STATUS_MODULE_ERR模块状态错误
    HLI_RTC_STATUS_CLOCK_ERR时钟源错误
    HLI_RTC_STATUS_ALREADY_INITIALIZEDRTC模块已经初始化

3.1.3 类型定义

  1. RTC日期结构体 (HLI_Rtc_DateType)

    成员解释
    YearBCD码, 取值范围为 0x0 ~ 0x99。
    MonthBCD码, 取值范围为 0x01 ~ 0x12。
    DayBCD码, 取值范围为 0x1 ~ 0x31。

  2. RTC时间结构体 (HLI_Rtc_TimeType)

    成员解释
    WeekBCD码, 取值范围为 0x0 ~ 0x6。星期天为 0x0。
    HourBCD码, 取值范围为 0x0 ~ 0x23。
    MinuteBCD码, 取值范围为 0x0 ~ 0x59。
    SecondBCD码, 取值范围为 0x0 ~ 0x59。

3.2 配置项说明

  1. RTC初始化配置 (HLI_Rtc_ConfigType)

    成员解释取值范围
    ClockRTC时钟源HLI_RTC_EXTLF 或 HLI_RTC_INTLF
    DateConfig指向RTC日期配置的指针指向 HLI_Rtc_DateType 类型的变量
    TimeConfig指向RTC时间配置的指针指向 HLI_Rtc_TimeType 类型的变量

  2. RTC闹钟配置 (HLI_Rtc_AlarmConfigType)

    成员解释取值范围
    AlarmIndex闹钟序号HLI_RTC_ALARM_A 或 HLI_RTC_ALARM_B
    AlarmTime指向闹钟时间的指针指向 HLI_Rtc_TimeType 类型的变量
    RepeatType闹钟重复模式HLI_RTC_ALARM_REPEAT_DAY 或 HLI_RTC_ALARM_REPEAT_WEEK
    AlarmCallback闹钟中断回调函数HLI_RTC_InterruptHandler 类型的函数指针

  3. RTC节拍配置 (HLI_Rtc_TickTimeConfigType)

    成员解释取值范围
    TickTimeType节拍时间类型参考 HLI_Rtc_TickTimeType 枚举
    TickTimeCallback节拍中断回调函数HLI_RTC_InterruptHandler 类型的函数指针

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Rtc_Init

NameDescription
函数名称HLI_Rtc_Init
语法:HLI_Rtc_StatusType HLI_Rtc_Init(HLI_Rtc_ConfigType *RtcConfig)
同步/异步:同步
重入性 :不可重入
形参(输入):RtcConfig: RTC配置结构体指针
返回值:HLI_RTC_STATUS_OK: 初始化成功
返回值:HLI_RTC_STATUS_INVALID_TIME: 传参为空指针，设置默认时间
返回值:HLI_RTC_STATUS_ALREADY_INITIALIZED: RTC模块已经初始化过
返回值:HLI_RTC_STATUS_CLOCK_ERR: RTC时钟源使能失败
描述:初始化RTC模块，设置RTC日期、时间。
注意事项:使用外部低频时钟时，内部会进行外部低频的初始化，其中会等待大约4s时间。建议在系统正常运行前进行RTC初始化，避免过长时间的阻塞影响程序逻辑。

4.1.2 HLI_Rtc_Enable

NameDescription
函数名称HLI_Rtc_Enable
语法:HLI_Rtc_StatusType HLI_Rtc_Enable(void)
同步/异步:同步
重入性 :不可重入
形参(输入):无
返回值:HLI_RTC_STATUS_OK: RTC使能成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC未处于就绪状态
描述:使能RTC。
注意事项:无

4.1.3 HLI_Rtc_Disable

NameDescription
函数名称HLI_Rtc_Disable
语法:void HLI_Rtc_Disable(void)
同步/异步:同步
重入性 :可重入
形参(输入):无
返回值:无
描述:失能RTC。
注意事项:无

4.1.4 HLI_Rtc_SetTime

NameDescription
函数名称HLI_Rtc_SetTime
语法:HLI_Rtc_StatusType HLI_Rtc_SetTime(HLI_Rtc_TimeType *TimeConfig)
同步/异步:同步
重入性 :不可重入
形参(输入):TimeConfig: RTC时间配置指针
返回值:HLI_RTC_STATUS_OK: 设置时间成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC未处于就绪状态
返回值:HLI_RTC_STATUS_INVALID_PARAM: 入参无效
描述:设置RTC时间。
注意事项:无

4.1.5 HLI_Rtc_SetDate

NameDescription
函数名称HLI_Rtc_SetDate
语法:HLI_Rtc_StatusType HLI_Rtc_SetDate(HLI_Rtc_DateType *DateConfig)
同步/异步:同步
重入性 :不可重入
形参(输入):DateConfig: RTC日期配置指针
返回值:HLI_RTC_STATUS_OK: 设置日期成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC未处于就绪状态
返回值:HLI_RTC_STATUS_INVALID_PARAM: 入参无效
描述:设置RTC日期。
注意事项:无

4.1.6 HLI_Rtc_GetTime

NameDescription
函数名称HLI_Rtc_GetTime
语法:void HLI_Rtc_GetTime(HLI_Rtc_TimeType *Time)
同步/异步:同步
重入性 :可重入
形参(输出):Time: RTC时间指针
返回值:无
描述:获取RTC时间。
注意事项:无

4.1.7 HLI_Rtc_GetDate

NameDescription
函数名称HLI_Rtc_GetDate
语法:void HLI_Rtc_GetDate(HLI_Rtc_DateType *Date)
同步/异步:同步
重入性 :可重入
形参(输出):Date: RTC日期指针
返回值:无
描述:获取RTC日期。
注意事项:无

4.1.8 HLI_Rtc_SetAlarm

NameDescription
函数名称HLI_Rtc_SetAlarm
语法:HLI_Rtc_StatusType HLI_Rtc_SetAlarm(HLI_Rtc_AlarmConfigType *AlarmConfig)
同步/异步:同步
重入性 :可重入
形参(输入):AlarmConfig: 闹钟时间配置指针
返回值:HLI_RTC_STATUS_OK: 设置闹钟成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC未处于就绪状态
返回值:HLI_RTC_STATUS_INVALID_PARAM: 入参无效
描述:设置RTC闹钟。
注意事项:无

4.1.9 HLI_Rtc_GetAlarm

NameDescription
函数名称HLI_Rtc_GetAlarm
语法:void HLI_Rtc_GetAlarm(HLI_Rtc_IndexType AlarmIndex, HLI_Rtc_TimeType *AlarmTime)
同步/异步:同步
重入性 :可重入
形参(输入):AlarmIndex: 闹钟序号
形参(输出):AlarmTime: 闹钟时间配置指针
返回值:无
描述:获取上一次配置的RTC闹钟时间。
注意事项:无

4.1.10 HLI_Rtc_AlarmEnable

NameDescription
函数名称HLI_Rtc_AlarmEnable
语法:HLI_Rtc_StatusType HLI_Rtc_AlarmEnable(HLI_Rtc_IndexType AlarmIndex)
同步/异步:同步
重入性 :不可重入
形参(输入):AlarmIndex: 闹钟序号
返回值:HLI_RTC_STATUS_OK: 使能闹钟成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC未处于就绪状态
描述:使能RTC闹钟及中断。
注意事项:无

4.1.11 HLI_Rtc_AlarmDisable

NameDescription
函数名称HLI_Rtc_AlarmDisable
语法:void HLI_Rtc_AlarmDisable(HLI_Rtc_IndexType AlarmIndex)
同步/异步:同步
重入性 :可重入
形参(输入):AlarmIndex: 闹钟序号
返回值:无
描述:失能RTC闹钟及中断。
注意事项:无

4.1.12 HLI_Rtc_TickTimeEnable

NameDescription
函数名称HLI_Rtc_TickTimeEnable
语法:HLI_Rtc_StatusType HLI_Rtc_TickTimeEnable(HLI_Rtc_TickTimeConfigType *TickTimeConfig)
同步/异步:同步
重入性 :不可重入
形参(输入):TickTimeConfig: 节拍时钟配置项
返回值:HLI_RTC_STATUS_OK: 使能节拍成功
返回值:HLI_RTC_STATUS_MODULE_ERR: RTC模块状态错误
描述:使能节拍及节拍中断。
注意事项:无

4.1.13 HLI_Rtc_TickTimeDisable

NameDescription
函数名称HLI_Rtc_TickTimeDisable
语法:void HLI_Rtc_TickTimeDisable(void)
同步/异步:同步
重入性 :可重入
形参(输入):无
返回值:无
描述:失能节拍及节拍中断。
注意事项:无

4.2 中断回调

4.2.1 HLI_RTC_InterruptHandler

NameDescription
回调类型HLI_RTC_InterruptHandler
语法typedef void (*HLI_RTC_InterruptHandler)(void);
形参(输入)无
返回值无
描述RTC闹钟或节拍中断的回调函数。
注意事项建议不在回调函数内进行耗时操作，仅操作数据。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

5.1 设置日期和时间

此示例展示了如何初始化RTC并设置/获取日期和时间。

5.2 设置闹钟

此示例展示了如何设置一个闹钟，并在指定时间触发中断。

5.3 设置节拍中断

此示例展示了如何设置一个周期性的节拍中断。

6. 限制与假设

  1. 时钟源: 仅支持使用内部低频时钟（INTLF）和外部32768Hz低频晶振（EXTLF）作为RTC的时钟源。
  2. 运行时错误:
    • 当模块未初始化时，调用 HLI_Rtc_Enable、HLI_Rtc_SetAlarm、HLI_Rtc_SetTime 等函数会返回错误。
    • 当初始化RTC模块时，若选择外部低频时钟但外部低频时钟使能失败，HLI_Rtc_Init 会返回错误。
  3. 中断配置: 使用闹钟或节拍中断功能时，必须在 kf32axxx_hli_irq_cfg.h 文件中使能 EINT19TO17_UNIFIED_INTERRUPT。

7. 变更记录

版本时间变更记录
v1.02025-11-24新增初版文档
最近更新
贡献者: 翟宇