# 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_LIBC_TIME_SYSCALL configuration option.

## RTC Timer Clock Sources

The RTC timer has the following clock sources:

- `Internal 90–150 kHz (depending on chip) 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 external crystal pins. This source provides a better frequency stability at the expense of a slightly higher (by 1 μA) Deep-sleep current consumption. Refer to the datasheet for information on which pins to connect to.

- `External 32 kHz oscillator`: Allows using a 32 kHz clock generated by an external circuit. The external clock signal must be connected to the external oscillator pin. The input amplitude must ensure that the digital circuit can correctly distinguish between logic high and low levels. Test results show that 1.7 V is the threshold between high and low levels. Therefore, make sure the input waveform has a peak value greater than 1.7 V and a minimum value lower than 1.7 V. For details on pin connections, please refer to the datasheet.

- `Internal 8.5–17.5 MHz oscillator (depending on chip), divided by 256`: Provides better frequency stability than the `Internal 90–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 the Hardware Design Guidelines.

### Selecting RTC Timer Clock Source

Use the default internal RC oscillator when:

- Minimizing sleep current consumption is critical for battery-powered or energy-constrained devices.

- High time accuracy during sleep modes is not required. Time drifting in the range of several seconds per day is acceptable.

- Minimizing external components and hardware complexity is a priority.

- The operating temperature is relatively stable (reducing frequency variation).

- Bluetooth LE with power saving is not used, or only used for legacy advertising/scanning without connections.

Use an external 32 kHz crystal or external 32 kHz oscillator when:

- Accurate time-keeping during Deep-sleep and Light-sleep modes is required.

- A small increase in sleep current (typically a few μA) fits within the power budget.

- Adding external components is acceptable for the design.

- Operating temperature may vary significantly.

- Bluetooth LE with power saving is enabled and connections are required.

Some chips may provide the internal oscillator option, which is a trade-off between the internal RC oscillator and external 32 kHz crystal/oscillator options. It does not require external components while providing better frequency stability than the internal RC oscillator but at the cost of higher sleep current consumption. If Bluetooth LE is used please verify the internal oscillator meets Bluetooth LE sleep clock accuracy requirements (see below).

In most designs, the additional sleep current is a reasonable trade-off for significantly improved RTC Timer frequency stability and reduced time drift during sleep.

Bluetooth LE requires sleep clock accuracy within 500 PPM. The RTC clock source may not meet this requirement, leading to connection establishment failures, unexpected timeouts, or incompatibility with non-Espressif peer devices.

For a detailed comparison of Bluetooth LE clock configurations and power consumption, refer to Low Power Mode in Bluetooth LE.

## 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 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. Applications can also subscribe to an event posted when time is synchronized (`NETIF_SNTP_EVENT`, ID `NETIF_SNTP_TIME_SYNC`). The event data is a pointer to `esp_netif_sntp_time_sync_t` containing the synchronized `timeval`:

    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 Service 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:

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

2. 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

  > or

  >     PRIV_REQUIRES lwip

### 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.

  Modes allowed: 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

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_init(void)

  Init and start SNTP service.

void esp_sntp_stop(void)

  Stops SNTP service.

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

void esp_sntp_setservername(u8_t idx, const char *server)

  Sets SNTP hostname.

  Parameters:

    - idx -- Index of the server

    - server -- Name of the server

const char *esp_sntp_getservername(u8_t idx)

  Gets SNTP server name.

  Parameters:

    idx -- Index of the server

  Returns:

    Name of the server

const ip_addr_t *esp_sntp_getserver(u8_t idx)

  Get SNTP server IP.

  Parameters:

    idx -- Index of the server

  Returns:

    IP address of the server

bool esp_sntp_enabled(void)

  Checks if sntp is enabled.

  Returns:

    true if sntp module is enabled

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

static inline void sntp_setoperatingmode(u8_t operating_mode)

  if not build within lwip, provide translating inlines, that will warn about thread safety

static inline void sntp_servermode_dhcp(int set_servers_from_dhcp)

static inline void sntp_setservername(u8_t idx, const char *server)

static inline void sntp_init(void)

static inline const char *sntp_getservername(u8_t idx)

static inline const ip_addr_t *sntp_getserver(u8_t idx)

static inline uint8_t sntp_getreachability(uint8_t idx)

static inline esp_sntp_operatingmode_t sntp_getoperatingmode(void)

### Macros

esp_sntp_sync_time

  Aliases for esp_sntp prefixed API (inherently thread safe)

esp_sntp_set_sync_mode

esp_sntp_get_sync_mode

esp_sntp_get_sync_status

esp_sntp_set_sync_status

esp_sntp_set_time_sync_notification_cb

esp_sntp_set_sync_interval

esp_sntp_get_sync_interval

esp_sntp_restart

SNTP_OPMODE_POLL

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

enum esp_sntp_operatingmode_t

  SNTP operating modes per lwip SNTP module.

  Values:

  enumerator ESP_SNTP_OPMODE_POLL
  enumerator ESP_SNTP_OPMODE_LISTENONLY

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.