sntp/lwip: Add some modes for time synchronization

Closes: IDF-236
Closes: https://github.com/espressif/esp-idf/pull/1668
Closes: https://github.com/espressif/esp-idf/pull/4103

examples/protocols/sntp/README.md

@@ -39,3 +39,42 @@ To set time, [`settimeofday`](http://man7.org/linux/man-pages/man2/settimeofday.
 ## Timezones
 
 To set local timezone, use [`setenv`](http://man7.org/linux/man-pages/man3/setenv.3.html) and [`tzset`](http://man7.org/linux/man-pages/man3/tzset.3.html) POSIX functions. First, call `setenv` to set `TZ` environment variable to the correct value depending on device location. Format of the time string is described in [libc documentation](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html). Next, call `tzset` to update C library runtime data for the new time zone. Once these steps are done, `localtime` function will return correct local time, taking time zone offset and daylight saving time into account.
+
+## Additional options
+
+This example can use 3 time synchronization method:
+
+- `update time immediately when received` - update time immediately as received an answer from SNTP server. Allows syncing the time without any additional code from the user side, and use a callback function or getting status for notification of the process of sync.
+
+- `update time with smooth method (adjtime)` - time synchronization will use the adjtime function to smoothly update the time. Allows syncing the time without any additional code from the user side, and use a callback function or getting status for notification of the process of sync.
+
+- `custom implementation` - allows replacing the built-in time synchronization functionality. This option redefines `sntp_sync_time()` function.
+
+## Useful API function:
+
+- `sntp_set_time_sync_notification_cb()` - use this function to set a callback function to notify about the time synchronization process.
+- `sntp_get_sync_status()` and `sntp_set_sync_status()` - get/set time synchronization status.
+- `sntp_get_sync_mode()` and `sntp_set_sync_mode()` - get/set the sync mode. Allowable two mode: `SNTP_SYNC_MODE_IMMED` and `SNTP_SYNC_MODE_SMOOTH`.
+
+## Mode of update time
+
+`sntp_set_sync_mode()` - Set the sync mode of the system time. It has two mode:
+
+* `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. This mode uses `adjtime()` function.
+
+## Adjtime()
+`int adjtime(const struct timeval *delta, struct timeval *outdelta)`
+
+`adjtime()` is a libc function that is called automatically in "smooth" time update mode, but can also be called from custom time synchronization code. 
+If the time error is less than 35 minutes then `adjtime` function will start smooth adjusting otherwise the return value is -1.
+
+This function speeds up or slows down the system clock in order to make a gradual adjustment. This ensures that the calendar time reported by the system clock is always monotonically increasing, which might not happen if you simply set the clock. If adjusting the system clock by `adjtime()` is already done during the second call `adjtime()`, and the delta of the second call is not NULL, the earlier tuning is stopped, but the already completed part of the adjustment is not canceled.
+
+The delta argument specifies a relative adjustment to be made to the clock time. If negative, the system clock is slowed down for a while until it has lost this much elapsed time. If positive, the system clock is speeded up for a while. 
+
+If the olddelta argument is not a null pointer, the adjtime function returns information about any previous time adjustment that has not yet completed. 
+
+The return value is 0 on success and -1 on failure.
+
+To stop the smooth time adjustment, you need to record the current time using the function `settimeofday()`.

examples/protocols/sntp/main/Kconfig.projbuild

@@ -14,4 +14,18 @@ menu "Example Configuration"
 
             Can be left blank if the network has no security set.
 
+    choice SNTP_TIME_SYNC_METHOD
+        prompt "Time synchronization method"
+        default SNTP_TIME_SYNC_METHOD_IMMED
+        help
+            Time synchronization method.
+
+        config SNTP_TIME_SYNC_METHOD_IMMED
+            bool "update time immediately when received"
+        config SNTP_TIME_SYNC_METHOD_SMOOTH
+            bool "update time with smooth method (adjtime)"
+        config SNTP_TIME_SYNC_METHOD_CUSTOM
+            bool "custom implementation"
+    endchoice
+
 endmenu

examples/protocols/sntp/main/sntp_example_main.c

@@ -19,9 +19,7 @@
 #include "esp_attr.h"
 #include "esp_sleep.h"
 #include "nvs_flash.h"
-
-#include "lwip/err.h"
-#include "lwip/apps/sntp.h"
+#include "esp_sntp.h"
 
 /* The examples use simple WiFi configuration that you can set via
    'make menuconfig'.
@@ -53,6 +51,19 @@ static void initialize_sntp(void);
 static void initialise_wifi(void);
 static esp_err_t event_handler(void *ctx, system_event_t *event);
 
+#ifdef CONFIG_SNTP_TIME_SYNC_METHOD_CUSTOM
+void sntp_sync_time(struct timeval *tv)
+{
+   settimeofday(tv, NULL);
+   ESP_LOGI(TAG, "Time is synchronized from custom code");
+   sntp_set_sync_status(SNTP_SYNC_STATUS_COMPLETED);
+}
+#endif
+
+void time_sync_notification_cb(struct timeval *tv)
+{
+    ESP_LOGI(TAG, "Notification of a time synchronization event");
+}
 
 void app_main()
 {
@@ -70,6 +81,27 @@ void app_main()
         // update 'now' variable with current time
         time(&now);
     }
+#ifdef CONFIG_SNTP_TIME_SYNC_METHOD_SMOOTH
+    else {
+        // add 500 ms error to the current system time.
+        // Only to demonstrate a work of adjusting method!
+        {
+            ESP_LOGI(TAG, "Add a error for test adjtime");
+            struct timeval tv_now;
+            gettimeofday(&tv_now, NULL);
+            int64_t cpu_time = (int64_t)tv_now.tv_sec * 1000000L + (int64_t)tv_now.tv_usec;
+            int64_t error_time = cpu_time + 500 * 1000L;
+            struct timeval tv_error = { .tv_sec = error_time / 1000000L, .tv_usec = error_time % 1000000L };
+            settimeofday(&tv_error, NULL);
+        }
+
+        ESP_LOGI(TAG, "Time was set, now just adjusting it. Use SMOOTH SYNC method.");
+        obtain_time();
+        // update 'now' variable with current time
+        time(&now);
+    }
+#endif
+
     char strftime_buf[64];
 
     // Set timezone to Eastern Standard Time and print local time
@@ -86,6 +118,18 @@ void app_main()
     strftime(strftime_buf, sizeof(strftime_buf), "%c", &timeinfo);
     ESP_LOGI(TAG, "The current date/time in Shanghai is: %s", strftime_buf);
 
+    if (sntp_get_sync_mode() == SNTP_SYNC_MODE_SMOOTH) {
+        struct timeval outdelta;
+        while (sntp_get_sync_status() == SNTP_SYNC_STATUS_IN_PROGRESS) {
+            adjtime(NULL, &outdelta);
+            ESP_LOGI(TAG, "Waiting for adjusting time ... outdelta = %li sec: %li ms: %li us",
+                        outdelta.tv_sec,
+                        outdelta.tv_usec/1000,
+                        outdelta.tv_usec%1000);
+            vTaskDelay(2000 / portTICK_PERIOD_MS);
+        }
+    }
+
     const int deep_sleep_sec = 10;
     ESP_LOGI(TAG, "Entering deep sleep for %d seconds", deep_sleep_sec);
     esp_deep_sleep(1000000LL * deep_sleep_sec);
@@ -104,12 +148,12 @@ static void obtain_time(void)
     struct tm timeinfo = { 0 };
     int retry = 0;
     const int retry_count = 10;
-    while(timeinfo.tm_year < (2016 - 1900) && ++retry < retry_count) {
+    while (sntp_get_sync_status() == SNTP_SYNC_STATUS_RESET && ++retry < retry_count) {
         ESP_LOGI(TAG, "Waiting for system time to be set... (%d/%d)", retry, retry_count);
         vTaskDelay(2000 / portTICK_PERIOD_MS);
-        time(&now);
-        localtime_r(&now, &timeinfo);
     }
+    time(&now);
+    localtime_r(&now, &timeinfo);
 
     ESP_ERROR_CHECK( esp_wifi_stop() );
 }
@@ -119,6 +163,10 @@ static void initialize_sntp(void)
     ESP_LOGI(TAG, "Initializing SNTP");
     sntp_setoperatingmode(SNTP_OPMODE_POLL);
     sntp_setservername(0, "pool.ntp.org");
+    sntp_set_time_sync_notification_cb(time_sync_notification_cb);
+#ifdef CONFIG_SNTP_TIME_SYNC_METHOD_SMOOTH
+    sntp_set_sync_mode(SNTP_SYNC_MODE_SMOOTH);
+#endif
     sntp_init();
 }