added three ntp server support

Author: zekageri

CHANGELOG.md

@@ -7,13 +7,14 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 ## [Unreleased]
 ### Added
 - `ESPDateConfig::usePSRAMBuffers` to prefer PSRAM-backed allocation for ESPDate-owned text/state buffers (timezone, NTP server, scoped TZ restore state) through `ESPBufferManager`, with automatic fallback to normal heap.
+- Multi-server NTP config support in `ESPDateConfig` via `ntpServer` (primary), `ntpServer2` (secondary), and `ntpServer3` (tertiary), with empty values ignored and compacted before calling `configTzTime`.
 - `isDstActive` helper to detect whether daylight saving time is in effect using a provided POSIX TZ string, the stored TZ config, or the current system TZ.
 - Moon phase calculation helpers returning phase angle and illumination for any `DateTime` (or `now()`).
 - Local time helpers: `nowLocal()` plus `toLocal(DateTime[, tz])` expose broken-out local components and UTC offset for debugging sunrise/sunset and DST handling.
 - Documented the recommended UTC storage + local UI workflow (convert user-picked local times back to UTC with `fromLocal`/`parseDateTimeLocal`).
 - `setNtpSyncCallback(...)` so applications can optionally react when SNTP reports a successful sync.
 - `setNtpSyncCallback(const NtpSyncCallable&)` overload so member methods can be registered via `std::bind`.
-- `syncNTP()` to immediately trigger a new SNTP sync using the configured NTP server.
+- `syncNTP()` to immediately trigger a new SNTP sync using the configured NTP server list.
 - `ntpSyncIntervalMs` config field plus `setNtpSyncIntervalMs(...)` runtime setter to override SNTP sync interval when runtime support is available.
 - Internal last-sync tracking plus `hasLastNtpSync()` / `lastNtpSync()` getters.
 - String formatting helpers for `DateTime`/`LocalDateTime` with buffer-based APIs plus `std::string` convenience wrappers (`nowUtcString`, `nowLocalString`, etc.).
@@ -23,7 +24,7 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 
 ### Changed
 - Replaced the `ESPDateConfig` constructor with an explicit `init(const ESPDateConfig&)` so configuration happens after the Arduino runtime is alive, avoiding early SNTP watchdog resets on some boards.
-- `ESPDateConfig` now accepts an `ntpServer`; when provided alongside `timeZone`, `init` calls `configTzTime` to set the TZ and bootstrap SNTP automatically.
+- `ESPDateConfig` now accepts up to three NTP servers; when at least one is provided alongside `timeZone`, `init` calls `configTzTime` to set the TZ and bootstrap SNTP automatically.
 
 ### Fixed
 - Restored builds by adding the missing internal `utils.h` helpers referenced by the sun/scheduler code paths.

README.md

@@ -19,7 +19,7 @@ ESPDate is a tiny C++17 helper for ESP32 projects that makes working with dates
 - **Sunrise / sunset**: compute daily sun times from lat/lon using numeric offsets or POSIX TZ strings (auto-DST aware).
 - **DST detection**: `isDstActive` reports whether daylight saving time applies using the stored TZ, an explicit POSIX TZ string, or the current system TZ.
 - **Moon phase**: `moonPhase` returns the current lunar phase angle and illumination fraction for any moment.
-- **Optional NTP bootstrap**: call `init` with `ESPDateConfig` containing both `timeZone` and `ntpServer` to set TZ and start SNTP after Arduino/WiFi is ready.
+- **Optional NTP bootstrap**: call `init` with `ESPDateConfig` containing `timeZone` and at least one NTP server (`ntpServer`, optional `ntpServer2`/`ntpServer3`) to set TZ and start SNTP after Arduino/WiFi is ready.
 - **NTP sync callback + manual re-sync**: register `setNtpSyncCallback(...)` with a function, lambda, or `std::bind`, call `syncNTP()` anytime to trigger an immediate refresh, and optionally override SNTP interval via `ntpSyncIntervalMs` / `setNtpSyncIntervalMs(...)`.
 - **Optional PSRAM-backed config/state buffers**: `ESPDateConfig::usePSRAMBuffers` routes ESPDate-owned text state (timezone/NTP/scoped TZ restore buffers) through `ESPBufferManager` with automatic fallback.
 - **Explicit lifecycle cleanup**: `deinit()` unregisters ESPDate-owned SNTP callback hooks, clears runtime config buffers, and is safe to call repeatedly; the destructor calls it automatically.
