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@2:a9a8027a7cb2, 2014-12-25 (annotated)

Committer:
loopsva
Date:
Thu Dec 25 21:38:22 2014 +0000
Revision:
2:a9a8027a7cb2
Parent:
1:0975d4a9b513
Child:
3:e9c5025ba2ca
Child:
6:968b8efe3ca0
Removed all RTOS contingency.  Put all RTOS Mutex I2C lock/unlock back on the calling program.

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