RTClib.h

Go to the documentation of this file.

/**************************************************************************/
/**************************************************************************/

#ifndef _RTCLIB_H_
#define _RTCLIB_H_

#include <Adafruit_I2CDevice.h>
#include <Arduino.h>

class TimeSpan;

#define SECONDS_PER_DAY 86400L 
#define SECONDS_FROM_1970_TO_2000                                              \
  946684800 


enum Ds1307SqwPinMode {
  DS1307_OFF = 0x00,            // Low
  DS1307_ON = 0x80,             // High
  DS1307_SquareWave1HZ = 0x10,  // 1Hz square wave
  DS1307_SquareWave4kHz = 0x11, // 4kHz square wave
  DS1307_SquareWave8kHz = 0x12, // 8kHz square wave
  DS1307_SquareWave32kHz = 0x13 // 32kHz square wave
};

enum Ds3231SqwPinMode {
  DS3231_OFF = 0x1C,            
  DS3231_SquareWave1Hz = 0x00,  
  DS3231_SquareWave1kHz = 0x08, 
  DS3231_SquareWave4kHz = 0x10, 
  DS3231_SquareWave8kHz = 0x18  
};

enum Ds3231Alarm1Mode {
  DS3231_A1_PerSecond = 0x0F, 
  DS3231_A1_Second = 0x0E,    
  DS3231_A1_Minute = 0x0C,    
  DS3231_A1_Hour = 0x08,      
  DS3231_A1_Date = 0x00,      
  DS3231_A1_Day = 0x10        
};
enum Ds3231Alarm2Mode {
  DS3231_A2_PerMinute = 0x7, 
  DS3231_A2_Minute = 0x6,    
  DS3231_A2_Hour = 0x4,      
  DS3231_A2_Date = 0x0,      
  DS3231_A2_Day = 0x8        
};
enum Pcf8523SqwPinMode {
  PCF8523_OFF = 7,             
  PCF8523_SquareWave1HZ = 6,   
  PCF8523_SquareWave32HZ = 5,  
  PCF8523_SquareWave1kHz = 4,  
  PCF8523_SquareWave4kHz = 3,  
  PCF8523_SquareWave8kHz = 2,  
  PCF8523_SquareWave16kHz = 1, 
  PCF8523_SquareWave32kHz = 0  
};

enum PCF8523TimerClockFreq {
  PCF8523_Frequency4kHz = 0,   
  PCF8523_Frequency64Hz = 1,   
  PCF8523_FrequencySecond = 2, 
  PCF8523_FrequencyMinute = 3, 
  PCF8523_FrequencyHour = 4,   
};

enum PCF8523TimerIntPulse {
  PCF8523_LowPulse3x64Hz = 0,  
  PCF8523_LowPulse4x64Hz = 1,  
  PCF8523_LowPulse5x64Hz = 2,  
  PCF8523_LowPulse6x64Hz = 3,  
  PCF8523_LowPulse8x64Hz = 4,  
  PCF8523_LowPulse10x64Hz = 5, 
  PCF8523_LowPulse12x64Hz = 6, 
  PCF8523_LowPulse14x64Hz = 7  
};

enum Pcf8523OffsetMode {
  PCF8523_TwoHours = 0x00, 
  PCF8523_OneMinute = 0x80 
};

enum Pcf8563SqwPinMode {
  PCF8563_SquareWaveOFF = 0x00,  
  PCF8563_SquareWave1Hz = 0x83,  
  PCF8563_SquareWave32Hz = 0x82, 
  PCF8563_SquareWave1kHz = 0x81, 
  PCF8563_SquareWave32kHz = 0x80 
};

/**************************************************************************/
/**************************************************************************/
class DateTime {
public:
  DateTime(uint32_t t = SECONDS_FROM_1970_TO_2000);
  DateTime(uint16_t year, uint8_t month, uint8_t day, uint8_t hour = 0,
           uint8_t min = 0, uint8_t sec = 0);
  DateTime(const DateTime &copy);
  DateTime(const char *date, const char *time);
  DateTime(const __FlashStringHelper *date, const __FlashStringHelper *time);
  DateTime(const char *iso8601date);
  bool isValid() const;
  char *toString(char *buffer) const;

  uint16_t year() const { return 2000U + yOff; }
  uint8_t month() const { return m; }
  uint8_t day() const { return d; }
  uint8_t hour() const { return hh; }

  uint8_t twelveHour() const;
  uint8_t isPM() const { return hh >= 12; }
  uint8_t minute() const { return mm; }
  uint8_t second() const { return ss; }

  uint8_t dayOfTheWeek() const;

  /* 32-bit times as seconds since 2000-01-01. */
  uint32_t secondstime() const;

  /* 32-bit times as seconds since 1970-01-01. */
  uint32_t unixtime(void) const;

  enum timestampOpt {
    TIMESTAMP_FULL, 
    TIMESTAMP_TIME, 
    TIMESTAMP_DATE  
  };
  String timestamp(timestampOpt opt = TIMESTAMP_FULL) const;

  DateTime operator+(const TimeSpan &span) const;
  DateTime operator-(const TimeSpan &span) const;
  TimeSpan operator-(const DateTime &right) const;
  bool operator<(const DateTime &right) const;

  bool operator>(const DateTime &right) const { return right < *this; }

  bool operator<=(const DateTime &right) const { return !(*this > right); }

