简介：一份完整的STM32网络授时时钟工程代码，以STM32F103C8T6为主控、ESP-12F为WiFi模块，配合PCF8563时钟芯片、按键和OLED显示屏，实现联网获取天气与时间信息并定时刷新。工程按功能拆分为多个可读性较强的模块：bsp_esp8266.c负责WiFi初始化与天气API调用，test.c完成配网流程与返回数据解析，bsp_pcf8563.c读写时钟，oled.c驱动显示，bsp_SysTick.c为I2C等时序敏感接口提供精准延时，bsp_TiMbase.c则用定时器控制每5分钟刷新一次数据；bsp_usart1.c还提供串口调试打印，便于观察运行状态。压缩包共101个文件、约217KB，以C源码与头文件为主，另含Keil工程配置、启动文件、Hex固件等，可直接编译烧录验证，目录层级清晰，便于对照学习驱动分层与应用逻辑。已有1329人学习下载，适合STM32开发者、物联网入门者作为WiFi应用、外设驱动和定时刷新策略的实战参考。 机缘巧合，我在整理旧硬盘时翻出一个压箱底的小项目——一个基于 WiFi 的网络授时时钟设计包，版本号标着 V1.0。当年玩这个东西纯粹是为了解决一个痛点：桌面上那块电子钟总是越走越偏，隔两周就得手动校准一次，而我偏偏是个懒得动手的人。后来干脆花了一个周末，用一款带 WiFi 的 MCU 做了一个能自动对时的时钟，从此再也没管过它。今天这篇博文，就把这个项目的设计思路、核心代码、踩坑过程完整拆开讲一讲，给想入门嵌入式网络应用、或者想给桌面添一件实用小玩意的朋友做个参考。
这款基于 WiFi 的授时时钟，本质上是让 MCU 通过路由器接入互联网，再结合网络时间协议（NTP）从公共时间服务器获取标准时间，以此校准本地时间显示。和传统 RTC 时钟相比，它的核心优势是“免手动、自动准”，只要网络正常，它就能一直保持秒级同步。适合嵌入式学习者研究网络协议栈、单片机爱好者做桌面小作品，也适合想改造家居信息屏的玩家。下面直接进入正题，聊聊这个 V1.0 版本是怎么一步步搭起来的。
1. 整体设计与方案选型
1.1 为什么选择“WiFi MCU + NTP”而不是纯 RTC 方案
做时钟，最简单粗暴的办法是买一颗 DS1302 或 DS3231 实时时钟芯片，配个 32.768kHz 晶振，让单片机自己走时。这个方案功耗低、电路简单，但有一个绕不开的问题：晶振频率受温度影响会漂移，普通晶振的误差能做到每天 ±1 秒就算不错，一个月下来就能积累出几十秒的偏差，依然需要人工干预。而 WiFi 授时方案的本质是“外部基准 + 本地走时”，本地晶振再不准，每天校时一次就能把误差拉回毫秒级，长期运行的稳定性完全取决于网络状态，而不是硬件精度。
V1.0 我采用的硬件组合是 ESP8266 + SSD1306 OLED 屏，外加一颗 DS3231 做掉电走时保存。ESP8266 自带完整 TCP/IP 协议栈，直接支持连接家里的无线路由器，用它做主力 MCU 可以省去外置 WiFi 模块的麻烦；DS3231 则是工业级的温度补偿 RTC，年误差通常在 ±2 分钟以内，负责在断电或断网时维持时间基准。显示部分选 OLED 是因为它的 I2C 接口只有两根线，焊接简单，而且 0.96 寸小屏显示日期、时间、星期刚好够用。
1.2 软件分层的四个模块
整个固件按照“连接、校时、计时、显示”四层来组织，这四块职责清晰，后面调试时能少掉很多头发。
- 连接层：负责 ESP8266 以 STA 模式连接路由器热点，获取 IP 地址。如果连接失败，会自动进入 AP 配网模式，用户可以用手机连接 ESP8266 发出的热点，在网页里输入 WiFi 账号密码并保存到 Flash。
- 校时层：基于 SNTP（简化版 NTP）协议，向时间服务器发起 UDP 请求，从返回报文中解析出标准 UTC 时间戳，再换算成本地北京时间。
- 计时层：以 DS3231 为本地时间载体，校时成功后把解析到的时间写进 RTC，之后系统按 1Hz 中断读取 RTC 刷新显示。
- 显示层：负责 OLED 的驱动和界面渲染，包括日期、星期、时分秒的刷新，以及网络状态指示图标。
这个分层思路是从做产品时的“高内聚、低耦合”原则搬过来的，每个模块只需要暴露几个简单接口。比如显示层只管一个display_update()函数，底层显示逻辑改版时，上层其他模块完全不用动。
2. 核心原理解析：SNTP 校时链路
2.1 网络时间协议的工作流程
SNTP 是 NTP 的简化实现，去掉了一些复杂的同步算法和校验机制，只保留了最基本的时间戳交换过程。它对嵌入式设备来说非常友好，目的就是让 MCU 花最小的资源开销拿到时间。
整个交互过程只有四步：
- 设备开机，通过 DHCP 获取局域网 IP 地址，同时拿到 DNS 服务器地址。
- 向指定的 NTP 服务器（比如
ntp.aliyun.com）发送一个 48 字节的 UDP 数据包，包里填充本地时间戳（通常为 0 或本地误差值）。 - 服务器收到请求后，在响应报文的“发送时间戳”字段写入当前 UTC 时间，然后原路返回。
- 设备解析响应报文，从第 40 到 43 字节提取这 4 个字节的整数部分，就得到了从 1900 年 1 月 1 日到当前的秒数，再换算成 Unix 时间戳，通过偏移量转成本地时间。
我直接给出一段 Arduino 框架下的核心校时代码，这段代码我在 ESP8266 上实测通过，拿到时间后写入 DS3231：
#include <ESP8266WiFi.h> #include <WiFiUdp.h> const char* ntpServer = "ntp.aliyun.com"; const int ntpPort = 123; const long timezoneOffset = 8 * 3600; // 东八区偏移秒数 WiFiUDP udp; byte ntpBuffer[48]; void sendNTPRequest() { memset(ntpBuffer, 0, 48); ntpBuffer[0] = 0x1B; // 版本号 3，工作模式 3：客户端模式 udp.beginPacket(ntpServer, ntpPort); udp.write(ntpBuffer, 48); udp.endPacket(); } unsigned long parseNTPResponse() { if (udp.parsePacket() == 48) { udp.read(ntpBuffer, 48); unsigned long secsSince1900 = (unsigned long)ntpBuffer[40] << 24 | (unsigned long)ntpBuffer[41] << 16 | (unsigned long)ntpBuffer[42] << 8 | (unsigned long)ntpBuffer[43]; // 转换为 Unix 时间戳，并加上时区偏移 return secsSince1900 - 2208988800UL + timezoneOffset; } return 0; }注意第 40 到 43 字节这个区间，这是 NTP 响应报文里“发送时间戳”的整数部分，也是整条链路最关键的数据。很多新手上来直接读整个缓冲区然后按 16 进制打印，结果发现完全对不上，就是因为没搞清楚字段偏移。
2.2 为什么需要 DS3231 做时间保持
如果纯粹靠 MCU 内部的定时器计数来走时，一旦断电重启，时间就归零了。所以 V1.0 引入了 DS3231，它有独立的电池备份引脚，接一颗 CR2032 纽扣电池就能在断电时继续走时。实际使用中，即使断网三五天，RTC 的时间偏差也只有几秒，一旦恢复 WiFi 连接，系统会立刻做一次校时，把误差清零。
DS3231 的 I2C 地址是0x68，读写寄存器并不复杂。关键在于把 SNTP 获取到的 Unix 时间戳拆分成年月日时分秒，再通过 BCD 码写入 DS3231 对应的寄存器。这个转换逻辑我建议直接用现成的TimeLib.h库里的breakTime()函数，避免自己去算闰年和每月天数，那部分太容易写错了。
3. 实操过程与核心功能实现
3.1 网络连接的配网方式
V1.0 的配网逻辑采用“SmartConfig + 网页手动配网”双保险。SmartConfig 适合手机 App 一键配置，但兼容性偶尔会出问题，稳定起见我额外实现了 AP 模式网页配网：ESP8266 启动后先检查 Flash 里有没有保存过的 WiFi 凭据，如果没有，就开启一个名为Clock_Config的软 AP，手机连上后访问192.168.4.1，在网页表单里输入家里 WiFi 的 SSID 和密码，点保存即可。数据用Preferences库写入 Flash，掉电不丢失。
下面是自动连接的核心逻辑，我加入了失败重试和超时判断，避免设备在错误凭据下死循环：
#include <Preferences.h> Preferences prefs; String ssid = ""; String password = ""; bool loadWiFiConfig() { prefs.begin("wifi", true); ssid = prefs.getString("ssid", ""); password = prefs.getString("pass", ""); prefs.end(); return ssid.length() > 0; } bool connectToWiFi() { WiFi.mode(WIFI_STA); WiFi.begin(ssid.c_str(), password.c_str()); int retries = 0; while (WiFi.status() != WL_CONNECTED && retries < 20) { delay(500); retries++; Serial.print("."); } if (WiFi.status() == WL_CONNECTED) { Serial.printf("\n连接成功，IP 地址：%s\n", WiFi.localIP().toString().c_str()); return true; } Serial.println("\n连接超时，请检查密码或信号强度"); return false; }3.2 显示界面与自动校时流程
显示部分我用了 U8g2 库，它支持多种字体和低资源消耗的缓冲模式。界面分为两屏，单击按键切换，第一屏是主时钟屏，显示时间、日期、星期，顶部有一个 WiFi 状态图标；第二屏显示设备 IP、网关心跳、上次校时耗时等诊断信息。
自动校时策略是这样的：上电后如果连接成功，立即执行一次校时；随后每小时校时一次，并随机跳过整点后 30 秒内的时刻，避免所有设备都在 0 秒发起请求导致服务器瞬时压力过大。每次校时完成后，把当前 Unix 时间戳写入 DS3231，再更新显示。校时失败不会影响显示，系统继续用 RTC 走时，并在下一次定时任务到达时重试。
这里有个细节要提醒：在写入 DS3231 前，需要用软件方法做“闰秒和时区补偿”。SNTP 返回的是 UTC 时间，中国在东八区，要加 8 小时，即timezoneOffset = 8 * 3600。字符串显示时还要注意跨天问题，比如 UTC 的 16:00 对应本地 00:00，日期已经变了，必须直接在校时完成的瞬间把完整时间戳保存，而不是只保存时分秒。
3.3 功耗与省电策略
做为桌面设备，功耗不是第一优先级，但我还是做了两档省电配置：白天正常亮度，夜间 23:00 到次日 7:00 自动降低 OLED 亮度到 20%，实测整机电流从 80mA 降到 40mA 左右。如果有电池供电需求，还可以在显示器休眠的同时让 ESP8266 进入 Modem Sleep 模式，只保留定时唤醒网络校时的能力，电流能压到个位数毫安，不过 V1.0 暂时没做这一步，留给下个版本迭代。
4. 常见问题与排查技巧
这部分是我自己反复折腾了一晚上总结出来的，直接对照着排查，能省下大量调试时间。
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| WiFi 连接失败，串口打印连不上 | 密码错误的特殊字符没有转义 | 用网页转义后再存储（+、%等） |
| NTP 请求能发出，但收不到响应 | 路由器的 UDP 123 端口被封锁 | 换用time.windows.com或pool.ntp.org备用服务器 |
| 时间显示早或晚 8 小时 | 时区偏移没有加到时间戳里 | 检查timezoneOffset是否乘以了 3600 |
| OLED 屏幕有鬼影或闪烁 | I2C 线太长且没有上拉电阻 | 缩短排线，并联 4.7k 欧姆上拉至 VCC |
| 断电重启后时间回到 1970 | 没有把校时结果写入 DS3231 | 确认setTime()调用以及 DS3231 的写寄存器逻辑 |
| 显示正常但每隔几十秒卡顿一次 | WiFi 扫描频道导致任务阻塞 | 定时扫描放到后台任务，显示任务用中断驱动刷新 |
其中最坑的一种情况是：路由器改了 WiFi 密码后，ESP8266 依然会不断尝试旧密码连接，每次都要等十几秒超时，然后重启循环。V1.0 增加了“超出重试次数自动进入 AP 配网模式”的逻辑，避免了这个问题，实际体验提升巨大。
4.1 关于校时频繁失败的一个真实血泪史
我第一次制作时，校时函数放在主循环里每 10 分钟调一次，结果发现有时候连着几个小时收不到服务器响应。排查后发现问题出在 ESP8266 的 SDK 对 UDP 接收 buffer 的大小有限制，如果强制一次读满 48 字节而内核 buffer 被其他协议栈占用，udp.read()会返回 0。解决办法是在读取前先调用udp.parsePacket()判断实际可读长度，并且把 UDP 接收函数放到中断标志位里，不在主循环轮询。
另一个容易被忽略的坑是：如果使用静态 IP，但网关和 DNS 配置不对，也能连接路由器，却发不出 DNS 解析请求，导致ntp.aliyun.com无法解析。因此我特意保留了 DHCP 自动获取 IP 的逻辑，除非在特殊场景下，否则不要轻易指定静态 IP。
4.2 精度实测与长期稳定性
在正常家庭网络条件下，这个时钟的显示秒与手机时间比对，肉眼几乎看不出误差。用串口连续打印 24 小时校时记录，最大偏差在 0.8 秒左右，这已经远超机械钟和普通 RTC 的精度了。需要注意的一点是：有些老路由器在高负载时 NTP 响应时间会明显波动，但 NTP 本来就是一个“用网络延迟换绝对精度”的协议，本地 RTC 在两次校时之间持续走时，所以短暂延迟并不会造成可见误差。
5. 这个项目的扩展空间与后续迭代
V1.0 的代码架构是刻意保持简洁的，初学者理解完整个链路后，可以在此基础上延伸出不少有意思的方向。我个人比较看好的几个扩展点：
- 传感器信息屏：在现有主板引脚空闲的情况下，外接 DHT11 温湿度传感器，在 OLED 第二屏显示环境数据，变成桌面气象站。
- 语音报时：接一个 DFPlayer Mini 播放模块，整点播放语音或清脆的提示音，比纯光显示更有场景感。
- 远程校时监控：利用 MQTT 协议把设备在线状态和当前时间戳推到本地 Home Assistant 或树莓派，随时用手机查看设备是否正常运行。
- 双网络冗余：在 WiFi 之外再预留一个 PPS 秒脉冲接口，用于接入 GPS 或北斗模块做高精度授时，这类应用在实验室或对时要求较高的场景特别实用。
如果你之前玩过 Arduino，上手这个项目基本没有门槛；如果你只会单片机裸机开发，一开始碰到 WiFi 库和 UDP 通信可能会有点懵，但照着代码跑通一遍链路，对网络编程的理解会立马上一个台阶。
最后分享一个小经验：如果你也想搭一个类似的网络时钟，第一版一定要先跑通“WiFi 连接 + NTP 查询 + 串口打印时间”这三步，再去做 OLED 显示和菜单交互。V1.0 当初就是先看到串口助手滚动输出的正确时间戳，才定下心继续往下做的。串口打印永远是嵌入式开发最快获得正反馈的窗口，别小看这行Serial.printf("%d-%02d-%02d %02d:%02d:%02d")，它比任何调试器都直观。
本文还有配套的精品资源，点击获取
