tstellanova
diff --git a/‎MCP79412RTC.cpp‎
Lines changed: 157 additions & 2 deletions b/‎MCP79412RTC.cpp‎
Lines changed: 157 additions & 2 deletions
diff --git a/‎MCP79412RTC.h‎
Lines changed: 17 additions & 15 deletions b/‎MCP79412RTC.h‎
Lines changed: 17 additions & 15 deletions
diff --git a/‎ReadMe.txt‎
Lines changed: 27 additions & 0 deletions b/‎ReadMe.txt‎
Lines changed: 27 additions & 0 deletions
@@ -69,7 +69,7 @@ void MCP79412RTC::read(tmElements_t &tm)
     tm.Second = bcd2dec(i2cRead() & ~_BV(ST));   
     tm.Minute = bcd2dec(i2cRead());
     tm.Hour = bcd2dec(i2cRead() & ~_BV(HR1224));    //assumes 24hr clock
-    tm.Wday = bcd2dec(i2cRead() & ~(_BV(OSCON) | _BV(VBAT) | _BV(VBATEN)) );    //mask off OSCON, VBAT, VBATEN bits
+    tm.Wday = i2cRead() & ~(_BV(OSCON) | _BV(VBAT) | _BV(VBATEN));    //mask off OSCON, VBAT, VBATEN bits
     tm.Day = bcd2dec(i2cRead());
     tm.Month = bcd2dec(i2cRead() & ~_BV(LP));       //mask off the leap year bit
     tm.Year = y2kYearToTm(bcd2dec(i2cRead()));
@@ -85,7 +85,7 @@ void MCP79412RTC::write(tmElements_t &tm)
     i2cWrite(0x00);                              //stops the oscillator (Bit 7, ST == 0)   
     i2cWrite(dec2bcd(tm.Minute));
     i2cWrite(dec2bcd(tm.Hour));                  //sets 24 hour format (Bit 6 == 0)
-    i2cWrite(dec2bcd(tm.Wday) | _BV(VBATEN));    //enable battery backup operation
+    i2cWrite(tm.Wday | _BV(VBATEN));             //enable battery backup operation
     i2cWrite(dec2bcd(tm.Day));
     i2cWrite(dec2bcd(tm.Month));
     i2cWrite(dec2bcd(tmYearToY2k(tm.Year))); 
@@ -328,6 +328,161 @@ void MCP79412RTC::idRead(byte *uniqueID)
     for (byte i=0; i<UNIQUE_ID_SIZE; i++) uniqueID[i] = i2cRead();
 }
 
