DS1307.h

00001 /* Rtc_Ds1307.h */
00002 /*
00003 Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
00004 
00005 Permission is hereby granted, free of charge, to any person obtaining a copy
00006 of this software and associated documentation files (the "Software"), to deal
00007 in the Software without restriction, including without limitation the rights
00008 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00009 copies of the Software, and to permit persons to whom the Software is
00010 furnished to do so, subject to the following conditions:
00011 
00012 The above copyright notice and this permission notice shall be included in
00013 all copies or substantial portions of the Software.
00014 
00015 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00016 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00017 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00018 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00019 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00020 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00021 THE SOFTWARE.
00022 */
00023 #include "mbed.h"
00024 
00025 #ifndef __DS1307_H__
00026 #define __DS1307_H__
00027 
00028 
00029 
00030 /** Class Rtc_Ds1307 implements the real time clock module DS1307
00031  *
00032  * You can read the clock and set a new time and date.
00033  * It is also possible to start and stop the clock.
00034  * Rtc_Ds1307 allows you to display the time in a 12h or 24h format
00035  */
00036 class DS1307
00037 {
00038 public:
00039     /** Structure which is used to exchange the time and date
00040      */
00041     typedef struct {
00042         int sec ;        /*!< seconds [0..59] */
00043         int min ;        /*!< minutes {0..59] */
00044         int hour ;       /*!< hours [0..23] */
00045         int wday ;       /*!< weekday [1..7, where 1 = sunday, 2 = monday, ... */
00046         int date ;       /*!< day of month [0..31] */
00047         int mon ;        /*!< month of year [1..12] */
00048         int year ;       /*!< year [2000..2255] */
00049     } Time_rtc;
00050 
00051 
00052     /** RateSelect specifies the valid frequency values for the square wave output
00053      */
00054     typedef enum {
00055         RS1Hz = 0,
00056         RS4kHz = 1,
00057         RS8kHz = 2,
00058         RS32kHz = 3
00059     } SqwRateSelect_t;
00060 
00061 protected:
00062     I2C *  m_rtc;
00063 
00064     static const char *m_weekDays[];
00065 
00066 public:
00067     /** public constructor which creates the real time clock object
00068      *
00069      * @param sda : specifies the pin for the SDA communication line.
00070      *
00071      * @param scl : the pin for the serial clock
00072      *
00073      */
00074     DS1307(I2C * );
00075 
00076     ~DS1307();
00077 
00078     /** Read the current time from RTC chip
00079      *
00080      * @param time : reference to a struct tm which will be filled with the time from rtc
00081      *
00082      * @returns true if successful, otherwise an acknowledge error occured
00083      */
00084     virtual bool getTime(Time_rtc& time);
00085 
00086     /** Write the given time onto the RTC chip
00087      *
00088      * @param time : refereence to a struct which contains valid date and time information
00089      *
00090      * @param start : contains true if the clock shall start (or keep on running).
00091      *
00092      * @param thm : 12-hour-mode if set to true, otherwise 24-hour-mode will be set.
00093      *
00094      * @returns true if successful, otherwise an acknowledge error occured
00095      */
00096     virtual bool setTime(Time_rtc& time, bool start, bool thm);
00097 
00098     /** Start the clock. Please note that the seconds register need to be read and
00099      * written in order to start or stop the clock. This can lead to an error
00100      * in the time value. The recommended way of starting and stoping the clock is
00101      * to write the actual date and time and set the start bit accordingly.
00102      *
00103      * @returns true if the clock was started, false if a communication error occured
00104      */
00105     bool startClock();
00106 
00107     /** Stop the clock. Please note that the seconds register need to be read and
00108      * written in order to start or stop the clock. This can lead to an error
00109      * in the time value. The recommended way of starting and stoping the clock is
00110      * to write the actual date and time and set the start bit accordingly.
00111      *
00112      * @returns true if the clock was stopped, false if a communication error occured
00113      */
00114     bool stopClock();
00115 
00116     /** Service function to convert a weekday into a string representation
00117      *
00118      * @param wday : day of week to convert (starting with sunday = 1, monday = 2, ..., saturday = 7
00119      *
00120      * @returns the corresponding string representation
00121      */
00122     const char* weekdayToString( int wday ) {
00123         return m_weekDays[wday%7];
00124     }
00125 
00126     /** Enable Square Wave output. The function enables or disables the square wave output
00127      * of the module and sets the desired frequency.
00128      *
00129      * @param ena : if set to true, the square wave output is enabled.
00130      *
00131      * @param rs : rate select, can be either one of the four values defined by type /c RateSelect_t
00132      *
00133      * @return true if the operation was successful or false otherwise
00134      */
00135     bool setSquareWaveOutput(bool ena, SqwRateSelect_t rs);
00136     
00137     void setLocalTime();
00138 
00139 private:
00140     bool read(int address, char* buffer, int len);
00141     bool write(int address, char* buffer, int len);
00142 
00143     static int bcdToDecimal(int bcd) {
00144         return ((bcd&0xF0)>>4)*10 + (bcd&0x0F);
00145     }
00146 
00147     static int decimalToBcd(int dec) {
00148         return (dec%10) + ((dec/10)<<4);
00149     }
00150 };
00151 
00152 
00153 
00154 typedef void (*RtcCallback_t) (void);
00155 
00156 
00157 class RtcCls : public DS1307
00158 {
00159 protected:
00160     InterruptIn                 m_sqw;
00161     bool                        m_bUseSqw;
00162     time_t                      m_time;             //  Only used in case SQW is used
00163     
00164     bool                        m_bAlarmEnabled;
00165     RtcCallback_t               m_alarmfunc;
00166     time_t                      m_alarmTime;
00167     
00168 public:
00169     RtcCls(I2C * i2c, PinName sqw, bool bUseSqw);
00170     
00171 protected:
00172     void _callback(void);
00173     
00174 public:
00175     time_t                      getTime();
00176     virtual bool                getTime(Time_rtc& time)                         { return DS1307::getTime(time); }
00177     void                        setTime(time_t time);
00178     virtual bool                setTime(Time_rtc& time, bool start, bool thm)   { return DS1307::setTime(time, start, thm); }
00179 public:
00180     void                        setAlarm(int nSeconds, RtcCallback_t alarmfunc) {
00181         m_alarmfunc = alarmfunc;
00182         m_alarmTime = m_time + nSeconds;
00183         m_bAlarmEnabled = (alarmfunc == NULL) ? false : true;
00184     }
00185 };
00186 
00187 #endif // __DS1307_H__