Update example sketches for new library version.

Add an example sketch showing alarm usage.
Add const to function parameters as appropriate.

Author: JChristensen

examples/PowerOutageLogger/PowerOutageLogger.ino

@@ -7,138 +7,140 @@
 // Assumes the RTC is running and set to UTC.
 // A maximum of 7 outages (power down/up times) can be logged in the
 // RTC's SRAM.
+// The logging data structure is automatically initialized if not
+// present. An initialization can be forced with a button switch
+// connected from pin 9 to ground. Hold the button down
+// while resetting the MCU to initialize the logging data.
 //
 // Jack Christensen 23Aug2012
 
 #include <MCP79412RTC.h>    // https://github.com/JChristensen/MCP79412RTC
-#include <Streaming.h>      // http://arduiniana.org/libraries/streaming/
-#include <TimeLib.h>        // https://github.com/PaulStoffregen/Time
+#include <Streaming.h>      // https://github.com/janelia-arduino/Streaming
 #include <Timezone.h>       // https://github.com/JChristensen/Timezone
 
-#define FIRST_OUTAGE_ADDR 0x08    // address of first outage timestamps in RTC SRAM
-#define OUTAGE_LENGTH 8           // 8 data bytes for each outage (start and end timestamps, both are time_t values)
-#define MAX_OUTAGES 7             // maximum number of outage timestamp pairs that can be stored in SRAM
-#define MAX_OUTAGE_ADDR FIRST_OUTAGE_ADDR + OUTAGE_LENGTH * (MAX_OUTAGES - 1)    // last outage address
-#define APP_ID 1                  // APP_ID and 4 bytes of the RTC ID are stored in sram to provide
-                                  // a way to recognize that the logging data structure has been initialized
-#define RTC_ID_LO 0x00            // lower 4 bytes of RTC unique ID are stored at sram addr 0x00
-#define APP_ID_ADDR 0x04          // address of appID (1)
-#define NBR_OUTAGES_ADDR 0x05     // address containing number of outages currently stored in SRAM
-#define NEXT_OUTAGE_ADDR 0x06     // address containing pointer to next outage
-#define RFU_ADDR 0x07             // reserved for future use
-
-// US Eastern Time Zone (New York, Detroit)
-TimeChangeRule myDST = {"EDT", Second, Sun, Mar, 2, -240};    // Daylight time = UTC - 4 hours
-TimeChangeRule mySTD = {"EST", First, Sun, Nov, 2, -300};     // Standard time = UTC - 5 hours
-Timezone myTZ(myDST, mySTD);
-TimeChangeRule *tcr;              // pointer to the time change rule, used to get TZ abbrev
-time_t utc, local, lastUTC;
+MCP79412RTC myRTC;
 
 void setup()
 {
+    constexpr uint8_t initButton {9};
+    pinMode(initButton, INPUT_PULLUP);
+    myRTC.begin();
     Serial.begin(115200);
+    Serial << F( "\n" __FILE__ " " __DATE__ " " __TIME__ "\n" );
 
-    setSyncProvider(RTC.get);     // the function to get the time from the RTC
+    setSyncProvider(myRTC.get);     // the function to get the time from the RTC
     Serial << "RTC SYNC";
     if (timeStatus()!= timeSet) Serial << " FAIL";
     Serial << endl;
 
-    //logClear();
+    if (!digitalRead(initButton)) logClear();
     logOutage();
+    //myRTC.dumpSRAM();
 }
 
