/bigdrive/home/boffin/Arduino-1.6/libraries/DS3231_Simple/DS3231_Simple.h

// Please note, the Arduino IDE is a bit retarded, if the below define has an
// underscore other than _h, it goes mental.  Wish it wouldn't  mess
// wif ma files!
#ifndef DS3231Easy_h
#define DS3231Easy_h
#include <Wire.h>


class DS3231_Simple
{
  public:
    
 // The DateTime structure can be implemented using bit-fields to probably reduce RAM
 // footprint, but costs quite a lot of flash (about 400 bytes) due to bit-juggling, 
 // Functionally equivalent in all other respects.
    
 // #define USE_BIT_FIELDS
    #ifdef USE_BIT_FIELDS
    struct DateTime 
    {      
      uint8_t Second:6;  // 0-59 = 6 bits
      uint8_t Minute:6;  // 0-59 = 6 bits
      uint8_t Hour:5;    // 0-23 = 5 bits
      uint8_t Dow:3;     // 1-7  = 3 bits (Day Of Week)
      uint8_t Day:5;     // 1-31 = 5 bits
      uint8_t Month:4;   // 1-12 = 4 bits
      uint8_t Year;      // 0-199 = 8 bits                  
    };
    #else
    struct DateTime 
    {      
      uint8_t Second;//:6;  // 0-59 = 6 bits
      uint8_t Minute;//:6;  // 0-59 = 6 bits
      uint8_t Hour;//:5;    // 0-23 = 5 bits
      uint8_t Dow;//:3;     // 1-7  = 3 bits (Day Of Week)
      uint8_t Day;//:5;     // 1-31 = 5 bits
      uint8_t Month;//:4;   // 1-12 = 4 bits
      uint8_t Year;      // 0-199 = 8 bits                  
    };
    #endif

    
    
  protected: 
  
    static const uint8_t      RTC_ADDRESS  = 0x68; 
      // Datasheet, Page 16, Figure 3.  Note that this is 7 bits, the last (LSB) bit of an I2C address indicates Read from Slave (1) or Write to Slave (1)   
      
    static uint8_t bcd2bin(uint8_t binaryRepresentation);
    static uint8_t bin2bcd(uint8_t bcdRepresentation);
    static uint8_t rtc_i2c_seek(const uint8_t Address);
    static uint8_t rtc_i2c_write_byte(const uint8_t Address, const uint8_t Byte);    
    static uint8_t rtc_i2c_read_byte(const uint8_t Address,  uint8_t &Byte);    
    static void    print_zero_padded(Stream &Printer, uint8_t x);    
          
  public:
    /* 
    static const uint8_t ALARM_EVERY_SECOND                    = 0B00101111;
    static const uint8_t ALARM_MATCH_SECOND                    = 0B00101110;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE             = 0B00101100;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR        = 0B00101000;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR_DATE   = 0B00100000;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR_DOW    = 0B00110000;

    static const uint8_t ALARM_EVERY_MINUTE                    = 0B01000111;
    static const uint8_t ALARM_MATCH_MINUTE                    = 0B01000110;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR               = 0B01000100;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR_DATE          = 0B01000000;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR_DOW           = 0B01010000;

    static const uint8_t ALARM_HOURLY                          = 0B11000110;
    static const uint8_t ALARM_DAILY                           = 0B11000100;
    static const uint8_t ALARM_WEEKLY                          = 0B11010000;
    static const uint8_t ALARM_MONTHLY                         = 0B11000000;    
    */
    
    static const uint8_t ALARM_EVERY_SECOND                    = 0B11110001;
    static const uint8_t ALARM_MATCH_SECOND                    = 0B01110001;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE             = 0B00110001;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR        = 0B00010001;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR_DATE   = 0B00000001;
    static const uint8_t ALARM_MATCH_SECOND_MINUTE_HOUR_DOW    = 0B00001001;

    static const uint8_t ALARM_EVERY_MINUTE                    = 0B01110010; 
    static const uint8_t ALARM_MATCH_MINUTE                    = 0B00110010;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR               = 0B00010010;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR_DATE          = 0B00000010;
    static const uint8_t ALARM_MATCH_MINUTE_HOUR_DOW           = 0B00001010;

    static const uint8_t ALARM_HOURLY                          = 0B00110011;
    static const uint8_t ALARM_DAILY                           = 0B00010011;
    static const uint8_t ALARM_WEEKLY                          = 0B00001011;
    static const uint8_t ALARM_MONTHLY                         = 0B00000011;  
    
    void begin();

    DateTime read();

    uint8_t  write(const DateTime&);

    void     promptForTimeAndDate(Stream &Serial);
    
    uint8_t  setAlarm(const DateTime &AlarmTime, uint8_t AlarmMode);

    uint8_t  setAlarm(uint8_t AlarmMode);    

    
    uint8_t  disableAlarms();
    
    uint8_t  checkAlarms(uint8_t PauseClock = false);

    uint8_t  getTemperature();

    float    getTemperatureFloat();

    void     printTo(Stream &Printer);

    void     printTo(Stream &Printer, const DateTime &Timestamp);
    
    void     printDateTo_DMY(Stream &Printer, const DateTime &Timestamp, const char separator = '/');
    
    void     printDateTo_DMY(Stream &Printer) { printDateTo_DMY(Printer, read()); }
    
    void     printDateTo_MDY(Stream &Printer, const DateTime &Timestamp, const char separator = '/');
    
    void     printDateTo_MDY(Stream &Printer) { printDateTo_MDY(Printer, read()); }
    
    void     printDateTo_YMD(Stream &Printer, const DateTime &Timestamp, const char separator = '-');       
    
