ds3231.h

00001 /******************************************************************//**
00002 * @file ds3231.h
00003 *
00004 * @author Justin Jordan
00005 *
00006 * @version 1.0
00007 *
00008 * Started: 11NOV14
00009 *
00010 * Updated: 
00011 *
00012 * @brief Header file for DS3231 class
00013 *
00014 ***********************************************************************
00015 *
00016 * @copyright 
00017 * Copyright (C) 2015 Maxim Integrated Products, Inc., All Rights Reserved.
00018 *
00019 * Permission is hereby granted, free of charge, to any person obtaining a
00020 * copy of this software and associated documentation files (the "Software"),
00021 * to deal in the Software without restriction, including without limitation
00022 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00023 * and/or sell copies of the Software, and to permit persons to whom the
00024 * Software is furnished to do so, subject to the following conditions:
00025 *
00026 * The above copyright notice and this permission notice shall be included
00027 * in all copies or substantial portions of the Software.
00028 *
00029 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00030 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00031 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00032 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00033 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00034 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00035 * OTHER DEALINGS IN THE SOFTWARE.
00036 *
00037 * Except as contained in this notice, the name of Maxim Integrated
00038 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00039 * Products, Inc. Branding Policy.
00040 *
00041 * The mere transfer of this software does not imply any licenses
00042 * of trade secrets, proprietary technology, copyrights, patents,
00043 * trademarks, maskwork rights, or any other form of intellectual
00044 * property whatsoever. Maxim Integrated Products, Inc. retains all
00045 * ownership rights.
00046 **********************************************************************/
00047 
00048 
00049 #ifndef DS3231_H
00050 #define DS3231_H
00051 
00052 
00053 #include "mbed.h"
00054 
00055 
00056 #define DS3231_I2C_ADRS 0x68 
00057 #define I2C_WRITE 0
00058 #define I2C_READ  1
00059 
00060 #define AM_PM     (1 << 5) 
00061 #define MODE      (1 << 6)
00062 #define DY_DT     (1 << 6)
00063 #define ALRM_MASK (1 << 7)
00064 
00065 //control register bit masks
00066 #define A1IE  (1 << 0)
00067 #define A2IE  (1 << 1)
00068 #define INTCN (1 << 2)
00069 #define RS1   (1 << 3)
00070 #define RS2   (1 << 4)
00071 #define CONV  (1 << 5)
00072 #define BBSQW (1 << 6)
00073 #define EOSC  (1 << 7)
00074 
00075 //status register bit masks
00076 #define A1F     (1 << 0)
00077 #define A2F     (1 << 1)
00078 #define BSY     (1 << 2)
00079 #define EN32KHZ (1 << 3)
00080 #define OSF     (1 << 7)
00081   
00082 
00083 /**
00084 * ds3231_time_t - Struct for containing time data.
00085 * 
00086 * Members:
00087 *
00088 * - uint32_t seconds - Use decimal value. Member fx's convert to BCD
00089 *
00090 * - uint32_t minutes - Use decimal value. Member fx's convert to BCD
00091 *
00092 * - uint32_t hours   - Use decimal value. Member fx's convert to BCD
00093 *
00094 * - bool am_pm      - TRUE for PM, same logic as datasheet
00095 *
00096 * - bool mode       - TRUE for 12 hour, same logic as datasheet
00097 */
00098 typedef struct
00099 {
00100     uint32_t seconds; 
00101     uint32_t minutes; 
00102     uint32_t hours; 
00103     bool am_pm; 
00104     bool mode; 
00105 }ds3231_time_t;
00106 
00107 
00108 /**
00109 * ds3231_calendar_t - Struct for containing calendar data.
00110 * 
00111 * Members:
00112 *
00113 * - uint32_t day   - Use decimal value. Member fx's convert to BCD
00114 *
00115 * - uint32_t date  - Use decimal value. Member fx's convert to BCD
00116 *
00117 * - uint32_t month - Use decimal value. Member fx's convert to BCD
00118 *
00119 * - uint32_t year  - Use decimal value. Member fx's convert to BCD
00120 */
00121 typedef struct
00122 {
00123     uint32_t day; 
00124     uint32_t date; 
00125     uint32_t month; 
00126     uint32_t year;
00127 }ds3231_calendar_t;
00128 
00129 
00130 /**
00131 * ds3231_alrm_t - Struct for containing alarm data.
00132 * 
00133 * Members:
00134 *
00135 * - uint32_t seconds - Use decimal value. Member fx's convert to BCD 
00136 *
00137 * - uint32_t minutes - Use decimal value. Member fx's convert to BCD 
00138 *
00139 * - uint32_t hours   - Use decimal value. Member fx's convert to BCD 
00140 *
00141 * - uint32_t day     - Use decimal value. Member fx's convert to BCD 
00142 *
00143 * - uint32_t date    - Use decimal value. Member fx's convert to BCD 
00144 *
00145 * - bool am1        - Flag for setting alarm rate
00146 *
00147 * - bool am2        - Flag for setting alarm rate
00148 *
00149 * - bool am3        - Flag for setting alarm rate
00150 *
00151 * - bool am4        - Flag for setting alarm rate
00152 *
00153 * - bool am_pm      - TRUE for PM, same logic as datasheet
00154 *
00155 * - bool mode       - TRUE for 12 hour, same logic as datasheet
00156 *
00157 * - bool dy_dt      - TRUE for Day, same logic as datasheet
00158 */
00159 typedef struct
00160 {
00161     //Seconds and am1 not used for alarm2
00162     uint32_t seconds; 
00163     uint32_t minutes; 
00164     uint32_t hours; 
00165     uint32_t day; 
00166     uint32_t date; 
00167     bool am1; 
00168     bool am2;
00169     bool am3;
00170     bool am4;
00171     bool am_pm; 
00172     bool mode; 
00173     bool dy_dt;
00174 }ds3231_alrm_t;
00175 
00176 
00177 /**
00178 * ds3231_cntl_stat_t - Struct for containing control and status 
00179 * register data.
00180 * 
00181 * Members:
00182 *
00183 * - uint8_t control - Binary data for read/write of control register 
00184 *
00185 * - uint8_t status  - Binary data  for read/write of status register 
00186 */
00187 typedef struct
00188 {
00189     uint8_t control; 
00190     uint8_t status; 
00191 }ds3231_cntl_stat_t;
00192         
00193                 
00194 /******************************************************************//**
00195 * Ds3231 Class
00196 **********************************************************************/
00197 class Ds3231 : public I2C
00198 {
00199     uint8_t w_adrs, r_adrs;
00200     
00201     /**********************************************************//**
00202     * Private mmber fx, converts unsigned char to BCD
00203     *
00204     * On Entry:
00205     *     @param[in] data - 0-255
00206     *
00207     * On Exit:
00208     *     @return bcd_result = BCD representation of data
00209     *
00210     **************************************************************/
00211     uint16_t uchar_2_bcd(uint8_t data);
00212     
00213     
00214     /**********************************************************//**
00215     * Private mmber fx, converts BCD to a uint8_t
00216     *
00217     * On Entry:
00218     *     @param[in] bcd - 0-99
00219     *
00220     * On Exit:
00221     *     @return rtn_val = integer rep. of BCD
00222     *
00223     **************************************************************/
00224     uint8_t bcd_2_uchar(uint8_t bcd);
00225     
00226     public:
00227     
00228         /**
00229         * ds3231_regs_t - enumerated DS3231 registers 
00230         */
00231         typedef enum
00232         {
00233             SECONDS,
00234             MINUTES,
00235             HOURS,
00236             DAY,
00237             DATE,
00238             MONTH,
00239             YEAR,
00240             ALRM1_SECONDS,
00241             ALRM1_MINUTES,
00242             ALRM1_HOURS,
00243             ALRM1_DAY_DATE,
00244             ALRM2_MINUTES,
00245             ALRM2_HOURS,
00246             ALRM2_DAY_DATE,
00247             CONTROL,
00248             STATUS,
00249             AGING_OFFSET, //don't touch this register
00250             MSB_TEMP,
00251             LSB_TEMP
00252         }ds3231_regs_t;
00253     
00254         
00255         /**********************************************************//**
00256         * Constructor for Ds3231 Class
00257         *
00258         * On Entry:
00259         *     @param[in] sda - sda pin of I2C bus
00260         *     @param[in] scl - scl pin of I2C bus
00261         *
00262         * On Exit:
00263         *    @return none
00264         *
00265         * Example:
00266         * @code
00267         * 
00268         * //instantiate rtc object
00269         * Ds3231 rtc(D14, D15); 
00270         *
00271         * @endcode
00272         **************************************************************/
00273         Ds3231(PinName sda, PinName scl);
00274         
00275         
00276         /**********************************************************//**
00277         * Sets the time on DS3231
00278         * Struct data is in integrer format, not BCD.  Fx will convert
00279         * to BCD for you.
00280         *
00281         * On Entry:
00282         *     @param[in] time - struct cotaining time data; 
00283         *
00284         * On Exit:
00285         *     @return return value = 0 on success, non-0 on failure
00286         *
00287         * Example:
00288         * @code
00289         * 
00290         * //instantiate rtc object
00291         * Ds3231 rtc(D14, D15); 
00292         * 
00293         * //time = 12:00:00 AM 12hr mode
00294         * ds3231_time_t time = {12, 0, 0, 0, 1}
00295         * uint16_t rtn_val;
00296         *
00297         * rtn_val = rtc.set_time(time);
00298         *
00299         * @endcode
00300         **************************************************************/
00301         uint16_t set_time(ds3231_time_t time);
00302         
00303         
00304         /**********************************************************//**
00305         * Sets the calendar on DS3231
00306         *
00307         * On Entry:
00308         *     @param[in] calendar - struct cotaining calendar data 
00309         *
00310         * On Exit:
00311         *     @return return value = 0 on success, non-0 on failure
00312         *
00313         * Example:
00314         * @code
00315         * 
00316         * //instantiate rtc object
00317         * Ds3231 rtc(D14, D15); 
00318         * 
00319         * //see datasheet for calendar format
00320         * ds3231_calendar_t calendar = {1, 1, 1, 0}; 
00321         * uint16_t rtn_val;
00322         *
00323         * rtn_val = rtc.set_calendar(calendar);
00324         *
00325         * @endcode
00326         **************************************************************/
00327         uint16_t set_calendar(ds3231_calendar_t calendar);
00328         
00329         
00330         /**********************************************************//**
00331         * Set either Alarm1 or Alarm2 of DS3231
00332         *
00333         * On Entry:
00334         *     @param[in] alarm - struct cotaining alarm data 
00335         *                        
00336         *     @param[in] one_r_two - TRUE for Alarm1 and FALSE for 
00337         *                            Alarm2
00338         *
00339         * On Exit:
00340         *     @return return value = 0 on success, non-0 on failure
00341         *
00342         * Example:
00343         * @code
00344         * 
00345         * //instantiate rtc object
00346         * Ds3231 rtc(D14, D15); 
00347         * 
00348         * //see ds3231.h for .members and datasheet for alarm format
00349         * ds3231_alrm_t alarm; 
00350         * uint16_t rtn_val;
00351         *
00352         * rtn_val = rtc.set_alarm(alarm, FALSE);
00353         *
00354         * @endcode
00355         **************************************************************/
00356         uint16_t set_alarm(ds3231_alrm_t alarm, bool one_r_two);
00357         
00358         
00359         /**********************************************************//**
00360         * Set control and status registers of DS3231
00361         *
00362         * On Entry:
00363         *     @param[in] data - Struct containing control and status 
00364         *                       register data
00365         *
00366         * On Exit:
00367         *     @return return value = 0 on success, non-0 on failure
00368         *
00369         * Example:
00370         * @code
00371         * 
00372         * //instantiate rtc object
00373         * Ds3231 rtc(D14, D15);  
00374         * 
00375         * //do not use 0xAA, see datasheet for appropriate data 
00376         * ds3231_cntl_stat_t data = {0xAA, 0xAA}; 
00377         *
00378         * rtn_val = rtc.set_cntl_stat_reg(data);
00379         *
00380         * @endcode
00381         **************************************************************/
00382         uint16_t set_cntl_stat_reg(ds3231_cntl_stat_t data);
00383         
00384         
00385         /**********************************************************//**
00386         * Gets the time on DS3231
00387         *
00388         * On Entry:
00389         *     @param[in] time - pointer to struct for storing time data
00390         *
00391         * On Exit:
00392         *     @param[out] time - contains current integrer rtc time 
00393         *                        data
00394         *     @return return value = 0 on success, non-0 on failure
00395         *
00396         * Example:
00397         * @code
00398         * 
00399         * //instantiate rtc object
00400         * Ds3231 rtc(D14, D15); 
00401         * 
00402         * //time = 12:00:00 AM 12hr mode
00403         * ds3231_time_t time = {12, 0, 0, 0, 1} 
00404         * uint16_t rtn_val;
00405         *
00406         * rtn_val = rtc.get_time(&time);
00407         *
00408         * @endcode
00409         **************************************************************/
00410         uint16_t get_time(ds3231_time_t* time);
00411         
00412         
00413         /**********************************************************//**
00414         * Gets the calendar on DS3231
00415         *
00416         * On Entry:
00417         *     @param[in] calendar - pointer to struct for storing 
00418         *                           calendar data
00419         *
00420         * On Exit:
00421         *     @param[out] calendar - contains current integer rtc 
00422         *                            calendar data
00423         *     @return return value = 0 on success, non-0 on failure
00424         *
00425         * Example:
00426         * @code
00427         * 
00428         * //instantiate rtc object
00429         * Ds3231 rtc(D14, D15); 
00430         * 
00431         * //see datasheet for calendar format
00432         * ds3231_calendar_t calendar = {1, 1, 1, 0}; 
00433         * uint16_t rtn_val;
00434         *
00435         * rtn_val = rtc.get_calendar(&calendar);
00436         *
00437         * @endcode
00438         **************************************************************/
00439         uint16_t get_calendar(ds3231_calendar_t* calendar);
00440         
00441         
00442         /**********************************************************//**
00443         * Get either Alarm1 or Alarm2 of DS3231
00444         *
00445         * On Entry:
00446         *     @param[in] alarm - pointer to struct for storing alarm 
00447         *                        data; 
00448         *
00449         *     @param[in] one_r_two - TRUE for Alarm1 and FALSE for 
00450         *                            Alarm2
00451         *
00452         * On Exit:
00453         *     @param[out] alarm - contains integer alarm data
00454         *     @return return value = 0 on success, non-0 on failure
00455         *
00456         * Example:
00457         * @code
00458         * 
00459         * //instantiate rtc object
00460         * Ds3231 rtc(D14, D15); 
00461         * 
00462         * //see ds3231.h for .members and datasheet for alarm format
00463         * ds3231_alrm_t alarm; 
00464         * uint16_t rtn_val;
00465         *
00466         * rtn_val = rtc.get_alarm(&alarm, FALSE);
00467         *
00468         * @endcode
00469         **************************************************************/
00470         uint16_t get_alarm(ds3231_alrm_t* alarm, bool one_r_two);
00471         
00472         
00473         /**********************************************************//**
00474         * Get control and status registers of DS3231
00475         *
00476         * On Entry:
00477         *     @param[in] data - pointer to struct for storing control 
00478         *                       and status register data
00479         *
00480         * On Exit:
00481         *     @param[out] data - contains control and status registers
00482         *                        data
00483         *     @return return value = 0 on success, non-0 on failure
00484         *
00485         * Example:
00486         * @code
00487         * 
00488         * //instantiate rtc object
00489         * Ds3231 rtc(D14, D15);  
00490         * 
00491         * //do not use 0xAA, see datasheet for appropriate data 
00492         * ds3231_cntl_stat_t data = {0xAA, 0xAA}; 
00493         *
00494         * rtn_val = rtc.get_cntl_stat_reg(&data);
00495         *
00496         * @endcode
00497         **************************************************************/
00498         uint16_t get_cntl_stat_reg(ds3231_cntl_stat_t* data);
00499         
00500         
00501         /**********************************************************//**
00502         * Get temperature data of DS3231
00503         *
00504         * On Entry:
00505         *
00506         * On Exit:
00507         *     @return return value = raw temperature data
00508         *
00509         * Example:
00510         * @code
00511         * 
00512         * //instantiate rtc object
00513         * Ds3231 rtc(D14, D15); 
00514         * 
00515         * uint16_t temp; 
00516         *
00517         * temp = rtc.get_temperature();
00518         *
00519         * @endcode
00520         **************************************************************/
00521         uint16_t get_temperature(void);
00522         
00523         
00524         /**********************************************************//**
00525         * Get epoch time based on current RTC time and date.  
00526         * DS3231 must be configured and running before this fx is 
00527         * called
00528         *
00529         * On Entry:
00530         *
00531         * On Exit:
00532         *     @return return value = epoch time
00533         *
00534         * Example:
00535         * @code
00536         * 
00537         * //instantiate rtc object
00538         * Ds3231 rtc(D14, D15); 
00539         * 
00540         * time_t epoch_time; 
00541         *
00542         * epoch_time = rtc.get_epoch();
00543         *
00544         * @endcode
00545         **************************************************************/
00546         time_t get_epoch(void);
00547         
00548 };
00549 #endif /* DS3231_H*/