NTP time with timezone and DST adjustement

[MrTinkerman]

Hi,

Based on: ntptime.py
and: Dutch DST begin/end datetimes
I wrote my own version that accepts a UTC offset(timezone) and adjusts for DST. DST adjustment is done by checking if the current UTC is within a DST-range for each year (2021-2037). The code is below.

There is one thing I don't completely understand though.
I would appreciate if someone could explain the following piece of code.

    EPOCH_YEAR = utime.gmtime(0)[0]
    
    if EPOCH_YEAR == 2000:
        # (date(2000, 1, 1) - date(1900, 1, 1)).days * 24*60*60
        NTP_DELTA = 3155673600
    elif EPOCH_YEAR == 1970:
        # (date(1970, 1, 1) - date(1900, 1, 1)).days * 24*60*60
        NTP_DELTA = 2208988800
    else:
        raise Exception("Unsupported epoch: {}".format(EPOCH_YEAR))

    return val - NTP_DELTA

I know Epoch starts at 1970.01.01 00:00
But where does 'NTP_DELTA' calculated on 1900, 1970 and 2000 come from?

Thanks.

My code:

import utime
import machine

try:
    import usocket as socket
except:
    import socket
try:
    import ustruct as struct
except:
    import struct

# UTC Epoch ranges in wich DST correction should be applied
# ranges for 2021 up until and including 2037
dst_ranges =[(1616893200, 1635645600), (1648342800, 1667095200), (1679792400, 1698544800), 
             (1711846800, 1729994400), (1743296400, 1761444000), (1774746000, 1792893600), 
             (1806195600, 1824948000), (1837645200, 1856397600), (1869094800, 1887847200), 
             (1901149200, 1919296800), (1932598800, 1950746400), (1964048400, 1982800800), 
             (1995498000, 2014250400), (2026947600, 2045700000), (2058397200, 2077149600), 
             (2090451600, 2108599200), (2121901200, 2140048800)]


def time(server, timeout):
    
    NTP_QUERY = bytearray(48)
    NTP_QUERY[0] = 0x1B
    addr = socket.getaddrinfo(server, 123)[0][-1]
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    
    try:
        s.settimeout(timeout)
        res = s.sendto(NTP_QUERY, addr)
        msg = s.recv(48)
    finally:
        s.close()
        
    val = struct.unpack("!I", msg[40:44])[0]
    
    EPOCH_YEAR = utime.gmtime(0)[0]
    
    if EPOCH_YEAR == 2000:
        # (date(2000, 1, 1) - date(1900, 1, 1)).days * 24*60*60
        NTP_DELTA = 3155673600
    elif EPOCH_YEAR == 1970:
        # (date(1970, 1, 1) - date(1900, 1, 1)).days * 24*60*60
        NTP_DELTA = 2208988800
    else:
        raise Exception("Unsupported epoch: {}".format(EPOCH_YEAR))

    return val - NTP_DELTA


def settime(server, server_timeout, utc_offset, dst):            # (NTP server, NTP server timeout in seconds,
                                                                 #  timezone offset from UTC, use DST True/False)
    utc = time(server, server_timeout)                           # utc is Epoch UTC time
    
    tz_adjust = utc_offset * 3600                                # Adjustment for timezone, (UTC offset in hours)*(seconds in one hour)
    dst_adjust = 0                                               # Set to zero in case DST is not requested
    
    if dst:                                                      # If DST adjustment is requested
        if any(lwr <= utc < upr for (lwr, upr) in dst_ranges):   # check if utc from server is in a DST range
            dst_adjust = 3600                                    # if so, add 3600 seconds (= one hour)
    
    lt = utime.gmtime(utc + tz_adjust + dst_adjust)              # lt is local time adjusted for timezone and DST                            

    machine.RTC().datetime((lt[0], lt[1], lt[2], lt[6],
                            lt[3], lt[4], lt[5], 0))

[scruss]

I know Epoch starts at 1970.01.01 00:00

Not on every MicroPython platform, though. Hence the checks.

[divergentti]

I don't know does this help, but I just wrote for ESP32 this script:

def weekday(year, month, day):
    # Returns weekday. Thanks to 2DOF @ Github
    t = [0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4]
    year -= month < 3
    return (year + int(year / 4) - int(year / 100) + int(year / 400) + t[month - 1] + day) % 7

