155.8.2Keil代码RTC

/* rtc.h：供 main.c 访问同一个 RTC 句柄和初始化函数 */
#ifndef __RTC_H
#define __RTC_H
#include "main.h"

extern RTC_HandleTypeDef hrtc;
void Init_RTC(void);
#endif

/* rtc.c：配套 Keil 工程的实际初始化代码 */
RTC_HandleTypeDef hrtc;

void Init_RTC(void)
{
    RTC_TimeTypeDef sTime = {0};
    RTC_DateTypeDef DateToUpdate = {0};

    hrtc.Instance = RTC;
    hrtc.Init.AsynchPrediv = RTC_AUTO_1_SECOND;
    hrtc.Init.OutPut = RTC_OUTPUTSOURCE_ALARM;
    if (HAL_RTC_Init(&hrtc) != HAL_OK) {
        Error_Handler();
    }

    /* 配套工程已将首次设定时间、日期的代码注释掉。
       取消注释后使用的值为 12:00:00、2023-10-31、星期二，且采用 BCD 格式。 */
    /* HAL_RTC_SetTime(&hrtc, &sTime, RTC_FORMAT_BCD); */
    /* HAL_RTC_SetDate(&hrtc, &DateToUpdate, RTC_FORMAT_BCD); */
}

void HAL_RTC_MspInit(RTC_HandleTypeDef *rtcHandle)
{
    if (rtcHandle->Instance == RTC) {
        HAL_PWR_EnableBkUpAccess();
        __HAL_RCC_BKP_CLK_ENABLE();
        __HAL_RCC_RTC_ENABLE();
    }
}

/* main.c 中的实际显示循环；RTC_FORMAT_BIN 表示读出的字段是二进制数。 */
HAL_RTC_GetDate(&hrtc, &RTC_Date, RTC_FORMAT_BIN);
sprintf(RTC_Buff, "Date:20%2d-%2d-%2d",
        RTC_Date.Year, RTC_Date.Month, RTC_Date.Date);
OLED_ShowString(0, 2, RTC_Buff, 16);

switch (RTC_Date.WeekDay) {
case 0: OLED_ShowString(0, 4, "Sunday",    16); break;
case 1: OLED_ShowString(0, 4, "Monday",    16); break;
case 2: OLED_ShowString(0, 4, "Tuesday",   16); break;
case 3: OLED_ShowString(0, 4, "Wednesday", 16); break;
case 4: OLED_ShowString(0, 4, "Thursday",  16); break;
case 5: OLED_ShowString(0, 4, "Friday",    16); break;
case 6: OLED_ShowString(0, 4, "Saturday",  16); break;
default: break;
}

HAL_RTC_GetTime(&hrtc, &RTC_Time, RTC_FORMAT_BIN);
sprintf(RTC_Buff, "Time:%2d:%2d:%2d",
        RTC_Time.Hours, RTC_Time.Minutes, RTC_Time.Seconds);
OLED_ShowString(0, 6, RTC_Buff, 16);
HAL_Delay(1000);

一、实时时钟

本节把上一节由 CubeIDE 生成的 RTC 配置移植到已有 OLED/I2C 驱动的 Keil 工程。实际数据路径是：RTC 计数器和 HAL 的日期状态 -> RTC_Time、RTC_Date 结构体 -> sprintf 格式化到 RTC_Buff -> OLED_ShowString 将字符字模经 I2C1 发给 OLED。显示正常只能说明这条链路工作；是否能在掉电后保持完整的日期时间，还取决于 LSE、VBAT 及软件保存策略。

1.1 打开工程

• 使用配套的 KEIL/9RTC/MDK-ARM/temp.uvprojx，其基础工程已含 GPIO、UART、软件 I2C 和 OLED 驱动。
• 在 Keil 的工程树中把 Core/Src/rtc.c 加入编译组，并确保 Core/Inc 位于 Include Paths；仅把文件放进磁盘目录而未加入工程，链接阶段仍不会生成 Init_RTC 和 hrtc。
• 本工程目标器件为 STM32F103ZE。RTC 时钟源的引脚和备用供电应以实际开发板原理图为准，不能仅凭型号假定已焊接 LSE 晶体或电池。

1.2 添加所需头文件

• rtc.h 用头文件保护符避免同一编译单元重复展开；它声明 extern RTC_HandleTypeDef hrtc;，并声明 Init_RTC(void)。
• main.c 需要包含 rtc.h，rtc.c 也需要包含它。extern 只是声明对象定义在别处，真正的定义只能保留一份：rtc.c 中的 RTC_HandleTypeDef hrtc;。
• 配套 main.c 仍包含 tim.h，但 Init_TIM2() 已注释。若后续不再使用定时器输入捕获及其回调，可在确认没有其他引用后再清理，不能为了消除表面“未使用”直接删掉仍被中断文件调用的代码。

