README clarification, additional example sketches.

Closes #65.

README.md

@@ -18,7 +18,12 @@ You should have received a copy of the GNU General Public License along with thi
 
 The **DS3232RTC** library is a drop-in replacement for the (older) DS1307RTC.h library by Michael Margolis that is supplied with the [Arduino Time library](https://www.arduino.cc/playground/Code/Time) (but not for [PJRC's newer version of the DS1307RTC library](https://www.pjrc.com/teensy/td_libs_DS1307RTC.html)). To change from using a DS1307 RTC to an DS323x RTC, it is only necessary to use `#include <DS3232RTC.h>` instead of `#include <DS1307RTC.h>`.
 
-**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).
+The **DS3232RTC** library also implements functions to support the additional features of the DS3232 and DS3231. The DS3232 has the same features as the DS3231, but the DS3232 also has these extra features:
+
+- Battery-backed SRAM
+- Battery-backed 32kHz output (BB32kHz bit in Control/Status register 0x0F)
+- Adjustable temperature sensor sample rate (CRATE1:0 bits in the Control/Status register).
+
 
 ## Examples
 The following example sketches are included with the **DS3232RTC** library:

examples/alarm_ex8/alarm_ex8.ino

@@ -0,0 +1,96 @@
+// 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 #8
+//
+// Set both alarms to occur once per day at different times.
+// Configure the RTC INT/SQW pin to be asserted when alarm match occurs.
+// Detect the alarms by polling the INT/SQW pin.
+// Assumes the RTC time is already set.
+//
+// Hardware:
+// Arduino Uno, DS3231 RTC.
+// Connect RTC SDA to Arduino pin A4.
+// Connect RTC SCL to Arduino pin A5.
+// Connect RTC INT/SQW to Arduino pin 2.
+//
+// Jack Christensen 17Dec2018
+
+#include <DS3232RTC.h>        // https://github.com/JChristensen/DS3232RTC
+#include <Streaming.h>        // http://arduiniana.org/libraries/streaming/
+
+// pin definitions
+const uint8_t RTC_INT_PIN(2);
+
+// current time from the RTC in text format
+char timestamp[32];
+
+void setup()
+{
+    Serial.begin(115200);
+    delay(1000);
+    Serial << F( "\n" __FILE__ " " __DATE__ " " __TIME__ "\n" );
+    pinMode(RTC_INT_PIN, INPUT_PULLUP);
+
+    // initialize the alarms to known values, clear the alarm flags, clear the alarm interrupt flags
+    RTC.setAlarm(ALM1_MATCH_DATE, 0, 0, 0, 1);
+    RTC.setAlarm(ALM2_MATCH_DATE, 0, 0, 0, 1);
+    RTC.alarm(ALARM_1);
+    RTC.alarm(ALARM_2);
+    RTC.alarmInterrupt(ALARM_1, false);
+    RTC.alarmInterrupt(ALARM_2, false);
+    RTC.squareWave(SQWAVE_NONE);
+
+    // print the current time
+    time_t t = RTC.get();
+    formatTime(timestamp, t);
+    Serial << millis() << F(" Current RTC time ") << timestamp << endl;
+
+    // set alarm 1 to occur in 1-2 minutes
+    // set alarm 2 to occur 1 minute after alarm 1
+    tmElements_t tm;
+    breakTime(t + 120, tm);
+    tm.Second = 0;
+    time_t a1 = makeTime(tm);
+    time_t a2 = a1 + 60;
+    formatTime(timestamp, a1);
+    timestamp[8] = 0;                   // keep just hh:mm:ss
+    Serial << millis() << F(" Alarm 1 set to ") << timestamp << endl;
+    formatTime(timestamp, a2);
+    timestamp[5] = 0;                   // keep just hh:mm
+    Serial << millis() << F(" Alarm 2 set to ") << timestamp << endl;
+    RTC.setAlarm(ALM1_MATCH_HOURS, minute(a1), hour(a1), 1);
+    RTC.alarm(ALARM_1);                 // ensure RTC interrupt flag is cleared
+    RTC.alarmInterrupt(ALARM_1, true);
+    RTC.setAlarm(ALM2_MATCH_HOURS, minute(a2), hour(a2), 1);
+    RTC.alarm(ALARM_2);                 // ensure RTC interrupt flag is cleared
+    RTC.alarmInterrupt(ALARM_2, true);
+}
+
+void loop()
+{
+    // check to see if the INT/SQW pin is low, i.e. an alarm has occurred
+    if (!digitalRead(RTC_INT_PIN))
+    {
+        formatTime(timestamp, RTC.get());   // get current RTC time
+        if (RTC.alarm(ALARM_1))             // resets the alarm flag if set
+        {
+            Serial << millis() << F(" Alarm 1 at ") << timestamp << endl;
+        }
+        else if (RTC.alarm(ALARM_2))
+        {
+            Serial << millis() << F(" Alarm 2 at ") << timestamp << endl;
+        }
+    }
+}
+
+// format a time_t value, return the formatted string in buf (must be at least 25 bytes)
+void formatTime(char *buf, time_t t)
+{
+    char m[4];    // temporary storage for month string (DateStrings.cpp uses shared buffer)
+    strcpy(m, monthShortStr(month(t)));
+    sprintf(buf, "%.2d:%.2d:%.2d %s %.2d %s %d",
+        hour(t), minute(t), second(t), dayShortStr(weekday(t)), day(t), m, year(t));
+}