+/*----------------------------------------------------------------------*
+ * Check to see if a power failure has occurred. If so, returns TRUE    *
+ * as the function value, and returns the power down and power up       *
+ * timestamps. After returning the time stamps, the RTC's timestamp     *
+ * registers are cleared and the VBAT bit which indicates a power       *
+ * failure is reset.                                                    *
+ *                                                                      *
+ * Note that the power down and power up timestamp registers do not     *
+ * contain values for seconds or for the year. The returned time stamps *
+ * will therefore contain the current year from the RTC. However, there *
+ * is a chance that a power outage spans from one year to the next.     *
+ * If we find the power down timestamp to be later (larger) than the    *
+ * power up timestamp, we will assume this has happened, and well       *
+ * subtract one year from the power down timestamp.                     *
+ *                                                                      *
+ * Still, there is an assumption that the timestamps are being read     *
+ * in the same year as that when the power up occurred.                 *
+ *                                                                      *
+ * Finally, note that once the RTC records a power outage, it must be   *
+ * cleared before another will be recorded.                             *
+ *----------------------------------------------------------------------*/
+boolean MCP79412RTC::powerFail(time_t *powerDown, time_t *powerUp)
+{
+    byte day, yr;                   //copies of the RTC Day and Year registers
+    tmElements_t dn, up;            //power down and power up times
+
+    ramRead(DAY_REG, &day, 1);
+    ramRead(YEAR_REG, &yr, 1);
+    yr = y2kYearToTm(bcd2dec(yr));
+    if ( day & _BV(VBAT) ) {
+        Wire.beginTransmission(RTC_ADDR);
+        i2cWrite(PWRDWN_TS_REG);
+        Wire.endTransmission();
+
+        Wire.requestFrom(RTC_ADDR, TIMESTAMP_SIZE);     //read both timestamp registers, 8 bytes total
+        dn.Second = 0;
+        dn.Minute = bcd2dec(i2cRead());
+        dn.Hour = bcd2dec(i2cRead() & ~_BV(HR1224));    //assumes 24hr clock
+        dn.Day = bcd2dec(i2cRead());
+        dn.Month = bcd2dec(i2cRead() & 0x1F);           //mask off the day, we don't need it
+        dn.Year = yr;                                   //assume current year
+        up.Second = 0;
+        up.Minute = bcd2dec(i2cRead());
+        up.Hour = bcd2dec(i2cRead() & ~_BV(HR1224));    //assumes 24hr clock
+        up.Day = bcd2dec(i2cRead());
+        up.Month = bcd2dec(i2cRead() & 0x1F);           //mask off the day, we don't need it
+        up.Year = yr;                                   //assume current year
+        
+        *powerDown = makeTime(dn);
+        *powerUp = makeTime(up);
+        
+        //clear the VBAT bit, which causes the RTC hardware to clear the timestamps too.
+        //I suppose there is a risk here that the day has changed since we read it,
+        //but the Day of Week is actually redundant data and the makeTime() function
+        //does not use it. This could be an issue if someone is reading the RTC
+        //registers directly, but as this library is meant to be used with the Time library,
+        //and also because we don't provide a method to read the RTC clock/calendar
+        //registers directly, we won't lose any sleep about it at this point unless
+        //some issue is actually brought to our attention ;-)
+        day &= ~_BV(VBAT);
+        ramWrite(DAY_REG, &day , 1);
+
+        //adjust the powerDown timestamp if needed (see notes above)
+        if (*powerDown > *powerUp) {
+            --dn.Year;
+            *powerDown = makeTime(dn);
+        }            
+    }
+    else
+        return false;
+}
+
+/*----------------------------------------------------------------------*
+ * Enable or disable the square wave output.                            *
+ *----------------------------------------------------------------------*/
+void MCP79412RTC::squareWave(uint8_t freq)
+{
+    uint8_t ctrlReg;
+
+    ramRead(CTRL_REG, &ctrlReg, 1);
+    if (freq > 3) {
+        ctrlReg &= ~_BV(SQWE);
+    }
+    else {
+        ctrlReg = (ctrlReg & 0xF8) | _BV(SQWE) | freq;
+    }
+    ramWrite(CTRL_REG, &ctrlReg, 1);
+}
+
+/*----------------------------------------------------------------------*
+ * Set an alarm time. Sets the alarm registers only, does not enable    *
+ * the alarm. See enableAlarm().                                        *
+ *----------------------------------------------------------------------*/
+void MCP79412RTC::setAlarm(uint8_t alarmNumber, time_t alarmTime)
+{
+    tmElements_t tm;
+    uint8_t day;        //need to preserve bits in the day (of week) register
+
+    alarmNumber &= 0x01;        //ensure a valid alarm number
+    ramRead( ALM0_DAY + alarmNumber * (ALM1_REG - ALM0_REG) , &day, 1);
+    breakTime(alarmTime, tm);
+    Wire.beginTransmission(RTC_ADDR);
+    i2cWrite( ALM0_REG + alarmNumber * (ALM1_REG - ALM0_REG) );
+    i2cWrite(dec2bcd(tm.Second));
+    i2cWrite(dec2bcd(tm.Minute));
+    i2cWrite(dec2bcd(tm.Hour));                  //sets 24 hour format (Bit 6 == 0)
+    i2cWrite( (day & 0xF8) + tm.Wday );
+    i2cWrite(dec2bcd(tm.Day));
+    i2cWrite(dec2bcd(tm.Month));
+    Wire.endTransmission();  
+}
+
+/*----------------------------------------------------------------------*
+ * Enable or disable an alarm, and set the trigger criteria,            *
+ * e.g. match only seconds, only minutes, entire time and date, etc.    *
+ *----------------------------------------------------------------------*/
+void MCP79412RTC::enableAlarm(uint8_t alarmNumber, uint8_t alarmType)
+{
+    uint8_t day;                //alarm day register has config & flag bits
+    uint8_t ctrl;               //control register has alarm enable bits
+
+    alarmNumber &= 0x01;        //ensure a valid alarm number
+    ramRead(CTRL_REG, &ctrl, 1);
+    if (alarmType < ALM_DISABLE) {
+        ramRead(ALM0_DAY + alarmNumber * (ALM1_REG - ALM0_REG), &day, 1);
+        day = ( day & 0x07 ) | alarmType << 4;      //reset interrupt flag, OR in the config bits
+        ramWrite(ALM0_DAY + alarmNumber * (ALM1_REG - ALM0_REG), &day, 1);
+        ctrl |= _BV(ALM0 + alarmNumber);        //enable the alarm
+    }
+    else {
+        ctrl &= ~(_BV(ALM0 + alarmNumber));     //disable the alarm
+    }
+    ramWrite(CTRL_REG, &ctrl, 1);
+}
+
+/*----------------------------------------------------------------------*
+ * Returns true or false depending on whether the given alarm has been  *
+ * triggered, and resets the alarm "interrupt" flag. This is not a real *
+ * interrupt, just a bit that's set when an alarm is triggered.         *
+ *----------------------------------------------------------------------*/
+boolean MCP79412RTC::alarm(uint8_t alarmNumber)
+{
+    uint8_t day;                //alarm day register has config & flag bits
+
+    alarmNumber &= 0x01;        //ensure a valid alarm number
+    ramRead( ALM0_DAY + alarmNumber * (ALM1_REG - ALM0_REG) , &day, 1);
+    if (day & _BV(ALMIF)) {
+        day &= ~_BV(ALMIF);     //turn off the alarm "interrupt" flag
+        ramWrite( ALM0_DAY + alarmNumber * (ALM1_REG - ALM0_REG) , &day, 1);
+        return true;
+    }
+    else
+        return false;
+}
+
 /*----------------------------------------------------------------------*
  * Check to see if the RTC's oscillator is started (ST bit in seconds   *
  * register). Returns true if started.                                  *
 
@@ -46,13 +46,17 @@
 
 //MCP7941x Register Addresses
 #define TIME_REG 0x00        //7 registers, Seconds, Minutes, Hours, DOW, Date, Month, Year
+#define DAY_REG 0x03         //the RTC Day register contains the OSCON, VBAT, and VBATEN bits
+#define YEAR_REG 0x06        //RTC year register   
 #define CTRL_REG 0x07        //control register
 #define CALIB_REG 0x08       //calibration register
 #define UNLOCK_ID_REG 0x09   //unlock ID register
 #define ALM0_REG 0x0A        //alarm 0, 6 registers, Seconds, Minutes, Hours, DOW, Date, Month
 #define ALM1_REG 0x11        //alarm 1, 6 registers, Seconds, Minutes, Hours, DOW, Date, Month
+#define ALM0_DAY 0x0D        //DOW register has alarm config/flag bits
 #define PWRDWN_TS_REG 0x18   //power-down timestamp, 4 registers, Minutes, Hours, Date, Month
 #define PWRUP_TS_REG 0x1C    //power-up timestamp, 4 registers, Minutes, Hours, Date, Month
+#define TIMESTAMP_SIZE 8     //number of bytes in the two timestamp registers
 #define SRAM_START_ADDR 0x20 //first SRAM address
 #define SRAM_SIZE 64         //number of bytes of SRAM
 #define EEPROM_SIZE 128      //number of bytes of EEPROM
@@ -70,11 +74,7 @@
 #define RS2 2       //RS2:0 set square wave output frequency: 0==1Hz, 1==4096Hz, 2==8192Hz, 3=32768Hz
 #define RS1 1
 #define RS0 0
-#define SQWAVE_1_HZ 0
-#define SQWAVE_4096_HZ 1
-#define SQWAVE_8192_HZ 2
-#define SQWAVE_32768_HZ 3
-#define SQWAVE_NONE 4
+enum {SQWAVE_1_HZ, SQWAVE_4096_HZ, SQWAVE_8192_HZ, SQWAVE_32768_HZ, SQWAVE_NONE};
 
 //Other Control Bits
 #define ST 7        //Seconds register (TIME_REG) oscillator start/stop bit, 1==Start, 0==Stop
@@ -92,22 +92,19 @@
 #define ALMC1 5
 #define ALMC0 4
 #define ALMIF 3     //Alarm Interrupt Flag: Set by hardware when an alarm was triggered, cleared by software.
-#define ALM_MATCH_SECONDS 0     //Match Seconds  
-#define ALM_MATCH_MINUTES 1     //Match Minutes
-#define ALM_MATCH_HOURS 2       //Match Hours
-#define ALM_MATCH_DAY 3         //Match Day (alarm triggers at midnight)
-#define ALM_MATCH_DATE 4        //Match Date
-#define ALM_MATCH_DATETIME 5    //Match Second, Minute, Hour, Day, Date, Month
-
+enum {ALM_MATCH_SECONDS, ALM_MATCH_MINUTES, ALM_MATCH_HOURS, ALM_MATCH_DAY, ALM_MATCH_DATE, ALM_RESERVED_5, ALM_RESERVED_6, ALM_MATCH_DATETIME, ALM_DISABLE};
+//Note ALM_MATCH_DAY triggers alarm at midnight
+#define ALARM_0 0   //constants for calling functions
+#define ALARM_1 1
 
 class MCP79412RTC
 {
     public:
         MCP79412RTC();
         static time_t get(void);
-	static void set(time_t t);
-	static void read(tmElements_t &tm);
-	static void write(tmElements_t &tm);
+        static void set(time_t t);
+        static void read(tmElements_t &tm);
+        static void write(tmElements_t &tm);
         void sramWrite(byte addr, byte value);
         void sramWrite(byte addr, byte *values, byte nBytes);
         byte sramRead(byte addr);
@@ -119,6 +116,11 @@ class MCP79412RTC
         int calibRead(void);
         void calibWrite(int value);
         void idRead(byte *uniqueID);
+        boolean powerFail(time_t *powerDown, time_t *powerUp);
+        void squareWave(uint8_t freq);
+        void setAlarm(uint8_t alarmNumber, time_t alarmTime);
+        void enableAlarm(uint8_t alarmNumber, uint8_t alarmType);
+        boolean alarm(uint8_t alarmNumber);
 
         boolean oscStarted(void);
 
 
@@ -89,3 +89,30 @@ void calibWrite(int value);
 
 Read the 64-bit unique ID from the RTC into the given 8-byte array.
 void idRead(byte *uniqueID);
+
+Returns true or false to indicate whether a power failure has occurred.
+If one occurred, the power down and power up timestamps are returned in the variables
+given by the caller, the RTC's power fail flag is reset and the power up/down
+timestamps are cleared.
+boolean powerFail(time_t *powerDown, time_t *powerUp);
+
+Enables or disables the square wave output on the multi-function pin (MFP).
+freq is one of the following:
+SQWAVE_1_HZ, SQWAVE_4096_HZ, SQWAVE_8192_HZ, SQWAVE_32768_HZ, SQWAVE_NONE
+void squareWave(uint8_t freq);
+
+Set an alarm time. Sets the alarm registers only, does not enable
+the alarm, use enableAlarm() for that. alarmNumber is 0 or 1, but is
+ruthlessly masked to ensure this is so.
+void setAlarm(uint8_t alarmNumber, time_t alarmTime);
+
+Enable or disable the given alarm (0 or 1).
+alarmNumber is masked to ensure a value of 0 or 1.
+alarmType is one of the following:
+ALM_MATCH_SECONDS, ALM_MATCH_MINUTES, ALM_MATCH_HOURS, ALM_MATCH_DAY, ALM_MATCH_DATE, ALM_MATCH_DATETIME, ALM_DISABLE
+void enableAlarm(uint8_t alarmNumber, uint8_t alarmType);
+
+Tests whether the given alarm (0 or 1) has been triggered, returns
+true if triggered, else false. Clears the alarm flag to trap the next
+trigger event can be trapped.
+boolean alarm(uint8_t alarmNumber);