System Time

Overview

System time can be kept using either one time source or two time sources simultaneously. The choice depends on the application purpose and accuracy requirements for system time.

There are the following two time sources:

RTC timer: Allows keeping the system time during any resets and sleep modes, only the power-up reset leads to resetting the RTC timer. The frequency deviation depends on an RTC Clock Source and affects accuracy only in sleep modes, in which case the time will be measured at 6.6667 us resolution.
High-resolution timer: Not available during any reset and sleep modes. The reason for using this timer is to achieve greater accuracy. It uses the APB_CLK clock source (typically 80 MHz), which has a frequency deviation of less than ±10 ppm. Time will be measured at 1 us resolution.

The settings for the system time source are as follows:

RTC and high-resolution timer (default)
RTC
High-resolution timer
None

It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure CONFIG_ESP32_TIME_SYSCALL in project configuration.

RTC Clock Source

The RTC timer has the following clock sources:

Internal 150kHz RC oscillator (default): Features lowest deep sleep current consumption and no dependence on any external components. However, as frequency stability is affected by temperature fluctuations, time may drift in both Deep and Light sleep modes.
External 32kHz crystal: Requires a 32kHz crystal to be connected to the 32K_XP and 32K_XN pins. Provides better frequency stability at the expense of slightly higher (by 1 uA) Deep sleep current consumption.
External 32kHz oscillator at 32K_XN pin: Allows using 32kHz clock generated by an external circuit. The external clock signal must be connected to the 32K_XN pin. The amplitude should be less than 1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the range of 0.1 < Vcm < 0.5xVamp, where Vamp is signal amplitude. Additionally, a 1 nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin cannot be used as a GPIO pin.
Internal 8.5MHz oscillator, divided by 256 (~33kHz): Provides better frequency stability than the internal 150kHz RC oscillator at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components.

The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set CONFIG_ESP32_RTC_CLK_SRC in project configuration.

More details on wiring requirements for the External 32kHz crystal and External 32kHz oscillator at 32K_XN pin sources can be found in Section Crystal Oscillator of ESP32 Hardware Design Guidelines.

Get Current Time

To get the current time, use the POSIX function gettimeofday(). Additionally, you can use the following standard C library functions to obtain time and manipulate it:

gettimeofday
time
asctime
clock
ctime
difftime
gmtime
localtime
mktime
strftime
adjtime*

* – To stop smooth time adjustment and update the current time immediately, use the POSIX function settimeofday().

If you need to obtain time with one second resolution, use the following method:

time_t now;
char strftime_buf[64];
struct tm timeinfo;

time(&now);
// Set timezone to China Standard Time
setenv("TZ", "CST-8", 1);
tzset();

localtime_r(&now, &timeinfo);
strftime(strftime_buf, sizeof(strftime_buf), "%c", &timeinfo);
ESP_LOGI(TAG, "The current date/time in Shanghai is: %s", strftime_buf);

If you need to obtain time with one microsecond resolution, use the code snippet below:

struct timeval tv_now;
gettimeofday(&tv_now, NULL);
int64_t time_us = (int64_t)tv_now.tv_sec * 1000000L + (int64_t)tv_now.tv_usec;

SNTP Time Synchronization

To set the current time, you can use the POSIX functions settimeofday() and adjtime(). They are used internally in the lwIP SNTP library to set current time when a response from the NTP server is received. These functions can also be used separately from the lwIP SNTP library.

A function to use inside the lwIP SNTP library depends on a sync mode for system time. Use the function sntp_set_sync_mode() to set one of the following sync modes:

SNTP_SYNC_MODE_IMMED (default) updates system time immediately upon receiving a response from the SNTP server after using settimeofday().
SNTP_SYNC_MODE_SMOOTH updates time smoothly by gradually reducing time error using the funcion adjtime(). If the difference between the SNTP response time and system time is more than 35 minutes, update system time immediately by using settimeofday().

The lwIP SNTP library has API functions for setting a callback function for a certain event. You might need the following functions:

sntp_set_time_sync_notification_cb() - use it for setting a callback function that will notify of the time synchronization process
sntp_get_sync_status() and sntp_set_sync_status() - use it to get/set time synchronization status

To start synchronization via SNTP, just call the following three functions.