@@ -31,8 +31,8 @@ ESPDate is a tiny C++17 helper for ESP32 projects that makes working with dates
 - **Class-based API**: everything hangs off a single `ESPDate` instance; no global namespace clutter.
 - **Lightweight & portable**: C++17, header-first public API; relies only on standard C time functions and the system clock (`time()`).
 
-ESPDate does not configure SNTP by default. Call `init` with a POSIX TZ string plus an `ntpServer` to have ESPDate call `configTzTime` for you—do this after the Arduino runtime and WiFi are up to avoid early watchdog resets. Otherwise you remain in control of time-zone setup and system clock sync.
-`syncNTP()` returns `true` only when an NTP server is configured and the runtime supports `configTzTime`.
+ESPDate does not configure SNTP by default. Call `init` with a POSIX TZ string plus at least one NTP server (`ntpServer`, optional `ntpServer2`/`ntpServer3`) to have ESPDate call `configTzTime` for you. Do this after the Arduino runtime and WiFi are up to avoid early watchdog resets. Otherwise you remain in control of time-zone setup and system clock sync.
+`syncNTP()` returns `true` only when one or more NTP servers are configured and the runtime supports `configTzTime`.
 SNTP exposes a system-level sync hook, so the last `setNtpSyncCallback(...)` registration is the active callback.
 For the same reason, `lastNtpSync()` is tracked on the currently active `ESPDate` instance.
 Example member-method binding style:
