DST-safe sun-event fix

Author: zekageri

=7.0.0

@@ -0,0 +1,133 @@
+The following files/directories have been created in /tmp/tmpifu8myj4
+include - Put project header files here
+lib - Put project specific (private) libraries here
+src - Put project source files here
+platformio.ini - Project Configuration File
+Resolving esp32dev dependencies...
+Library Manager: Installing git+https://github.com/ESPToolKit/esp-buffer-manager.git
+git version 2.43.0
+Library Manager: ESPBufferManager@0.1.0+sha.a72e21b has been installed!
+Already up-to-date.
+Project has been successfully initialized!
+Processing esp32dev (platform: https://github.com/pioarduino/platform-espressif32.git; board: esp32dev; framework: arduino)
+--------------------------------------------------------------------------------
+Verbose mode can be enabled via `-v, --verbose` option
+CONFIGURATION: https://docs.platformio.org/page/boards/espressif32/esp32dev.html
+PLATFORM: Espressif 32 (55.3.37+sha.a9fac07) > Espressif ESP32 Dev Module
+HARDWARE: ESP32 240MHz, 320KB RAM, 4MB Flash
+DEBUG: Current (cmsis-dap) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
+PACKAGES: 
+ - contrib-piohome @ 3.4.4 
+ - framework-arduinoespressif32 @ 3.3.7 
+ - framework-arduinoespressif32-libs @ 5.5.0+sha.87912cd291 
+ - tool-esptoolpy @ 5.1.2 
+ - toolchain-xtensa-esp-elf @ 14.2.0+20251107
+LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf
+LDF Modes: Finder ~ chain, Compatibility ~ soft
+Library Manager: Installing ArduinoJson
+Unpacking 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100%
+Library Manager: ArduinoJson@7.4.3 has been installed!
+Found 46 compatible libraries
+Scanning dependencies...
+Dependency Graph
+|-- ArduinoJson @ 7.4.3
+|-- ESPDate @ 1.0.2
+Building in release mode
+Compiling .pio/build/esp32dev/libaff/ESPBufferManager/esp_buffer_manager/buffer_manager.cpp.o
+Compiling .pio/build/esp32dev/libe64/esp-date/esp_date/date.cpp.o
+Compiling .pio/build/esp32dev/libe64/esp-date/esp_date/moon.cpp.o
+Compiling .pio/build/esp32dev/libe64/esp-date/esp_date/sun.cpp.o
+Compiling .pio/build/esp32dev/src/test_esp_date.cpp.o
+Building .pio/build/esp32dev/bootloader.bin
+Generating partitions .pio/build/esp32dev/partitions.bin
+Compiling .pio/build/esp32dev/FrameworkArduino/ColorFormat.c.o
+esptool v5.1.2
+Creating ESP32 image...
+Merged 2 ELF sections.
+Successfully created ESP32 image.
+Compiling .pio/build/esp32dev/FrameworkArduino/Esp.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/FirmwareMSC.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/FunctionalInterrupt.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/HEXBuilder.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/HWCDC.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/HardwareSerial.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/HashBuilder.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/IPAddress.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/MD5Builder.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/MacAddress.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/Print.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/Stream.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/StreamString.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/Tone.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/USB.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/USBCDC.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/USBMSC.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/WMath.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/WString.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/base64.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/cbuf.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/chip-debug-report.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-adc.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-bt.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-cpu.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-dac.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-gpio.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-hosted.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-i2c-ng.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-i2c-slave.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-i2c.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-ledc.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-log-wrapper.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-matrix.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-misc.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-periman.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-psram.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-rgb-led.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-rmt.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-sigmadelta.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-spi.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-time.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-timer.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-tinyusb.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-touch-ng.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-touch.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/esp32-hal-uart.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/firmware_msc_fat.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/freertos_stats.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/idf_openthread_mpool_wrapper.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/libb64/cdecode.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/libb64/cencode.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/main.cpp.o
+Compiling .pio/build/esp32dev/FrameworkArduino/stdlib_noniso.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/wiring_pulse.c.o
+Compiling .pio/build/esp32dev/FrameworkArduino/wiring_shift.c.o
+Archiving .pio/build/esp32dev/libFrameworkArduino.a
+Indexing .pio/build/esp32dev/libFrameworkArduino.a
+Linking .pio/build/esp32dev/firmware.elf
+                            Memory Type Usage Summary                             
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ Memory Type/Section ┃ Used [bytes] ┃ Used [%] ┃ Remain [bytes] ┃ Total [bytes] ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ Flash Code          │       258196 │          │                │               │
+│    .text            │       258196 │          │                │               │
+│ Flash Data          │        94352 │          │                │               │
+│    .rodata          │        94096 │          │                │               │
+│    .appdesc         │          256 │          │                │               │
+│ IRAM                │        68559 │    52.31 │          62513 │        131072 │
+│    .text            │        67531 │    51.52 │                │               │
+│    .vectors         │         1028 │     0.78 │                │               │
+│ DRAM                │        28310 │    22.72 │          96270 │        124580 │
+│    .data            │        18230 │    14.63 │                │               │
+│    .bss             │        10080 │     8.09 │                │               │
+└─────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘
+Retrieving maximum program size .pio/build/esp32dev/firmware.elf
+Checking size .pio/build/esp32dev/firmware.elf
+Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
+RAM:   [=         ]   8.6% (used 28312 bytes from 327680 bytes)
+Flash: [===       ]  33.5% (used 439081 bytes from 1310720 bytes)
+Building .pio/build/esp32dev/firmware.bin
+esptool v5.1.2
+Creating ESP32 image...
+Merged 2 ELF sections.
+Successfully created ESP32 image.
+========================= [SUCCESS] Took 19.47 seconds =========================

CHANGELOG.md

@@ -21,6 +21,7 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 - Added `lastNtpSyncStringLocal/Utc` helpers (buffer + `std::string`) to serialize the last NTP sync timestamp directly.
 - Added direct `DateTime::utcString/localString` and `LocalDateTime::localString` methods so standalone values can be formatted without an `ESPDate` round-trip.
 - Added focused example sketches: `examples/string_helpers` and `examples/ntp_sync_tracking`.
+- Added additive NTP sync listeners via `addNtpSyncListener(...)` / `removeNtpSyncListener(...)` so multiple consumers can observe sync events without replacing the primary callback.
 
 ### 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.
@@ -30,6 +31,7 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 - Restored builds by adding the missing internal `utils.h` helpers referenced by the sun/scheduler code paths.
 - Resolved ambiguous `setNtpSyncCallback(...)` overload selection for non-capturing lambdas on ESP32 toolchains.
 - Added `ESPDate::deinit()` and destructor cleanup so a destroyed active instance releases SNTP callback ownership instead of leaving stale global callback state.
+- Sunrise/sunset now resolve UTC results from the event's local wall-clock time instead of the query timestamp offset, which keeps DST transition days stable before and after the clock change.
 
 ## [1.0.1] - 2025-12-09
 ### Added

README.md

@@ -16,11 +16,11 @@ ESPDate is a tiny C++17 helper for ESP32 projects that makes working with dates
 - **Formatting / parsing**: ISO-8601 and `YYYY-MM-DD HH:MM:SS` helpers, plus `strftime`-style patterns for UTC or local time.
 - **String helpers**: embedded-safe buffer methods and `std::string` convenience wrappers for `DateTime`, `LocalDateTime`, `nowUtc`, and `nowLocal`.
 - **Direct value formatting**: `DateTime::localString/utcString` and `LocalDateTime::localString` let individual values format themselves.
-- **Sunrise / sunset**: compute daily sun times from lat/lon using numeric offsets or POSIX TZ strings (auto-DST aware).
+- **Sunrise / sunset**: compute daily sun times from lat/lon using numeric offsets or POSIX TZ strings (auto-DST aware, resolved at the event time on DST transition days).
 - **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 `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(...)`.
+- **NTP sync callback + listeners + manual re-sync**: register `setNtpSyncCallback(...)` plus additive `addNtpSyncListener(...)` observers, 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.
 - **Init-state introspection**: `isInitialized()` reports whether `init(...)` has been called without a matching `deinit()`.
@@ -35,6 +35,7 @@ ESPDate does not configure SNTP by default. Call `init` with a POSIX TZ string p
 `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.
+`addNtpSyncListener(...)` attaches extra observers on that active instance without replacing the primary callback; use the returned token with `removeNtpSyncListener(...)` to detach them.
 Example member-method binding style:
 `date.setNtpSyncCallback(std::bind(&App::handleNTPSync, this, std::placeholders::_1));`
 Set interval from config or at runtime:
@@ -160,7 +161,7 @@ date.formatLocal(when, ESPDateFormat::DateTime, buf, sizeof(buf));
 Serial.printf("Scheduled for local time: %s\n", buf);
 ```
 
-Sunrise/sunset use your configured TZ (or system TZ) to compute the correct local event, but they return a UTC-backed `DateTime`. Use `formatLocal`/`toLocal` to display those events in local time.
+Sunrise/sunset use your configured TZ (or system TZ) to compute the correct local event, but they return a UTC-backed `DateTime`. Use `formatLocal`/`toLocal` to display those events in local time. On DST transition days, ESPDate resolves the UTC result from the event's local wall-clock time, so sunrise/sunset remain stable for the whole local day even if you query before and after the clock change.
 
 ## Date & Time Model
 `DateTime` is a small value type representing a moment in time, backed by seconds since the Unix epoch:
@@ -212,6 +213,8 @@ public:
     bool setNtpSyncIntervalMs(uint32_t intervalMs);
     bool hasLastNtpSync() const;
     DateTime lastNtpSync() const;
+    NtpSyncListenerId addNtpSyncListener(const NtpSyncCallable &listener);
+    bool removeNtpSyncListener(NtpSyncListenerId id);
     bool syncNTP();
 
     bool dateTimeToStringUtc(const DateTime &dt, char *outBuffer, size_t outSize, ESPDateFormat style = ESPDateFormat::DateTime) const;

src/esp_date/date.cpp

@@ -71,16 +71,7 @@ void ESPDate::handleSntpSync(struct timeval *tv) {
 	}
 	const DateTime syncedAtUtc{syncedEpoch};
 	if (activeNtpSyncOwner_) {
-		activeNtpSyncOwner_->lastNtpSync_ = syncedAtUtc;
-		activeNtpSyncOwner_->hasLastNtpSync_ = true;
-	}
-
-	if (activeNtpSyncCallbackCallable_) {
-		activeNtpSyncCallbackCallable_(syncedAtUtc);
-		return;
-	}
-	if (activeNtpSyncCallback_) {
-		activeNtpSyncCallback_(syncedAtUtc);
+		activeNtpSyncOwner_->dispatchNtpSync(syncedAtUtc);
 	}
 }
 #endif
