ds3231.h

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