1 /* 2 * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include <stdbool.h> 10 #include <stdint.h> 11 #include "freertos/FreeRTOS.h" 12 #include "esp_err.h" 13 #include "esp_netif_types.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * @defgroup ESP_NETIF_SNTP_API ESP-NETIF SNTP API 21 * @brief SNTP API for underlying TCP/IP stack 22 * 23 */ 24 25 /** @addtogroup ESP_NETIF_SNTP_API 26 * @{ 27 */ 28 29 30 /** 31 * @brief Time sync notification function 32 */ 33 typedef void (*esp_sntp_time_cb_t)(struct timeval *tv); 34 35 /** 36 * @brief Utility macro for providing multiple servers in parentheses 37 */ 38 #define ESP_SNTP_SERVER_LIST(...) { __VA_ARGS__ } 39 40 /** 41 * @brief Default configuration to init SNTP with multiple servers 42 * @param servers_in_list Number of servers in the list 43 * @param list_of_servers List of servers (use ESP_SNTP_SERVER_LIST(...)) 44 * 45 */ 46 #define ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(servers_in_list, list_of_servers) { \ 47 .smooth_sync = false, \ 48 .server_from_dhcp = false, \ 49 .wait_for_sync = true, \ 50 .start = true, \ 51 .sync_cb = NULL, \ 52 .renew_servers_after_new_IP = false, \ 53 .ip_event_to_renew = 0, \ 54 .index_of_first_server = 0, \ 55 .num_of_servers = (servers_in_list), \ 56 .servers = list_of_servers, \ 57 } 58 59 /** 60 * @brief Default configuration with a single server 61 */ 62 #define ESP_NETIF_SNTP_DEFAULT_CONFIG(server) \ 63 ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(1, {server}) 64 65 /** 66 * @brief SNTP configuration struct 67 */ 68 typedef struct esp_sntp_config { 69 bool smooth_sync; ///< set to true if smooth sync required 70 bool server_from_dhcp; ///< set to true to request NTP server config from DHCP 71 bool wait_for_sync; ///< if true, we create a semaphore to signal time sync event 72 bool start; ///< set to true to automatically start the SNTP service 73 esp_sntp_time_cb_t sync_cb; ///< optionally sets callback function on time sync event 74 bool renew_servers_after_new_IP; ///< this is used to refresh server list if NTP provided by DHCP (which cleans other pre-configured servers) 75 ip_event_t ip_event_to_renew; ///< set the IP event id on which we refresh server list (if renew_servers_after_new_IP=true) 76 size_t index_of_first_server; ///< refresh server list after this server (if renew_servers_after_new_IP=true) 77 size_t num_of_servers; ///< number of preconfigured NTP servers 78 const char* servers[CONFIG_LWIP_SNTP_MAX_SERVERS]; ///< list of servers 79 } esp_sntp_config_t; 80 81 /** 82 * @brief Initialize SNTP with supplied config struct 83 * @param config Config struct 84 * @return ESP_OK on success 85 */ 86 esp_err_t esp_netif_sntp_init(const esp_sntp_config_t * config); 87 88 /** 89 * @brief Start SNTP service 90 * if it wasn't started during init (config.start = false) 91 * or restart it if already started 92 * @return ESP_OK on success 93 */ 94 esp_err_t esp_netif_sntp_start(void); 95 96 /** 97 * @brief Deinitialize esp_netif SNTP module 98 */ 99 void esp_netif_sntp_deinit(void); 100 101 /** 102 * @brief Wait for time sync event 103 * @param tout Specified timeout in RTOS ticks 104 * @return ESP_TIMEOUT if sync event didn't came withing the timeout 105 * ESP_ERR_NOT_FINISHED if the sync event came, but we're in smooth update mode and still in progress (SNTP_SYNC_STATUS_IN_PROGRESS) 106 * ESP_OK if time sync'ed 107 */ 108 esp_err_t esp_netif_sntp_sync_wait(TickType_t tout); 109 110 /** 111 * @} 112 */ 113 114 #ifdef __cplusplus 115 } 116 #endif 117