examples/mcu_clock_drift/mcu_clock_drift.ino

@@ -0,0 +1,75 @@
+// 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 demonstrate microcontroller clock drift vs. RTC.
+// The MCU's time of day is synchronized with the RTC every five minutes (by default).
+// Between syncs, the MCU's time of day is goverened by its system clock (which
+// also is used for millis). Because the MCU system clock and the RTC cannot be
+// expected to run at identical rates, discontinuities in the MCU's time of day
+// will occur when its time is synchronized with the RTC.
+//
+// We can see the drift and discontinuities by printing both millis and
+// the time of day together.
+//
+// Jack Christensen 27Dec2018
+
+#include <DS3232RTC.h>      // https://github.com/JChristensen/DS3232RTC
+
+void setup()
+{
+    Serial.begin(115200);
+    Serial.println(F("\n" __FILE__ " " __DATE__ " " __TIME__));
+    setSyncProvider(RTC.get);   // the function to get the time from the RTC
+    Serial.print(F("RTC sync "));
+    if (timeStatus() == timeSet)
+        Serial.println(F("OK"));
+    else
+        Serial.println(F("FAIL!"));
+}
+
+// when the MCU's time of day changes, if it did not move forward
+// by one second, or if millis changed by something other than about
+// one second, then print the millis and time values before and after.
+void loop()
+{
+    static uint32_t msLast;
+    static time_t tLast;
+    uint32_t ms = millis();
+    time_t t = now();
+    if (t != tLast)
+    {
+        if (t - tLast != 1 || ms - msLast > 1010 || ms - msLast < 990)
+        {
+            Serial.print(msLast);
+            Serial.print(' ');
+            Serial.print(ms);
+            Serial.print(' ');
+            printTime(tLast);
+            Serial.print(' ');
+            printTime(t);
+            Serial.println();
+        }
+        tLast = t;
+        msLast = ms;
+    }
+}
+
+// format and print a time_t value
+void printTime(time_t t)
+{
+    if (t > 0)
+    {
+        char buf[25];
+        char m[4];    // temporary storage for month string (DateStrings.cpp uses shared buffer)
+        strcpy(m, monthShortStr(month(t)));
+        sprintf(buf, "%.2d:%.2d:%.2d %.4d-%.2d-%.2d",
+            hour(t), minute(t), second(t), year(t), month(t), day(t));
+        Serial.print(buf);
+    }
+    else
+    {
+        Serial.print(F("Start"));
+    }
+}

