Add library.properties file,

change to TimeLib.h (https://github.com/PaulStoffregen/Time), add function to read/update TimeChangeRules from RAM, update doc (README), update examples.
Phil-dav · Jan 2, 2018 · b33f21a · b33f21a
1 parent fc2d1ec
commit b33f21a
Show file tree

Hide file tree

Showing 11 changed files with 451 additions and 226 deletions.
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,11 +1,9 @@
-#Arduino Timezone Library v1.0
+#Arduino Timezone Library 1.1.0
 https://github.com/JChristensen/Timezone  
 LICENSE file  
 Jack Christensen Mar 2012  
 
 ![CC BY-SA](http://mirrors.creativecommons.org/presskit/buttons/88x31/png/by-sa.png)
 ##CC BY-SA
-Arduino Timezone Library by Jack Christensen is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to:  
-Creative Commons  
-444 Castro Street, Suite 900  
-Mountain View, CA 94041  
+Arduino Timezone Library by Jack Christensen is licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/).
+
diff --git a/ReadMe.md → README.md b/ReadMe.md → README.md
@@ -1,34 +1,30 @@
-# Arduino Timezone Library v1.0 #
+# Arduino Timezone Library 1.1.0
 https://github.com/JChristensen/Timezone  
-ReadMe file  
+README file  
 Jack Christensen Mar 2012  
 
 ![CC BY-SA](http://mirrors.creativecommons.org/presskit/buttons/80x15/png/by-sa.png)
 
-## Introduction ##
-The **Timezone** library is designed to work in conjunction with the [Arduino Time library](http://www.arduino.cc/playground/Code/Time).  The Time library must be installed and referenced in your sketch with `#include <Time.h>`.  This documentation assumes some familiarity with the Time library.
+## Introduction
+The **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.
 
-The 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; although the Time library can function as a software RTC without additional hardware, its accuracy is dependent on the accuracy of the microcontroller's system clock.
+The 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.)
 
 The **Timezone** library implements two objects to facilitate time zone conversions:
 - A **TimeChangeRule** object describes when local time changes to daylight (summer) time, or to standard time, for a particular locale.
 - 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.
 
-## Installation ##
-To use the **Timezone** library:  
-- Go to https://github.com/JChristensen/Timezone and click the **Download 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**.
-- Rename the folder to just **Timezone**.
-- Copy the renamed folder to the Arduino sketchbook\libraries folder.
-
-## Examples ##
+## Examples
 The following example sketches are included with the **Timezone** library:
+
 - **Clock:** A simple self-adjusting clock for a single time zone.  **TimeChangeRule**s may be optionally read from EEPROM.
 - **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.  
 - **WorldClock:** A self-adjusting clock for multiple time zones.
 - **WriteRules:** A sketch to write **TimeChangeRule**s to EEPROM.
+- **Change_TZ_1:** Changes between time zones by modifying the TimeChangeRules.
+- **Change_TZ_2:** Changes between time zones by selecting from an array of Timezone objects.
 
-## Coding TimeChangeRules ##
+## Coding TimeChangeRules
 Normally 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.
 
 As 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.
@@ -65,7 +61,7 @@ TimeChangeRule usEST = {"EST", First, Sun, Nov, 2, -300};   //UTC - 5 hours
 For a time zone that does not change to daylight/summer time, pass the same rule twice to the constructor, for example:  
 `Timezone usAZ(usMST, usMST);`
 
-## Coding Timezone objects ##
+## Coding Timezone objects
 There are two ways to define **Timezone** objects.
 
 By first defining **TimeChangeRule**s (as above) and giving the daylight time rule and the standard time rule (assuming usEDT and usEST defined as above):  
@@ -76,19 +72,19 @@ By reading rules previously stored in EEPROM.  This reads both the daylight and
 
 Note 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)`.
 
-## Timezone library methods ##
-Note that the `time_t` data type is defined by the Arduino Time library <Time.h>. See the [Time library documentation](http://www.arduino.cc/playground/Code/Time) for additional details.
+## Timezone library methods
+Note that the `time_t` data type is defined by the Arduino Time library <TimeLib.h>. 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.
 
-### time_t toLocal(time_t utc); ###
-##### Description #####
+### time_t toLocal(time_t utc);
+##### Description
 Converts the given UTC time to local time, standard or daylight as appropriate.
-##### Syntax #####
+##### Syntax
 `myTZ.toLocal(utc);`
-##### Parameters #####
+##### Parameters
 ***utc:*** Universal Coordinated Time *(time_t)*  
-##### Returns #####
+##### Returns 
 Local time *(time_t)*  
-##### Example #####
+##### Example
 ```c++
 time_t eastern, utc;
 TimeChangeRule usEDT = {"EDT", Second, Sun, Mar, 2, -240};  //UTC - 4 hours
@@ -98,18 +94,18 @@ utc = now();	//current time from the Time Library
 eastern = usEastern.toLocal(utc);
 ```
 
-### time_t toLocal(time_t utc, TimeChangeRule **tcr); ###
-##### Description #####
+### time_t toLocal(time_t utc, TimeChangeRule **tcr);
+##### Description
 As 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.
-##### Syntax #####
+##### Syntax
 `myTZ.toLocal(utc, &tcr);`  
-##### Parameters #####
+##### Parameters
 ***utc:*** Universal Coordinated Time *(time_t)*  
 ***tcr:*** Address of a pointer to a **TimeChangeRule** _(\*\*TimeChangeRule)_   
-##### Returns #####
+##### Returns
 Local time *(time_t)*  
 Pointer to **TimeChangeRule**  _(\*\*TimeChangeRule)_    
-##### Example #####
+##### Example
 ```c++
 time_t eastern, utc;
 TimeChangeRule *tcr;
@@ -122,37 +118,56 @@ Serial.print("The time zone is: ");
 Serial.println(tcr -> abbrev);
 ```
 
-### boolean utcIsDST(time_t utc); ###
-### boolean locIsDST(time_t local); ###
-##### Description #####
+### boolean utcIsDST(time_t utc);
+### boolean locIsDST(time_t local);
+##### Description
 These 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.
-##### Syntax #####
+##### Syntax
 `utcIsDST(utc);`  
 `locIsDST(local);`  
-##### Parameters #####
+##### Parameters
 ***utc:*** Universal Coordinated Time *(time_t)*  
 ***local:*** Local Time *(time_t)*  
-##### Returns #####
+##### Returns
 true or false *(boolean)*
-##### Example #####
+##### Example
 `if (usEastern.utcIsDST(utc)) { /*do something*/ }`
 
-### void readRules(int address); ###
-### void writeRules(int address); ###
-##### Description #####
+### void readRules(int address);
+### void writeRules(int address);
+##### Description
 These functions read or write a **Timezone** object's two **TimeChangeRule**s from or to EEPROM.
-##### Syntax #####
+##### Syntax
 `myTZ.readRules(address);`  
 `myTZ.writeRules(address);`  
-##### Parameters #####
+##### Parameters
 ***address:*** The beginning EEPROM address to write to or read from *(int)*
-##### Returns #####
+##### Returns
 None.
-##### Example #####
+##### Example
 `usEastern.writeRules(100);  //write rules beginning at EEPROM address 100`
 
-### time_t toUTC(time_t local); ###
-##### Description #####
+### void readRules(TimeChangeRule dstStart, TimeChangeRule stdStart);
+##### Description
+This function reads or updates the daylight and standard time rules from RAM. Can be used to change TimeChangeRules dynamically while a sketch runs.
+##### Syntax
+`myTZ.readRules(dstStart, stdStart);`  
+##### Parameters
+***dstStart:*** A TimeChangeRule denoting the start of daylight saving (summer) time.  
+***stdStart:*** A TimeChangeRule denoting the start of standard time.
+##### Returns
+None.
+##### Example
+```c++
+TimeChangeRule EDT = {"EDT", Second, Sun, Mar, 2, -240};
+TimeChangeRule EST = {"EST", First, Sun, Nov, 2, -300};
+Timezone ET(EDT, EST);
+...
+tz.readRules(EDT, EST);
+
+```
+### time_t toUTC(time_t local);
+##### Description
 Converts the given local time to UTC time.
 
 **WARNING:** This function is provided for completeness, but should seldom be needed and should be used sparingly and carefully.
@@ -164,9 +179,9 @@ This function does not test whether it is passed an erroneous time value during
 If 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.
 
 Calling this function with local times during a transition interval should be avoided!
-##### Syntax #####
+##### Syntax
 `myTZ.toUTC(local);`
-##### Parameters #####
+##### Parameters
 ***local:*** Local Time *(time_t)*  
-##### Returns #####
+##### Returns
 UTC *(time_t)*