This library evolved from procedural code that I've been using for about a year. All feedback welcome.

The Timezone library facilitates time zone conversions and automatic daylight saving (summer) time adjustments. This is accomplished by setting a Real Time Clock (RTC) to Universal Coordinated Time (UTC) and then converting UTC to the correct local time, whether it is daylight saving time (a.k.a. summer time) or standard time.

The Timezone library is designed to work in conjunction with the Arduino Time library at http://www.arduino.cc/playground/Code/Time. To download and use the library, including documentation and example sketches:

Go to https://github.com/JChristensen/Timezone and click the ZIP button to download the repository as a ZIP file to a convenient location on your PC.

Uncompress the downloaded file. This will result in a folder containing all the files for the library, that has a name that includes the branch name, for example "Timezone-master".

Very usefull as there are many questions about getting the time zone right (after I had written an NTP-RTC article on the playground).

I am wondering about the DST algorithm, does it include Europe? did not dive into the code yet

Hi Rob, yes it should work for Europe, see the "WorldClock" example supplied with the library. The examples should work right out of the box on a bare Arduino. Glad to have you kick the tires, let me know if you find issues!

Should also work in the Southern hemisphere, I knew Nick would never let me live it down otherwise

The algorithm works from rules that you supply. For example, US Eastern Daylight Time, which has a UTC offset of -240 minutes, starts on the 2nd Sunday in March at 02:00 local time. So the rules are coded, in pairs, like this:

//Arizona is US Mountain Time Zone but does not use DSTTimezone usAZ(usMST, usMST);

Still there should be little harm in the additional constructor, so I think I will add it.

In reality there are more than 24 timezones, given that a lot of locales use DST. So to predefine the 24 "standard" time zones, i.e. Alpha, Bravo, Charlie, etc. may not be all that useful. I didn't intend the library to replace the tz database, and thereby be at the whim of numerous governmental decisions

1) should the EEPROM address be checked if it is valid / in range. And that there are 2 x 12 bytes free after it. Or a note in the readme.txt ...

2) _dst.offset * SECS_PER_MIN (+other) is calculated 8 times, maybe the internal representation could be an long which is calculated only once.you would get rid of all multiplications for only 4 bytes extra per TZ. Don't know if and how much smaller the footprint of the lib would become .

(1) The ReadMe does talk to the size of the TimeChangeRule, and that could be elaborated on. Being very conscious of resources, mostly size in this case, I'm not terribly inclined to check the address. I also see that the Arduino EEPROM library doesn't validate addresses.

(2) Yes that bothered me just a little. Like I said, I didn't want to waste space, but on the other hand I didn't sweat processing overhead terribly, my assumption there being that there just isn't a lot of reason to do time zone conversions very frequently. I'd think once per second would be about it, that being the typical RTC resolution. BUT still a good point that is worth experimenting with. One of those things that I just didn't think through any further at the time.

(2) I did some testing with the worldclock sample yesterday and a version in which the TimeChangeRule was using a long (calculated in the constructor) and no multiply in the functions was larger than the original. If I recall correctly orig==7508 and new==7632 This seems quite an increase as there are only 9*2 TimeChangeRules = 18 rules * 2 bytes = 36 bytes more memory and there should be less math...

(1) No big deal, EEPROM will probably wrap around as the higher addresslines are ignored...

Hi Jack, thanks for this fine library! I recently wrote decoder DCF77 library (for the atomic time broadcasted by the DCF77 radiostation) (see this thread) which now includes an example of usage together with your TimeZone library.

Before I read the TimeZone README I had not considered that converting from local time to UTC is ambiguous in the hour before switching to winter time. Luckily for us DCF77 users, the DCF77 data package includes info about DST, so in the latest version I added a function to the library that unambiguously converts CET to UTC time.

Hi mrTee, thanks for the feedback, glad you found the library useful! We have WWV here which is similar to DCF77 in that it has a DST/Summer time indicator. Have not tried a WWV receiver myself, although I do have several clocks around that pick up the signal.

Yes daylight and summer time is evil with the ambiguity. Back in the day, every fall we used to have to shut the mainframe computers down and let them sit for an hour, else, the system and applications could generate redundant time stamps in logs and such. I'll have to ask around and see if they ever fixed that! My preference is to always use UTC internally and convert it to local time for human consumption.

I am trying to work on a DCF77 radio controlled clock with timezome support but it guess I need a bit of help with finding the timezone selection.What I am trying to do is the following :I would like to be able to select a timezone (with switches on the Arduino board).At this moment I am stuck with the CET (Central European Time) showing on the LCD.

I was thinking if condition in the setSyncProvider line or unsigned long getDCFTime() {.... But no luck yet.

I don't see any logic in the sketch to actually read the switches, obviously that will be needed, and it will just need to set the pointer variable to the desired timezone. I think you're just asking about how to handle the timezone, so I'll assume you've got working with the switches figured out.

Here is a comprehensive example that works similarly. It uses US timezones rather than European but still should illustrate the technique https://github.com/JChristensen/PowerOutageMonitor_SW

Thank you very much for your help, pointers are indeed better than the if or if else conditions.Actually I already added the switches in the code because they will be used to select the timezone, instead of using a menu on LCD screen (I still have lots to learn, and I am not at this point yet).