1.3 复制RTC代码

• 迁移的最小单元是 rtc.c、rtc.h、main.c 中的初始化调用、系统时钟中 LSE/RTC 的选择，以及 HAL RTC 驱动源文件；只复制 Init_RTC() 不能使 RTC 获得时钟。
• HAL_RTC_MspInit() 允许访问备份域、打开 BKP 时钟和 RTC 外设时钟。LSE 的启动及 RTC 时钟源选择则在 SystemClock_Config() 中完成，两处职责不同。
• RTC_AUTO_1_SECOND 是该 F1 HAL 对预分频的自动配置选项。使用 32.768 kHz LSE 时，预分频得到 1 Hz，RTC 的硬件计数器每秒递增一次。

1.4 添加主函数

• 本工程的初始化顺序为 HAL_Init()、SystemClock_Config()、GPIO/UART/I2C、Init_RTC()、OLED。必须先完成系统和外设时钟配置，再初始化依赖这些时钟的模块。
• 循环中先读日期再读时间，是 F1 HAL 为维护软件日期所采用的典型读取顺序。两个调用都使用 RTC_FORMAT_BIN，因此 Month、Hours 等字段可直接用 %d 输出；若指定 RTC_FORMAT_BCD，字段是压缩 BCD，不能当作普通十进制整数打印。

1.5 打开RTC所在工程

• 应以 KEIL/9RTC/Core/Src/rtc.c、main.c 和工程文件中的源文件列表为准，而不是以转写中的临时编辑画面为准。
• 系统时钟函数实际启用了 HSE 和 LSE，并通过 HAL_RCCEx_PeriphCLKConfig() 把 RTC 时钟源选为 RCC_RTCCLKSOURCE_LSE。若 LSE 不起振，HAL_RCC_OscConfig() 会失败并进入 Error_Handler()。

1.6 复制RTC所在工程代码

• rtc.h 中函数原型末尾的分号不可缺少：void Init_RTC(void);。这是声明，不是函数实现。
• 本工程同时编译了 stm32f1xx_hal_rtc.c 与 stm32f1xx_hal_rtc_ex.c。前者提供 HAL_RTC_Init、读写日期时间等实现；仅包含头文件只会让编译器认识函数声明，不能解决链接时的未定义符号。
• 移植 CubeMX 生成的 SystemClock_Config() 时必须连同相关宏、HAL RCC 驱动和实际硬件条件一起核对。把函数文本粘入另一个工程并不自动保证晶振频率、电源和管脚连接正确。

1.7 编译错误处理

1.7.1 编译错误示例分析

• “某变量未定义”不一定表示该变量从未书写；它也可能是前一个声明少了分号、头文件未被找到，或变量只在另一个 .c 文件中定义却没有 extern 声明。
• 应先看报错文件、行号和第一条错误。后续大量错误常是第一处语法错误导致编译器无法继续正确解析的连锁结果。

1.7.2 编译错误原因查找

• 预处理器会把 #include "rtc.h" 的内容展开到 main.c。因此 rtc.h 缺分号时，诊断可能显示在 main.c 的包含位置，但根因在头文件。
• 分清三类问题：找不到头文件是 Include Paths 或文件名问题；编译期未声明是头文件内容或可见性问题；链接期未定义通常是 .c 未加入工程或符号名不一致。

1.7.3 编译错误修正过程

• 先补正 rtc.h 中的语法，再确认 Core/Src/rtc.c 已被工程编译，最后确认 HAL 源文件列表含 RTC 驱动。每完成一步都保存并重新编译，以免多个改动叠加后无法定位原因。
• rtc_ex 不是因为“预先包含就能避免报错”而必须加入；是否需要它应由调用的 API 和链接结果决定。此配套工程已经将其列入 HAL 驱动组，可以保留原工程配置。

1.8 查看问题并解决

• 将故障范围缩小为时钟、RTC 读取、字符串格式化、I2C/OLED 显示四段。可先用 UART 输出 RTC_Buff 验证读数，再检查 OLED，而不是一开始同时修改所有模块。
• 调试时不要长期用大段注释替代理解。临时注释应有明确目的，例如确认问题是否出在 HAL_RTC_GetTime() 之前；验证后恢复或形成最终、可编译的代码。

1.9 将之前的主函数代码粘过来

• 配套代码保留 Init_UART1()，且两处 HAL_UART_Transmit() 已注释。恢复其中一处可把同一份 RTC_Buff 输出到串口，便于与 OLED 显示比较。
• 向串口插入临时标识字符可以帮助区分版本，但最终代码应移除无意义标记，并检查缓冲区长度和字符串结束符。