def resolve_dst():
    (year, month, mdate, hour, minute, second, wday, yday) = localtime()   # supposed to be GMT/UTC
    match_days_begin = []
    match_days_end = []
    # Define the DST rules for the specified time zone
    # Replace these rules with the actual DST rules for your time zone
    dst_rules = {
        "begin": (3, 6, 2, 3),  # DST begin month, day, 1=first, 2=last at 03:00. 0= Monday, 6 = Sunday
            # March, last Sunday, 03:00
        "end": (10, 6, 2, 4),   # DST end  month, day, 1=first, 2=last at 04:00.
            # October, last Sunday, 04:00
        "timezone": 2,          # hours from UTC during normal (winter time)
        "offset": 1             # hours to be +/-
    }
    # Iterate begin
    if dst_rules["begin"][0] in (1,3,5,7,8,10,11):
        days_in_month = 30
    else:
        days_in_month = 31   # February does not matter here
    # Iterate months and find days matching criteria
    for x in range(days_in_month):
        if weekday(year,dst_rules["begin"][0],x) == dst_rules["begin"][1]:
            if dst_rules["begin"][2] == 2:  # last day first in the list
                match_days_begin.insert(0,x)
            else:
                match_days_begin.append(x)  # fist day first in the list
    dst_begin = mktime((year, dst_rules["begin"][0], match_days_begin[0], dst_rules["begin"][3], 0, 0,
                        dst_rules["begin"][1], 0))
    if dst_rules["end"][0] in (1,3,5,7,8,10,11):
        days_in_month = 30
    else:
        days_in_month = 31   # February does not matter here
    for x in range(days_in_month):
        if weekday(year,dst_rules["end"][0],x) == dst_rules["end"][1]:
            if dst_rules["end"][2] == 2:  # last day first in the list
                match_days_end.insert(0,x)
            else:
                match_days_end.append(x)  # fist day first in the list
    dst_end = mktime((year, dst_rules["end"][0], match_days_end[0], dst_rules["end"][3], 0, 0,
                        dst_rules["end"][1], 0))
    if (mktime(localtime()) < dst_begin) or (mktime(localtime()) > dst_end):
        return localtime(mktime(localtime()) + 3600 * dst_rules["timezone"])
    else:
        return localtime(mktime(localtime()) + (3600 * dst_rules["timezone"]) + (3600 * dst_rules["offset"]))

def resolve_date():
    (year, month, mdate, hour, minute, second, wday, yday) = resolve_dst()
    weekdays = ['Ma', 'Ti', 'Ke', 'To', 'Pe', 'La', 'Su']
    day = "%s.%s.%s" % (mdate, month, year)
    hours = "%s:%s:%s" % ("{:02d}".format(hour), "{:02d}".format(minute), "{:02d}".format(second))
    return day, hours, weekdays[wday]

Idea is to keep system RTC on GMT/UTC updated from the satellite and then on the display show correct time based on DST.

