{"id":13893743,"url":"https://github.com/JChristensen/Timezone","last_synced_at":"2025-07-17T08:30:42.394Z","repository":{"id":2723159,"uuid":"3717899","full_name":"JChristensen/Timezone","owner":"JChristensen","description":"Arduino library to facilitate time zone conversions and automatic daylight saving (summer) time adjustments.","archived":false,"fork":false,"pushed_at":"2025-04-25T17:28:48.000Z","size":65,"stargazers_count":287,"open_issues_count":3,"forks_count":103,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-25T18:37:40.597Z","etag":null,"topics":["arduino","arduino-library","time","timezone"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JChristensen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-03-14T13:33:30.000Z","updated_at":"2025-04-25T17:28:51.000Z","dependencies_parsed_at":"2024-11-25T00:00:26.361Z","dependency_job_id":null,"html_url":"https://github.com/JChristensen/Timezone","commit_stats":{"total_commits":34,"total_committers":3,"mean_commits":"11.333333333333334","dds":0.4411764705882353,"last_synced_commit":"7cf1425b4ee598573e85b6fa124d4514f71c2586"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/JChristensen/Timezone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FTimezone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FTimezone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FTimezone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FTimezone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JChristensen","download_url":"https://codeload.github.com/JChristensen/Timezone/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FTimezone/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265585272,"owners_count":23792712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","time","timezone"],"created_at":"2024-08-06T18:01:15.842Z","updated_at":"2025-07-17T08:30:42.055Z","avatar_url":"https://github.com/JChristensen.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# Arduino Timezone Library\nhttps://github.com/JChristensen/Timezone  \nREADME file  \nJack Christensen  \nMar 2012  \n\n## License\nArduino Timezone Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see \u003chttps://www.gnu.org/licenses/gpl.html\u003e\n\n## Introduction\nThe **Timezone** library is designed to work in conjunction with the [Arduino Time library](https://github.com/PaulStoffregen/Time), which must also be installed on your system. This documentation assumes some familiarity with the Time library.\n\nThe primary aim of the **Timezone** library is to convert Universal Coordinated Time (UTC) to the correct local time, whether it is daylight saving time (a.k.a. summer time) or standard time. The time source could be a GPS receiver, an NTP server, or a Real-Time Clock (RTC) set to UTC.  But whether a hardware RTC or other time source is even present is immaterial, since the Time library can function as a software RTC without additional hardware (although its accuracy is dependent on the accuracy of the microcontroller's system clock.)\n\nThe **Timezone** library implements two objects to facilitate time zone conversions:\n- A **TimeChangeRule** object describes when local time changes to daylight (summer) time, or to standard time, for a particular locale.\n- A **Timezone** object uses **TimeChangeRule**s to perform conversions and related functions.  It can also write its **TimeChangeRule**s to EEPROM, or read them from EEPROM.  Multiple time zones can be represented by defining multiple **Timezone** objects.\n\n## Examples\nThe following example sketches are included with the **Timezone** library:\n\n- **Clock:** A simple self-adjusting clock for a single time zone.  **TimeChangeRule**s may be optionally read from EEPROM.\n- **HardwareRTC:** A self-adjusting clock for one time zone using an external real-time clock, either a DS1307 or DS3231 (e.g. Chronodot) which is set to UTC.  \n- **WorldClock:** A self-adjusting clock for multiple time zones.\n- **WriteRules:** A sketch to write **TimeChangeRule**s to EEPROM.\n- **Change_TZ_1:** Changes between time zones by modifying the TimeChangeRules.\n- **Change_TZ_2:** Changes between time zones by selecting from an array of Timezone objects.\n\n## Coding TimeChangeRules\nNormally these will be coded in pairs for a given time zone: One rule to describe when daylight (summer) time starts, and one to describe when standard time starts.\n\nAs an example, here in the Eastern US time zone, Eastern Daylight Time (EDT) starts on the 2nd Sunday in March at 02:00 local time. Eastern Standard Time (EST) starts on the 1st Sunday in November at 02:00 local time.\n\nDefine a **TimeChangeRule** as follows:\n\n`TimeChangeRule myRule = {abbrev, week, dow, month, hour, offset};`\n\nWhere:\n\n**abbrev** is a character string abbreviation for the time zone; it must be no longer than five characters.\n\n**week** is the week of the month that the rule starts.\n\n**dow** is the day of the week that the rule starts.\n\n**hour** is the hour in local time that the rule starts (0-23).\n\n**offset** is the UTC offset _in minutes_ for the time zone being defined.\n\nFor convenience, the following symbolic names can be used:\n\n**week:** First, Second, Third, Fourth, Last  \n**dow:** Sun, Mon, Tue, Wed, Thu, Fri, Sat  \n**month:** Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec\n\nFor the Eastern US time zone, the **TimeChangeRule**s could be defined as follows:\n\n```c++\nTimeChangeRule usEDT = {\"EDT\", Second, Sun, Mar, 2, -240};  //UTC - 4 hours\nTimeChangeRule usEST = {\"EST\", First, Sun, Nov, 2, -300};   //UTC - 5 hours\n```\n\n## Coding Timezone objects\nThere are three ways to define **Timezone** objects.\n\nBy first defining **TimeChangeRule**s (as above) and giving the daylight time rule and the standard time rule (assuming usEDT and usEST defined as above):  \n`Timezone usEastern(usEDT, usEST);`\n\nFor a time zone that does not change to daylight/summer time, pass a single rule to the constructor. For example:  \n`Timezone usAZ(usMST, usMST);`\n\nBy reading rules previously stored in EEPROM.  This reads both the daylight and standard time rules previously stored at EEPROM address 100:  \n`Timezone usPacific(100);`\n\nNote that **TimeChangeRule**s require 12 bytes of storage each, so the pair of rules associated with a Timezone object requires 24 bytes total.  This could possibly change in future versions of the library.  The size of a **TimeChangeRule** can be checked with `sizeof(usEDT)`.\n\n## Timezone library methods\nNote that the `time_t` data type is defined by the Arduino Time library \u003cTimeLib.h\u003e. See the Time library documentation [here](https://playground.arduino.cc/Code/Time) and [here](https://www.pjrc.com/teensy/td_libs_Time.html) for additional details.\n\n### time_t toLocal(time_t utc);\n##### Description\nConverts the given UTC time to local time, standard or daylight as appropriate.\n##### Syntax\n`myTZ.toLocal(utc);`\n##### Parameters\n***utc:*** Universal Coordinated Time *(time_t)*  \n##### Returns \nLocal time *(time_t)*  \n##### Example\n```c++\ntime_t eastern, utc;\nTimeChangeRule usEDT = {\"EDT\", Second, Sun, Mar, 2, -240};  //UTC - 4 hours\nTimeChangeRule usEST = {\"EST\", First, Sun, Nov, 2, -300};   //UTC - 5 hours\nTimezone usEastern(usEDT, usEST);\nutc = now();\t//current time from the Time Library\neastern = usEastern.toLocal(utc);\n```\n\n### time_t toLocal(time_t utc, TimeChangeRule **tcr);\n##### Description\nAs above, converts the given UTC time to local time, and also returns a pointer to the **TimeChangeRule** that was applied to do the conversion. This could then be used, for example, to include the time zone abbreviation as part of a time display.  The caller must take care not to alter the pointed **TimeChangeRule**, as this will then result in incorrect conversions.\n##### Syntax\n`myTZ.toLocal(utc, \u0026tcr);`  \n##### Parameters\n***utc:*** Universal Coordinated Time *(time_t)*  \n***tcr:*** Address of a pointer to a **TimeChangeRule** _(\\*\\*TimeChangeRule)_   \n##### Returns\nLocal time *(time_t)*  \nPointer to **TimeChangeRule**  _(\\*\\*TimeChangeRule)_    \n##### Example\n```c++\ntime_t eastern, utc;\nTimeChangeRule *tcr;\nTimeChangeRule usEDT = {\"EDT\", Second, Sun, Mar, 2, -240};  //UTC - 4 hours\nTimeChangeRule usEST = {\"EST\", First, Sun, Nov, 2, -300};   //UTC - 5 hours\nTimezone usEastern(usEDT, usEST);\nutc = now();\t//current time from the Time Library\neastern = usEastern.toLocal(utc, \u0026tcr);\nSerial.print(\"The time zone is: \");\nSerial.println(tcr -\u003e abbrev);\n```\n\n### bool utcIsDST(time_t utc);\n### bool locIsDST(time_t local);\n##### Description\nThese functions determine whether a given UTC time or a given local time is within the daylight saving (summer) time interval, and return true or false accordingly.\n##### Syntax\n`utcIsDST(utc);`  \n`locIsDST(local);`  \n##### Parameters\n***utc:*** Universal Coordinated Time *(time_t)*  \n***local:*** Local Time *(time_t)*  \n##### Returns\ntrue or false *(bool)*\n##### Example\n`if (usEastern.utcIsDST(utc)) { /*do something*/ }`\n\n### void readRules(int address);\n### void writeRules(int address);\n##### Description\nThese functions read or write a **Timezone** object's two **TimeChangeRule**s from or to EEPROM.\n##### Syntax\n`myTZ.readRules(address);`  \n`myTZ.writeRules(address);`  \n##### Parameters\n***address:*** The beginning EEPROM address to write to or read from *(int)*\n##### Returns\nNone.\n##### Example\n`usEastern.writeRules(100);  //write rules beginning at EEPROM address 100`\n\n### void setRules(TimeChangeRule dstStart, TimeChangeRule stdStart);\n##### Description\nThis function reads or updates the daylight and standard time rules from RAM. Can be used to change TimeChangeRules dynamically while a sketch runs.\n##### Syntax\n`myTZ.setRules(dstStart, stdStart);`  \n##### Parameters\n***dstStart:*** A TimeChangeRule denoting the start of daylight saving (summer) time.  \n***stdStart:*** A TimeChangeRule denoting the start of standard time.\n##### Returns\nNone.\n##### Example\n```c++\nTimeChangeRule EDT = {\"EDT\", Second, Sun, Mar, 2, -240};\nTimeChangeRule EST = {\"EST\", First, Sun, Nov, 2, -300};\nTimezone ET(EDT, EST);\n...\ntz.setRules(EDT, EST);\n\n```\n### time_t toUTC(time_t local);\n##### Description\nConverts the given local time to UTC time.\n\n**WARNING:** This function is provided for completeness, but should seldom be needed and should be used sparingly and carefully.\n\nAmbiguous situations occur after the Standard-to-DST and the DST-to-Standard time transitions. When changing to DST, there is one hour of local time that does not exist, since the clock moves forward one hour. Similarly, when changing to standard time, there is one hour of local time that occurs twice since the clock moves back one hour.\n\nThis function does not test whether it is passed an erroneous time value during the Local-to-DST transition that does not exist. If passed such a time, an incorrect UTC time value will be returned.\n\nIf passed a local time value during the DST-to-Local transition that occurs twice, it will be treated as the earlier time, i.e. the time that occurs before the transition.\n\nCalling this function with local times during a transition interval should be avoided!\n##### Syntax\n`myTZ.toUTC(local);`\n##### Parameters\n***local:*** Local Time *(time_t)*  \n##### Returns\nUTC *(time_t)*  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJChristensen%2FTimezone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJChristensen%2FTimezone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJChristensen%2FTimezone/lists"}