Kevin Braun / ds3232m

Library for Maxim DS3232M super-accurate, I2C based Real Time Clock chip with 234 bytes of user RAM. Library includes user RAM read/write operations along with CRC routines for accessing the user RAM area.

Dependents:   ds3232m_HelloWorld

ds3232m.h@0:30a7faf58768, 2014-12-08 (annotated)

Committer:
loopsva
Date:
Mon Dec 08 20:15:16 2014 +0000
Revision:
0:30a7faf58768
Child:
1:0975d4a9b513
Library for Maxim DS3232M super-accurate Real Time Clock with user RAM.  Operates on I2C bus.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
loopsva 0:30a7faf58768 1 #ifndef DS3232M_H
loopsva 0:30a7faf58768 2 #define DS3232M_H
loopsva 0:30a7faf58768 3
loopsva 0:30a7faf58768 4 /*
loopsva 0:30a7faf58768 5 Maxim Integrated DS3232M, fully integrated Real Time Clock chip. The
loopsva 0:30a7faf58768 6 chip contains an I2C interface, compatable time-base registers to
loopsva 0:30a7faf58768 7 the DS1307 and M11T41, a super-accurate internal oscillator, 2 alarms
loopsva 0:30a7faf58768 8 and 236 bytes of user defined battery-backed RAM.
loopsva 0:30a7faf58768 9 */
loopsva 0:30a7faf58768 10
loopsva 0:30a7faf58768 11 /** Class ds3232m implements the real time clock
loopsva 0:30a7faf58768 12 *
loopsva 0:30a7faf58768 13 *
loopsva 0:30a7faf58768 14 *
loopsva 0:30a7faf58768 15 */
loopsva 0:30a7faf58768 16
loopsva 0:30a7faf58768 17 class ds3232m {
loopsva 0:30a7faf58768 18
loopsva 0:30a7faf58768 19 public:
loopsva 0:30a7faf58768 20 /** Structure which is used to exchange the time and date
loopsva 0:30a7faf58768 21 */
loopsva 0:30a7faf58768 22 typedef struct {
loopsva 0:30a7faf58768 23 int sec; /*!< seconds [0..59] */
loopsva 0:30a7faf58768 24 int min; /*!< minutes {0..59] */
loopsva 0:30a7faf58768 25 int hour; /*!< hours [0..23] */
loopsva 0:30a7faf58768 26 int wday; /*!< weekday [1..7, where 1 = sunday, 2 = monday, ... */
loopsva 0:30a7faf58768 27 int date; /*!< day of month [0..31] */
loopsva 0:30a7faf58768 28 int mon; /*!< month of year [1..12] */
loopsva 0:30a7faf58768 29 int year; /*!< year [2000..2255] */
loopsva 0:30a7faf58768 30 } Time_rtc;
loopsva 0:30a7faf58768 31
loopsva 0:30a7faf58768 32 protected:
loopsva 0:30a7faf58768 33 I2C* _i2c_;
loopsva 0:30a7faf58768 34
loopsva 0:30a7faf58768 35 // static const char *m_weekDays[];
loopsva 0:30a7faf58768 36
loopsva 0:30a7faf58768 37 public:
loopsva 0:30a7faf58768 38 /**
loopsva 0:30a7faf58768 39 * Constructor with default i2c clock speed
loopsva 0:30a7faf58768 40 * - Fixed at I2C address 0x80
loopsva 0:30a7faf58768 41 * - I2C speed set to 400KHz
loopsva 0:30a7faf58768 42 *
loopsva 0:30a7faf58768 43 * @param sda - mbed I2C interface pin
loopsva 0:30a7faf58768 44 * @param scl - mbed I2C interface pin
loopsva 0:30a7faf58768 45 */
loopsva 0:30a7faf58768 46 ds3232m(PinName sda, PinName scl);
loopsva 0:30a7faf58768 47 /**
loopsva 0:30a7faf58768 48 * Constructor with i2c clock setting option
loopsva 0:30a7faf58768 49 * - Fixed at I2C address 0x80
loopsva 0:30a7faf58768 50 * - I2C speed set by user
loopsva 0:30a7faf58768 51 *
loopsva 0:30a7faf58768 52 * @param sda - mbed I2C interface pin
loopsva 0:30a7faf58768 53 * @param scl - mbed I2C interface pin
loopsva 0:30a7faf58768 54 * @param set_I2C_frequency
loopsva 0:30a7faf58768 55 */
loopsva 0:30a7faf58768 56 ds3232m(PinName sda, PinName scl, int i2cFrequency);
loopsva 0:30a7faf58768 57 /**
loopsva 0:30a7faf58768 58 * Destructor
loopsva 0:30a7faf58768 59 *
loopsva 0:30a7faf58768 60 * @param --none--
loopsva 0:30a7faf58768 61 */
loopsva 0:30a7faf58768 62 ~ds3232m();
loopsva 0:30a7faf58768 63 /**
loopsva 0:30a7faf58768 64 * See if temperature conversion is busy or not
loopsva 0:30a7faf58768 65 *
loopsva 0:30a7faf58768 66 * @param --none--
loopsva 0:30a7faf58768 67 *
loopsva 0:30a7faf58768 68 * @return busy_flag - Temperature Conversion is busy
loopsva 0:30a7faf58768 69 * - true = busy
loopsva 0:30a7faf58768 70 * - false = ready
loopsva 0:30a7faf58768 71 */
loopsva 0:30a7faf58768 72 bool checkTempBusy();
loopsva 0:30a7faf58768 73 /**
loopsva 0:30a7faf58768 74 * Start a temperature conversion cycle
loopsva 0:30a7faf58768 75 * - Note: only 1 conversion per second allowed
loopsva 0:30a7faf58768 76 *
loopsva 0:30a7faf58768 77 * @param --none--
loopsva 0:30a7faf58768 78 *
loopsva 0:30a7faf58768 79 * @return busy_flag Temperature Conversion is Busy
loopsva 0:30a7faf58768 80 * - true = started new conversion
loopsva 0:30a7faf58768 81 * - false = already busy from previous converstion start
loopsva 0:30a7faf58768 82 */
loopsva 0:30a7faf58768 83 bool startTempCycle();
loopsva 0:30a7faf58768 84 /**
loopsva 0:30a7faf58768 85 * Get the chip temperature from the DS3232M
loopsva 0:30a7faf58768 86 *
loopsva 0:30a7faf58768 87 * @param --none--
loopsva 0:30a7faf58768 88 *
loopsva 0:30a7faf58768 89 * @return Temperature 0.25degC accuracy
loopsva 0:30a7faf58768 90 * @return 255.0 if temperature conversion not complete (still busy)
loopsva 0:30a7faf58768 91 */
loopsva 0:30a7faf58768 92 float getTemperature();
loopsva 0:30a7faf58768 93 /**
loopsva 0:30a7faf58768 94 * Get seconds register from DS3232M
loopsva 0:30a7faf58768 95 *
loopsva 0:30a7faf58768 96 * @param --none--
loopsva 0:30a7faf58768 97 *
loopsva 0:30a7faf58768 98 * @return BCD-to-decimal corrected seconds register
loopsva 0:30a7faf58768 99 */
loopsva 0:30a7faf58768 100 int getSeconds();
loopsva 0:30a7faf58768 101 /**
loopsva 0:30a7faf58768 102 * Clear out all 236 bytes of user RAM, from address 0x14 to 0xff
loopsva 0:30a7faf58768 103 * - 00h is put in all user RAM area
loopsva 0:30a7faf58768 104 *
loopsva 0:30a7faf58768 105 * @param --none--
loopsva 0:30a7faf58768 106 *
loopsva 0:30a7faf58768 107 * @return --none--
loopsva 0:30a7faf58768 108 */
loopsva 0:30a7faf58768 109 void clearRAM();
loopsva 0:30a7faf58768 110 /**
loopsva 0:30a7faf58768 111 * Retrieve data from DS3232M's user RAM area
loopsva 0:30a7faf58768 112 * - addresses range 0x14 - 0xfd
loopsva 0:30a7faf58768 113 * - CRC is checked of entire RAM contents
loopsva 0:30a7faf58768 114 *
loopsva 0:30a7faf58768 115 * @param buffer pointer
loopsva 0:30a7faf58768 116 * @param offset into DS3232M's RAM (range 0x14 = 0xfd)
loopsva 0:30a7faf58768 117 * @param length number of bytes to get
loopsva 0:30a7faf58768 118 *
loopsva 0:30a7faf58768 119 * @return 00 = no error
loopsva 0:30a7faf58768 120 * @return 01 = length + offset is over the highest user RAM location
loopsva 0:30a7faf58768 121 * @return 02 = offset < 0x14
loopsva 0:30a7faf58768 122 * @return 04 = length = 0
loopsva 0:30a7faf58768 123 * @return 08 = crc error occured from LoadRTCRam()
loopsva 0:30a7faf58768 124 */
loopsva 0:30a7faf58768 125 int getUserRAM(char *buffer, int offset, int length);
loopsva 0:30a7faf58768 126 /**
loopsva 0:30a7faf58768 127 * Store data DS3232M's user RAM area
loopsva 0:30a7faf58768 128 * - addresses range 0x14 - 0xfd
loopsva 0:30a7faf58768 129 * - CRC is added to the last 2 locations using addCRC16()
loopsva 0:30a7faf58768 130 *
loopsva 0:30a7faf58768 131 * @param buffer pointer
loopsva 0:30a7faf58768 132 * @param offset into DS3232M's RAM (range 0x14 = 0xfd)
loopsva 0:30a7faf58768 133 * @param length number of bytes to store
loopsva 0:30a7faf58768 134 *
loopsva 0:30a7faf58768 135 * @return 00 = no error
loopsva 0:30a7faf58768 136 * @return 01 = length + offset is over the highest user RAM location
loopsva 0:30a7faf58768 137 * @return 02 = offset < 0x14
loopsva 0:30a7faf58768 138 * @return 04 = length = 0
loopsva 0:30a7faf58768 139 */
loopsva 0:30a7faf58768 140 int putUserRAM(char *buffer, int offset, int length);
loopsva 0:30a7faf58768 141 /**
loopsva 0:30a7faf58768 142 * Calculate CRC16
loopsva 0:30a7faf58768 143 *
loopsva 0:30a7faf58768 144 * @param input buffer pointer
loopsva 0:30a7faf58768 145 * @param address offset into buffer
loopsva 0:30a7faf58768 146 * @param length number of bytes to calculate
loopsva 0:30a7faf58768 147 *
loopsva 0:30a7faf58768 148 * @return CRC16 value
loopsva 0:30a7faf58768 149 */
loopsva 0:30a7faf58768 150 uint16_t calculateCRC16(char input[], int offset, int length);
loopsva 0:30a7faf58768 151 /**
loopsva 0:30a7faf58768 152 * Turn on/off the 32KHz output pin
loopsva 0:30a7faf58768 153 * - with option to keep 32KHz output ON during battery backup
loopsva 0:30a7faf58768 154 * - This pin is push-pull, no pullup is required
loopsva 0:30a7faf58768 155 *
loopsva 0:30a7faf58768 156 * @param ena
loopsva 0:30a7faf58768 157 * - true = enable during normal operation
loopsva 0:30a7faf58768 158 * - false = disable 32KHz output pin during normal operation
loopsva 0:30a7faf58768 159 * @param batt
loopsva 0:30a7faf58768 160 * - true = enable 32KHz output pin during battery backup mode
loopsva 0:30a7faf58768 161 * - false = disable 32KHz output pin during battery backup mode
loopsva 0:30a7faf58768 162 * - Note: "ena" must be true or else batt is ignored
loopsva 0:30a7faf58768 163 *
loopsva 0:30a7faf58768 164 * @return --none--
loopsva 0:30a7faf58768 165 */
loopsva 0:30a7faf58768 166 void set32KhzOutput(bool ena, bool batt);
loopsva 0:30a7faf58768 167 /**
loopsva 0:30a7faf58768 168 * Turn on/off the 1Hz output pin
loopsva 0:30a7faf58768 169 * - with option to keep 1Hz output ON during battery backup
loopsva 0:30a7faf58768 170 * - This pin is open-drain
loopsva 0:30a7faf58768 171 * - Requires a pullup resistor to Vcc or the backup battery
loopsva 0:30a7faf58768 172 *
loopsva 0:30a7faf58768 173 * @param ena
loopsva 0:30a7faf58768 174 * - true = enable 1Hz output pin during normal operation
loopsva 0:30a7faf58768 175 * - false = disable 1Hz output pin during normal operation
loopsva 0:30a7faf58768 176 * @param batt
loopsva 0:30a7faf58768 177 * - true = enable 1Hz output pin during battery backup mode
loopsva 0:30a7faf58768 178 * - false = disable 1Hz output pin during battery backup mode
loopsva 0:30a7faf58768 179 * - Note: "ena" must be true or else batt is ignored
loopsva 0:30a7faf58768 180 *
loopsva 0:30a7faf58768 181 * @return --none--
loopsva 0:30a7faf58768 182 */
loopsva 0:30a7faf58768 183 void set1hzOutput(bool ena, bool batt);
loopsva 0:30a7faf58768 184 /**
loopsva 0:30a7faf58768 185 * Turn on/off the main oscillator during battery backup mode
loopsva 0:30a7faf58768 186 * - The oscillator always runs when Vcc is valid
loopsva 0:30a7faf58768 187 *
loopsva 0:30a7faf58768 188 * @param batt
loopsva 0:30a7faf58768 189 * - true = enable the oscillator during battery backup mode
loopsva 0:30a7faf58768 190 * - false = disable the oscillator during battery backup mode
loopsva 0:30a7faf58768 191 *
loopsva 0:30a7faf58768 192 * @return --none--
loopsva 0:30a7faf58768 193 */
loopsva 0:30a7faf58768 194 void enableBattClock(bool batt);
loopsva 0:30a7faf58768 195 /**
loopsva 0:30a7faf58768 196 * Read all of the current time registers from the DS3232M
loopsva 0:30a7faf58768 197 *
loopsva 0:30a7faf58768 198 * @param time_structure - will be filled with the time from DS3232M
loopsva 0:30a7faf58768 199 *
loopsva 0:30a7faf58768 200 * @returns --none--
loopsva 0:30a7faf58768 201 */
loopsva 0:30a7faf58768 202 void getTime(Time_rtc& time);
loopsva 0:30a7faf58768 203 /**
loopsva 0:30a7faf58768 204 * Write all of the current time registers into the DS3232M
loopsva 0:30a7faf58768 205 *
loopsva 0:30a7faf58768 206 * @param time_structure - will be filled with the time into the DS3232M
loopsva 0:30a7faf58768 207 *
loopsva 0:30a7faf58768 208 * @returns --none--
loopsva 0:30a7faf58768 209 */
loopsva 0:30a7faf58768 210 void setTime(Time_rtc& time);
loopsva 0:30a7faf58768 211 /**
loopsva 0:30a7faf58768 212 * Load the entire contents of the DS3232M into dedicated buffer RTCbuffer[]
loopsva 0:30a7faf58768 213 * - includes time registers, alarm registers and user RAM
loopsva 0:30a7faf58768 214 *
loopsva 0:30a7faf58768 215 * @param --none--
loopsva 0:30a7faf58768 216 *
loopsva 0:30a7faf58768 217 * @return CRC_Status - pass/fail of CRC readback of user RAM data
loopsva 0:30a7faf58768 218 * - true = CRC is ok
loopsva 0:30a7faf58768 219 * - false = CRC failed
loopsva 0:30a7faf58768 220 */
loopsva 0:30a7faf58768 221 bool LoadRTCRam();
loopsva 0:30a7faf58768 222 /**
loopsva 0:30a7faf58768 223 * Dedicated buffer that mirrors the RTC's entire contents
loopsva 0:30a7faf58768 224 * - loaded by LoadRTCRam()
loopsva 0:30a7faf58768 225 *
loopsva 0:30a7faf58768 226 * @param --none--
loopsva 0:30a7faf58768 227 *
loopsva 0:30a7faf58768 228 * @return --none--
loopsva 0:30a7faf58768 229 */
loopsva 0:30a7faf58768 230 char RTCbuffer[256];
loopsva 0:30a7faf58768 231
loopsva 0:30a7faf58768 232 private:
loopsva 0:30a7faf58768 233 void getControlStatusRegs();
loopsva 0:30a7faf58768 234 char RtcCtlReg;
loopsva 0:30a7faf58768 235 char RtcStatReg;
loopsva 0:30a7faf58768 236 void addCRC16();
loopsva 0:30a7faf58768 237
loopsva 0:30a7faf58768 238 // BCD-Decimal Conversions, hacked from Henry Leinen's RTC-DS1307 library
loopsva 0:30a7faf58768 239 static int BCDToDec(int dat) {
loopsva 0:30a7faf58768 240 return ((dat & 0xF0) >> 4) * 10 + (dat & 0x0F);
loopsva 0:30a7faf58768 241 }
loopsva 0:30a7faf58768 242
loopsva 0:30a7faf58768 243 static int DecToBCD(int dat) {
loopsva 0:30a7faf58768 244 return (dat % 10) + ((dat / 10) << 4);
loopsva 0:30a7faf58768 245 }
loopsva 0:30a7faf58768 246 };
loopsva 0:30a7faf58768 247
loopsva 0:30a7faf58768 248 #endif // DS3232M_H