examples/rtc_interrupt/rtc_interrupt.ino

@@ -0,0 +1,95 @@
+// 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 use a 1Hz interrupt from the DS3231 to keep time.
+// This is an alternative to using the "setSyncProvider" function from
+// the Time library to periodically sync the MCU's time with the RTC.
+//
+// Periodic synchronization will cause discontinuities in the MCU's perceived
+// time of day. Depending on the relative frequency of the MCU's clock compared to
+// the RTC, when synchronization occurs, a second according to the MCU's time
+// of day may appear to be longer or shorter than one second. Alternately, the
+// MCU's time of day could jump backwards or forward by more than a second.
+//
+// While this method requires setting up an interrupt and a few short
+// functions to handle the interrupt and to set and read the time,
+// it has the following advantages: (1) The MCU time is always exactly
+// in step with the RTC time and is not dependent on the MCU's clock
+// which will always drift relative to the RTC, and (2) It is more efficient
+// as the RTC's time is only read once over the I2C bus and the interrupt
+// service routine to increment the time is minimal.
+//
+// When using the technique of periodically synchronizing the MCU's time
+// with the RTC, we have 
+//
+// Jack Christensen 27Dec2018
+
+#include <DS3232RTC.h>          // https://github.com/JChristensen/DS3232RTC
+
+const uint8_t RTC_1HZ_PIN(2);   // RTC provides a 1Hz interrupt signal on this pin
+
+void setup()
+{
+    Serial.begin(115200);
+    Serial.println(F("\n" __FILE__ " " __DATE__ " " __TIME__));
+
+    pinMode(RTC_1HZ_PIN, INPUT_PULLUP);     // enable pullup on interrupt pin (RTC SQW pin is open drain)
+    attachInterrupt(digitalPinToInterrupt(RTC_1HZ_PIN), incrementTime, FALLING);
+    RTC.squareWave(SQWAVE_1_HZ);            // 1 Hz square wave
+
+    time_t utc = getUTC();                  // synchronize with RTC
+    while ( utc == getUTC() );              // wait for increment to the next second
+    utc = RTC.get();                        // get the time from the RTC
+    setUTC(utc);                            // set our time to the RTC's time
+    Serial.println("Time set from RTC");
+}
+
+void loop()
+{
+    static time_t tLast;
+    time_t t = getUTC();
+
+    if (t != tLast)
+    {
+        tLast = t;
+        printTime(t);
+    }
+}
+
+volatile time_t isrUTC;         // ISR's copy of current time in UTC
+
+// return current time
+time_t getUTC()
+{
+    noInterrupts();
+    time_t utc = isrUTC;
+    interrupts();
+    return utc;
+}
+
+// set the current time
+void setUTC(time_t utc)
+{
+    noInterrupts();
+    isrUTC = utc;
+    interrupts();
+}
+
+// 1Hz RTC interrupt handler increments the current time
+void incrementTime()
+{
+    ++isrUTC;
+}
+
+// format and print a time_t value
+void printTime(time_t t)
+{
+    char buf[25];
+    char m[4];    // temporary storage for month string (DateStrings.cpp uses shared buffer)
+    strcpy(m, monthShortStr(month(t)));
+    sprintf(buf, "%.2d:%.2d:%.2d %s %.2d %s %d",
+        hour(t), minute(t), second(t), dayShortStr(weekday(t)), day(t), m, year(t));
+    Serial.println(buf);
+}

library.properties

@@ -1,5 +1,5 @@
 name=DS3232RTC
-version=1.2.5
+version=1.2.6
 author=Jack Christensen <[email protected]>
 maintainer=Jack Christensen <[email protected]>
 sentence=Arduino Library for Maxim Integrated DS3232 and DS3231 Real-Time Clocks.