单片机与物联网 / 系统课时
同步网络时间
同步网络时间
ESP32 上电后并不知道当前日期时间。本课用 Wi-Fi 连接 NTP 服务器完成校时,再把 UTC 按时区规则转换为本地时间,并验证 Wi-Fi 断开后系统时钟仍能继续走时。
学习目标
- 使用
configTzTime()和getLocalTime()完成一次网络校时 - 正确处理时区规则,避免把时区偏移写反
- 理解首次同步失败与断网后的处理策略
网络校时到底做了什么
ESP32 联网后,SNTP 客户端向时间服务器获取标准时间并校准系统时钟。应用读取时间时,不应自己给“小时”做加减,而应让系统根据 TZ 规则把 UTC 转成本地时间。一次校时成功后,即使 Wi-Fi 暂时断开,系统时钟仍会继续递增,只是长时间离线后会逐渐产生漂移。

完成一次同步并验证离线走时
下面使用 Arduino-ESP32 的时间 API。示例时区设为中国标准时间,CST-8 是 POSIX TZ 写法,其中符号方向与常见 UTC 偏移表示法相反,所以 UTC+8 写成 -8。
cpp
#include <Arduino.h>
#include <WiFi.h>
#include <time.h>
const char* WIFI_SSID = "YOUR_WIFI_SSID";
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";
const char* NTP_SERVER_1 = "pool.ntp.org";
const char* NTP_SERVER_2 = "time.nist.gov";
const char* TZ_INFO = "CST-8"; // 中国标准时间:UTC+8
bool connectWiFi(uint32_t timeoutMs) {
WiFi.mode(WIFI_STA);
WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
uint32_t startedAt = millis();
while (WiFi.status() != WL_CONNECTED) {
if (millis() - startedAt >= timeoutMs) {
return false;
}
delay(250);
}
return true;
}
bool syncClock(uint32_t timeoutMs) {
// 配置时区和 NTP 服务器后,等待系统时间变为有效值。
configTzTime(TZ_INFO, NTP_SERVER_1, NTP_SERVER_2);
struct tm timeInfo;
return getLocalTime(&timeInfo, timeoutMs);
}
void printLocalTime() {
struct tm timeInfo;
if (!getLocalTime(&timeInfo, 100)) {
Serial.println("Time is not ready");
return;
}
char buffer[32];
strftime(buffer, sizeof(buffer), "%Y-%m-%d %H:%M:%S", &timeInfo);
Serial.printf("Local time: %s\n", buffer);
}
void setup() {
Serial.begin(115200);
if (!connectWiFi(15000)) {
Serial.println("Wi-Fi connection failed");
return;
}
Serial.print("Wi-Fi connected: ");
Serial.println(WiFi.localIP());
if (!syncClock(15000)) {
Serial.println("NTP synchronization failed");
return;
}
Serial.println("NTP synchronized");
printLocalTime();
// 主动关闭 Wi-Fi,用来验证系统时钟不会因断网立即失效。
WiFi.disconnect(true);
WiFi.mode(WIFI_OFF);
Serial.println("Wi-Fi turned off; system clock keeps running");
}
void loop() {
printLocalTime();
delay(10000);
}预期输出:
text
Wi-Fi connected: <IP>
NTP synchronized
Local time: <TIME>
Wi-Fi turned off; system clock keeps running
Local time: <TIME>
Local time: <TIME><IP> 与 <TIME> 会随网络和实际时刻变化。后两次时间即使在 Wi-Fi 已关闭时仍应继续递增,这说明应用读取的是已经校准过的系统时钟,而不是每次显示时间都去访问 NTP 服务器。
处理时区和断网边界
固定时区且没有夏令时的地区可以使用简单 POSIX TZ 字符串;存在夏令时切换的地区应使用包含切换规则的 TZ 字符串,而不是全年固定秒偏移。这样跨季节时系统会自动选择正确的本地时间。
首次启动如果没有网络,不能把未校准的时间当真实时间写入日志、证书判断或业务数据。更稳妥的做法是维护“时间是否可信”的状态:同步成功前只记录相对运行时长,联网后再确认绝对时间。
网络时间的关键不是“拿到一个日期字符串”,而是建立 NTP 校准系统时钟、TZ 负责本地化、业务只读取系统时间 的分工。这样换时区、短时断网和后续重连都不需要在业务代码里手工修正小时数。
按自己的节奏,确认真正理解。