I am testing this in this [script] (https://github.com/divergentti/Micropython-for-ESP32/blob/main/esp32-gps-oled-bme680/main.py)

[kjm1102]

I wrote a little function for finding the time in Sydney AU. It uses +10 & +11 hrs for the winter / summer offsets & 3am Apr 1st / 2am Oct 1st as the local changeover times but should work for other offsets / change over times with a few edits.

def _showtime():
  year=gmtime()[0]; winter_shift=10*3600; summer_shift=11*3600; mo=['', 'Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
  summer=list(gmtime(mktime((year, 10, 1, 2, 0, 0, 0, 0)))); summer[2]+=(6-summer[6]); summer_utc=mktime(summer)-winter_shift                         # summer from 2am local 1st Sunday of Oct when we are 10 hrs ahead
  winter=list(gmtime(mktime((year, 4, 1, 3, 0, 0, 0, 0)))); winter[2]+=(6-winter[6]); winter_utc=mktime(winter)-summer_shift                          # winter from 3am local 1st Sunday of April when we are 11 hrs ahead
  print('change to winter epoch',winter_utc, '  change to summer epoch',summer_utc)
  tz=winter_shift if (winter_utc<time()<summer_utc) else summer_shift; utctuple=gmtime(); loctuple=gmtime(time()+tz)                                  # adjust time zone
  print('tz', tz, '  utc', utctuple, '  loc', loctuple)
  date=mo[loctuple[1]]+' %02d'%loctuple[2]; hr='  %02d:'%loctuple[3]; min='%02d'%loctuple[4]; print('local time', date+hr+min)  

ntptime.settime(); _showtime()

[villeneuve]

I have a small function that returns CET (Central European Time) from time.localtime()
Including daylight saving

# This code returns the Central European Time (CET) including daylight saving
# Winter (CET) is UTC+1H Summer (CEST) is UTC+2H
# Changes happen last Sundays of March (CEST) and October (CET) at 01:00 UTC
# Ref. formulas : http://www.webexhibits.org/daylightsaving/i.html
#                 Since 1996, valid through 2099

import time

def cettime():
    year = time.localtime()[0]       #get current year
    HHMarch   = time.mktime((year,3 ,(31-(int(5*year/4+4))%7),1,0,0,0,0,0)) #Time of March change to CEST
    HHOctober = time.mktime((year,10,(31-(int(5*year/4+1))%7),1,0,0,0,0,0)) #Time of October change to CET
    now=time.time()
    if now < HHMarch :               # we are before last sunday of march
        cet=time.localtime(now+3600) # CET:  UTC+1H
    elif now < HHOctober :           # we are before last sunday of october
        cet=time.localtime(now+7200) # CEST: UTC+2H
    else:                            # we are after last sunday of october
        cet=time.localtime(now+3600) # CET:  UTC+1H
    return(cet)

Exemple:

>>> from time import localtime
>>> localtime()
(2023, 6, 2, 16, 2, 37, 4, 153)
>>> from MyCetTime import cettime
>>> cettime()
(2023, 6, 2, 18, 3, 7, 4, 153)
>>> 

[omeErik]

thanks! really needed this.

[MrEbbinghaus]

If you set the RTC to a timezone other than UTC, you will break every existing function that promises to return UTC (like gmttime, time, time_ns, ...).

A better solution would be to use the offset only where the function says it would return local time.

I have a module my_time.py like this:

import time
TZ_OFFSET = 0

def localtime(secs=None):
  """Convert the time secs expressed in seconds since the Epoch into an 8-tuple which contains: (year, month, mday, hour, minute, second, weekday, yearday) If secs is not provided or None, then the current time from the RTC is used."""
  return time.localtime((secs if secs else time.time()) + TZ_OFFSET)

[rafaellago]

i don't know if this has been said before, but for this method to work, the call must be with TZ_OFFSET * 3600, otherwise, it will add/subtract only seconds from the UTC

[BenjaminEHowe]

@rafaellago I think it's intentional that TZ_OFFSET is measured in seconds -- not all timezones are a whole number of hours. See falsehoods programmers believe about time zones for a fun read.

[rafaellago]

Oh I agree. But as the original post hasn't specified this, I tried the code thinking it was in hours instead of seconds, and got a little confused. May these messages stay as a heads up for other newbies like me haha

[steka]

I agree with @MrEbbinghaus, but why not take it a bit futher.

In my projects I have used the abillity to extend a standard library.

That way replacing the standard time.localtime() with an own version that returns the local time of my region (Sweden), including the change to/from daylight saving time.

That will make the localtime function available to all modules that uses the standard time.localtime() function.

My time.py looks like this (Note that it has to be named time.py to replace the standard):

import sys

# Replace standard time.localtime()
#
# For more information about extending built in libraries, see:
# https://docs.micropython.org/en/latest/library/index.html#extending-built-in-libraries-from-python

_path = sys.path
sys.path = ()

try:
    from time import *
finally:
    sys.path = _path
    del _path


def localtime(secs: int | None = None) -> tuple[int, int, int, int, int, int, int, int]:
    """Returns Swedish local time.

    According to [Wikipedia](https://en.wikipedia.org/wiki/Time_in_Sweden)
    does Sweden observe daylight saving time
    from: the last Sunday in March (02:00 CET)
    to:   the last Sunday in October (03:00 CEST)
    """

    def last_sunday(year: int, month: int, hour: int, minute: int) -> int:
        """Get the time of the last sunday of the month
        It returns an integer which is the number of seconds since Jan 1, 2000, just like mktime().
        """

        # Get the UTC time of the last day of the month
        seconds = mktime((year, month + 1, 0, hour, minute, 0, None, None))

        # Calculate the offset to the last sunday of the month
        (year, month, mday, hour, minute, second, weekday, yearday) = gmtime(seconds)
        offset = (weekday + 1) % 7

        # Return the time of the last sunday of the month
        return mktime((year, month, mday - offset, hour, minute, second, None, None))

    utc = gmtime(secs)

    # Find start date for daylight saving, i.e. last Sunday in March (01:00 UTC)
    start_secs = last_sunday(year=utc[0], month=3, hour=1, minute=0)

    # Find stop date for daylight saving, i.e. last Sunday in October (01:00 UTC)
    stop_secs = last_sunday(year=utc[0], month=10, hour=1, minute=0)

    utc_secs = mktime(utc)
    if utc_secs >= start_secs and utc_secs < stop_secs:
        delta_secs = 2 * 60 * 60  # Swedish summer time (CEST or UTC + 2h)
    else:
        delta_secs = 1 * 60 * 60  # Swedish normal time (CET or UTC + 1h)

    return gmtime(utc_secs + delta_secs)