From 07a3eca372c70c6c00d1b787f66f21efac24f015 Mon Sep 17 00:00:00 2001 From: Konstantin Kondrashov Date: Sat, 2 Mar 2019 02:12:11 +0800 Subject: [PATCH] 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 --- components/lwip/CMakeLists.txt | 2 + components/lwip/apps/sntp/sntp.c | 93 ++++++++++++++ components/lwip/component.mk | 2 + components/lwip/include/apps/esp_sntp.h | 22 ++++ components/lwip/include/apps/sntp/sntp.h | 119 ++++++++++++++++++ .../lwip/include_compat/apps/sntp/sntp.h | 4 +- components/lwip/port/esp32/include/lwipopts.h | 5 +- examples/protocols/sntp/README.md | 39 ++++++ .../protocols/sntp/main/Kconfig.projbuild | 14 +++ .../protocols/sntp/main/sntp_example_main.c | 60 ++++++++- 10 files changed, 350 insertions(+), 10 deletions(-) create mode 100644 components/lwip/apps/sntp/sntp.c create mode 100644 components/lwip/include/apps/esp_sntp.h create mode 100644 components/lwip/include/apps/sntp/sntp.h diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt index aa53a6fecc..632d866ed3 100644 --- a/components/lwip/CMakeLists.txt +++ b/components/lwip/CMakeLists.txt @@ -1,5 +1,6 @@ set(COMPONENT_ADD_INCLUDEDIRS include/apps + include/apps/sntp lwip/src/include port/esp32/include port/esp32/include/arch @@ -9,6 +10,7 @@ set(COMPONENT_ADD_INCLUDEDIRS set(COMPONENT_SRCS "apps/dhcpserver/dhcpserver.c" "apps/ping/esp_ping.c" "apps/ping/ping.c" + "apps/sntp/sntp.c" "lwip/src/api/api_lib.c" "lwip/src/api/api_msg.c" "lwip/src/api/err.c" diff --git a/components/lwip/apps/sntp/sntp.c b/components/lwip/apps/sntp/sntp.c new file mode 100644 index 0000000000..58b84f5a78 --- /dev/null +++ b/components/lwip/apps/sntp/sntp.c @@ -0,0 +1,93 @@ +// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#include +#include +#include +#include +#include "esp_log.h" +#include "sntp.h" + +static const char *TAG = "sntp"; + +static volatile sntp_sync_mode_t sntp_sync_mode = SNTP_SYNC_MODE_IMMED; +static volatile sntp_sync_status_t sntp_sync_status = SNTP_SYNC_STATUS_RESET; +static sntp_sync_time_cb_t time_sync_notification_cb = NULL; + +inline void sntp_set_sync_status(sntp_sync_status_t sync_status) +{ + sntp_sync_status = sync_status; +} + +void __attribute__((weak)) sntp_sync_time(struct timeval *tv) +{ + if (sntp_sync_mode == SNTP_SYNC_MODE_IMMED) { + settimeofday(tv, NULL); + sntp_set_sync_status(SNTP_SYNC_STATUS_COMPLETED); + } else if (sntp_sync_mode == SNTP_SYNC_MODE_SMOOTH) { + 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 sntp_time = (int64_t)tv->tv_sec * 1000000L + (int64_t)tv->tv_usec; + int64_t delta = sntp_time - cpu_time; + struct timeval tv_delta = { .tv_sec = delta / 1000000L, .tv_usec = delta % 1000000L }; + if (adjtime(&tv_delta, NULL) == -1) { + ESP_LOGD(TAG, "Function adjtime don't update time because the error is very big"); + settimeofday(tv, NULL); + ESP_LOGD(TAG, "Time was synchronized through settimeofday"); + sntp_set_sync_status(SNTP_SYNC_STATUS_COMPLETED); + } else { + sntp_set_sync_status(SNTP_SYNC_STATUS_IN_PROGRESS); + } + } + if (time_sync_notification_cb) { + time_sync_notification_cb(tv); + } +} + +void sntp_set_sync_mode(sntp_sync_mode_t sync_mode) +{ + sntp_sync_mode = sync_mode; +} + +sntp_sync_mode_t sntp_get_sync_mode(void) +{ + return sntp_sync_mode; +} + +// set a callback function for time synchronization notification +void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback) +{ + time_sync_notification_cb = callback; +} + +sntp_sync_status_t sntp_get_sync_status(void) +{ + sntp_sync_status_t ret_sync_status = SNTP_SYNC_STATUS_RESET; + sntp_sync_status_t sync_status = sntp_sync_status; + if (sync_status == SNTP_SYNC_STATUS_COMPLETED) { + sntp_set_sync_status(SNTP_SYNC_STATUS_RESET); + ret_sync_status = SNTP_SYNC_STATUS_COMPLETED; + } else if (sync_status == SNTP_SYNC_STATUS_IN_PROGRESS) { + struct timeval outdelta; + adjtime(NULL, &outdelta); + if (outdelta.tv_sec == 0 && outdelta.tv_usec == 0) { + sntp_set_sync_status(SNTP_SYNC_STATUS_RESET); + ret_sync_status = SNTP_SYNC_STATUS_COMPLETED; + } else { + ret_sync_status = SNTP_SYNC_STATUS_IN_PROGRESS; + } + } + return ret_sync_status; +} diff --git a/components/lwip/component.mk b/components/lwip/component.mk index 45a083d509..f43250baa6 100644 --- a/components/lwip/component.mk +++ b/components/lwip/component.mk @@ -5,6 +5,7 @@ COMPONENT_SUBMODULES += lwip COMPONENT_ADD_INCLUDEDIRS := \ include/apps \ + include/apps/sntp \ lwip/src/include \ port/esp32/include \ port/esp32/include/arch \ @@ -13,6 +14,7 @@ COMPONENT_ADD_INCLUDEDIRS := \ COMPONENT_SRCDIRS := \ apps/dhcpserver \ apps/ping \ + apps/sntp \ lwip/src/api \ lwip/src/apps/sntp \ lwip/src/core \ diff --git a/components/lwip/include/apps/esp_sntp.h b/components/lwip/include/apps/esp_sntp.h new file mode 100644 index 0000000000..020f0cf36a --- /dev/null +++ b/components/lwip/include/apps/esp_sntp.h @@ -0,0 +1,22 @@ +// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#ifndef __ESP_SNTP_H__ +#define __ESP_SNTP_H__ + +#include "lwip/err.h" +#include "lwip/apps/sntp.h" +#include "sntp.h" + +#endif // __ESP_SNTP_H__ diff --git a/components/lwip/include/apps/sntp/sntp.h b/components/lwip/include/apps/sntp/sntp.h new file mode 100644 index 0000000000..418d3c70ed --- /dev/null +++ b/components/lwip/include/apps/sntp/sntp.h @@ -0,0 +1,119 @@ +// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#ifndef __SNTP_H__ +#define __SNTP_H__ + +/* + * 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 modes are available: + * - 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 + * + * Allowable two mode: 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); + +#endif // __SNTP_H__ diff --git a/components/lwip/include_compat/apps/sntp/sntp.h b/components/lwip/include_compat/apps/sntp/sntp.h index 3db0fba1eb..7758cfa7d7 100644 --- a/components/lwip/include_compat/apps/sntp/sntp.h +++ b/components/lwip/include_compat/apps/sntp/sntp.h @@ -1,3 +1,3 @@ #pragma once -#warning "This header file is deprecated, please include lwip/apps/sntp.h instead." -#include "lwip/apps/sntp.h" +#warning "This header file is deprecated, please include esp_sntp.h instead." +#include "esp_sntp.h" diff --git a/components/lwip/port/esp32/include/lwipopts.h b/components/lwip/port/esp32/include/lwipopts.h index 883abe5574..c22046e0d0 100644 --- a/components/lwip/port/esp32/include/lwipopts.h +++ b/components/lwip/port/esp32/include/lwipopts.h @@ -43,7 +43,7 @@ #include "esp_task.h" #include "esp_system.h" #include "sdkconfig.h" - +#include "sntp.h" #include "netif/dhcp_state.h" /* Enable all Espressif-only options */ @@ -836,7 +836,7 @@ enum { #define SNTP_SET_SYSTEM_TIME_US(sec, us) \ do { \ struct timeval tv = { .tv_sec = sec, .tv_usec = us }; \ - settimeofday(&tv, NULL); \ + sntp_sync_time(&tv); \ } while (0); #define SNTP_GET_SYSTEM_TIME(sec, us) \ @@ -845,6 +845,7 @@ enum { gettimeofday(&tv, NULL); \ (sec) = tv.tv_sec; \ (us) = tv.tv_usec; \ + sntp_set_sync_status(SNTP_SYNC_STATUS_RESET); \ } while (0); #define SOC_SEND_LOG //printf diff --git a/examples/protocols/sntp/README.md b/examples/protocols/sntp/README.md index 52db973b85..a5a26d3097 100644 --- a/examples/protocols/sntp/README.md +++ b/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()`. diff --git a/examples/protocols/sntp/main/Kconfig.projbuild b/examples/protocols/sntp/main/Kconfig.projbuild index 803ab080a8..8e751bfbb9 100644 --- a/examples/protocols/sntp/main/Kconfig.projbuild +++ b/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 diff --git a/examples/protocols/sntp/main/sntp_example_main.c b/examples/protocols/sntp/main/sntp_example_main.c index 0cfdeb7a58..3055fde82e 100644 --- a/examples/protocols/sntp/main/sntp_example_main.c +++ b/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(); }