@@ -202,6 +193,11 @@ void ESPDate::deinit() {
 	ntpSyncCallbackCallable_ = NtpSyncCallable{};
 	hasLastNtpSync_ = false;
 	lastNtpSync_ = DateTime{};
+	nextNtpSyncListenerId_ = 1;
+	for (size_t i = 0; i < kMaxNtpSyncListeners; ++i) {
+		ntpSyncListeners_[i].id = 0;
+		ntpSyncListeners_[i].listener = NtpSyncCallable{};
+	}
 	hasLocation_ = false;
 	latitude_ = 0.0f;
 	longitude_ = 0.0f;
@@ -307,10 +303,62 @@ DateTime ESPDate::lastNtpSync() const {
 	return lastNtpSync_;
 }
 
+ESPDate::NtpSyncListenerId ESPDate::addNtpSyncListener(const NtpSyncCallable &listener) {
+	if (!listener) {
+		return 0;
+	}
+	for (size_t i = 0; i < kMaxNtpSyncListeners; ++i) {
+		if (ntpSyncListeners_[i].id != 0) {
+			continue;
+		}
+		NtpSyncListenerId id = nextNtpSyncListenerId_++;
+		if (id == 0) {
+			id = nextNtpSyncListenerId_++;
+		}
+		ntpSyncListeners_[i].id = id;
+		ntpSyncListeners_[i].listener = listener;
+		return id;
+	}
+	return 0;
+}
+
+bool ESPDate::removeNtpSyncListener(NtpSyncListenerId id) {
+	if (id == 0) {
+		return false;
+	}
+	for (size_t i = 0; i < kMaxNtpSyncListeners; ++i) {
+		if (ntpSyncListeners_[i].id != id) {
+			continue;
+		}
+		ntpSyncListeners_[i].id = 0;
+		ntpSyncListeners_[i].listener = NtpSyncCallable{};
+		return true;
+	}
+	return false;
+}
+
 bool ESPDate::syncNTP() {
 	return applyNtpConfig();
 }
 
+void ESPDate::dispatchNtpSync(const DateTime &syncedAtUtc) {
+	lastNtpSync_ = syncedAtUtc;
+	hasLastNtpSync_ = true;
+
+	if (activeNtpSyncCallbackCallable_) {
+		activeNtpSyncCallbackCallable_(syncedAtUtc);
+	} else if (activeNtpSyncCallback_) {
+		activeNtpSyncCallback_(syncedAtUtc);
+	}
+
+	for (size_t i = 0; i < kMaxNtpSyncListeners; ++i) {
+		if (!ntpSyncListeners_[i].listener) {
+			continue;
+		}
+		ntpSyncListeners_[i].listener(syncedAtUtc);
+	}
+}
+
 bool ESPDate::hasAnyNtpServerConfigured() const {
 	for (size_t i = 0; i < kMaxNtpServers; ++i) {
 		if (!ntpServers_[i].empty()) {

src/esp_date/date.h

@@ -75,6 +75,7 @@ class ESPDate {
   public:
 	using NtpSyncCallback = void (*)(const DateTime &syncedAtUtc);
 	using NtpSyncCallable = std::function<void(const DateTime &syncedAtUtc)>;
+	using NtpSyncListenerId = uint32_t;
 
 	ESPDate();
 	~ESPDate();
@@ -103,6 +104,8 @@ class ESPDate {
 	// Returns the last SNTP sync timestamp (UTC epoch-backed DateTime).
 	// When hasLastNtpSync() is false this returns DateTime{}.
 	DateTime lastNtpSync() const;
+	NtpSyncListenerId addNtpSyncListener(const NtpSyncCallable &listener);
+	bool removeNtpSyncListener(NtpSyncListenerId id);
 	// 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();
@@ -307,6 +310,7 @@ class ESPDate {
 	static void handleSntpSync(struct timeval *tv);
 #endif
 #endif
+	void dispatchNtpSync(const DateTime &syncedAtUtc);
 	void setNtpSyncCallbackCallable(const NtpSyncCallable &callback);
 	bool applyNtpConfig() const;
 	bool hasAnyNtpServerConfigured() const;
@@ -326,9 +330,21 @@ class ESPDate {
 	bool hasLastNtpSync_ = false;
 	NtpSyncCallback ntpSyncCallback_ = nullptr;
 	NtpSyncCallable ntpSyncCallbackCallable_;
+	struct NtpSyncListenerSlot {
+		NtpSyncListenerId id = 0;
+		NtpSyncCallable listener{};
+	};
+	static constexpr size_t kMaxNtpSyncListeners = 4;
+	NtpSyncListenerSlot ntpSyncListeners_[kMaxNtpSyncListeners]{};
+	NtpSyncListenerId nextNtpSyncListenerId_ = 1;
 	static NtpSyncCallback activeNtpSyncCallback_;
 	static NtpSyncCallable activeNtpSyncCallbackCallable_;
 	static ESPDate *activeNtpSyncOwner_;
 	bool hasLocation_ = false;
 	bool initialized_ = false;
+
+  public:
+	void _testDispatchNtpSync(const DateTime &syncedAtUtc) {
+		dispatchNtpSync(syncedAtUtc);
+	}
 };