ESP32-S3 uses two hardware timers for the purpose of keeping system time. System time can be kept by using either one or both of the hardware timers depending on the application’s purpose and accuracy requirements for system time. The two hardware timers are:
RTC timer: This timer allows time keeping in various sleep modes, and can also persist time keeping across any resets (with the exception of power-on resets which reset the RTC timer). The frequency deviation depends on the RTC Timer Clock Sources and affects the accuracy only in sleep modes, in which case the time will be measured at 6.6667 μs resolution.
High-resolution timer: This timer is not available in sleep modes and will not persist over a reset, but has greater accuracy. The timer 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 μs resolution.
The possible combinations of hardware timers used to keep system time are listed below:
RTC and high-resolution timer (default)
It is recommended that users stick to the default option as it provides the highest accuracy. However, users can also select a different setting via the CONFIG_NEWLIB_TIME_SYSCALL configuration option.
RTC Timer Clock Sources
The RTC timer has the following clock sources:
Internal 136 kHz RC oscillator(default): Features the lowest Deep-sleep current consumption and no dependence on any external components. However, the frequency stability of this clock source is affected by temperature fluctuations, so time may drift in both Deep-sleep and Light-sleep modes.
External 32 kHz crystal: Requires a 32 kHz crystal to be connected to the XTAL_32K_P and XTAL_32K_N pins. This source provides a better frequency stability at the expense of a slightly higher (by 1 μA) Deep-sleep current consumption.
External 32 kHz oscillator at XTAL_32K_P pin: Allows using 32 kHz clock generated by an external circuit. The external clock signal must be connected to the XTAL_32K_P 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 stands for signal amplitude. In this case, the XTAL_32K_P pin cannot be used as a GPIO pin.
Internal 17.5 MHz oscillator, divided by 256 (~68 kHz): Provides better frequency stability than the
Internal 136 kHz RC oscillatorat the expense of a higher (by 5 μA) 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_RTC_CLK_SRC in project configuration.
More details about the wiring requirements for the external crystal or external oscillator, please refer to ESP32-S3 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
If you need to obtain time with one second resolution, use the following code snippet:
time_t now; char strftime_buf; 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
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.
The function to use inside the lwIP SNTP library depends on the 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
SNTP_SYNC_MODE_SMOOTH: Updates time smoothly by gradually reducing time error using the function
adjtime(). If the difference between the SNTP response time and system time is more than 35 minutes, update system time immediately by using
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(): Can be used to set a callback function that will notify of the time synchronization process.
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 (the 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 the protocols/sntp directory.
To set the local timezone, use the following POSIX functions:
setenv()to set the
TZenvironment variable to the correct value based 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).
tzset()to update C library runtime data for the new timezone.
Once these steps are completed, call the standard C library function
localtime(), and it will return the correct local time taking into account the timezone offset and daylight saving time.
ESP-IDF uses 32-bit
time_t type by default. To address the Y2K38 issue, you may need to use 64-bit
time_t type when building the application.
Currently, this requires building the cross-compiler toolchain from scratch. See the instructions for building the toolchain in Standard Toolchain Setup for Linux and macOS. To enable 64-bit
time_t support in the toolchain, you need to remove the
--enable-newlib-long-time_t option from the
crosstool-NG/samples/xtensa-esp32-elf/crosstool.config file before building the toolchain.
If you need to make the program compatible with both 32-bit and 64-bit
time_t, you may use the following methods:
In C or C++ source files,
_USE_LONG_TIME_Tpreprocessor macro will be defined if 32-bit
time_tis used. You need to include
<sys/types.h>to make this macro available.
In CMake files,
TIME_T_SIZEIDF build property will be set to the size of
time_tin bytes. You may call
idf_build_get_property(var TIME_T_SIZE)to get the value of this property into a CMake variable
var. See ESP-IDF CMake Build System API for more information about
Note that the size of
time_t type also affects the sizes of other types, for example,
struct stat, and
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.
tv – Time received from SNTP server.
void sntp_set_sync_mode(sntp_sync_mode_t sync_mode)
Set the sync mode.
Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
sync_mode – Sync mode.
Get set sync mode.
SNTP_SYNC_MODE_IMMED: Update time immediately. SNTP_SYNC_MODE_SMOOTH: Smooth time updating.
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.
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.
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.
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.
interval_ms – The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds will be set.
Get the sync interval of SNTP operation.
the sync interval
True - Restart False - SNTP was not initialized yet
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.
SNTP time update mode.
Update system time immediately when receiving a response from the SNTP server.
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.
- enumerator SNTP_SYNC_MODE_IMMED