  bool operator>=(const DateTime &right) const { return !(*this < right); }
  bool operator==(const DateTime &right) const;

  bool operator!=(const DateTime &right) const { return !(*this == right); }

protected:
  uint8_t yOff; 
  uint8_t m;    
  uint8_t d;    
  uint8_t hh;   
  uint8_t mm;   
  uint8_t ss;   
};

/**************************************************************************/
/**************************************************************************/
class TimeSpan {
public:
  TimeSpan(int32_t seconds = 0);
  TimeSpan(int16_t days, int8_t hours, int8_t minutes, int8_t seconds);
  TimeSpan(const TimeSpan &copy);

  int16_t days() const { return _seconds / 86400L; }
  int8_t hours() const { return _seconds / 3600 % 24; }
  int8_t minutes() const { return _seconds / 60 % 60; }
  int8_t seconds() const { return _seconds % 60; }
  int32_t totalseconds() const { return _seconds; }

  TimeSpan operator+(const TimeSpan &right) const;
  TimeSpan operator-(const TimeSpan &right) const;

protected:
  int32_t _seconds; 
};

/**************************************************************************/
/**************************************************************************/
class RTC_I2C {
protected:
  static uint8_t bcd2bin(uint8_t val) { return val - 6 * (val >> 4); }
  static uint8_t bin2bcd(uint8_t val) { return val + 6 * (val / 10); }
  Adafruit_I2CDevice *i2c_dev = NULL; 
  uint8_t read_register(uint8_t reg);
  void write_register(uint8_t reg, uint8_t val);
};

/**************************************************************************/
/**************************************************************************/
class RTC_DS1307 : RTC_I2C {
public:
  bool begin(TwoWire *wireInstance = &Wire);
  void adjust(const DateTime &dt);
  uint8_t isrunning(void);
  DateTime now();
  Ds1307SqwPinMode readSqwPinMode();
  void writeSqwPinMode(Ds1307SqwPinMode mode);
  uint8_t readnvram(uint8_t address);
  void readnvram(uint8_t *buf, uint8_t size, uint8_t address);
  void writenvram(uint8_t address, uint8_t data);
  void writenvram(uint8_t address, const uint8_t *buf, uint8_t size);
};

/**************************************************************************/
/**************************************************************************/
class RTC_DS3231 : RTC_I2C {
public:
  bool begin(TwoWire *wireInstance = &Wire);
  void adjust(const DateTime &dt);
  bool lostPower(void);
  DateTime now();
  Ds3231SqwPinMode readSqwPinMode();
  void writeSqwPinMode(Ds3231SqwPinMode mode);
  bool setAlarm1(const DateTime &dt, Ds3231Alarm1Mode alarm_mode);
  bool setAlarm2(const DateTime &dt, Ds3231Alarm2Mode alarm_mode);
  DateTime getAlarm1();
  DateTime getAlarm2();
  Ds3231Alarm1Mode getAlarm1Mode();
  Ds3231Alarm2Mode getAlarm2Mode();
  void disableAlarm(uint8_t alarm_num);
  void clearAlarm(uint8_t alarm_num);
  bool alarmFired(uint8_t alarm_num);
  void enable32K(void);
  void disable32K(void);
  bool isEnabled32K(void);
  float getTemperature(); // in Celsius degree
  static uint8_t dowToDS3231(uint8_t d) { return d == 0 ? 7 : d; }
};

/**************************************************************************/
/**************************************************************************/
class RTC_PCF8523 : RTC_I2C {
public:
  bool begin(TwoWire *wireInstance = &Wire);
  void adjust(const DateTime &dt);
  bool lostPower(void);
  bool initialized(void);
  DateTime now();
  void start(void);
  void stop(void);
  uint8_t isrunning();
  Pcf8523SqwPinMode readSqwPinMode();
  void writeSqwPinMode(Pcf8523SqwPinMode mode);
  void enableSecondTimer(void);
  void disableSecondTimer(void);
  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods,
                            uint8_t lowPulseWidth);
  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods);
  void disableCountdownTimer(void);
  void deconfigureAllTimers(void);
  void calibrate(Pcf8523OffsetMode mode, int8_t offset);
};

/**************************************************************************/
/**************************************************************************/
class RTC_PCF8563 : RTC_I2C {
public:
  bool begin(TwoWire *wireInstance = &Wire);
  bool lostPower(void);
  void adjust(const DateTime &dt);
  DateTime now();
  void start(void);
  void stop(void);
  uint8_t isrunning();
  Pcf8563SqwPinMode readSqwPinMode();
  void writeSqwPinMode(Pcf8563SqwPinMode mode);
};

/**************************************************************************/
/**************************************************************************/
class RTC_Millis {
public:
  void begin(const DateTime &dt) { adjust(dt); }
  void adjust(const DateTime &dt);
  DateTime now();

protected:
  uint32_t lastUnix;
  uint32_t lastMillis;
};

/**************************************************************************/
/**************************************************************************/
class RTC_Micros {
public:
  void begin(const DateTime &dt) { adjust(dt); }
  void adjust(const DateTime &dt);
  void adjustDrift(int ppm);
  DateTime now();

protected:
  uint32_t microsPerSecond = 1000000;
  uint32_t lastUnix;
  uint32_t lastMicros;
};

#endif // _RTCLIB_H_