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@4:b5acccb6c3d1, 2015-04-28 (annotated)

Committer:
loopsva
Date:
Tue Apr 28 22:27:21 2015 +0000
Revision:
4:b5acccb6c3d1
Parent:
3:e9c5025ba2ca 
Added ability to use hi-level I2C commands, not just low level commands. #define DS3232_i2c_LOWLEVEL 1 in ds3232m.h will force the use of low-level i2c commands. Comment out for hi-level i2c command usage.

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