1.10 覆盖之前用到的变量定义

• RTC_Time 和 RTC_Date 是两个全局结构体，分别承接 HAL_RTC_GetTime() 与 HAL_RTC_GetDate() 的结果；RTC_Buff[200] 承接格式化文本。
• 同一作用域中不能重复定义同名变量。删除变量前应先用工程范围搜索确认它没有被回调、其他源文件或调试代码引用。
• 此处的全局变量规模很小，便于初学调试；项目扩大后可将显示状态封装为结构体，减少跨模块直接访问。

1.11 查看效果

• 日期显示调用为 OLED_ShowString(0, 2, RTC_Buff, 16)，时间为 OLED_ShowString(0, 6, RTC_Buff, 16)；0 是横向起点，第二个参数是 OLED 驱动使用的页行起点，不是“第 0 或第 6 个像素”。
• 显示异常时，先确认 OLED 已初始化、I2C 总线正常，再查看 RTC_Buff 的实际内容。不能仅凭屏幕空白就断定 RTC 初始化失败。

1.12 日期时间同时显示

• 工程在同一循环内读日期、显示日期、显示星期、读时间、显示时间，然后延时 1 秒，因而视觉上同时显示。它不是中断刷新，刷新周期还会受 I2C 发送和格式化耗时的轻微影响。
• 日期文本中的 20%2d 是配套代码针对两位年份字段的写法；当 Year 为 23 时输出 2023。它只适用于 2000--2099 的显示约定，不是通用四位年份算法。
• 若需要显示中文“星期一”，应确保字库中有相应字模；本工程最终选择英文星期，避免额外字模处理。

1.13 周一到周日的英文

Monday、Tuesday、Wednesday、Thursday、Friday、Saturday、Sunday 是正确的英文拼写。特别注意 Wednesday 中的 d，以及 Thursday 中的 h；代码中的字符串大小写会原样显示。

1.14 日期时间同时显示并注释

1.14.1 代码结构与初始化

• RTC_TimeTypeDef 保存时、分、秒，RTC_DateTypeDef 保存年、月、日、星期。它们是读取结果的容器，不会自行让硬件走时。
• 当前 Init_RTC() 只初始化 RTC；设定默认时间和日期的两段 HAL_RTC_SetTime()、HAL_RTC_SetDate() 已被注释。这一选择用于避免每次软件复位都重写计数器。

1.14.2 代码中星期的显示逻辑

• switch (RTC_Date.WeekDay) 将 HAL 返回的枚举值映射为英文字符串，并在每个 case 后使用 break 防止继续执行下一个分支。
• STM32F1 HAL 的定义是 RTC_WEEKDAY_SUNDAY = 0、RTC_WEEKDAY_MONDAY = 1，依次到 RTC_WEEKDAY_SATURDAY = 6。配套 switch 的 0--6 映射与该驱动一致。

1.14.3 代码修正与完善

• default 当前不显示任何内容；若 WeekDay 非法，旧星期字符串会留在屏幕上。可在调试时显示固定错误提示，或在刷新前清除该显示区域。
• 星期名长度不同：Wednesday 为 9 个字符，而 Sunday 为 6 个字符。由长字符串切换到短字符串时，OLED_ShowString() 若不擦除尾部，右侧可能残留旧字符。应先清除该行或输出固定宽度的填充字符串。

1.14.4 例题1: 一周七天的命名及文化底蕴

本节源码实际练习的是英文星期字符串与枚举映射，并未实现文化背景相关功能。不同软件可把周日或周一视为一周开始日，但嵌入式程序不能据此猜测枚举值，必须查当前 HAL 头文件；在这个 F1 工程中周日明确为 0。

1.14.5 代码中日期与星期的显示调整

• 显示星期前先调用 HAL_RTC_GetDate()，因为 WeekDay 属于 RTC_DateTypeDef，不在 RTC_TimeTypeDef 内。
• 不应把“周日通常是 0 或 7”的泛化约定直接写入程序。具体值由库定义决定；本工程的 0--6 映射已与 stm32f1xx_hal_rtc.h 对齐。

1.14.6 代码中switch语句的完善

• case 匹配一个确定值，break 结束当前分支，default 处理未覆盖值。漏掉 break 会发生贯穿，导致同一次循环连续写入多个星期字符串。
• 若改用字符串数组，可用枚举值作下标，但必须先范围检查，避免非法值越界；对于初学阶段，当前显式 switch 更直观。

1.14.7 显示行数的解释与现象观察

• SSD1306 类 128x64 OLED 以 8 像素为一页。16 像素字高要占两页，因此起点 y=0、2、4、6 正好形成四个不重叠的逻辑行：标题、日期、星期、时间。
• 这也是时间放在 y=6 的原因：它占用最后两页 6 和 7。若传入奇数起点或超过 6 的 16 像素文本，字模可能与相邻行重叠或越界。

