Declan Gordon / ds3231

j

Dependents:   LPC-SD-35

Fork of ds3231 by Maxim Integrated

ds3231.h@13:aa3eb69b25bb, 2015-03-17 (annotated)

Committer:
j3
Date:
Tue Mar 17 00:34:36 2015 +0000
Revision:
13:aa3eb69b25bb
Parent:
12:b9f13fd8c1b6
Child:
14:11630748e2f2
moved enum and structs inside class

Who changed what in which revision?

UserRevisionLine numberNew contents of line
j3 0:b00c4699ae6f 1 /******************************************************************//**
j3 0:b00c4699ae6f 2 * @file ds3231.h
j3 0:b00c4699ae6f 3 *
j3 0:b00c4699ae6f 4 * @author Justin Jordan
j3 0:b00c4699ae6f 5 *
j3 11:1654fcc0a5ea 6 * @version 1.0
j3 0:b00c4699ae6f 7 *
j3 0:b00c4699ae6f 8 * Started: 11NOV14
j3 0:b00c4699ae6f 9 *
j3 0:b00c4699ae6f 10 * Updated:
j3 0:b00c4699ae6f 11 *
j3 0:b00c4699ae6f 12 * @brief Header file for DS3231 class
j3 0:b00c4699ae6f 13 *
j3 0:b00c4699ae6f 14 ***********************************************************************
j3 0:b00c4699ae6f 15 *
j3 0:b00c4699ae6f 16 * @copyright
j3 12:b9f13fd8c1b6 17 * Copyright (C) 2015 Maxim Integrated Products, Inc., All Rights Reserved.
j3 0:b00c4699ae6f 18 *
j3 0:b00c4699ae6f 19 * Permission is hereby granted, free of charge, to any person obtaining a
j3 0:b00c4699ae6f 20 * copy of this software and associated documentation files (the "Software"),
j3 0:b00c4699ae6f 21 * to deal in the Software without restriction, including without limitation
j3 0:b00c4699ae6f 22 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
j3 0:b00c4699ae6f 23 * and/or sell copies of the Software, and to permit persons to whom the
j3 0:b00c4699ae6f 24 * Software is furnished to do so, subject to the following conditions:
j3 0:b00c4699ae6f 25 *
j3 0:b00c4699ae6f 26 * The above copyright notice and this permission notice shall be included
j3 0:b00c4699ae6f 27 * in all copies or substantial portions of the Software.
j3 0:b00c4699ae6f 28 *
j3 0:b00c4699ae6f 29 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
j3 0:b00c4699ae6f 30 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
j3 0:b00c4699ae6f 31 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
j3 0:b00c4699ae6f 32 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
j3 0:b00c4699ae6f 33 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
j3 0:b00c4699ae6f 34 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
j3 0:b00c4699ae6f 35 * OTHER DEALINGS IN THE SOFTWARE.
j3 0:b00c4699ae6f 36 *
j3 0:b00c4699ae6f 37 * Except as contained in this notice, the name of Maxim Integrated
j3 0:b00c4699ae6f 38 * Products, Inc. shall not be used except as stated in the Maxim Integrated
j3 0:b00c4699ae6f 39 * Products, Inc. Branding Policy.
j3 0:b00c4699ae6f 40 *
j3 0:b00c4699ae6f 41 * The mere transfer of this software does not imply any licenses
j3 0:b00c4699ae6f 42 * of trade secrets, proprietary technology, copyrights, patents,
j3 0:b00c4699ae6f 43 * trademarks, maskwork rights, or any other form of intellectual
j3 0:b00c4699ae6f 44 * property whatsoever. Maxim Integrated Products, Inc. retains all
j3 0:b00c4699ae6f 45 * ownership rights.
j3 0:b00c4699ae6f 46 **********************************************************************/
j3 0:b00c4699ae6f 47
j3 0:b00c4699ae6f 48
j3 0:b00c4699ae6f 49 #ifndef DS3231_H
j3 0:b00c4699ae6f 50 #define DS3231_H
j3 0:b00c4699ae6f 51
j3 0:b00c4699ae6f 52
j3 0:b00c4699ae6f 53 #include "mbed.h"
j3 0:b00c4699ae6f 54
j3 0:b00c4699ae6f 55
j3 3:312589d8185c 56 #define DS3231_I2C_ADRS 0x68
j3 0:b00c4699ae6f 57 #define I2C_WRITE 0
j3 0:b00c4699ae6f 58 #define I2C_READ 1
j3 0:b00c4699ae6f 59
j3 2:4e6e761c60f2 60 #define AM_PM (1 << 5)
j3 2:4e6e761c60f2 61 #define MODE (1 << 6)
j3 2:4e6e761c60f2 62 #define DY_DT (1 << 6)
j3 2:4e6e761c60f2 63 #define ALRM_MASK (1 << 7)
j3 0:b00c4699ae6f 64
j3 0:b00c4699ae6f 65 //control register bit masks
j3 0:b00c4699ae6f 66 #define A1IE (1 << 0)
j3 0:b00c4699ae6f 67 #define A2IE (1 << 1)
j3 0:b00c4699ae6f 68 #define INTCN (1 << 2)
j3 0:b00c4699ae6f 69 #define RS1 (1 << 3)
j3 0:b00c4699ae6f 70 #define RS2 (1 << 4)
j3 0:b00c4699ae6f 71 #define CONV (1 << 5)
j3 0:b00c4699ae6f 72 #define BBSQW (1 << 6)
j3 2:4e6e761c60f2 73 #define EOSC (1 << 7)
j3 0:b00c4699ae6f 74
j3 0:b00c4699ae6f 75 //status register bit masks
j3 0:b00c4699ae6f 76 #define A1F (1 << 0)
j3 0:b00c4699ae6f 77 #define A2F (1 << 1)
j3 0:b00c4699ae6f 78 #define BSY (1 << 2)
j3 0:b00c4699ae6f 79 #define EN32KHZ (1 << 3)
j3 0:b00c4699ae6f 80 #define OSF (1 << 7)
j3 9:e57201ee8921 81
j3 9:e57201ee8921 82
j3 0:b00c4699ae6f 83 /******************************************************************//**
j3 0:b00c4699ae6f 84 * Ds3231 Class
j3 0:b00c4699ae6f 85 **********************************************************************/
j3 1:c814af60fdbf 86 class Ds3231 : public I2C
j3 0:b00c4699ae6f 87 {
j3 0:b00c4699ae6f 88 uint8_t w_adrs, r_adrs;
j3 0:b00c4699ae6f 89
j3 2:4e6e761c60f2 90 /**********************************************************//**
j3 2:4e6e761c60f2 91 * Private mmber fx, converts unsigned char to BCD
j3 2:4e6e761c60f2 92 *
j3 2:4e6e761c60f2 93 * On Entry:
j3 2:4e6e761c60f2 94 * @param[in] data - 0-255
j3 2:4e6e761c60f2 95 *
j3 2:4e6e761c60f2 96 * On Exit:
j3 2:4e6e761c60f2 97 * @return bcd_result = BCD representation of data
j3 2:4e6e761c60f2 98 *
j3 2:4e6e761c60f2 99 **************************************************************/
j3 2:4e6e761c60f2 100 uint16_t uchar_2_bcd(uint8_t data);
j3 2:4e6e761c60f2 101
j3 2:4e6e761c60f2 102
j3 2:4e6e761c60f2 103 /**********************************************************//**
j3 2:4e6e761c60f2 104 * Private mmber fx, converts BCD to a uint8_t
j3 2:4e6e761c60f2 105 *
j3 2:4e6e761c60f2 106 * On Entry:
j3 2:4e6e761c60f2 107 * @param[in] bcd - 0-99
j3 2:4e6e761c60f2 108 *
j3 2:4e6e761c60f2 109 * On Exit:
j3 2:4e6e761c60f2 110 * @return rtn_val = integer rep. of BCD
j3 2:4e6e761c60f2 111 *
j3 2:4e6e761c60f2 112 **************************************************************/
j3 2:4e6e761c60f2 113 uint8_t bcd_2_uchar(uint8_t bcd);
j3 2:4e6e761c60f2 114
j3 0:b00c4699ae6f 115 public:
j3 13:aa3eb69b25bb 116
j3 13:aa3eb69b25bb 117 /**
j3 13:aa3eb69b25bb 118 * ds3231_regs_t - enumerated DS3231 registers
j3 13:aa3eb69b25bb 119 */
j3 13:aa3eb69b25bb 120 typedef enum
j3 13:aa3eb69b25bb 121 {
j3 13:aa3eb69b25bb 122 SECONDS,
j3 13:aa3eb69b25bb 123 MINUTES,
j3 13:aa3eb69b25bb 124 HOURS,
j3 13:aa3eb69b25bb 125 DAY,
j3 13:aa3eb69b25bb 126 DATE,
j3 13:aa3eb69b25bb 127 MONTH,
j3 13:aa3eb69b25bb 128 YEAR,
j3 13:aa3eb69b25bb 129 ALRM1_SECONDS,
j3 13:aa3eb69b25bb 130 ALRM1_MINUTES,
j3 13:aa3eb69b25bb 131 ALRM1_HOURS,
j3 13:aa3eb69b25bb 132 ALRM1_DAY_DATE,
j3 13:aa3eb69b25bb 133 ALRM2_MINUTES,
j3 13:aa3eb69b25bb 134 ALRM2_HOURS,
j3 13:aa3eb69b25bb 135 ALRM2_DAY_DATE,
j3 13:aa3eb69b25bb 136 CONTROL,
j3 13:aa3eb69b25bb 137 STATUS,
j3 13:aa3eb69b25bb 138 AGING_OFFSET, //don't touch this register
j3 13:aa3eb69b25bb 139 MSB_TEMP,
j3 13:aa3eb69b25bb 140 LSB_TEMP
j3 13:aa3eb69b25bb 141 }ds3231_regs_t;
j3 13:aa3eb69b25bb 142
j3 13:aa3eb69b25bb 143
j3 13:aa3eb69b25bb 144 /**
j3 13:aa3eb69b25bb 145 * ds3231_time_t - Struct for containing time data.
j3 13:aa3eb69b25bb 146 *
j3 13:aa3eb69b25bb 147 * Members:
j3 13:aa3eb69b25bb 148 *
j3 13:aa3eb69b25bb 149 * - uint32_t seconds - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 150 *
j3 13:aa3eb69b25bb 151 * - uint32_t minutes - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 152 *
j3 13:aa3eb69b25bb 153 * - uint32_t hours - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 154 *
j3 13:aa3eb69b25bb 155 * - bool am_pm - TRUE for PM, same logic as datasheet
j3 13:aa3eb69b25bb 156 *
j3 13:aa3eb69b25bb 157 * - bool mode - TRUE for 12 hour, same logic as datasheet
j3 13:aa3eb69b25bb 158 */
j3 13:aa3eb69b25bb 159 typedef struct
j3 13:aa3eb69b25bb 160 {
j3 13:aa3eb69b25bb 161 uint32_t seconds;
j3 13:aa3eb69b25bb 162 uint32_t minutes;
j3 13:aa3eb69b25bb 163 uint32_t hours;
j3 13:aa3eb69b25bb 164 bool am_pm;
j3 13:aa3eb69b25bb 165 bool mode;
j3 13:aa3eb69b25bb 166 }ds3231_time_t;
j3 13:aa3eb69b25bb 167
j3 13:aa3eb69b25bb 168
j3 13:aa3eb69b25bb 169 /**
j3 13:aa3eb69b25bb 170 * ds3231_calendar_t - Struct for containing calendar data.
j3 13:aa3eb69b25bb 171 *
j3 13:aa3eb69b25bb 172 * Members:
j3 13:aa3eb69b25bb 173 *
j3 13:aa3eb69b25bb 174 * - uint32_t day - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 175 *
j3 13:aa3eb69b25bb 176 * - uint32_t date - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 177 *
j3 13:aa3eb69b25bb 178 * - uint32_t month - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 179 *
j3 13:aa3eb69b25bb 180 * - uint32_t year - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 181 */
j3 13:aa3eb69b25bb 182 typedef struct
j3 13:aa3eb69b25bb 183 {
j3 13:aa3eb69b25bb 184 uint32_t day;
j3 13:aa3eb69b25bb 185 uint32_t date;
j3 13:aa3eb69b25bb 186 uint32_t month;
j3 13:aa3eb69b25bb 187 uint32_t year;
j3 13:aa3eb69b25bb 188 }ds3231_calendar_t;
j3 13:aa3eb69b25bb 189
j3 13:aa3eb69b25bb 190
j3 13:aa3eb69b25bb 191 /**
j3 13:aa3eb69b25bb 192 * ds3231_alrm_t - Struct for containing alarm data.
j3 13:aa3eb69b25bb 193 *
j3 13:aa3eb69b25bb 194 * Members:
j3 13:aa3eb69b25bb 195 *
j3 13:aa3eb69b25bb 196 * - uint32_t seconds - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 197 *
j3 13:aa3eb69b25bb 198 * - uint32_t minutes - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 199 *
j3 13:aa3eb69b25bb 200 * - uint32_t hours - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 201 *
j3 13:aa3eb69b25bb 202 * - uint32_t day - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 203 *
j3 13:aa3eb69b25bb 204 * - uint32_t date - Use decimal value. Member fx's convert to BCD
j3 13:aa3eb69b25bb 205 *
j3 13:aa3eb69b25bb 206 * - bool am1 - Flag for setting alarm rate
j3 13:aa3eb69b25bb 207 *
j3 13:aa3eb69b25bb 208 * - bool am2 - Flag for setting alarm rate
j3 13:aa3eb69b25bb 209 *
j3 13:aa3eb69b25bb 210 * - bool am3 - Flag for setting alarm rate
j3 13:aa3eb69b25bb 211 *
j3 13:aa3eb69b25bb 212 * - bool am4 - Flag for setting alarm rate
j3 13:aa3eb69b25bb 213 *
j3 13:aa3eb69b25bb 214 * - bool am_pm - TRUE for PM, same logic as datasheet
j3 13:aa3eb69b25bb 215 *
j3 13:aa3eb69b25bb 216 * - bool mode - TRUE for 12 hour, same logic as datasheet
j3 13:aa3eb69b25bb 217 *
j3 13:aa3eb69b25bb 218 * - bool dy_dt - TRUE for Day, same logic as datasheet
j3 13:aa3eb69b25bb 219 */
j3 13:aa3eb69b25bb 220 typedef struct
j3 13:aa3eb69b25bb 221 {
j3 13:aa3eb69b25bb 222 //Seconds and am1 not used for alarm2
j3 13:aa3eb69b25bb 223 uint32_t seconds;
j3 13:aa3eb69b25bb 224 uint32_t minutes;
j3 13:aa3eb69b25bb 225 uint32_t hours;
j3 13:aa3eb69b25bb 226 uint32_t day;
j3 13:aa3eb69b25bb 227 uint32_t date;
j3 13:aa3eb69b25bb 228 bool am1;
j3 13:aa3eb69b25bb 229 bool am2;
j3 13:aa3eb69b25bb 230 bool am3;
j3 13:aa3eb69b25bb 231 bool am4;
j3 13:aa3eb69b25bb 232 bool am_pm;
j3 13:aa3eb69b25bb 233 bool mode;
j3 13:aa3eb69b25bb 234 bool dy_dt;
j3 13:aa3eb69b25bb 235 }ds3231_alrm_t;
j3 13:aa3eb69b25bb 236
j3 13:aa3eb69b25bb 237
j3 13:aa3eb69b25bb 238 /**
j3 13:aa3eb69b25bb 239 * ds3231_cntl_stat_t - Struct for containing control and status
j3 13:aa3eb69b25bb 240 * register data.
j3 13:aa3eb69b25bb 241 *
j3 13:aa3eb69b25bb 242 * Members:
j3 13:aa3eb69b25bb 243 *
j3 13:aa3eb69b25bb 244 * - uint8_t control - Binary data for read/write of control register
j3 13:aa3eb69b25bb 245 *
j3 13:aa3eb69b25bb 246 * - uint8_t status - Binary data for read/write of status register
j3 13:aa3eb69b25bb 247 */
j3 13:aa3eb69b25bb 248 typedef struct
j3 13:aa3eb69b25bb 249 {
j3 13:aa3eb69b25bb 250 uint8_t control;
j3 13:aa3eb69b25bb 251 uint8_t status;
j3 13:aa3eb69b25bb 252 }ds3231_cntl_stat_t;
j3 9:e57201ee8921 253
j3 0:b00c4699ae6f 254 /**********************************************************//**
j3 0:b00c4699ae6f 255 * Constructor for Ds3231 Class
j3 0:b00c4699ae6f 256 *
j3 0:b00c4699ae6f 257 * On Entry:
j3 1:c814af60fdbf 258 * @param[in] sda - sda pin of I2C bus
j3 1:c814af60fdbf 259 * @param[in] scl - scl pin of I2C bus
j3 0:b00c4699ae6f 260 *
j3 0:b00c4699ae6f 261 * On Exit:
j3 0:b00c4699ae6f 262 * @return none
j3 0:b00c4699ae6f 263 *
j3 0:b00c4699ae6f 264 * Example:
j3 0:b00c4699ae6f 265 * @code
j3 0:b00c4699ae6f 266 *
j3 0:b00c4699ae6f 267 * //instantiate rtc object
j3 1:c814af60fdbf 268 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 269 *
j3 0:b00c4699ae6f 270 * @endcode
j3 0:b00c4699ae6f 271 **************************************************************/
j3 1:c814af60fdbf 272 Ds3231(PinName sda, PinName scl);
j3 0:b00c4699ae6f 273
j3 0:b00c4699ae6f 274
j3 0:b00c4699ae6f 275 /**********************************************************//**
j3 0:b00c4699ae6f 276 * Sets the time on DS3231
j3 2:4e6e761c60f2 277 * Struct data is in integrer format, not BCD. Fx will convert
j3 2:4e6e761c60f2 278 * to BCD for you.
j3 0:b00c4699ae6f 279 *
j3 0:b00c4699ae6f 280 * On Entry:
j3 0:b00c4699ae6f 281 * @param[in] time - struct cotaining time data;
j3 0:b00c4699ae6f 282 *
j3 0:b00c4699ae6f 283 * On Exit:
j3 0:b00c4699ae6f 284 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 285 *
j3 0:b00c4699ae6f 286 * Example:
j3 0:b00c4699ae6f 287 * @code
j3 0:b00c4699ae6f 288 *
j3 0:b00c4699ae6f 289 * //instantiate rtc object
j3 1:c814af60fdbf 290 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 291 *
j3 4:0beb5e9ac927 292 * //time = 12:00:00 AM 12hr mode
j3 4:0beb5e9ac927 293 * ds3231_time_t time = {12, 0, 0, 0, 1}
j3 0:b00c4699ae6f 294 * uint16_t rtn_val;
j3 0:b00c4699ae6f 295 *
j3 0:b00c4699ae6f 296 * rtn_val = rtc.set_time(time);
j3 0:b00c4699ae6f 297 *
j3 0:b00c4699ae6f 298 * @endcode
j3 0:b00c4699ae6f 299 **************************************************************/
j3 0:b00c4699ae6f 300 uint16_t set_time(ds3231_time_t time);
j3 0:b00c4699ae6f 301
j3 0:b00c4699ae6f 302
j3 0:b00c4699ae6f 303 /**********************************************************//**
j3 0:b00c4699ae6f 304 * Sets the calendar on DS3231
j3 0:b00c4699ae6f 305 *
j3 0:b00c4699ae6f 306 * On Entry:
j3 3:312589d8185c 307 * @param[in] calendar - struct cotaining calendar data
j3 0:b00c4699ae6f 308 *
j3 0:b00c4699ae6f 309 * On Exit:
j3 0:b00c4699ae6f 310 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 311 *
j3 0:b00c4699ae6f 312 * Example:
j3 0:b00c4699ae6f 313 * @code
j3 0:b00c4699ae6f 314 *
j3 0:b00c4699ae6f 315 * //instantiate rtc object
j3 1:c814af60fdbf 316 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 317 *
j3 0:b00c4699ae6f 318 * //see datasheet for calendar format
j3 0:b00c4699ae6f 319 * ds3231_calendar_t calendar = {1, 1, 1, 0};
j3 0:b00c4699ae6f 320 * uint16_t rtn_val;
j3 0:b00c4699ae6f 321 *
j3 0:b00c4699ae6f 322 * rtn_val = rtc.set_calendar(calendar);
j3 0:b00c4699ae6f 323 *
j3 0:b00c4699ae6f 324 * @endcode
j3 0:b00c4699ae6f 325 **************************************************************/
j3 0:b00c4699ae6f 326 uint16_t set_calendar(ds3231_calendar_t calendar);
j3 0:b00c4699ae6f 327
j3 0:b00c4699ae6f 328
j3 0:b00c4699ae6f 329 /**********************************************************//**
j3 0:b00c4699ae6f 330 * Set either Alarm1 or Alarm2 of DS3231
j3 0:b00c4699ae6f 331 *
j3 0:b00c4699ae6f 332 * On Entry:
j3 0:b00c4699ae6f 333 * @param[in] alarm - struct cotaining alarm data
j3 3:312589d8185c 334 *
j3 0:b00c4699ae6f 335 * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
j3 0:b00c4699ae6f 336 * Alarm2
j3 0:b00c4699ae6f 337 *
j3 0:b00c4699ae6f 338 * On Exit:
j3 0:b00c4699ae6f 339 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 340 *
j3 0:b00c4699ae6f 341 * Example:
j3 0:b00c4699ae6f 342 * @code
j3 0:b00c4699ae6f 343 *
j3 0:b00c4699ae6f 344 * //instantiate rtc object
j3 1:c814af60fdbf 345 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 346 *
j3 4:0beb5e9ac927 347 * //see ds3231.h for .members and datasheet for alarm format
j3 4:0beb5e9ac927 348 * ds3231_alrm_t alarm;
j3 0:b00c4699ae6f 349 * uint16_t rtn_val;
j3 0:b00c4699ae6f 350 *
j3 0:b00c4699ae6f 351 * rtn_val = rtc.set_alarm(alarm, FALSE);
j3 0:b00c4699ae6f 352 *
j3 0:b00c4699ae6f 353 * @endcode
j3 0:b00c4699ae6f 354 **************************************************************/
j3 0:b00c4699ae6f 355 uint16_t set_alarm(ds3231_alrm_t alarm, bool one_r_two);
j3 0:b00c4699ae6f 356
j3 0:b00c4699ae6f 357
j3 0:b00c4699ae6f 358 /**********************************************************//**
j3 0:b00c4699ae6f 359 * Set control and status registers of DS3231
j3 0:b00c4699ae6f 360 *
j3 0:b00c4699ae6f 361 * On Entry:
j3 0:b00c4699ae6f 362 * @param[in] data - Struct containing control and status
j3 0:b00c4699ae6f 363 * register data
j3 0:b00c4699ae6f 364 *
j3 0:b00c4699ae6f 365 * On Exit:
j3 0:b00c4699ae6f 366 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 367 *
j3 0:b00c4699ae6f 368 * Example:
j3 0:b00c4699ae6f 369 * @code
j3 0:b00c4699ae6f 370 *
j3 0:b00c4699ae6f 371 * //instantiate rtc object
j3 1:c814af60fdbf 372 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 373 *
j3 0:b00c4699ae6f 374 * //do not use 0xAA, see datasheet for appropriate data
j3 0:b00c4699ae6f 375 * ds3231_cntl_stat_t data = {0xAA, 0xAA};
j3 0:b00c4699ae6f 376 *
j3 0:b00c4699ae6f 377 * rtn_val = rtc.set_cntl_stat_reg(data);
j3 0:b00c4699ae6f 378 *
j3 0:b00c4699ae6f 379 * @endcode
j3 0:b00c4699ae6f 380 **************************************************************/
j3 0:b00c4699ae6f 381 uint16_t set_cntl_stat_reg(ds3231_cntl_stat_t data);
j3 0:b00c4699ae6f 382
j3 0:b00c4699ae6f 383
j3 0:b00c4699ae6f 384 /**********************************************************//**
j3 0:b00c4699ae6f 385 * Gets the time on DS3231
j3 0:b00c4699ae6f 386 *
j3 0:b00c4699ae6f 387 * On Entry:
j3 4:0beb5e9ac927 388 * @param[in] time - pointer to struct for storing time data
j3 0:b00c4699ae6f 389 *
j3 0:b00c4699ae6f 390 * On Exit:
j3 2:4e6e761c60f2 391 * @param[out] time - contains current integrer rtc time
j3 2:4e6e761c60f2 392 * data
j3 0:b00c4699ae6f 393 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 394 *
j3 0:b00c4699ae6f 395 * Example:
j3 0:b00c4699ae6f 396 * @code
j3 0:b00c4699ae6f 397 *
j3 0:b00c4699ae6f 398 * //instantiate rtc object
j3 1:c814af60fdbf 399 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 400 *
j3 4:0beb5e9ac927 401 * //time = 12:00:00 AM 12hr mode
j3 4:0beb5e9ac927 402 * ds3231_time_t time = {12, 0, 0, 0, 1}
j3 0:b00c4699ae6f 403 * uint16_t rtn_val;
j3 0:b00c4699ae6f 404 *
j3 3:312589d8185c 405 * rtn_val = rtc.get_time(&time);
j3 0:b00c4699ae6f 406 *
j3 0:b00c4699ae6f 407 * @endcode
j3 0:b00c4699ae6f 408 **************************************************************/
j3 2:4e6e761c60f2 409 uint16_t get_time(ds3231_time_t* time);
j3 0:b00c4699ae6f 410
j3 0:b00c4699ae6f 411
j3 0:b00c4699ae6f 412 /**********************************************************//**
j3 0:b00c4699ae6f 413 * Gets the calendar on DS3231
j3 0:b00c4699ae6f 414 *
j3 0:b00c4699ae6f 415 * On Entry:
j3 2:4e6e761c60f2 416 * @param[in] calendar - pointer to struct for storing
j3 4:0beb5e9ac927 417 * calendar data
j3 0:b00c4699ae6f 418 *
j3 0:b00c4699ae6f 419 * On Exit:
j3 2:4e6e761c60f2 420 * @param[out] calendar - contains current integer rtc
j3 2:4e6e761c60f2 421 * calendar data
j3 0:b00c4699ae6f 422 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 423 *
j3 0:b00c4699ae6f 424 * Example:
j3 0:b00c4699ae6f 425 * @code
j3 0:b00c4699ae6f 426 *
j3 0:b00c4699ae6f 427 * //instantiate rtc object
j3 1:c814af60fdbf 428 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 429 *
j3 0:b00c4699ae6f 430 * //see datasheet for calendar format
j3 0:b00c4699ae6f 431 * ds3231_calendar_t calendar = {1, 1, 1, 0};
j3 0:b00c4699ae6f 432 * uint16_t rtn_val;
j3 0:b00c4699ae6f 433 *
j3 3:312589d8185c 434 * rtn_val = rtc.get_calendar(&calendar);
j3 0:b00c4699ae6f 435 *
j3 0:b00c4699ae6f 436 * @endcode
j3 0:b00c4699ae6f 437 **************************************************************/
j3 2:4e6e761c60f2 438 uint16_t get_calendar(ds3231_calendar_t* calendar);
j3 0:b00c4699ae6f 439
j3 0:b00c4699ae6f 440
j3 0:b00c4699ae6f 441 /**********************************************************//**
j3 0:b00c4699ae6f 442 * Get either Alarm1 or Alarm2 of DS3231
j3 0:b00c4699ae6f 443 *
j3 0:b00c4699ae6f 444 * On Entry:
j3 2:4e6e761c60f2 445 * @param[in] alarm - pointer to struct for storing alarm
j3 2:4e6e761c60f2 446 * data;
j3 2:4e6e761c60f2 447 *
j3 0:b00c4699ae6f 448 * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
j3 0:b00c4699ae6f 449 * Alarm2
j3 0:b00c4699ae6f 450 *
j3 0:b00c4699ae6f 451 * On Exit:
j3 2:4e6e761c60f2 452 * @param[out] alarm - contains integer alarm data
j3 0:b00c4699ae6f 453 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 454 *
j3 0:b00c4699ae6f 455 * Example:
j3 0:b00c4699ae6f 456 * @code
j3 0:b00c4699ae6f 457 *
j3 0:b00c4699ae6f 458 * //instantiate rtc object
j3 1:c814af60fdbf 459 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 460 *
j3 4:0beb5e9ac927 461 * //see ds3231.h for .members and datasheet for alarm format
j3 4:0beb5e9ac927 462 * ds3231_alrm_t alarm;
j3 0:b00c4699ae6f 463 * uint16_t rtn_val;
j3 0:b00c4699ae6f 464 *
j3 3:312589d8185c 465 * rtn_val = rtc.get_alarm(&alarm, FALSE);
j3 0:b00c4699ae6f 466 *
j3 0:b00c4699ae6f 467 * @endcode
j3 0:b00c4699ae6f 468 **************************************************************/
j3 2:4e6e761c60f2 469 uint16_t get_alarm(ds3231_alrm_t* alarm, bool one_r_two);
j3 0:b00c4699ae6f 470
j3 0:b00c4699ae6f 471
j3 0:b00c4699ae6f 472 /**********************************************************//**
j3 0:b00c4699ae6f 473 * Get control and status registers of DS3231
j3 0:b00c4699ae6f 474 *
j3 0:b00c4699ae6f 475 * On Entry:
j3 2:4e6e761c60f2 476 * @param[in] data - pointer to struct for storing control
j3 4:0beb5e9ac927 477 * and status register data
j3 0:b00c4699ae6f 478 *
j3 0:b00c4699ae6f 479 * On Exit:
j3 0:b00c4699ae6f 480 * @param[out] data - contains control and status registers
j3 0:b00c4699ae6f 481 * data
j3 0:b00c4699ae6f 482 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 483 *
j3 0:b00c4699ae6f 484 * Example:
j3 0:b00c4699ae6f 485 * @code
j3 0:b00c4699ae6f 486 *
j3 0:b00c4699ae6f 487 * //instantiate rtc object
j3 1:c814af60fdbf 488 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 489 *
j3 0:b00c4699ae6f 490 * //do not use 0xAA, see datasheet for appropriate data
j3 0:b00c4699ae6f 491 * ds3231_cntl_stat_t data = {0xAA, 0xAA};
j3 0:b00c4699ae6f 492 *
j3 3:312589d8185c 493 * rtn_val = rtc.get_cntl_stat_reg(&data);
j3 0:b00c4699ae6f 494 *
j3 0:b00c4699ae6f 495 * @endcode
j3 0:b00c4699ae6f 496 **************************************************************/
j3 2:4e6e761c60f2 497 uint16_t get_cntl_stat_reg(ds3231_cntl_stat_t* data);
j3 0:b00c4699ae6f 498
j3 0:b00c4699ae6f 499
j3 0:b00c4699ae6f 500 /**********************************************************//**
j3 0:b00c4699ae6f 501 * Get temperature data of DS3231
j3 0:b00c4699ae6f 502 *
j3 0:b00c4699ae6f 503 * On Entry:
j3 0:b00c4699ae6f 504 *
j3 0:b00c4699ae6f 505 * On Exit:
j3 2:4e6e761c60f2 506 * @return return value = raw temperature data
j3 0:b00c4699ae6f 507 *
j3 0:b00c4699ae6f 508 * Example:
j3 0:b00c4699ae6f 509 * @code
j3 0:b00c4699ae6f 510 *
j3 0:b00c4699ae6f 511 * //instantiate rtc object
j3 1:c814af60fdbf 512 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 513 *
j3 0:b00c4699ae6f 514 * uint16_t temp;
j3 0:b00c4699ae6f 515 *
j3 2:4e6e761c60f2 516 * temp = rtc.get_temperature();
j3 0:b00c4699ae6f 517 *
j3 0:b00c4699ae6f 518 * @endcode
j3 0:b00c4699ae6f 519 **************************************************************/
j3 2:4e6e761c60f2 520 uint16_t get_temperature(void);
j3 0:b00c4699ae6f 521
j3 5:61dfe2690360 522
j3 5:61dfe2690360 523 /**********************************************************//**
j3 5:61dfe2690360 524 * Get epoch time based on current RTC time and date.
j3 5:61dfe2690360 525 * DS3231 must be configured and running before this fx is
j3 5:61dfe2690360 526 * called
j3 5:61dfe2690360 527 *
j3 5:61dfe2690360 528 * On Entry:
j3 5:61dfe2690360 529 *
j3 5:61dfe2690360 530 * On Exit:
j3 5:61dfe2690360 531 * @return return value = epoch time
j3 5:61dfe2690360 532 *
j3 5:61dfe2690360 533 * Example:
j3 5:61dfe2690360 534 * @code
j3 5:61dfe2690360 535 *
j3 5:61dfe2690360 536 * //instantiate rtc object
j3 5:61dfe2690360 537 * Ds3231 rtc(D14, D15);
j3 5:61dfe2690360 538 *
j3 5:61dfe2690360 539 * time_t epoch_time;
j3 5:61dfe2690360 540 *
j3 5:61dfe2690360 541 * epoch_time = rtc.get_epoch();
j3 5:61dfe2690360 542 *
j3 5:61dfe2690360 543 * @endcode
j3 5:61dfe2690360 544 **************************************************************/
j3 5:61dfe2690360 545 time_t get_epoch(void);
j3 5:61dfe2690360 546
j3 0:b00c4699ae6f 547 };
j3 0:b00c4699ae6f 548 #endif /* DS3231_H*/