    void     printDateTo_YMD(Stream &Printer) { printDateTo_YMD(Printer, read()); }
    
    void     printTimeTo_HMS(Stream &Printer, const DateTime &Timestamp, const char hoursToMinutesSeparator = ':', const char minutesToSecondsSeparator = ':');
    
    void     printTimeTo_HMS(Stream &Printer) { printTimeTo_HMS(Printer, read()); }

    void     printTimeTo_HM (Stream &Printer, const DateTime &Timestamp, const char hoursToMinutesSeparator = ':');
    
    void     printTimeTo_HM(Stream &Printer) { printTimeTo_HM(Printer, read()); }

    void     print12HourTimeTo_HMS(Stream &Printer, const DateTime &Timestamp, const char hoursToMinutesSeparator = ':', const char minutesToSecondsSeparator = ':');
    
    void     print12HourTimeTo_HMS(Stream &Printer) { print12HourTimeTo_HMS(Printer, read()); }

    void     print12HourTimeTo_HM (Stream &Printer, const DateTime &Timestamp, const char hoursToMinutesSeparator = ':');
    
    void     print12HourTimeTo_HM(Stream &Printer) { print12HourTimeTo_HM(Printer, read()); }
    
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // EEPROM LOGGING
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  protected:
  
    static const uint8_t      EEPROM_ADDRESS   = 0x57;                          
      // 7 Bit address, the first 4 bits are 1010, the the last 3 bits according to A2, A1 and A0
      // On the common ZS-042 board, this corresponds to (where x is jumper open, and 1 is jumper closed)
      // A0    A1    A2
      //  x    x     x    0x57  (default)
      //  1    x     x    0x56
      //  x    1     x    0x55
      //  1    1     x    0x54
      //  0    0     1    0x53
      //  1    0     1    0x52
      //  1    1     1    0x51
                                                                                
                                                                                
    static const uint16_t     EEPROM_SIZE_KBIT = 32768;                         // EEPROMs are sized in kilobit
    static const uint8_t      EEPROM_PAGE_SIZE = 32;                            // And have a number of bytes per page
    static const uint16_t     EEPROM_BYTES     = EEPROM_SIZE_KBIT/8;            
    static const uint8_t      EEPROM_PAGES     = EEPROM_BYTES/EEPROM_PAGE_SIZE; 

    // EEPROM structure       
    //  The EEPROM is used to store "log entries" which each consist of a 5 byte header and an additional 0 to 7 data bytes.
    //  The Header of each block includes a count of the data bytes and then a binary representation of the timestamp.
    //
    //  Blocks are recorded in a circular-buffer fashion in order to reduce wear on the EEPROM, that is, each next block is stored
    //  after the block preceeding it, when the top of the EEPROM is reached the next block goes to the EEPROM address zero.
    //
    //  Blocks do NOT cross EEPROM boundary (a block will not start at the top of the EEPROM and loop around to the bottom) before ending
    //  if a block doesn't fit in the available space at the top of the blocks in the EEPROM, it will be placed in address zero.  
    // 
    //  Blocks are zeroed completely on read or when they are to be overwritten (even partially overwritten the entire block is nuked).
    //    
    //  <Block>     ::= <Header><DataBytes>
    //  <Header> ::= 0Bzzzwwwyy yyyyyymm mmdddddh hhhhiiii iissssss binary representation of DateTime, (zzz = number of data bytes following timestamp, www = day-of-week)
    //  <DataBytes> ::= DB1..7   

    
    uint16_t                  eepromWriteAddress   = EEPROM_BYTES;               // Byte address of the "top" of the EEPROM "stack", the next
                                                                                // "block" stored will be put here, this location may be 
                                                                                // a valid block start byte, or it may be 00000000 in which case
                                                                                // there are zero bytes until the next block start which will be
                                                                                // the first of the series.      
                                                                                
    uint16_t                  eepromReadAddress = EEPROM_BYTES;                 // Byte address of the "bottom" of the EEPROM "stack", the next
                                                                                // "block" to read is found here, this location may be 
                                                                                // a valid block start byte, or it may be 00000000 in which case
                                                                                // there are zero bytes to read.

    uint16_t findEEPROMWriteAddress();    

    uint8_t  makeEEPROMSpace(uint16_t Address, int8_t BytesRequired);

    uint16_t findEEPROMReadAddress();

    uint16_t readLogFrom(uint16_t Address, DateTime &timestamp, uint8_t *data, uint8_t size = 0);

    uint8_t writeBytePagewizeStart();

    uint8_t writeBytePagewize(const uint8_t data);

    uint8_t writeBytePagewizeEnd();
      
    uint8_t  readEEPROMByte(const uint16_t Address);

    
  public:
    uint8_t  formatEEPROM();
  
    template <typename datatype>
      uint8_t  writeLog( const datatype &data  )   { 
         return writeLog(read(), (uint8_t *) &data, (uint8_t)sizeof(datatype));         
      }
   
    template <typename datatype>
      uint8_t  writeLog( const DateTime &timestamp,  const datatype &data  )   {      
         return writeLog(timestamp, (uint8_t *) &data, (uint8_t)sizeof(datatype));         
      }

    uint8_t  writeLog( const DateTime &timestamp,  const uint8_t *data, uint8_t size = 1 );
    

    template <typename datatype>
      uint8_t  readLog( DateTime &timestamp,  datatype &data  )   {   
         return readLog(timestamp, (uint8_t *) &data, (uint8_t)sizeof(datatype));         
      }
      
    uint8_t  readLog( DateTime &timestamp,         uint8_t *data,       uint8_t size = 1 );
    

    int8_t   compareTimestamps(const DateTime &A, const DateTime &B);
    
};

typedef DS3231_Simple::DateTime DateTime;
#endif