sntp_setoperatingmode(SNTP_OPMODE_POLL);
sntp_setservername(0, "pool.ntp.org");
sntp_init();

An application with this initialization code will periodically synchronize the time. The time synchronization period is determined by CONFIG_LWIP_SNTP_UPDATE_DELAY (default value is one hour). To modify the variable, set CONFIG_LWIP_SNTP_UPDATE_DELAY in project configuration.

A code example that demonstrates the implementation of time synchronization based on the lwIP SNTP library is provided in protocols/sntp directory.

Timezones

To set local timezone, use the following POSIX functions:

Call setenv() to set the TZ environment variable to the correct value depending on the device location. The format of the time string is the same as described in the GNU libc documentation (although the implementation is different).
Call tzset() to update C library runtime data for the new time zone.

Once these steps are completed, call the standard C library function localtime(), and it will return correct local time taking into account the time zone offset and daylight saving time.

API Reference

Header File

components/lwip/include/apps/esp_sntp.h

Functions

void sntp_sync_time(struct timeval *tv)

This function updates the system time.

This is a weak-linked function. It is possible to replace all SNTP update functionality by placing a sntp_sync_time() function in the app firmware source. If the default implementation is used, calling sntp_set_sync_mode() allows the time synchronization mode to be changed to instant or smooth. If a callback function is registered via sntp_set_time_sync_notification_cb(), it will be called following time synchronization.

Parameters: tv – Time received from SNTP server.

void sntp_set_sync_mode(sntp_sync_mode_t sync_mode)

Set the sync mode.

Allowable two mode: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.

Parameters: sync_mode – Sync mode.

sntp_sync_mode_t sntp_get_sync_mode(void)

Get set sync mode.

Returns: SNTP_SYNC_MODE_IMMED: Update time immediately. SNTP_SYNC_MODE_SMOOTH: Smooth time updating.

sntp_sync_status_t sntp_get_sync_status(void)

Get status of time sync.

After the update is completed, the status will be returned as SNTP_SYNC_STATUS_COMPLETED. After that, the status will be reset to SNTP_SYNC_STATUS_RESET. If the update operation is not completed yet, the status will be SNTP_SYNC_STATUS_RESET. If a smooth mode was chosen and the synchronization is still continuing (adjtime works), then it will be SNTP_SYNC_STATUS_IN_PROGRESS.

Returns: SNTP_SYNC_STATUS_RESET: Reset status. SNTP_SYNC_STATUS_COMPLETED: Time is synchronized. SNTP_SYNC_STATUS_IN_PROGRESS: Smooth time sync in progress.

void sntp_set_sync_status(sntp_sync_status_t sync_status)

Set status of time sync.

Parameters: sync_status – status of time sync (see sntp_sync_status_t)

void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback)

Set a callback function for time synchronization notification.

Parameters: callback – a callback function

void sntp_set_sync_interval(uint32_t interval_ms)

Set the sync interval of SNTP operation.

Note: SNTPv4 RFC 4330 enforces a minimum sync interval of 15 seconds. This sync interval will be used in the next attempt update time throught SNTP. To apply the new sync interval call the sntp_restart() function, otherwise, it will be applied after the last interval expired.

Parameters: interval_ms – The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds will be set.

uint32_t sntp_get_sync_interval(void)

Get the sync interval of SNTP operation.

Returns: the sync interval

bool sntp_restart(void)

Restart SNTP.

Returns: True - Restart False - SNTP was not initialized yet

Type Definitions

typedef void (*sntp_sync_time_cb_t)(struct timeval *tv)

SNTP callback function for notifying about time sync event.

Param tv: Time received from SNTP server.

Enumerations

enum sntp_sync_mode_t

SNTP time update mode.

Values:

enumerator SNTP_SYNC_MODE_IMMED: Update system time immediately when receiving a response from the SNTP server.

enumerator SNTP_SYNC_MODE_SMOOTH: Smooth time updating. Time error is gradually reduced using adjtime function. If the difference between SNTP response time and system time is large (more than 35 minutes) then update immediately.

enum sntp_sync_status_t

SNTP sync status.

Values:

enumerator SNTP_SYNC_STATUS_RESET

enumerator SNTP_SYNC_STATUS_COMPLETED

enumerator SNTP_SYNC_STATUS_IN_PROGRESS

Provide feedback about this document