@@ -63,9 +63,12 @@ void setup() {
 
     // Configure TZ + NTP after WiFi is connected if you want ESPDate to call configTzTime
     ESPDateConfig dateCfg{0.0f, 0.0f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000};
+    dateCfg.ntpServer2 = "time.google.com";
+    dateCfg.ntpServer3 = "time.cloudflare.com";
     dateCfg.usePSRAMBuffers = true; // optional: best effort, falls back automatically on non-PSRAM boards
     date.init(dateCfg);
 
+    // Single-server config remains valid as before.
     ESPDateConfig solarCfg{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000};
     solarCfg.usePSRAMBuffers = true;
     solar.init(solarCfg);
@@ -386,7 +389,10 @@ Bind your coordinates and TZ once via `init`, then fetch today’s sun cycle (au
 
 ```cpp
 ESPDate solar;
-solar.init(ESPDateConfig{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"});
+ESPDateConfig cfg{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"};
+cfg.ntpServer2 = "time.google.com";
+cfg.ntpServer3 = "time.cloudflare.com";
+solar.init(cfg);
 
 SunCycleResult rise = solar.sunrise();                     // today, using stored config
 SunCycleResult setToday = solar.sunset();                  // today, using stored config
@@ -456,7 +462,10 @@ See `examples/sun_cycle/sun_cycle.ino` for a full sketch. Key bits:
 
 ```cpp
 ESPDate solar;
-solar.init(ESPDateConfig{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"}); // call in setup after WiFi
+ESPDateConfig cfg{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"};
+cfg.ntpServer2 = "time.google.com";
+cfg.ntpServer3 = "time.cloudflare.com";
+solar.init(cfg); // call in setup after WiFi
 DateTime today = solar.now();
 
 SunCycleResult rise = solar.sunrise(today);
@@ -472,7 +481,7 @@ if (rise.ok && set.ok) {
 ```
 
 ## Gotchas
-- ESPDate configures SNTP only when you call `init` with both `timeZone` and `ntpServer` in `ESPDateConfig` (it calls `configTzTime`). Call it after WiFi is up, or ensure the device clock is set before calling `now()`. Sunrise/sunset use either the stored TZ string (if provided) or the current process TZ—make sure it matches the coordinates you pass.
+- ESPDate configures SNTP only when you call `init` with `timeZone` and at least one configured NTP server (`ntpServer`, `ntpServer2`, or `ntpServer3`) in `ESPDateConfig` (it calls `configTzTime`). Empty server strings are ignored and compacted. Call it after WiFi is up, or ensure the device clock is set before calling `now()`. Sunrise/sunset use either the stored TZ string (if provided) or the current process TZ; make sure it matches the coordinates you pass.
 - All arithmetic and comparisons are UTC-first. Local helpers rely on the current process TZ (`setenv("TZ", ...)`, `tzset()`); make sure that matches your deployment.
 - Month/year arithmetic clamps to the last valid day of the target month (e.g., Jan 31 + 1 month → Feb 28/29; Feb 29 - 1 year → Feb 28).
 - `differenceInDays` is purely `seconds / 86400` truncated toward zero, not a calendar-boundary delta.

examples/basic_date/basic_date.ino

@@ -27,7 +27,10 @@ void setup() {
   delay(200);
   Serial.println("ESPDate basic example");
   Serial.println("Connect WiFi so configTzTime can sync time, or set the system clock manually before using date.now().");
-  date.init(ESPDateConfig{0.0f, 0.0f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000});
+  ESPDateConfig cfg{0.0f, 0.0f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000};
+  cfg.ntpServer2 = "time.google.com";
+  cfg.ntpServer3 = "time.cloudflare.com";
+  date.init(cfg);
   date.setNtpSyncCallback(std::bind(&SyncObserver::onNtpSync, &syncObserver, std::placeholders::_1));
   date.setNtpSyncIntervalMs(10 * 60 * 1000);  // optional runtime update
   date.syncNTP();  // force an immediate refresh using configured NTP

examples/ntp_sync_tracking/ntp_sync_tracking.ino

@@ -26,9 +26,12 @@ void setup() {
   Serial.begin(115200);
   delay(200);
   Serial.println("ESPDate NTP sync tracking example");
-  Serial.println("Connect WiFi before this sketch runs so SNTP can reach the server.");
+  Serial.println("Connect WiFi before this sketch runs so SNTP can reach the configured servers.");
 
-  date.init(ESPDateConfig{0.0f, 0.0f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000});
+  ESPDateConfig cfg{0.0f, 0.0f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org", 15 * 60 * 1000};
+  cfg.ntpServer2 = "time.google.com";
+  cfg.ntpServer3 = "time.cloudflare.com";
+  date.init(cfg);
   date.setNtpSyncCallback([](const DateTime &syncedAtUtc) {
     char buf[32];
     if (syncedAtUtc.localString(buf, sizeof(buf))) {

examples/sun_cycle/sun_cycle.ino

@@ -17,7 +17,10 @@ void setup() {
   delay(250);
   Serial.println("ESPDate sun cycle example");
   Serial.println("Connect WiFi so configTzTime can sync time, or set system clock/TZ manually before running.");
-  solar.init(ESPDateConfig{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"});
+  ESPDateConfig cfg{47.4979f, 19.0402f, "CET-1CEST,M3.5.0/2,M10.5.0/3", "pool.ntp.org"};
+  cfg.ntpServer2 = "time.google.com";
+  cfg.ntpServer3 = "time.cloudflare.com";
+  solar.init(cfg);
 
   DateTime today = solar.now();
 

src/esp_date/date.cpp

@@ -199,7 +199,9 @@ void ESPDate::deinit() {
   ntpSyncIntervalMs_ = 0;
   const bool usePSRAM = usePSRAMBuffers_;
   timeZone_ = DateString(DateAllocator<char>(usePSRAM));
-  ntpServer_ = DateString(DateAllocator<char>(usePSRAM));
+  for (size_t i = 0; i < kMaxNtpServers; ++i) {
+    ntpServers_[i] = DateString(DateAllocator<char>(usePSRAM));
+  }
   usePSRAMBuffers_ = false;
   initialized_ = false;
 
@@ -219,18 +221,25 @@ void ESPDate::init(const ESPDateConfig& config) {
   hasLocation_ = true;
   usePSRAMBuffers_ = config.usePSRAMBuffers;
   timeZone_ = DateString(DateAllocator<char>(usePSRAMBuffers_));
-  ntpServer_ = DateString(DateAllocator<char>(usePSRAMBuffers_));
+  for (size_t i = 0; i < kMaxNtpServers; ++i) {
+    ntpServers_[i] = DateString(DateAllocator<char>(usePSRAMBuffers_));
+  }
   ntpSyncIntervalMs_ = config.ntpSyncIntervalMs;
   hasLastNtpSync_ = false;
   lastNtpSync_ = DateTime{};
 
   const bool hasTz = config.timeZone && config.timeZone[0] != '\0';
-  const bool hasNtp = config.ntpServer && config.ntpServer[0] != '\0';
+  const char* configuredNtpServers[kMaxNtpServers] = {config.ntpServer, config.ntpServer2, config.ntpServer3};
+  size_t ntpServerCount = 0;
   if (hasTz) {
     timeZone_ = config.timeZone;
   }
-  if (hasNtp) {
-    ntpServer_ = config.ntpServer;
+  for (size_t i = 0; i < kMaxNtpServers; ++i) {
+    const char* server = configuredNtpServers[i];
+    if (!server || server[0] == '\0') {
+      continue;
+    }
+    ntpServers_[ntpServerCount++] = server;
   }
 
   if (!applyNtpConfig() && hasTz) {
@@ -247,7 +256,7 @@ void ESPDate::setNtpSyncCallback(NtpSyncCallback callback) {
   activeNtpSyncCallback_ = callback;
   activeNtpSyncCallbackCallable_ = NtpSyncCallable{};
 #if ESPDATE_HAS_SNTP_NOTIFICATION_CB
-  const bool keepTrackingEnabled = !ntpServer_.empty();
+  const bool keepTrackingEnabled = hasAnyNtpServerConfigured();
   sntp_set_time_sync_notification_cb((callback || keepTrackingEnabled) ? &ESPDate::handleSntpSync : nullptr);
 #endif
 }
@@ -259,7 +268,7 @@ void ESPDate::setNtpSyncCallbackCallable(const NtpSyncCallable& callback) {
   activeNtpSyncCallback_ = nullptr;
   activeNtpSyncCallbackCallable_ = callback;
 #if ESPDATE_HAS_SNTP_NOTIFICATION_CB
-  const bool keepTrackingEnabled = !ntpServer_.empty();
+  const bool keepTrackingEnabled = hasAnyNtpServerConfigured();
   sntp_set_time_sync_notification_cb((static_cast<bool>(callback) || keepTrackingEnabled) ? &ESPDate::handleSntpSync
                                                                                            : nullptr);
 #endif
@@ -289,9 +298,18 @@ bool ESPDate::syncNTP() {
   return applyNtpConfig();
 }
 
+bool ESPDate::hasAnyNtpServerConfigured() const {
+  for (size_t i = 0; i < kMaxNtpServers; ++i) {
+    if (!ntpServers_[i].empty()) {
+      return true;
+    }
+  }
+  return false;
+}
+
 bool ESPDate::applyNtpConfig() const {
 #if ESPDATE_HAS_CONFIG_TZ_TIME
-  if (ntpServer_.empty()) {
+  if (!hasAnyNtpServerConfigured()) {
     return false;
   }
   activeNtpSyncOwner_ = const_cast<ESPDate*>(this);
@@ -310,7 +328,10 @@ bool ESPDate::applyNtpConfig() const {
 #endif
 
   const char* tz = timeZone_.empty() ? "UTC0" : timeZone_.c_str();
-  configTzTime(tz, ntpServer_.c_str(), nullptr, nullptr);
+  const char* ntpServer1 = ntpServers_[0].empty() ? nullptr : ntpServers_[0].c_str();
+  const char* ntpServer2 = ntpServers_[1].empty() ? nullptr : ntpServers_[1].c_str();
+  const char* ntpServer3 = ntpServers_[2].empty() ? nullptr : ntpServers_[2].c_str();
+  configTzTime(tz, ntpServer1, ntpServer2, ntpServer3);
   return true;
 #else
   return false;

src/esp_date/date.h

@@ -54,9 +54,11 @@ struct ESPDateConfig {
   float latitude = 0.0f;
   float longitude = 0.0f;
   const char* timeZone = nullptr;  // POSIX TZ string, e.g. "CET-1CEST,M3.5.0/2,M10.5.0/3"
-  const char* ntpServer = nullptr; // optional NTP server; used with timeZone to call configTzTime
+  const char* ntpServer = nullptr; // optional primary NTP server; used with timeZone to call configTzTime
   uint32_t ntpSyncIntervalMs = 0;  // optional SNTP sync interval override; 0 keeps runtime default
   bool usePSRAMBuffers = false;    // prefer PSRAM for ESPDate-owned config/state text buffers
+  const char* ntpServer2 = nullptr; // optional secondary NTP server
+  const char* ntpServer3 = nullptr; // optional tertiary NTP server
 };
 
 struct SunCycleResult {
@@ -101,7 +103,7 @@ class ESPDate {
   // Returns the last SNTP sync timestamp (UTC epoch-backed DateTime).
   // When hasLastNtpSync() is false this returns DateTime{}.
   DateTime lastNtpSync() const;
-  // Triggers an immediate NTP sync with the configured server.
+  // Triggers an immediate NTP sync with the configured server list.
   // Returns false when no NTP server is configured or SNTP runtime support is unavailable.
   bool syncNTP();
 
@@ -282,6 +284,7 @@ class ESPDate {
 #endif
   void setNtpSyncCallbackCallable(const NtpSyncCallable& callback);
   bool applyNtpConfig() const;
+  bool hasAnyNtpServerConfigured() const;
 
   SunCycleResult sunriseFromConfig(const DateTime& day) const;
   SunCycleResult sunsetFromConfig(const DateTime& day) const;
@@ -290,7 +293,8 @@ class ESPDate {
   float latitude_ = 0.0f;
   float longitude_ = 0.0f;
   DateString timeZone_;
-  DateString ntpServer_;
+  static constexpr size_t kMaxNtpServers = 3;
+  DateString ntpServers_[kMaxNtpServers];
   uint32_t ntpSyncIntervalMs_ = 0;
   bool usePSRAMBuffers_ = false;
   DateTime lastNtpSync_{};

test/test_esp_date/test_esp_date.cpp

@@ -7,10 +7,28 @@
 #include <functional>
 #include <string>
 
+#if defined(__has_include)
+#  if __has_include(<esp_sntp.h>) || __has_include(<esp_netif_sntp.h>)
+#    define TEST_ESPDATE_HAS_CONFIG_TZ_TIME 1
+#  else
+#    define TEST_ESPDATE_HAS_CONFIG_TZ_TIME 0
+#  endif
+#else
+#  define TEST_ESPDATE_HAS_CONFIG_TZ_TIME 0
+#endif
+
 ESPDate date;
 static const float kBudapestLat = 47.4979f;
 static const float kBudapestLon = 19.0402f;
 
+static bool expected_sync_result_with_any_ntp_server() {
+#if TEST_ESPDATE_HAS_CONFIG_TZ_TIME
+    return true;
+#else
+    return false;
+#endif
+}
+
 static void test_deinit_is_safe_before_init() {
     ESPDate monitor;
     TEST_ASSERT_FALSE(monitor.isInitialized());
@@ -267,6 +285,34 @@ static void test_sync_ntp_requires_server_config() {
     TEST_ASSERT_FALSE(onlyTimezone.syncNTP());
 }
 
+static void test_sync_ntp_accepts_secondary_or_tertiary_server_only() {
+    ESPDate secondaryOnly;
+    ESPDateConfig secondaryCfg{0.0f, 0.0f, "UTC0", nullptr};
+    secondaryCfg.ntpServer2 = "time.google.com";
+    secondaryOnly.init(secondaryCfg);
+    TEST_ASSERT_EQUAL(expected_sync_result_with_any_ntp_server(), secondaryOnly.syncNTP());
+
+    ESPDate tertiaryOnly;
+    ESPDateConfig tertiaryCfg{0.0f, 0.0f, "UTC0", nullptr};
+    tertiaryCfg.ntpServer3 = "time.cloudflare.com";
+    tertiaryOnly.init(tertiaryCfg);
+    TEST_ASSERT_EQUAL(expected_sync_result_with_any_ntp_server(), tertiaryOnly.syncNTP());
+}
+
+static void test_sync_ntp_with_three_servers_matches_single_server_behavior() {
+    ESPDate singleServer;
+    singleServer.init(ESPDateConfig{0.0f, 0.0f, "UTC0", "pool.ntp.org"});
+    const bool singleResult = singleServer.syncNTP();
+    TEST_ASSERT_EQUAL(expected_sync_result_with_any_ntp_server(), singleResult);
+
+    ESPDate threeServers;
+    ESPDateConfig threeServerCfg{0.0f, 0.0f, "UTC0", "pool.ntp.org"};
+    threeServerCfg.ntpServer2 = "time.google.com";
+    threeServerCfg.ntpServer3 = "time.cloudflare.com";
+    threeServers.init(threeServerCfg);
+    TEST_ASSERT_EQUAL(singleResult, threeServers.syncNTP());
+}
+
 struct NtpSyncTestObserver {
     int callCount = 0;
     int64_t lastEpoch = 0;
@@ -385,6 +431,8 @@ void setup() {
     RUN_TEST(test_to_local_breakdown);
     RUN_TEST(test_moon_phase_full_and_new_moon);
     RUN_TEST(test_sync_ntp_requires_server_config);
+    RUN_TEST(test_sync_ntp_accepts_secondary_or_tertiary_server_only);
+    RUN_TEST(test_sync_ntp_with_three_servers_matches_single_server_behavior);
     RUN_TEST(test_ntp_callback_registration_supports_member_binding);
     RUN_TEST(test_ntp_sync_interval_setter_accepts_default);
     RUN_TEST(test_last_ntp_sync_defaults_to_empty);