From 00970d425a6a0b4afbabb10af268555e7c80e7fd Mon Sep 17 00:00:00 2001 From: czjaso Date: Tue, 27 Jan 2026 15:40:59 -0800 Subject: [PATCH 1/2] Add migration guide for v2.0.0 --- MigrationGuide.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 MigrationGuide.md diff --git a/MigrationGuide.md b/MigrationGuide.md new file mode 100644 index 0000000..2e669fb --- /dev/null +++ b/MigrationGuide.md @@ -0,0 +1,69 @@ +## coreSNTP version >=v2.0.0 Migration Guide + +With coreSNTP versions >=v2.0.0, there are breaking changes that need to be addressed when upgrading. + +### Breaking Changes + +* The `Sntp_ConvertToUnixTime` function now uses `uint32_t *` instead of `UnixTime_t *` for the Unix time seconds parameter. This change was made because: + - A `uint32_t` Unix timestamp can represent dates until February 7, 2106 06:28:15 UTC + - Beyond this date, we cannot differentiate between NTP era 0 and era 1 timestamps + - This provides a more accurate representation of the library's actual capabilities + +Thus, the signature of `Sntp_ConvertToUnixTime` changed from: +```c +SntpStatus_t Sntp_ConvertToUnixTime( const SntpTimestamp_t * pSntpTime, + UnixTime_t * pUnixTimeSecs, + uint32_t * pUnixTimeMicrosecs ); +``` + +to: + +```c +SntpStatus_t Sntp_ConvertToUnixTime( const SntpTimestamp_t * pSntpTime, + uint32_t * pUnixTimeSecs, + uint32_t * pUnixTimeMicrosecs ); +``` + +To migrate, update any code that uses `UnixTime_t` for storing the Unix time seconds value to use `uint32_t` instead. + +**Old Code Snippet**: +```c +SntpTimestamp_t sntpTime; +UnixTime_t unixTimeSecs; +uint32_t unixTimeMicrosecs; +SntpStatus_t status; + +// Assume sntpTime has been populated from an SNTP response + +status = Sntp_ConvertToUnixTime( &sntpTime, &unixTimeSecs, &unixTimeMicrosecs ); + +if( status == SntpSuccess ) +{ + // Use the Unix time + printf( "Unix time: %llu.%06u\n", ( unsigned long long ) unixTimeSecs, unixTimeMicrosecs ); +} +``` + +**New Code Snippet**: +```c +SntpTimestamp_t sntpTime; +uint32_t unixTimeSecs; +uint32_t unixTimeMicrosecs; +SntpStatus_t status; + +// Assume sntpTime has been populated from an SNTP response + +status = Sntp_ConvertToUnixTime( &sntpTime, &unixTimeSecs, &unixTimeMicrosecs ); + +if( status == SntpSuccess ) +{ + // Use the Unix time + printf( "Unix time: %u.%06u\n", unixTimeSecs, unixTimeMicrosecs ); +} +``` + +### Additional Changes + +* **Year 2038 Problem Fixed**: The library now properly handles timestamps beyond January 19, 2038 03:14:07 UTC (the traditional Unix timestamp overflow point for 32-bit signed integers). The library uses unsigned 32-bit integers and can represent dates until February 7, 2106. + +* **Improved Time Conversion**: The `Sntp_ConvertToUnixTime` function now includes proper overflow and underflow checking to ensure time conversions are handled safely. From 7fc3b0f149249a12a11f4af4451ad5ef1f0d792c Mon Sep 17 00:00:00 2001 From: czjaso Date: Tue, 27 Jan 2026 15:45:15 -0800 Subject: [PATCH 2/2] Add migration guide for going to v2.x.x. --- MigrationGuide.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/MigrationGuide.md b/MigrationGuide.md index 2e669fb..56523b4 100644 --- a/MigrationGuide.md +++ b/MigrationGuide.md @@ -6,8 +6,7 @@ With coreSNTP versions >=v2.0.0, there are breaking changes that need to be addr * The `Sntp_ConvertToUnixTime` function now uses `uint32_t *` instead of `UnixTime_t *` for the Unix time seconds parameter. This change was made because: - A `uint32_t` Unix timestamp can represent dates until February 7, 2106 06:28:15 UTC - - Beyond this date, we cannot differentiate between NTP era 0 and era 1 timestamps - - This provides a more accurate representation of the library's actual capabilities + - Beyond this date, we cannot differentiate between NTP era 0 and era 1 timestamps, thus it does not need to be a `uint64_t` Thus, the signature of `Sntp_ConvertToUnixTime` changed from: ```c @@ -36,12 +35,6 @@ SntpStatus_t status; // Assume sntpTime has been populated from an SNTP response status = Sntp_ConvertToUnixTime( &sntpTime, &unixTimeSecs, &unixTimeMicrosecs ); - -if( status == SntpSuccess ) -{ - // Use the Unix time - printf( "Unix time: %llu.%06u\n", ( unsigned long long ) unixTimeSecs, unixTimeMicrosecs ); -} ``` **New Code Snippet**: @@ -54,16 +47,4 @@ SntpStatus_t status; // Assume sntpTime has been populated from an SNTP response status = Sntp_ConvertToUnixTime( &sntpTime, &unixTimeSecs, &unixTimeMicrosecs ); - -if( status == SntpSuccess ) -{ - // Use the Unix time - printf( "Unix time: %u.%06u\n", unixTimeSecs, unixTimeMicrosecs ); -} -``` - -### Additional Changes - -* **Year 2038 Problem Fixed**: The library now properly handles timestamps beyond January 19, 2038 03:14:07 UTC (the traditional Unix timestamp overflow point for 32-bit signed integers). The library uses unsigned 32-bit integers and can represent dates until February 7, 2106. - -* **Improved Time Conversion**: The `Sntp_ConvertToUnixTime` function now includes proper overflow and underflow checking to ensure time conversions are handled safely. +``` \ No newline at end of file