Improved documentation regarding non-AVR architectures, constructor, …

…begin() function.

Change license to GNU GPL 3.0.
Cosmetic and style changes.

README.md

@@ -1,9 +1,17 @@
 # Arduino DS3232RTC Library
 https://github.com/JChristensen/DS3232RTC  
 README file  
-Jack Christensen Mar 2013
+Jack Christensen  
+Mar 2013
 
-![CC BY-SA](http://mirrors.creativecommons.org/presskit/buttons/80x15/png/by-sa.png)
+## License
+Arduino DS3232RTC Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0
+
+This 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.
+
+This 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.
+
+You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/gpl.html>
 
 ## Introduction
 **DS3232RTC** is an Arduino library that supports the Maxim Integrated DS3232 and DS3231 Real-Time Clocks. This library is intended to be used with [PJRC's Arduino Time library](https://github.com/PaulStoffregen/Time).
@@ -12,8 +20,6 @@ The **DS3232RTC** library is a drop-in replacement for the (older) DS1307RTC.h l
 
 **DS3232RTC** also implements functions to support the additional features of the DS3232 and DS3231. The DS3231 has the same features as the DS3232 except: (1) Battery-backed SRAM, (2) Battery-backed 32kHz output (BB32kHz bit in Control/Status register 0x0F), and (3) Adjustable temperature sensor sample rate (CRATE1:0 bits in the Control/Status register).
 
-"Arduino DS3232RTC Library" by Jack Christensen is licensed under CC BY-SA 4.0.
-
 ## Examples
 The following example sketches are included with the **DS3232RTC** library:
 
@@ -26,12 +32,10 @@ The following example sketches are included with the **DS3232RTC** library:
 
 When using the **DS3232RTC** library, the user is responsible for ensuring that reads and writes do not exceed the device's address space (0x00-0x12 for DS3231, 0x00-0xFF for DS3232); no bounds checking is done by the library.            
 
-Similar to the **DS1307RTC** library, the **DS3232RTC** library instantiates an RTC object; the user does not need to do this.
-
 ## Enumerations
 ### SQWAVE_FREQS_t
 ##### Description
-Symbolic names used with the squareWave() method (described below).
+Symbolic names used with the squareWave() function (described below).
 ##### Values
 - SQWAVE_NONE
 - SQWAVE_1_HZ
@@ -41,7 +45,7 @@ Symbolic names used with the squareWave() method (described below).
 
 ### ALARM_TYPES_t
 ##### Description
-Symbolic names used with the setAlarm() method (described below).
+Symbolic names used with the setAlarm() function (described below).
 ##### Values for Alarm 1
 - ALM1_EVERY_SECOND -- causes an alarm once per second.
 - ALM1_MATCH_SECONDS -- causes an alarm when the seconds match (i.e. once per minute).
@@ -57,9 +61,42 @@ Symbolic names used with the setAlarm() method (described below).
 - ALM2_MATCH_DATE -- causes an alarm when the date of the month *and* hours *and* minutes match.
 - ALM2_MATCH_DAY -- causes an alarm when the day of the week *and* hours *and* minutes match.
 
+## Constructor
+### DS3232RTC(bool initI2C)
+##### Description
+For AVR architecture only (for backwards compatibility with the **DS1307RTC** library), the **DS3232RTC** library instantiates a DS3232RTC object named `RTC`; the user should not use the constructor for AVR boards. For other architectures, the user's code must instantiate a DS3232RTC object.
+##### Syntax
+`DS3232RTC myRTC(initI2C);`
+##### Parameters
+**initI2C:** An optional parameter to control whether the constructor initializes the I2C bus. The default is true (again for backwards compatibility). *(bool)*
+##### Returns
+None.
+##### Example
+```c++
+// For non-AVR boards only. Not needed for AVR boards.
+DS3232RTC myRTC(false);     // tell constructor not to initialize the I2C bus.
+```
 
-## Methods for setting and reading the time
+## Initialization function
+### begin()
+##### Description
+Initializes the I2C bus. For use with non-AVR architectures where the user has instantiated a DS3232RTC object and specified no initialization in the constructor (see above).
+##### Syntax
+`begin();`
+##### Parameters
+None.
+##### Returns
+None.
+##### Example
+```c++
+// For non-AVR boards only. Not needed for AVR boards.
+DS3232RTC myRTC(false);     // tell constructor not to initialize the I2C bus.
+void setup() {
+    myRTC.begin();          // initialize the I2C bus here.
+}
+```
 
+## Functions for setting and reading the time
 ### get(void)
 ##### Description
 Reads the current date and time from the RTC and returns it as a *time_t* value. Returns zero if an I2C error occurs (RTC not present, etc.).
@@ -134,7 +171,7 @@ tm.Year = 2009 - 1970;    //tmElements_t.Year is the offset from 1970
 RTC.write(tm);            //set the RTC from the tm structure
 ```
 
-## Methods for reading and writing RTC registers or static RAM (SRAM) for the DS3232
+## Functions for reading and writing RTC registers or static RAM (SRAM) for the DS3232
 The DS3232RTC.h file defines symbolic names for the timekeeping, alarm, status and control registers. These can be used for the addr argument in the functions below.
 
 ### writeRTC(byte addr, byte *values, byte nBytes)
@@ -203,12 +240,12 @@ byte val;
 val = RTC.readRTC(3);  //read the value from SRAM location 3
 ```
 
-## Alarm methods
+## Alarm functions
 The DS3232 and DS3231 have two alarms. Alarm1 can be set to seconds precision; Alarm2 can only be set to minutes precision.
 
 ### setAlarm(ALARM_TYPES_t alarmType, byte seconds, byte minutes, byte hours, byte daydate)
 ##### Description
-Set an alarm time. Sets the alarm registers only.  To cause the INT pin to be asserted on alarm match, use alarmInterrupt(). This method can set either Alarm 1 or Alarm 2, depending on the value of alarmType (use the ALARM_TYPES_t enumeration above). When setting Alarm 2, the seconds value must be supplied but is ignored, recommend using zero. (Alarm 2 has no seconds register.)
+Set an alarm time. Sets the alarm registers only.  To cause the INT pin to be asserted on alarm match, use alarmInterrupt(). This function can set either Alarm 1 or Alarm 2, depending on the value of alarmType (use the ALARM_TYPES_t enumeration above). When setting Alarm 2, the seconds value must be supplied but is ignored, recommend using zero. (Alarm 2 has no seconds register.)
 
 ##### Syntax
 `RTC.setAlarm(alarmType, seconds, minutes, hours, dayOrDate);`
@@ -228,7 +265,7 @@ RTC.setAlarm(ALM1_MATCH_DAY, 56, 34, 12, dowSunday);
 
 ### setAlarm(ALARM_TYPES_t alarmType, byte minutes, byte hours, byte daydate)
 ##### Description
-Set an alarm time. Sets the alarm registers only.  To cause the INT pin to be asserted on alarm match, use alarmInterrupt().  This method can set either Alarm 1 or Alarm 2, depending on the value of alarmType (use the ALARM_TYPES_t enumeration above). However, when using this method to set Alarm 1, the seconds value is set to zero. (Alarm 2 has no seconds register.)
+Set an alarm time. Sets the alarm registers only.  To cause the INT pin to be asserted on alarm match, use alarmInterrupt().  This functiuon can set either Alarm 1 or Alarm 2, depending on the value of alarmType (use the ALARM_TYPES_t enumeration above). However, when using this function to set Alarm 1, the seconds value is set to zero. (Alarm 2 has no seconds register.)
 
 ##### Syntax
 `RTC.setAlarm(alarmType, minutes, hours, dayOrDate);`
@@ -281,7 +318,7 @@ else {
 }
 ```
 
-## Other methods
+## Other function
 ### temperature(void)
 ##### Description
 Returns the RTC temperature.

examples/SetSerial/SetSerial.ino

@@ -1,83 +1,78 @@
-/*----------------------------------------------------------------------*
- * Display the date and time from a DS3231 or DS3232 RTC every second.  *
- * Display the temperature once per minute. (The DS3231 does a          *
- * temperature conversion once every 64 seconds. This is also the       *
- * default for the DS3232.)                                             *
- *                                                                      *
- * Set the date and time by entering the following on the Arduino       *
- * serial monitor:                                                      *
- *    year,month,day,hour,minute,second,                                *
- *                                                                      *
- * Where                                                                *
- *    year can be two or four digits,                                   *
- *    month is 1-12,                                                    *
- *    day is 1-31,                                                      *
- *    hour is 0-23, and                                                 *
- *    minute and second are 0-59.                                       *
- *                                                                      *
- * Entering the final comma delimiter (after "second") will avoid a     *
- * one-second timeout and will allow the RTC to be set more accurately. *
- *                                                                      *
- * No validity checking is done, invalid values or incomplete syntax    *
- * in the input will result in an incorrect RTC setting.                *
- *                                                                      *
- * Jack Christensen 08Aug2013                                           *
- *                                                                      *
- * Tested with Arduino 1.0.5, Arduino Uno, DS3231/Chronodot, DS3232.    *
- *                                                                      *
- * This work 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, 171 Second Street, Suite 300,            *
- * San Francisco, California, 94105, USA.                               *
- *----------------------------------------------------------------------*/ 
+// Arduino DS3232RTC Library
+// https://github.com/JChristensen/DS3232RTC
+// Copyright (C) 2018 by Jack Christensen and licensed under
+// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html
+//
+// Example sketch to display the date and time from a DS3231
+// or DS3232 RTC every second. Display the temperature once per
+// minute. (The DS3231 does a temperature conversion once every
+// 64 seconds. This is also the default for the DS3232.)
+//
+// Set the date and time by entering the following on the Arduino
+// serial monitor:
+//  year,month,day,hour,minute,second,
+//
+// Where
+//  year can be two or four digits,
+//  month is 1-12,
+//  day is 1-31,
+//  hour is 0-23, and
+//  minute and second are 0-59.
+//
+// Entering the final comma delimiter (after "second") will avoid a
+// one-second timeout and will allow the RTC to be set more accurately.
+//
+// No validity checking is done, invalid values or incomplete syntax
+// in the input will result in an incorrect RTC setting.
+//
+// Jack Christensen 08Aug2013
 
-#include <DS3232RTC.h>        //http://github.com/JChristensen/DS3232RTC
-#include <Streaming.h>        //http://arduiniana.org/libraries/streaming/
+#include <DS3232RTC.h>      // https://github.com/JChristensen/DS3232RTC
+#include <Streaming.h>      // http://arduiniana.org/libraries/streaming/
 
-void setup(void)
+void setup()
 {
     Serial.begin(115200);
 
-    //setSyncProvider() causes the Time library to synchronize with the
-    //external RTC by calling RTC.get() every five minutes by default.
+    // setSyncProvider() causes the Time library to synchronize with the
+    // external RTC by calling RTC.get() every five minutes by default.
     setSyncProvider(RTC.get);
     Serial << F("RTC Sync");
     if (timeStatus() != timeSet) Serial << F(" FAIL!");
     Serial << endl;
 }
 
-void loop(void)
+void loop()
 {
     static time_t tLast;
     time_t t;
     tmElements_t tm;
 
-    //check for input to set the RTC, minimum length is 12, i.e. yy,m,d,h,m,s
+    // check for input to set the RTC, minimum length is 12, i.e. yy,m,d,h,m,s
     if (Serial.available() >= 12) {
-        //note that the tmElements_t Year member is an offset from 1970,
-        //but the RTC wants the last two digits of the calendar year.
-        //use the convenience macros from the Time Library to do the conversions.
+        // note that the tmElements_t Year member is an offset from 1970,
+        // but the RTC wants the last two digits of the calendar year.
+        // use the convenience macros from the Time Library to do the conversions.
         int y = Serial.parseInt();
         if (y >= 100 && y < 1000)
             Serial << F("Error: Year must be two digits or four digits!") << endl;
         else {
             if (y >= 1000)
                 tm.Year = CalendarYrToTm(y);
-            else    //(y < 100)
+            else    // (y < 100)
                 tm.Year = y2kYearToTm(y);
             tm.Month = Serial.parseInt();
             tm.Day = Serial.parseInt();
             tm.Hour = Serial.parseInt();
             tm.Minute = Serial.parseInt();
             tm.Second = Serial.parseInt();
             t = makeTime(tm);
-            RTC.set(t);        //use the time_t value to ensure correct weekday is set
+            RTC.set(t);        // use the time_t value to ensure correct weekday is set
             setTime(t);        
             Serial << F("RTC set to: ");
             printDateTime(t);
             Serial << endl;
-            //dump any extraneous input
+            // dump any extraneous input
             while (Serial.available() > 0) Serial.read();
         }
     }
@@ -95,32 +90,32 @@ void loop(void)
     }
 }
 
-//print date and time to Serial
+// print date and time to Serial
 void printDateTime(time_t t)
 {
     printDate(t);
     Serial << ' ';
     printTime(t);
 }
 
-//print time to Serial
+// print time to Serial
 void printTime(time_t t)
 {
     printI00(hour(t), ':');
     printI00(minute(t), ':');
     printI00(second(t), ' ');
 }
 
-//print date to Serial
+// print date to Serial
 void printDate(time_t t)
 {
     printI00(day(t), 0);
     Serial << monthShortStr(month(t)) << _DEC(year(t));
 }
 
-//Print an integer in "00" format (with leading zero),
-//followed by a delimiter character to Serial.
-//Input value assumed to be between 0 and 99.
+// Print an integer in "00" format (with leading zero),
+// followed by a delimiter character to Serial.
+// Input value assumed to be between 0 and 99.
 void printI00(int val, char delim)
 {
     if (val < 10) Serial << '0';

examples/TimeRTC/TimeRTC.ino

@@ -1,13 +1,13 @@
-/*
- * TimeRTC.pde
- * Example code illustrating Time library with Real Time Clock.
- * This example is identical to the example provided with the Time Library,
- * only the #include statement has been changed to include the DS3232RTC library.
- */
+// Arduino DS3232RTC Library
+// https://github.com/JChristensen/DS3232RTC
+//
+// Example sketch illustrating Time library with Real Time Clock.
+// This example is identical to the example provided with the Time Library,
+// only the #include statement has been changed to include the DS3232RTC library.
 
-#include <DS3232RTC.h>    //http://github.com/JChristensen/DS3232RTC
+#include <DS3232RTC.h>      // https://github.com/JChristensen/DS3232RTC
 
-void setup(void)
+void setup()
 {
     Serial.begin(9600);
     setSyncProvider(RTC.get);   // the function to get the time from the RTC
@@ -17,13 +17,13 @@ void setup(void)
         Serial.println("RTC has set the system time");      
 }
 
-void loop(void)
+void loop()
 {
     digitalClockDisplay();  
     delay(1000);
 }
 
-void digitalClockDisplay(void)
+void digitalClockDisplay()
 {
     // digital clock display of the time
     Serial.print(hour());

examples/alarm_ex1/alarm_ex1.ino

@@ -1,18 +1,21 @@
-/*-----------------------------------------------------------------------------*
- * DS3231/DS3232 Alarm Example #1                                              *
- *                                                                             *
- * Set Alarm 1 to occur once a minute at 5 seconds after the minute.           *
- * Detect the alarm by polling the RTC alarm flag.                             *
- *                                                                             *
- * Hardware:                                                                   *
- * Arduino Uno, DS3231 RTC.                                                    *
- * Connect RTC SDA to Arduino pin A4.                                          *
- * Connect RTC SCL to Arduino pin A5.                                          *
- *                                                                             *
- * Jack Christensen 16Sep2017                                                  *
- *-----------------------------------------------------------------------------*/
-
-#include <DS3232RTC.h>      // http://github.com/JChristensen/DS3232RTC
+// Arduino DS3232RTC Library
+// https://github.com/JChristensen/DS3232RTC
+// Copyright (C) 2018 by Jack Christensen and licensed under
+// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html
+//
+// DS3231/DS3232 Alarm Example Sketch #1
+//
+// Set Alarm 1 to occur once a minute at 5 seconds after the minute.
+// Detect the alarm by polling the RTC alarm flag.
+//
+// Hardware:
+// Arduino Uno, DS3231 RTC.
+// Connect RTC SDA to Arduino pin A4.
+// Connect RTC SCL to Arduino pin A5.
+//
+// Jack Christensen 16Sep2017
+
+#include <DS3232RTC.h>      // https://github.com/JChristensen/DS3232RTC
 #include <Streaming.h>      // http://arduiniana.org/libraries/streaming/
 
 void setup()
@@ -89,4 +92,3 @@ time_t compileTime()
     time_t t = makeTime(tm);
     return t + FUDGE;        //add fudge factor to allow for compile time
 }
-