gettimeofday
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 code snippet:
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.
Some lwIP APIs, including SNTP functions, are not thread safe, so it is recommended to use esp_netif component when interacting with SNTP module.
To initialize a particular SNTP server and also start the SNTP service, simply create a default SNTP server configuration with a particular server name, then call esp_netif_sntp_init() to register that server and start the SNTP service.
esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG("pool.ntp.org");
esp_netif_sntp_init(&config);
This code automatically performs time synchronization once a reply from the SNTP server is received. Sometimes it is useful to wait until the time gets synchronized, esp_netif_sntp_sync_wait() can be used for this purpose:
if (esp_netif_sntp_sync_wait(pdMS_TO_TICKS(10000)) != ESP_OK) {
    printf("Failed to update system time within 10s timeout");
To configure multiple NTP servers (or use more advanced settings, such as DHCP provided NTP servers), please refer to the detailed description of SNTP API in esp_netif documentation.
The lwIP SNTP library could work in 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 function adjtime(). If the difference between the SNTP response time and system time is more than 35 minutes, update system time immediately by using settimeofday().
If you want to choose the SNTP_SYNC_MODE_SMOOTH mode, please set the esp_sntp_config::smooth to true in the SNTP configuration struct. Otherwise (and by default) the SNTP_SYNC_MODE_IMMED mode will be used.




    

For setting a callback function that is called when time gets synchronized, use the esp_sntp_config::sync_cb field in the configuration struct.
An application with this initialization code periodically synchronizes 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.
Note that it is also possible to use lwIP API directly, but care must be taken to thread safety. Here we list the thread-safe APIs:
sntp_set_time_sync_notification_cb() can be used to set a callback function that notifies of the time synchronization process.
sntp_get_sync_status() and sntp_set_sync_status() can be used to get/set time synchronization status.
sntp_set_sync_mode() can be used to set the synchronization mode.
esp_sntp_setoperatingmode() sets the preferred operating mode.:cpp:enumerator:ESP_SNTP_OPMODE_POLL and esp_sntp_init() initializes SNTP module.
esp_sntp_setservername() configures one SNTP server.
Timezones
To set the local timezone, use the following POSIX functions:
Call setenv() to set the TZ environment 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).
Call 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 returns the correct local time taking into account the timezone offset and daylight saving time.
Year 2036 and 2038 Overflow Issues
SNTP/NTP 2036 Overflow
SNTP/NTP timestamps are represented as 64-bit unsigned fixed point numbers, where the first 32 bits represent the integer part, and the last 32 bits represent the fractional part. The 64-bit unsigned fixed point number represents the number of seconds since 00:00 on 1st of January 1900, thus SNTP/NTP times will overflow in the year 2036.
To address this issue, lifetime of the SNTP/NTP timestamps has been extended by convention by using the MSB (bit 0 by convention) of the integer part to indicate time ranges between years 1968 to 2104 (see RFC2030 for more details). This convention is implemented in lwIP library SNTP module. Therefore SNTP-related functions in ESP-IDF are future-proof until year 2104.
Unix Time 2038 Overflow
Unix time (type time_t) was previously represented as a 32-bit signed integer, leading to an overflow in year 2038 (i.e., Y2K38 issue). To address the Y2K38 issue, ESP-IDF uses a 64-bit signed integer to represent time_t starting from release v5.0, thus deferring time_t overflow for another 292 billion years.
API Reference
Header File
components/lwip/include/apps/esp_sntp.h
This header file can be included with:
#include "esp_sntp.h"
This header file is a part of the API provided by the lwip component. To declare that your component depends on lwip, add the following to your CMakeLists.txt:
REQUIRES lwip
PRIV_REQUIRES lwip
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. 
Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH. 
Parameters
sync_mode -- Sync mode. 
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_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. 
void esp_sntp_setoperatingmode(esp_sntp_operatingmode_t operating_mode)

Sets SNTP operating mode. The mode has to be set before init. 
Parameters
operating_mode -- Desired operating mode 
void esp_sntp_setserver(u8_t idx, const ip_addr_t *addr)

Sets SNTP server address. 
Parameters
idx -- Index of the server 
addr -- IP address of the server 
uint8_t esp_sntp_getreachability(uint8_t idx)

Gets the server reachability shift register as described in RFC 5905. 
Parameters
idx -- Index of the SNTP server 
Returns
reachability shift register 
esp_sntp_operatingmode_t esp_sntp_getoperatingmode(void)

Get the configured operating mode. 
Returns
operating mode enum 
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.