Add rtc_temperature example sketch.

examples/rtc_interrupt/rtc_interrupt.ino

@@ -3,26 +3,26 @@
 // 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.
+// Example sketch that uses a 1Hz interrupt from the DS3231/2 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.
+// that of the RTC, when synchronization occurs, a second according to the MCU's
+// time may appear to be longer or shorter than one RTC second. Alternately, the
+// MCU's time 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.
+// service routine to increment the time is trivial.
 //
-// When using the technique of periodically synchronizing the MCU's time
-// with the RTC, we have 
+// When using setSyncProvider and periodically synchronizing the MCU's time
+// with the RTC, we effectively have two clocks instead of one.
 //
 // Jack Christensen 27Dec2018
 

examples/rtc_temperature/rtc_temperature.ino

@@ -0,0 +1,136 @@
+// Arduino DS3232RTC Library
+// https://github.com/JChristensen/DS3232RTC
+// Copyright (C) 2019 by Jack Christensen and licensed under
+// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html
+//
+// Example sketch that initiates an RTC temperature conversion every
+// 10 seconds and prints temperature, time and date if the temperature has
+// changed since the last conversion. If the temperature does not change,
+// it is still printed once per minute.
+//
+// The default temperature conversion rate for the DS3231/2 is every 64 seconds
+// so this allows quicker observation of temperature changes. Note that the
+// automatic conversions still occur every 64 seconds in addition to the
+// forced conversions.
+//
+// This sketch uses a 1Hz interrupt from the RTC to keep time instead of
+// using the "setSyncProvider" function from the Time library. See the
+// rtc_interrupt example sketch for more information.
+//
+// Jack Christensen 09Sep2019
+
+#include <DS3232RTC.h>          // https://github.com/JChristensen/DS3232RTC
+#include <Streaming.h>          // http://arduiniana.org/libraries/streaming/
+
+const uint8_t RTC_1HZ_PIN(2);   // RTC provides a 1Hz interrupt signal on this pin
+
+void setup()
+{
+    Serial.begin(115200);
+    Serial << F("\n" __FILE__ " " __DATE__ " " __TIME__ "\n");
+
+    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 << F("Time set from RTC\n");
+}
+
+void loop()
+{
+    static time_t tLast;
+    static int16_t lastTemp;
+    time_t t = getUTC();
+
+    if (t != tLast)
+    {
+        tLast = t;
+        if (second(t) % 10 == 0) convertTemperature();
+        int16_t rtcTemp = RTC.temperature();
+        if (rtcTemp != lastTemp || second(t) == 0)
+        {
+            lastTemp = rtcTemp;
+            float c = rtcTemp / 4.;
+            float f = c * 9. / 5. + 32.;
+            Serial << c << F(" C ") << f << F(" F  ");
+            printTime(t);
+        }
+    }
+}
+
+#define RTC_CONTROL 0x0E
+#define RTC_STATUS 0x0F
+#define CONV 5
+#define BSY 2
+
+// force the RTC to do a temperature conversion
+void convertTemperature()
+{
+    // get the status register
+    uint8_t s = RTC.readRTC(RTC_STATUS);
+    // start a conversion, unless one is already in progress
+    if (!(s & _BV(BSY)))
+    {
+        // get the control register and set the CONV bit
+        uint8_t c = RTC.readRTC(RTC_CONTROL);
+        RTC.writeRTC(RTC_CONTROL, c | _BV(CONV));
+        // wait for the CONV bit to turn off
+        bool busy = true;
+        while (busy)
+        {
+            Serial << F("Wait CONV\n");
+            delay(100);
+            busy = RTC.readRTC(RTC_CONTROL) & _BV(CONV);
+        }
+    }
+    else
+    {
+        bool busy = true;
+        while (busy)
+        {
+            Serial << F("Wait BSY\n");
+            delay(100);
+            busy = RTC.readRTC(RTC_STATUS) & _BV(BSY);
+        }
+    }
+}
+
+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.7
+version=1.2.8
 author=Jack Christensen <jack.christensen@outlook.com>
 maintainer=Jack Christensen <jack.christensen@outlook.com>
 sentence=Arduino Library for Maxim Integrated DS3232 and DS3231 Real-Time Clocks.