1.14.8 最终代码调整与显示效果

• 最终工程使用 RTC_Time、RTC_Date 和 RTC_Buff；转写中出现的 time、delta 等说法不是该工程的最终变量名，不应据此修改源码。
• 预期页面从上到下为固定中文标题、日期、英文星期和时间。出现不完整字符时，优先检查星期行的长短字符串残留与 I2C 通信，而非盲目重设 RTC。

1.15 断电后时间归零问题处理

• 注释掉 HAL_RTC_SetTime() 和 HAL_RTC_SetDate() 可以避免每次启动把硬件计数器重设为演示值，但这不是完整的“断电日期保持”方案。
• F1 的 RTC 硬件核心是秒计数器、预分频和闹钟；日期由 HAL 在 RTC_HandleTypeDef.DateToUpdate 中以软件方式维护。该状态在普通 RAM，复位、停止或备用状态后会丢失。当前工程没有写入任何 BKP 数据寄存器，因此它不能独立恢复完整日期和星期。
• 若 VDD 断电而 VBAT 仍有效、LSE 持续振荡，RTC 计数器可以继续走时；若 VBAT 也失电或 LSE 没有工作，计数器也会停止。STM32F103 的 VBAT 供电范围及 LSE/备份域连接均需按数据手册和开发板原理图核对。
• 实际产品应在备份寄存器设置首次初始化标志，并保存足以恢复日期的状态；有标志时不重复设时，无标志时才让用户设定初值。还应设计掉电后跨多日的日期推进策略，不能仅依赖本工程循环中的显示调用。

1.16 系统时钟配置分析

• 配套 SystemClock_Config() 同时设置 RCC_OSCILLATORTYPE_HSE | RCC_OSCILLATORTYPE_LSE，使 HSE 经 PLL 供主系统使用，LSE 作为 RTC 的低速时钟源；两种振荡器用途不同。
• PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_RTC 与 PeriphClkInit.RTCClockSelection = RCC_RTCCLKSOURCE_LSE 才完成 RTC 源选择。仅在 HAL_RTC_MspInit() 中打开 RTC 时钟，并没有选择 LSE。
• LSE 通常为 32.768 kHz，适合整除为 1 Hz。HSE/128、LSI 也可作 F1 RTC 源，但精度、功耗和后备供电行为不同，切换前必须重新评估预分频和硬件条件。

1.17 屏幕显示情况

• 正常时应每秒更新一次末行秒数；日期、星期只在跨日时变化。重置后若时间仍在走而日期变为默认值，正是本工程未持久化 HAL 软件日期的表现之一。
• 下载调试器、按复位键和真正切断 VDD 是不同操作。验证后备功能时，要分别测试软件复位、VDD 短时掉电且 VBAT 保持、VBAT 也断电三种场景，并记录结果。

1.18 百分号问题处理

• sprintf 中 %2d 的含义是“最小字段宽度为 2”，数值不足两位时在左侧补空格，例如 5 输出为 5；它不是“数字占两个字节”。数值超过两位时字段会自动变宽。
• 若希望时钟显示为 05:07:09，格式应为 %02d:%02d:%02d。0 是补零标志，2 是最小宽度。日期同理可用 %02d，并应评估缓冲区大小。
• sprintf 不检查目标容量；本例文本短于 RTC_Buff[200]，暂不会溢出，但更通用的代码应使用 snprintf(RTC_Buff, sizeof RTC_Buff, ...) 并处理截断结果。

1.19 定义结构体

• RTC_TimeTypeDef 与 RTC_DateTypeDef 已是 HAL 定义的结构体，分别保存读取出的时间和日期字段；无需再为同一用途重复设计结构体。
• 若增加按键设时状态，可定义独立的应用层结构体保存“当前编辑字段、待提交日期时间、按键事件”等，而不要直接把未校验的按键值写进 RTC。

1.20 通过按键调节时间功能

• 配套 9RTC 工程没有按键 GPIO 初始化、扫描、消抖或 HAL_RTC_SetTime()/HAL_RTC_SetDate() 的实际调用；转写中的“四个按键”“按七次保存”是后续设计思路，不是本工程已实现的功能。
• 一个可靠的实现至少需要：将按键抖动转换为单次事件；选择年、月、日、时、分、秒字段；限制每个字段的有效范围并处理闰年；只在用户确认时一次性写入时间和日期；必要时同步更新备份域中的初始化标志和日期状态。
• 设定过程中应在内存副本中修改并预览，取消时不触及 RTC。这样可避免用户调整到一半时写入无效日期，也减少频繁改写备份域。