RTClib.h

00001 /**************************************************************************/
00002 /*!
00003   @file     RTClib.h
00004 
00005   Original library by JeeLabs http://news.jeelabs.org/code/, released to the public domain
00006 
00007   License: MIT (see LICENSE)
00008 
00009   This is a fork of JeeLab's fantastic real time clock library for Arduino.
00010 
00011   For details on using this library with an RTC module like the DS1307, PCF8523, or DS3231,
00012   see the guide at: https://learn.adafruit.com/ds1307-real-time-clock-breakout-board-kit/overview
00013 
00014   Adafruit invests time and resources providing this open source code,
00015   please support Adafruit and open-source hardware by purchasing
00016   products from Adafruit!
00017 */
00018 /**************************************************************************/
00019 
00020 #ifndef _RTCLIB_H_
00021 #define _RTCLIB_H_
00022 
00023 #include "mbed.h"
00024 #include <string>
00025 //using namespace std;
00026 class TimeSpan;
00027 
00028 #define DS3231_ADDRESS      0xD0    ///< I2C address for DS3231
00029 
00030 /** Registers */
00031 #define DS3231_SECONDS      0x00
00032 #define DS3231_MINUTES      0x01
00033 #define DS3231_HOURS        0x02
00034 #define DS3231_DAY          0x03
00035 #define DS3231_DATE         0x04
00036 #define DS3231_MONTH        0x05
00037 #define DS3231_YEAR         0x06
00038 #define DS3231_A1SEC        0x07
00039 #define DS3231_A1MIN        0x08
00040 #define DS3231_A1HOUR       0x09
00041 #define DS3231_A1DYDT       0x0A
00042 #define DS3231_A2MIN        0x0B
00043 #define DS3231_A2HOUR       0x0C
00044 #define DS3231_A2DYDT       0x0D
00045 #define DS3231_CONTROL      0x0E    ///< Control register
00046 #define DS3231_STATUSREG    0x0F    ///< Status register
00047 #define DS3231_AGINGOFFSET  0x10
00048 #define DS3231_TEMPREG1     0x11
00049 #define DS3231_TEMPREG2     0x12
00050 
00051 /** Constants */
00052 #define SECONDS_PER_DAY             86400L      ///< 60 * 60 * 24
00053 #define SECONDS_FROM_1970_TO_2000   946684800   ///< Unixtime for 2000-01-01 00:00:00, useful for initialization
00054 
00055 
00056 /**************************************************************************/
00057 /*!
00058     @brief  Simple general-purpose date/time class (no TZ / DST / leap second handling!).
00059             See http://en.wikipedia.org/wiki/Leap_second
00060 */
00061 /**************************************************************************/
00062 class DateTime
00063 {
00064 public:
00065     DateTime (uint32_t t = SECONDS_FROM_1970_TO_2000);
00066     DateTime (uint16_t year, uint8_t month, uint8_t day,
00067               uint8_t hour = 0, uint8_t min = 0, uint8_t sec = 0);
00068     DateTime (const DateTime& copy);
00069     DateTime (const char* date, const char* time);
00070     //DateTime (const __FlashstringHelper* date, const __FlashstringHelper* time);
00071     char* tostring(char* buffer);
00072 
00073     /*!
00074         @brief  Return the year, stored as an offset from 2000
00075         @return uint16_t year
00076     */
00077     uint16_t year() const
00078     {
00079         return 2000 + yOff;
00080     }
00081     /*!
00082         @brief  Return month
00083         @return uint8_t month
00084     */
00085     uint8_t month() const
00086     {
00087         return m;
00088     }
00089     /*!
00090         @brief  Return day
00091         @return uint8_t day
00092     */
00093     uint8_t day() const
00094     {
00095         return d;
00096     }
00097     /*!
00098         @brief  Return hours
00099         @return uint8_t hours
00100     */
00101     uint8_t hour() const
00102     {
00103         return hh;
00104     }
00105     /*!
00106         @brief  Return minutes
00107         @return uint8_t minutes
00108     */
00109     uint8_t minute() const
00110     {
00111         return mm;
00112     }
00113     /*!
00114         @brief  Return seconds
00115         @return uint8_t seconds
00116     */
00117     uint8_t second() const
00118     {
00119         return ss;
00120     }
00121 
00122     uint8_t dayOfTheWeek() const;
00123 
00124     /** 32-bit times as seconds since 1/1/2000 */
00125     long secondstime() const;
00126 
00127     /** 32-bit times as seconds since 1/1/1970 */
00128     uint32_t unixtime(void) const;
00129 
00130     /** ISO 8601 Timestamp function */
00131     enum timestampOpt {
00132         TIMESTAMP_FULL, // YYYY-MM-DDTHH:MM:SS
00133         TIMESTAMP_TIME, // HH:MM:SS
00134         TIMESTAMP_DATE  // YYYY-MM-DD
00135     };
00136     string timestamp(timestampOpt opt = TIMESTAMP_FULL);
00137 
00138     DateTime operator+(const TimeSpan& span);
00139     DateTime operator-(const TimeSpan& span);
00140     TimeSpan operator-(const DateTime& right);
00141     bool operator<(const DateTime& right) const;
00142     /*!
00143         @brief  Test if one DateTime is greater (later) than another
00144         @param right DateTime object to compare
00145         @return True if the left object is greater than the right object, false otherwise
00146     */
00147     bool operator>(const DateTime& right) const
00148     {
00149         return right < *this;
00150     }
00151     /*!
00152         @brief  Test if one DateTime is less (earlier) than or equal to another
00153         @param right DateTime object to compare
00154         @return True if the left object is less than or equal to the right object, false otherwise
00155     */
00156     bool operator<=(const DateTime& right) const
00157     {
00158         return !(*this > right);
00159     }
00160     /*!
00161         @brief  Test if one DateTime is greater (later) than or equal to another
00162         @param right DateTime object to compare
00163         @return True if the left object is greater than or equal to the right object, false otherwise
00164     */
00165     bool operator>=(const DateTime& right) const
00166     {
00167         return !(*this < right);
00168     }
00169     bool operator==(const DateTime& right) const;
00170     /*!
00171         @brief  Test if two DateTime objects not equal
00172         @param right DateTime object to compare
00173         @return True if the two objects are not equal, false if they are
00174     */
00175     bool operator!=(const DateTime& right) const
00176     {
00177         return !(*this == right);
00178     }
00179 
00180 protected:
00181     uint8_t yOff;   ///< Year offset from 2000
00182     uint8_t m;      ///< Month 1-12
00183     uint8_t d;      ///< Day 1-31
00184     uint8_t hh;     ///< Hours 0-23
00185     uint8_t mm;     ///< Minutes 0-59
00186     uint8_t ss;     ///< Seconds 0-59
00187 };
00188 
00189 
00190 /**************************************************************************/
00191 /*!
00192     @brief  Timespan which can represent changes in time with seconds accuracy.
00193 */
00194 /**************************************************************************/
00195 class TimeSpan
00196 {
00197 public:
00198     TimeSpan (int32_t seconds = 0);
00199     TimeSpan (int16_t days, int8_t hours, int8_t minutes, int8_t seconds);
00200     TimeSpan (const TimeSpan& copy);
00201 
00202     /*!
00203         @brief  Number of days in the TimeSpan
00204                 e.g. 4
00205         @return int16_t days
00206     */
00207     int16_t days() const
00208     {
00209         return _seconds / 86400L;
00210     }
00211     /*!
00212         @brief  Number of hours in the TimeSpan
00213                 This is not the total hours, it includes the days
00214                 e.g. 4 days, 3 hours - NOT 99 hours
00215         @return int8_t hours
00216     */
00217     int8_t  hours() const
00218     {
00219         return _seconds / 3600 % 24;
00220     }
00221     /*!
00222         @brief  Number of minutes in the TimeSpan
00223                 This is not the total minutes, it includes days/hours
00224                 e.g. 4 days, 3 hours, 27 minutes
00225         @return int8_t minutes
00226     */
00227     int8_t  minutes() const
00228     {
00229         return _seconds / 60 % 60;
00230     }
00231     /*!
00232         @brief  Number of seconds in the TimeSpan
00233                 This is not the total seconds, it includes the days/hours/minutes
00234                 e.g. 4 days, 3 hours, 27 minutes, 7 seconds
00235         @return int8_t seconds
00236     */
00237     int8_t  seconds() const
00238     {
00239         return _seconds % 60;
00240     }
00241     /*!
00242         @brief  Total number of seconds in the TimeSpan, e.g. 358027
00243         @return int32_t seconds
00244     */
00245     int32_t totalseconds() const
00246     {
00247         return _seconds;
00248     }
00249 
00250     TimeSpan operator+(const TimeSpan& right);
00251     TimeSpan operator-(const TimeSpan& right);
00252 
00253 protected:
00254     int32_t _seconds;   ///< Actual TimeSpan value is stored as seconds
00255 };
00256 
00257 /** DS3231 SQW pin mode settings */
00258 enum Ds3231SqwPinMode {
00259     DS3231_OFF            = 0x01, // Off
00260     DS3231_SquareWave1Hz  = 0x00, // 1Hz square wave
00261     DS3231_SquareWave1kHz = 0x08, // 1kHz square wave
00262     DS3231_SquareWave4kHz = 0x10, // 4kHz square wave
00263     DS3231_SquareWave8kHz = 0x18  // 8kHz square wave
00264 };
00265 
00266 /**************************************************************************/
00267 /*!
00268     @brief  RTC based on the DS3231 chip connected via I2C and the Wire library
00269 */
00270 /**************************************************************************/
00271 class RTC_DS3231
00272 {
00273 public:
00274     RTC_DS3231(I2C *i2c);
00275     ~RTC_DS3231();
00276     bool begin(void);
00277     void adjust(const DateTime& dt);
00278     bool lostPower(void);
00279     DateTime now();
00280     Ds3231SqwPinMode readSqwPinMode();
00281     void writeSqwPinMode(Ds3231SqwPinMode mode);
00282     float getTemperature();  // in Celcius degree
00283     uint8_t read_i2c_register(uint8_t addr, uint8_t reg);
00284     void write_i2c_register(uint8_t addr, uint8_t reg, uint8_t val) ;
00285 private:
00286     // Internal Resources
00287     I2C *_i2c;
00288 };
00289 
00290 
00291 #endif // _RTCLIB_H_