Bird Techstep / DS3231

DS3231 External RTC I2C

Dependents:   HumidityController

DS3231.h@1:1607610a4ee9, 2014-08-06 (annotated)

Committer:
techstep
Date:
Wed Aug 06 03:03:29 2014 +0000
Revision:
1:1607610a4ee9
Parent:
0:e4fbbd93299b 
DS3231

Who changed what in which revision?

UserRevisionLine numberNew contents of line
techstep 0:e4fbbd93299b 1 /*****************************************************************************
techstep 0:e4fbbd93299b 2 * Type : Header
techstep 0:e4fbbd93299b 3 * File : DS3231.h
techstep 0:e4fbbd93299b 4 * Dec. : DS3231 + AT24C32 IIC Module Precision RTC Module Memory Module
techstep 0:e4fbbd93299b 5 * Copyright (c) 2013-2014, Bird Techstep, tbird_th@hotmail.com
techstep 0:e4fbbd93299b 6 *
techstep 0:e4fbbd93299b 7 * Remark Original codr from DS3231 Library [Arduino]
techstep 0:e4fbbd93299b 8 *
techstep 0:e4fbbd93299b 9 * Permission is hereby granted, free of charge, to any person obtaining a copy
techstep 0:e4fbbd93299b 10 * of this software and associated documentation files (the "Software"), to deal
techstep 0:e4fbbd93299b 11 * in the Software without restriction, including without limitation the rights
techstep 0:e4fbbd93299b 12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
techstep 0:e4fbbd93299b 13 * copies of the Software, and to permit persons to whom the Software is
techstep 0:e4fbbd93299b 14 * furnished to do so, subject to the following conditions:
techstep 0:e4fbbd93299b 15 *
techstep 0:e4fbbd93299b 16 * The above copyright notice and this permission notice shall be included in
techstep 0:e4fbbd93299b 17 * all copies or substantial portions of the Software.
techstep 0:e4fbbd93299b 18 *
techstep 0:e4fbbd93299b 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
techstep 0:e4fbbd93299b 20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
techstep 0:e4fbbd93299b 21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
techstep 0:e4fbbd93299b 22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
techstep 0:e4fbbd93299b 23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
techstep 0:e4fbbd93299b 24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
techstep 0:e4fbbd93299b 25 * THE SOFTWARE.
techstep 0:e4fbbd93299b 26 *****************************************************************************/
techstep 0:e4fbbd93299b 27 #ifndef DS3231_H
techstep 0:e4fbbd93299b 28 #define DS3231_H
techstep 0:e4fbbd93299b 29
techstep 0:e4fbbd93299b 30 #include "mbed.h"
techstep 0:e4fbbd93299b 31 #include "I2C.h"
techstep 0:e4fbbd93299b 32
techstep 0:e4fbbd93299b 33 class DS3231 {
techstep 0:e4fbbd93299b 34 public:
techstep 0:e4fbbd93299b 35 /*************************************************************************
techstep 0:e4fbbd93299b 36 * Create MAX72XX Object.
techstep 0:e4fbbd93299b 37 *************************************************************************
techstep 0:e4fbbd93299b 38 * @param scl_pin : Clock
techstep 0:e4fbbd93299b 39 * @param sda_pin : Data Input & Output
techstep 0:e4fbbd93299b 40 * @param addrDevice : Address device.
techstep 0:e4fbbd93299b 41 *************************************************************************/
techstep 0:e4fbbd93299b 42 DS3231(PinName sda_pin, PinName scl_pin);
techstep 0:e4fbbd93299b 43
techstep 0:e4fbbd93299b 44 // Time-retrieval functions
techstep 0:e4fbbd93299b 45
techstep 0:e4fbbd93299b 46 // the get*() functions retrieve current values of the registers.
techstep 0:e4fbbd93299b 47 // If you only need one element, use that one for simplicity; but
techstep 0:e4fbbd93299b 48 // if you need the whole passel then use getTime() to avoid
techstep 0:e4fbbd93299b 49 // the chance of rollover between reads of the different components.
techstep 0:e4fbbd93299b 50 void getTime(uint8_t& year, uint8_t& month, uint8_t& date, uint8_t& DoW, uint8_t& hour, uint8_t& minute, uint8_t& second);
techstep 0:e4fbbd93299b 51 int8_t getSecond();
techstep 0:e4fbbd93299b 52 uint8_t getMinute();
techstep 0:e4fbbd93299b 53 uint8_t getHour(bool& h12, bool& PM);
techstep 0:e4fbbd93299b 54 // In addition to returning the hour register, this function
techstep 0:e4fbbd93299b 55 // returns the values of the 12/24-hour flag and the AM/PM flag.
techstep 0:e4fbbd93299b 56 uint8_t getDoW();
techstep 0:e4fbbd93299b 57 uint8_t getDate();
techstep 0:e4fbbd93299b 58 uint8_t getMonth(bool& Century);
techstep 0:e4fbbd93299b 59 // Also sets the flag indicating century roll-over.
techstep 0:e4fbbd93299b 60 uint8_t getYear();
techstep 0:e4fbbd93299b 61 // Last 2 digits only
techstep 0:e4fbbd93299b 62
techstep 0:e4fbbd93299b 63 // Time-setting functions
techstep 0:e4fbbd93299b 64 // Note that none of these check for sensibility: You can set the
techstep 0:e4fbbd93299b 65 // date to July 42nd and strange things will probably result.
techstep 0:e4fbbd93299b 66
techstep 0:e4fbbd93299b 67 void setSecond(uint8_t Second);
techstep 0:e4fbbd93299b 68 // In addition to setting the seconds, this clears the
techstep 0:e4fbbd93299b 69 // "Oscillator Stop Flag".
techstep 0:e4fbbd93299b 70 void setMinute(uint8_t Minute);
techstep 0:e4fbbd93299b 71 // Sets the minute
techstep 0:e4fbbd93299b 72 void setHour(uint8_t Hour);
techstep 0:e4fbbd93299b 73 // Sets the hour
techstep 0:e4fbbd93299b 74 void setDoW(uint8_t DoW);
techstep 0:e4fbbd93299b 75 // Sets the Day of the Week (1-7);
techstep 0:e4fbbd93299b 76 void setDate(uint8_t Date);
techstep 0:e4fbbd93299b 77 // Sets the Date of the Month
techstep 0:e4fbbd93299b 78 void setMonth(uint8_t Month);
techstep 0:e4fbbd93299b 79 // Sets the Month of the year
techstep 0:e4fbbd93299b 80 void setYear(uint8_t Year);
techstep 0:e4fbbd93299b 81 // Last two digits of the year
techstep 0:e4fbbd93299b 82 void setClockMode(bool h12);
techstep 0:e4fbbd93299b 83 // Set 12/24h mode. True is 12-h, false is 24-hour.
techstep 0:e4fbbd93299b 84
techstep 0:e4fbbd93299b 85 // Temperature function
techstep 0:e4fbbd93299b 86 float getTemperature();
techstep 0:e4fbbd93299b 87
techstep 0:e4fbbd93299b 88 // Alarm functions
techstep 0:e4fbbd93299b 89 void getA1Time(uint8_t& A1Day, uint8_t& A1Hour, uint8_t& A1Minute, uint8_t& A1Second, uint8_t& AlarmBits, bool& A1Dy, bool& A1h12, bool& A1PM);
techstep 0:e4fbbd93299b 90
techstep 0:e4fbbd93299b 91 /* Retrieves everything you could want to know about alarm
techstep 0:e4fbbd93299b 92 * one.
techstep 0:e4fbbd93299b 93 * A1Dy true makes the alarm go on A1Day = Day of Week,
techstep 0:e4fbbd93299b 94 * A1Dy false makes the alarm go on A1Day = Date of month.
techstep 0:e4fbbd93299b 95 *
techstep 0:e4fbbd93299b 96 * byte AlarmBits sets the behavior of the alarms:
techstep 0:e4fbbd93299b 97 * Dy A1M4 A1M3 A1M2 A1M1 Rate
techstep 0:e4fbbd93299b 98 * X 1 1 1 1 Once per second
techstep 0:e4fbbd93299b 99 * X 1 1 1 0 Alarm when seconds match
techstep 0:e4fbbd93299b 100 * X 1 1 0 0 Alarm when min, sec match
techstep 0:e4fbbd93299b 101 * X 1 0 0 0 Alarm when hour, min, sec match
techstep 0:e4fbbd93299b 102 * 0 0 0 0 0 Alarm when date, h, m, s match
techstep 0:e4fbbd93299b 103 * 1 0 0 0 0 Alarm when DoW, h, m, s match
techstep 0:e4fbbd93299b 104 *
techstep 0:e4fbbd93299b 105 * Dy A2M4 A2M3 A2M2 Rate
techstep 0:e4fbbd93299b 106 * X 1 1 1 Once per minute (at seconds = 00)
techstep 0:e4fbbd93299b 107 * X 1 1 0 Alarm when minutes match
techstep 0:e4fbbd93299b 108 * X 1 0 0 Alarm when hours and minutes match
techstep 0:e4fbbd93299b 109 * 0 0 0 0 Alarm when date, hour, min match
techstep 0:e4fbbd93299b 110 * 1 0 0 0 Alarm when DoW, hour, min match
techstep 0:e4fbbd93299b 111 */
techstep 0:e4fbbd93299b 112 void getA2Time(uint8_t& A2Day, uint8_t& A2Hour, uint8_t& A2Minute, uint8_t& AlarmBits, bool& A2Dy, bool& A2h12, bool& A2PM);
techstep 0:e4fbbd93299b 113 // Same as getA1Time();, but A2 only goes on seconds == 00.
techstep 0:e4fbbd93299b 114 void setA1Time(uint8_t A1Day, uint8_t A1Hour, uint8_t A1Minute, uint8_t A1Second, uint8_t AlarmBits, bool A1Dy, bool A1h12, bool A1PM);
techstep 0:e4fbbd93299b 115 // Set the details for Alarm 1
techstep 0:e4fbbd93299b 116 void setA2Time(uint8_t A2Day, uint8_t A2Hour, uint8_t A2Minute, uint8_t AlarmBits, bool A2Dy, bool A2h12, bool A2PM);
techstep 0:e4fbbd93299b 117 // Set the details for Alarm 2
techstep 0:e4fbbd93299b 118 void turnOnAlarm(uint8_t Alarm);
techstep 0:e4fbbd93299b 119 // Enables alarm 1 or 2 and the external interrupt pin.
techstep 0:e4fbbd93299b 120 // If Alarm != 1, it assumes Alarm == 2.
techstep 0:e4fbbd93299b 121 void turnOffAlarm(uint8_t Alarm);
techstep 0:e4fbbd93299b 122 // Disables alarm 1 or 2 (default is 2 if Alarm != 1);
techstep 0:e4fbbd93299b 123 // and leaves the interrupt pin alone.
techstep 0:e4fbbd93299b 124 bool checkAlarmEnabled(uint8_t Alarm);
techstep 0:e4fbbd93299b 125 // Returns T/F to indicate whether the requested alarm is
techstep 0:e4fbbd93299b 126 // enabled. Defaults to 2 if Alarm != 1.
techstep 0:e4fbbd93299b 127 bool checkIfAlarm(uint8_t Alarm);
techstep 0:e4fbbd93299b 128 // Checks whether the indicated alarm (1 or 2, 2 default);
techstep 0:e4fbbd93299b 129 // has been activated.
techstep 0:e4fbbd93299b 130
techstep 0:e4fbbd93299b 131 // Oscillator functions
techstep 0:e4fbbd93299b 132 void enableOscillator(bool TF, bool battery, uint8_t frequency);
techstep 0:e4fbbd93299b 133 // turns oscillator on or off. True is on, false is off.
techstep 0:e4fbbd93299b 134 // if battery is true, turns on even for battery-only operation,
techstep 0:e4fbbd93299b 135 // otherwise turns off if Vcc is off.
techstep 0:e4fbbd93299b 136 // frequency must be 0, 1, 2, or 3.
techstep 0:e4fbbd93299b 137 // 0 = 1 Hz
techstep 0:e4fbbd93299b 138 // 1 = 1.024 kHz
techstep 0:e4fbbd93299b 139 // 2 = 4.096 kHz
techstep 0:e4fbbd93299b 140 // 3 = 8.192 kHz (Default if frequency byte is out of range);
techstep 0:e4fbbd93299b 141 void enable32kHz(bool TF);
techstep 0:e4fbbd93299b 142 // Turns the 32kHz output pin on (true); or off (false).
techstep 0:e4fbbd93299b 143 bool oscillatorCheck();
techstep 0:e4fbbd93299b 144 // Checks the status of the OSF (Oscillator Stop Flag);.
techstep 0:e4fbbd93299b 145 // If this returns false, then the clock is probably not
techstep 0:e4fbbd93299b 146 // giving you the correct time.
techstep 0:e4fbbd93299b 147 // The OSF is cleared by function setSecond();.
techstep 0:e4fbbd93299b 148
techstep 0:e4fbbd93299b 149 private:
techstep 0:e4fbbd93299b 150
techstep 0:e4fbbd93299b 151 uint8_t decToBcd(uint8_t val);
techstep 0:e4fbbd93299b 152 // Convert normal decimal numbers to binary coded decimal
techstep 0:e4fbbd93299b 153 uint8_t bcdToDec(uint8_t val);
techstep 0:e4fbbd93299b 154 // Convert binary coded decimal to normal decimal numbers
techstep 0:e4fbbd93299b 155 uint8_t readControlByte(bool which);
techstep 0:e4fbbd93299b 156 // Read selected control byte: (0); reads 0x0e, (1) reads 0x0f
techstep 0:e4fbbd93299b 157 void writeControlByte(uint8_t control, bool which);
techstep 0:e4fbbd93299b 158 // Write the selected control byte.
techstep 0:e4fbbd93299b 159 // which == false -> 0x0e, true->0x0f.
techstep 0:e4fbbd93299b 160 protected:
techstep 0:e4fbbd93299b 161 I2C _i2c;
techstep 0:e4fbbd93299b 162 //int8_t _addrDevice;
techstep 0:e4fbbd93299b 163 };
techstep 0:e4fbbd93299b 164
techstep 0:e4fbbd93299b 165 #endif // MAX72XX_H