Learn/sntpesp32esp-idftime

ESP32 Time Sync at Home: SNTP From Your Own Network

An ESP32 boots with no idea what time it is. How ESP32 time sync works with SNTP in ESP-IDF v6.1.1, why HTTPS and logs need it, and how to serve time from home.

Signed by M·
Brick study at dawn where a desktop computer holds a small steady orb and thin silver threads run to three small green boards on a shelf, each beside a tiny clock face
How do I set the time on an ESP32?

Use SNTP. In ESP-IDF v6.1.1, call esp_netif_sntp_init with a server, then esp_netif_sntp_sync_wait before anything that needs the date. The lwIP client then re-syncs every hour by default. At home, point it at a time server on your own computer and keep a public pool as a fallback.

An ESP32 has no idea what time it is when it boots. Its timers count from boot, and the calendar date it reports means nothing until something sets it. For a lamp that only toggles, that never matters. For anything that writes logs, runs schedules or checks a certificate, it does.

The usual fix is SNTP, the simple form of the Network Time Protocol, and ESP-IDF ships a client for it. This guide covers how ESP32 time sync works in ESP-IDF v6.1.1, where time quietly matters on a home network, and how to serve the time from a computer you own instead of a stranger's server. It belongs to the Connect part of the site. Nothing here was re-run on a board for this page; every behavior is quoted from Espressif's documentation or the RFCs.

Why ESP32 time sync matters at home

Three jobs on a home board depend on the clock.

Logs and events. A door sensor that says "opened at 03:12" is only useful if 03:12 is real. Without time sync, every event is stamped relative to the last boot, and a power cut resets the story.

Schedules. Lights at sunset, a heater at six, a plant pump every morning. A schedule needs the wall clock and the local time zone, and the ESP-IDF guide sets the zone with the standard TZ variable and tzset().

Certificates. This is the one that surprises people. In ESP-IDF, CONFIG_MBEDTLS_HAVE_TIME_DATE is disabled by default, and the Kconfig reference says that when it is off, a certificate's "valid from" and "valid to" fields are ignored. Turn it on and the device compares them with its own clock, which means the clock has to be right before the first TLS connection. Espressif recommends SNTP for that, and warns about the trade-off: if every trusted certificate expires while a device is offline, it may not be able to connect to fetch the update that would fix it. If you followed our ESP32 OTA updates at home guide, this is the same HTTPS path, and it is worth deciding on purpose.

How SNTP time sync works in ESP-IDF v6.1.1

The system time guide keeps time with two hardware timers by default: an RTC timer that runs through sleep and most resets, and a high-resolution timer that is more accurate but stops in sleep and on reset. Neither knows the date until SNTP sets it.

Start SNTP and wait for the first sync

The guide's example creates a default config with ESP_NETIF_SNTP_DEFAULT_CONFIG("pool.ntp.org"), starts the service with esp_netif_sntp_init(), and then calls esp_netif_sntp_sync_wait() with a timeout. Do the wait before anything that needs the date, such as the first HTTPS request, and decide what the board does if it times out. Espressif recommends the esp_netif wrapper because some lwIP SNTP functions are not thread safe.

Pick a sync mode and an update period

Two sync modes exist. The default, SNTP_SYNC_MODE_IMMED, sets the clock with settimeofday() as soon as a reply arrives. SNTP_SYNC_MODE_SMOOTH slews the clock gradually with adjtime(), unless the error is more than 35 minutes, in which case it steps immediately. Smooth suits logs that should never jump backward; immediate suits a board that just booted. After the first sync, the client repeats every CONFIG_LWIP_SNTP_UPDATE_DELAY, which defaults to one hour.

Let the router name the time server

You do not have to hard-code a server. RFC 2132 defines DHCP option 42, a list of NTP servers in order of preference. In ESP-IDF, CONFIG_LWIP_DHCP_GET_NTP_SRV is off by default; enable it and lwIP asks for option 42 in its DHCP request. One detail to check: CONFIG_LWIP_SNTP_MAX_SERVERS defaults to 1, so raise it if you want a local server and a public fallback at the same time.

Serve ESP32 time sync from your own network

A public pool works, but every board on your network then asks the internet what time it is, on the internet's schedule. A household time server is a small, quiet improvement: boards sync from a machine you own, and only that machine talks to the outside.

Run a time server on the home computer

Any NTP server works for SNTP clients, because SNTP speaks the same packets as NTPv4 in RFC 5905. The computer that already runs your household services is the natural place for it. Our sibling project rusty_time is a pure-Rust NTP and NTS client and server; the rusty_time notes on Remade With Rust cover its status, which is pre-1.0. Point your router's option 42, or the board's config, at that machine, and keep a public pool second.

Know what plain SNTP does not protect

Without NTS or a shared key, a time client cannot prove that a reply came from its server, so a device on a hostile network can be fed a wrong time. Network Time Security, RFC 8915, adds TLS-based key exchange and authenticated NTP packets for client and server. The ESP-IDF time guide documents plain SNTP, not NTS. On a home network that is an acceptable trade for most sensors, and one more reason to keep the time server inside the house and the boards on a network you control.

Where Janus devices stand

Our own rusty_esp_core takes a different path. There is no wall clock on a Janus device: it counts microseconds since boot, and the home computer maps device time to wall time once per session, reporting an unmeasured offset as infinite error rather than a silent zero. That design keeps the calendar on the home computer, and boards reach it over the household mesh through rusty_esp_iroh. If you are bringing ESP32 boards into a MATA home, the MATA Home guide for dldeploy boards explains how the home computer fits in, and deploy ESP32 at home in an afternoon is the starting point for a first board.

FAQ

Quick answers for builders evaluating this technology.

Does an ESP32 keep the time after a reset?

Partly. Espressif's system time guide says the RTC timer keeps counting through sleep and most resets, but a power-on reset resets it. Without a battery-backed clock, a board that loses power has no valid date until SNTP or another source sets the time again.

Why does ESP32 HTTPS ignore certificate expiry dates?

Because CONFIG_MBEDTLS_HAVE_TIME_DATE is disabled by default in ESP-IDF, so the valid-from and valid-to fields are ignored. Turning it on means the device compares them with its own clock, which requires setting the clock first. Espressif recommends SNTP for that and warns about devices that stay offline.

How often does ESP-IDF SNTP sync the time?

Once an hour by default. CONFIG_LWIP_SNTP_UPDATE_DELAY sets the period, and Espressif's guide says the default value is one hour. The default sync mode sets the clock immediately on each reply, and the smooth mode slews it with adjtime unless the error is more than 35 minutes.

Can my router tell the ESP32 which time server to use?

Yes, if your router's DHCP server hands out NTP servers. RFC 2132 defines option 42 for that list. In ESP-IDF, enable CONFIG_LWIP_DHCP_GET_NTP_SRV, which is off by default, so the device asks for option 42 and can use the server it receives.

Do Janus devices use SNTP?

This page does not claim they do. The rusty_esp_core notes say there is no wall clock on a Janus device: it counts microseconds since boot, and the home computer maps that to wall time once per session. Nothing in this guide was re-run on a board.