+// US Eastern Time Zone (New York, Detroit)
+TimeChangeRule myDST = {"EDT", Second, Sun, Mar, 2, -240};  // Daylight time = UTC - 4 hours
+TimeChangeRule mySTD = {"EST", First, Sun, Nov, 2, -300};   // Standard time = UTC - 5 hours
+Timezone myTZ(myDST, mySTD);
+TimeChangeRule *tcr;            // pointer to the time change rule, used to get TZ abbrev
+
 void loop()
 {
     // nothing here in loop() has anything to do with logging power outages,
-    // we just print the time every second so that something is happening.
-    utc = now();
-    if (utc != lastUTC)
-    {
+    // we just print the time once a minute so that something is happening.
+    static time_t lastUTC;
+    time_t utc = now();
+    if (minute(utc) != minute(lastUTC)) {
         lastUTC = utc;
-        local = myTZ.toLocal(utc, &tcr);
+        time_t local = myTZ.toLocal(utc, &tcr);
         Serial << endl;
         printTime(utc, "UTC");
         printTime(local, tcr -> abbrev);
     }
 }
 
+// constants for logging
+constexpr uint8_t
+    firstOutageAddr {0x08},     // address of first outage timestamps in RTC SRAM
+    outageLength    {8},        // 8 data bytes for each outage (start and end timestamps, both are time_t values)
+    maxOutages      {7},        // maximum number of outage timestamp pairs that can be stored in SRAM
+    lastOutageAddr  {firstOutageAddr + outageLength * (maxOutages - 1)},    // last outage address
+    appID           {1},        // appID and 4 bytes of the RTC ID are stored in sram to provide
+                                // a way to recognize that the logging data structure has been initialized
+    rtcID           {0x00},     // lower 4 bytes of RTC unique ID are stored at sram addr 0x00
+    appAddr         {0x04},     // address of appID in sram
+    nbrOutagesAddr  {0x05},     // address containing number of outages currently stored in SRAM
+    nextOutageAddr  {0x06},     // address containing pointer to next outage
+    rfuAddr         {0x07};     // reserved for future use
+
 // initialize the log data structure in the RTC SRAM if needed.
 // log a new outage if one occurred.
 // print out the outages logged.
-void logOutage()
-{
+void logOutage() {
     union {
         uint8_t b[8];
         struct {
             uint32_t hi;
             uint32_t lo;
         };
-    } uniqueID;                   // 8-byte RTC "unique ID" with access to upper and lower halves
-
-    uint32_t loID;                // lower half of the unique ID read from sram
-    uint8_t appID;                // app ID read from sram
-    uint8_t nOutage;              // number of outages stored in sram
-    uint8_t nextOutage;           // address of next outage timestamps in sram
-    uint8_t outageAddr;           // outage address in sram
-    time_t powerDown, powerUp;    // power outage timestamps
-
-    RTC.idRead(uniqueID.b);       // get the RTC's ID
-    loID = read32(RTC_ID_LO);     // if already initialized, the lower half of the ID is stored at SRAM addr 0x00,
-    appID = RTC.sramRead(APP_ID_ADDR);     // and the app ID (1) is at addr 0x04.
+    } uniqueID;                 // 8-byte RTC "unique ID" with access to upper and lower halves
+
+    myRTC.idRead(uniqueID.b);           // get the RTC's ID
+    uint32_t loID = read32(rtcID);      // if already initialized, the lower half of the ID is stored in SRAM,
+    uint8_t app = myRTC.sramRead(appAddr);  // and also the app ID
     Serial << "RTC ID";
-    for (uint8_t i=0; i<8; i++)
-    {
+    for (uint8_t i=0; i<8; i++) {
         Serial << (uniqueID.b[i] < 16 ? " 0" : " ") << _HEX(uniqueID.b[i]);
     }
+    Serial << endl;
 
-    if ( loID != uniqueID.lo || appID != 1 )                // logging initialized?
-    {
-        write32(RTC_ID_LO, uniqueID.lo);                    // least significant half of the RTC unique ID
-        RTC.sramWrite(APP_ID_ADDR, APP_ID);                 // app ID
-        RTC.sramWrite(NBR_OUTAGES_ADDR, 0);                 // number of outages
-        RTC.sramWrite(NEXT_OUTAGE_ADDR, FIRST_OUTAGE_ADDR); // next location for outage times
-        RTC.sramWrite(RFU_ADDR, 0);                         // reserved for future use
+    if ( loID != uniqueID.lo || app != appID ) {            // logging initialized?
+        write32(rtcID, uniqueID.lo);                        // least significant half of the RTC unique ID
+        myRTC.sramWrite(appAddr, appID);                    // app ID
+        myRTC.sramWrite(nbrOutagesAddr, 0);                 // number of outages
+        myRTC.sramWrite(nextOutageAddr, firstOutageAddr);   // next location for outage times
+        myRTC.sramWrite(rfuAddr, 0);                        // reserved for future use
         Serial << "Logging initialized" << endl;            // no, do it now
     }
 
     // if an outage has occurred, record it
-    if ( RTC.powerFail(&powerDown, &powerUp) )
-    {
-        nOutage = RTC.sramRead(NBR_OUTAGES_ADDR);
-        nextOutage = RTC.sramRead(NEXT_OUTAGE_ADDR);
+    time_t powerDown, powerUp;  // power outage timestamps
+    uint8_t nOutage;            // number of outages stored in sram
+    uint8_t nextOutage;         // address of next outage timestamps in sram
+    if ( myRTC.powerFail(&powerDown, &powerUp) ) {
+        nOutage = myRTC.sramRead(nbrOutagesAddr);
+        nextOutage = myRTC.sramRead(nextOutageAddr);
         write32(nextOutage, powerDown);
         write32(nextOutage + 4, powerUp);
-        nextOutage += OUTAGE_LENGTH;
-        if (nextOutage > MAX_OUTAGE_ADDR) nextOutage = FIRST_OUTAGE_ADDR;
-        RTC.sramWrite(NEXT_OUTAGE_ADDR, nextOutage);
-        if (nOutage < MAX_OUTAGES) RTC.sramWrite(NBR_OUTAGES_ADDR, ++nOutage);
+        nextOutage += outageLength;
+        if (nextOutage > lastOutageAddr) nextOutage = firstOutageAddr;
+        myRTC.sramWrite(nextOutageAddr, nextOutage);
+        if (nOutage < maxOutages) myRTC.sramWrite(nbrOutagesAddr, ++nOutage);
     }
 
     // print out all the outages logged
-    nOutage = RTC.sramRead(NBR_OUTAGES_ADDR);
-    nextOutage = RTC.sramRead(NEXT_OUTAGE_ADDR);
-    outageAddr = nextOutage - OUTAGE_LENGTH;
-    if (outageAddr < FIRST_OUTAGE_ADDR) outageAddr = MAX_OUTAGE_ADDR;
-    Serial << endl << endl << "Power outages logged: " << _DEC(nOutage) << endl;
-    for (uint8_t i=nOutage; i>0; i--)
-    {
+    nOutage = myRTC.sramRead(nbrOutagesAddr);
+    nextOutage = myRTC.sramRead(nextOutageAddr);
+    uint8_t outageAddr = nextOutage - outageLength;
+    if (outageAddr < firstOutageAddr) outageAddr = lastOutageAddr;
+    Serial << endl << "Power outages logged: " << _DEC(nOutage) << endl;
+    for (uint8_t i=nOutage; i>0; i--) {
         powerDown = read32(outageAddr);
         powerUp = read32(outageAddr + 4);
         Serial << endl << _DEC(i) << ": Power down ";
         printTime(myTZ.toLocal(powerDown, &tcr), tcr -> abbrev);
         Serial << _DEC(i) << ": Power up   ";
         printTime(myTZ.toLocal(powerUp, &tcr), tcr -> abbrev);
-        outageAddr -= OUTAGE_LENGTH;
-        if (outageAddr < FIRST_OUTAGE_ADDR) outageAddr = MAX_OUTAGE_ADDR;
+        outageAddr -= outageLength;
+        if (outageAddr < firstOutageAddr) outageAddr = lastOutageAddr;
     }
 }
 
 // initialize the logging data structure and log data
 void logClear()
 {
-    for (uint8_t i=0; i<MAX_OUTAGE_ADDR + OUTAGE_LENGTH; i++)
-    {
-        RTC.sramWrite(i, 0);
+    for (uint8_t i=0; i<lastOutageAddr + outageLength; i++) {
+        myRTC.sramWrite(i, 0);
     }
 }
 
@@ -151,7 +153,7 @@ void write32(uint8_t addr, uint32_t t)
     } i;
 
     i.t = t;
-    RTC.sramWrite(addr, i.b, 4);
+    myRTC.sramWrite(addr, i.b, 4);
 }
 
 // read a time_t or other uint32_t value from sram starting at addr
@@ -162,7 +164,7 @@ time_t read32(uint8_t addr)
         time_t t;
     } i;
 
-    RTC.sramRead(addr, i.b, 4);
+    myRTC.sramRead(addr, i.b, 4);
     return i.t;
 }
 

examples/SetSerial/SetSerial.ino

@@ -32,7 +32,6 @@
 
 #include <MCP79412RTC.h>    // https://github.com/JChristensen/MCP79412RTC
 #include <Streaming.h>      // http://arduiniana.org/libraries/streaming/
-#include <TimeLib.h>        // https://github.com/PaulStoffregen/Time
 
 MCP79412RTC myRTC;
 
@@ -133,7 +132,7 @@ void loop()
 }
 
 // format and print a time_t value
-void printTime(time_t t)
+void printTime(const time_t t)
 {
     char buf[25];
     char m[4];    // temporary storage for month string (DateStrings.cpp uses shared buffer)

examples/TimeRTC/TimeRTC.ino

@@ -1,50 +1,49 @@
 // Arduino MCP79412RTC Library
 // https://github.com/JChristensen/MCP79412RTC
 // TimeRTC.ino
-// 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 MCP79412RTC library.
+// Example sketch showing basic usage.
 
 #include <MCP79412RTC.h>    // http://github.com/JChristensen/MCP79412RTC
-#include <TimeLib.h>        // https://www.pjrc.com/teensy/td_libs_DS1307RTC.html
-#include <Wire.h>           // https://www.arduino.cc/en/Reference/Wire
+
+MCP79412RTC myRTC;
 
 void setup()
 {
-  Serial.begin(9600);
-  setSyncProvider(RTC.get);   // the function to get the time from the RTC
-  if(timeStatus()!= timeSet)
-     Serial.println("Unable to sync with the RTC");
-  else
-     Serial.println("RTC has set the system time");
+    myRTC.begin();
+    Serial.begin(115200);
+    setSyncProvider(myRTC.get); // the function to get the time from the RTC
+    if (timeStatus() != timeSet)
+        Serial.println("Unable to sync with the RTC");
+    else
+        Serial.println("RTC has set the system time");
 }
 
 void loop()
 {
-  digitalClockDisplay();
-  delay(1000);
+    digitalClockDisplay();
+    delay(1000);
 }
 
+// digital clock display of the time
 void digitalClockDisplay()
 {
-  // digital clock display of the time
-  Serial.print(hour());
-  printDigits(minute());
-  printDigits(second());
-  Serial.print(" ");
-  Serial.print(day());
-  Serial.print(" ");
-  Serial.print(month());
-  Serial.print(" ");
-  Serial.print(year());
-  Serial.println();
+    Serial.print(hour());
+    printDigits(minute());
+    printDigits(second());
+    Serial.print(" ");
+    Serial.print(day());
+    Serial.print(" ");
+    Serial.print(month());
+    Serial.print(" ");
+    Serial.print(year());
+    Serial.println();
 }
 
+// utility function for digital clock display: prints preceding colon and leading 0
 void printDigits(int digits)
 {
-  // utility function for digital clock display: prints preceding colon and leading 0
-  Serial.print(":");
-  if(digits < 10)
-    Serial.print('0');
-  Serial.print(digits);
+    Serial.print(":");
+    if (digits < 10)
+        Serial.print('0');
+    Serial.print(digits);
 }

examples/alarm_ex1/alarm_ex1.ino

@@ -0,0 +1,74 @@
+// Arduino MCP79412RTC Library
+// https://github.com/JChristensen/MCP79412RTC
+// Copyright (C) 2018 by Jack Christensen and licensed under
+// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html
+//
+// MCP79412RTC Alarm Example Sketch #1
+//
+// Set Alarm 0 to occur once a minute at 5 seconds after the minute.
+// Detect the alarm by polling the MFP output as well as the RTC alarm flag.
+//
+// Hardware:
+// Arduino Uno, MCP79410/11/12 RTC.
+// Connect RTC SDA to Arduino pin A4.
+// Connect RTC SCL to Arduino pin A5.
+//
+// Jack Christensen 27Apr2022
+
+#include <MCP79412RTC.h>    // https://github.com/JChristensen/MCP79412RTC
+#include <Streaming.h>      // https://github.com/janelia-arduino/Streaming
+
+MCP79412RTC myRTC;
+constexpr uint8_t mfp {3};  // connect to RTC multi-function pin.
+
+void setup()
+{
+    Serial.begin(115200);
+    Serial << F( "\n" __FILE__ "\nCompiled " __DATE__ " " __TIME__ "\n" );
+    pinMode(mfp, INPUT_PULLUP);
+
+    // initialize the alarms to known values, clear the alarm flags, clear the alarm interrupt flags
+    myRTC.begin();
+    myRTC.enableAlarm(MCP79412RTC::ALARM_0, MCP79412RTC::ALM_DISABLE);
+    myRTC.enableAlarm(MCP79412RTC::ALARM_1, MCP79412RTC::ALM_DISABLE);
+    myRTC.alarm(MCP79412RTC::ALARM_0);
+    myRTC.alarm(MCP79412RTC::ALARM_1);
+    myRTC.squareWave(MCP79412RTC::SQWAVE_NONE);
+
+    // set Alarm 0 to occur at 5 seconds after every minute
+    myRTC.setAlarm(MCP79412RTC::ALARM_0, 2022, 1, 1, 0, 0, 5);
+    myRTC.enableAlarm(MCP79412RTC::ALARM_0, MCP79412RTC::ALM_MATCH_SECONDS);
+
+    Serial << endl << millis() << " Start ";
+    printTime(myRTC.get());
+    myRTC.dumpRegs();
+}
+
+void loop()
+{
+    if (!digitalRead(mfp)) {                    // is the mfp pulled low
+        Serial << millis() << " MFP LOW ";
+        printTime(myRTC.get());
+    }
+    if ( myRTC.alarm(MCP79412RTC::ALARM_0) ) {  // check alarm flag, clear it if set
+        Serial << millis() << " ALARM_0 ";
+        printTime(myRTC.get());
+    }
+    if ( myRTC.alarm(MCP79412RTC::ALARM_1) ) {  // check alarm flag, clear it if set
+        Serial << millis() << " ALARM_1 ";
+        printTime(myRTC.get());
+    }
+
+    delay(100);     // no need to bombard the RTC continuously
+}
+
+// format and print a time_t value
+void printTime(const 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);
+}