System Time 

Overview
ESP32 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)
RTC
High-resolution timer
None

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 150 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 
32K_XP and 32K_XN 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 32K_XN pin: Allows using 32 kHz 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 stands for signal amplitude. In this case, 
the 32K_XN pin cannot be used as a GPIO pin.
Internal 8.5 MHz oscillator, divided by 256 (~33 kHz): Provides better 
frequency stability than the Internal 150 kHz RC oscillator at 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 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:

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:

 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.

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 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().

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.
sntp_get_sync_status() and sntp_set_sync_status(): Can be used 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 (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.



 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 will return the correct local time taking into account the timezone 
offset and daylight saving time.



 64-bit time_t 
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_T preprocessor macro will be 
defined if 32-bit time_t is used. You need to include  to make this
macro available.
In CMake files, TIME_T_SIZE IDF build property will be set to the size of 
time_t in 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 idf_build_get_property.


Note that the size of time_t type also affects the sizes of other types, for 
example, struct timeval, struct stat, and struct utimbuf.



 API Reference 

Header File

components/lwip/include/apps/esp_sntp.h



 Functions 

/*F********************************************************************
* This function updates the system time.
**********************************************************************/
void 
sntp_sync_time( struct timeval *tv )

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.



/*F********************************************************************
* Set the sync mode.
**********************************************************************/
void 
sntp_set_sync_mode( sntp_sync_mode_t sync_mode )

	Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.

Parameters
	sync_mode – Sync mode.



/*F********************************************************************
* Get set sync mode.
**********************************************************************/
sntp_sync_mode_t 
sntp_get_sync_mode( void )

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



/*F********************************************************************
* Get status of time sync.
**********************************************************************/
sntp_sync_status_t sntp_get_sync_status( void )

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.



/*F********************************************************************
* Set status of time sync.
**********************************************************************/
void 
sntp_set_sync_status( sntp_sync_status_t sync_status )

Parameters
	sync_status – status of time sync (see sntp_sync_status_t)



/*F********************************************************************
*Set a callback function for time synchronization notification.
**********************************************************************/
void 
sntp_set_time_sync_notification_cb( sntp_sync_time_cb_t callback )

Parameters
	callback – a callback function



/*F********************************************************************
* Set the sync interval of SNTP operation.
**********************************************************************/
void 
sntp_set_sync_interval( uint32_t interval_ms )

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.



/*F********************************************************************
* Get the sync interval of SNTP operation.
**********************************************************************/
uint32_t sntp_get_sync_interval(void)

Returns
	the sync interval



/*F********************************************************************
*Restart SNTP.
**********************************************************************/
bool sntp_restart(void)

Returns
	True - Restart False - SNTP was not initialized yet



 Type Definitions

/*F********************************************************************
*SNTP callback function for notifying about time sync event.
**********************************************************************/
typedef void (*sntp_sync_time_cb_t)(struct timeval *tv)

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
=======================================================


 components/lwip/include/apps/esp_sntp.h 
/*H*******************************************************
 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************/
#ifndef __ESP_SNTP_H__
#define __ESP_SNTP_H__

#include "lwip/err.h"
#include "lwip/apps/sntp.h"


#ifdef __cplusplus
extern "C" {
#endif

/*
 * The time update takes place in the sntp_sync_time() function.
 * The user has the ability to redefine this function in order
 * to re-define its functionality. This function has two time update modes,
 * which can be set via the sntp_set_sync_mode() function.
 * Two available modes are as follows:
 * - the first is an immediate update when receiving time from the sntp server,
 * - the second is a smooth time update (if the time error is no more than 35 minutes,
 *   and an immediate update if the error is more than 35 minutes).
 *
 * To receive notification of time synchronization,
 * you can use the callback function or get the synchronization status
 * via the sntp_get_sync_status() function.
 *
 * To determine the time synchronization time on the device, you can use:
 * 1) sntp_set_time_sync_notification_cb() function to set the callback function,
 *    which is convenient to use to receive notification of the update time.
 * 2) sntp_get_sync_status() function for getting time synchronization status.
 *    After the time synchronization is completed, the status will be
 *    SNTP_SYNC_STATUS_COMPLETED, after, it will be reseted to SNTP_SYNC_STATUS_RESET
 *    to wait for the next sync cycle.
 */

/// SNTP time update mode
typedef enum {
    SNTP_SYNC_MODE_IMMED,   /*!< Update system time immediately when receiving a response from the SNTP server. */
    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. */
} sntp_sync_mode_t;

/// SNTP sync status
typedef enum {
    SNTP_SYNC_STATUS_RESET,         // Reset status.
    SNTP_SYNC_STATUS_COMPLETED,     // Time is synchronized.
    SNTP_SYNC_STATUS_IN_PROGRESS,   // Smooth time sync in progress.
} sntp_sync_status_t;

/**
 * @brief SNTP callback function for notifying about time sync event
 *
 * @param tv Time received from SNTP server.
 */
typedef void (*sntp_sync_time_cb_t) (struct timeval *tv);

/**
 * @brief 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.
 *
 * @param tv Time received from SNTP server.
 */
void sntp_sync_time(struct timeval *tv);

/**
 * @brief Set the sync mode
 *
 * Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
 * @param sync_mode Sync mode.
 */
void sntp_set_sync_mode(sntp_sync_mode_t sync_mode);

/**
 * @brief Get set sync mode
 *
 * @return  SNTP_SYNC_MODE_IMMED: Update time immediately.
 *          SNTP_SYNC_MODE_SMOOTH: Smooth time updating.
 */
sntp_sync_mode_t sntp_get_sync_mode(void);

/**
 * @brief 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.
 *
 * @return  SNTP_SYNC_STATUS_RESET: Reset status.
 *          SNTP_SYNC_STATUS_COMPLETED: Time is synchronized.
 *          SNTP_SYNC_STATUS_IN_PROGRESS: Smooth time sync in progress.
 */
sntp_sync_status_t sntp_get_sync_status(void);

/**
 * @brief Set status of time sync
 *
 * @param sync_status status of time sync (see sntp_sync_status_t)
 */
void sntp_set_sync_status(sntp_sync_status_t sync_status);

/**
 * @brief Set a callback function for time synchronization notification
 *
 * @param callback a callback function
 */
void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback);

/**
 * @brief 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.
 *
 * @param interval_ms   The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds will be set.
 */
void sntp_set_sync_interval(uint32_t interval_ms);

/**
 * @brief Get the sync interval of SNTP operation
 *
 * @return  the sync interval
 */
uint32_t sntp_get_sync_interval(void);

/**
 * @brief Restart SNTP
 *
 * @return True  - Restart
 *         False - SNTP was not initialized yet
 */
bool sntp_restart(void);

#ifdef __cplusplus
}
#endif

#endif // __ESP_SNTP_H__