Maxim Integrated / ds3231

Library for DS3231 RTC

Dependents:   ard2pmod DS3231demo DS3231demo_COM_Port_Output MAXREFDES99_RTC_Display ... more

DS3231 Component Page

ds3231.h@8:c7484a65fcea, 2014-12-05 (annotated)

Committer:
j3
Date:
Fri Dec 05 21:11:26 2014 +0000
Revision:
8:c7484a65fcea
Parent:
5:61dfe2690360
Child:
9:e57201ee8921
Updated doxygen formatting for structs

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 0:b00c4699ae6f 6 * @version 0.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 0:b00c4699ae6f 17 * Copyright (C) 2013 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 0:b00c4699ae6f 81
j3 0:b00c4699ae6f 82
j3 8:c7484a65fcea 83 /**
j3 8:c7484a65fcea 84 * !!!!!TEST!!!!!
j3 8:c7484a65fcea 85 * enumerated registers
j3 8:c7484a65fcea 86 */
j3 0:b00c4699ae6f 87 typedef enum
j3 0:b00c4699ae6f 88 {
j3 0:b00c4699ae6f 89 SECONDS,
j3 0:b00c4699ae6f 90 MINUTES,
j3 0:b00c4699ae6f 91 HOURS,
j3 0:b00c4699ae6f 92 DAY,
j3 0:b00c4699ae6f 93 DATE,
j3 0:b00c4699ae6f 94 MONTH,
j3 0:b00c4699ae6f 95 YEAR,
j3 0:b00c4699ae6f 96 ALRM1_SECONDS,
j3 0:b00c4699ae6f 97 ALRM1_MINUTES,
j3 0:b00c4699ae6f 98 ALRM1_HOURS,
j3 0:b00c4699ae6f 99 ALRM1_DAY_DATE,
j3 0:b00c4699ae6f 100 ALRM2_MINUTES,
j3 0:b00c4699ae6f 101 ALRM2_HOURS,
j3 0:b00c4699ae6f 102 ALRM2_DAY_DATE,
j3 0:b00c4699ae6f 103 CONTROL,
j3 0:b00c4699ae6f 104 STATUS,
j3 0:b00c4699ae6f 105 AGING_OFFSET, //don't touch this register
j3 0:b00c4699ae6f 106 MSB_TEMP,
j3 0:b00c4699ae6f 107 LSB_TEMP
j3 0:b00c4699ae6f 108 }ds3231_regs_t;
j3 0:b00c4699ae6f 109
j3 0:b00c4699ae6f 110
j3 8:c7484a65fcea 111 /**
j3 8:c7484a65fcea 112 * ds3231_time_t - Struct for containing time data.
j3 8:c7484a65fcea 113 *
j3 8:c7484a65fcea 114 * Members:
j3 8:c7484a65fcea 115 *
j3 8:c7484a65fcea 116 * - uint8_t seconds - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 117 *
j3 8:c7484a65fcea 118 * - uint8_t minutes - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 119 *
j3 8:c7484a65fcea 120 * - uint8_t hours - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 121 *
j3 8:c7484a65fcea 122 * - bool am_pm - TRUE for PM, same logic as datasheet
j3 8:c7484a65fcea 123 *
j3 8:c7484a65fcea 124 * - bool mode - TRUE for 12 hour, same logic as datasheet
j3 8:c7484a65fcea 125 */
j3 0:b00c4699ae6f 126 typedef struct
j3 0:b00c4699ae6f 127 {
j3 3:312589d8185c 128 uint8_t seconds; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 129 uint8_t minutes; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 130 uint8_t hours; //Use decimal value. Member fx's convert to BCD
j3 2:4e6e761c60f2 131 bool am_pm; //TRUE for PM, same logic as datasheet
j3 2:4e6e761c60f2 132 bool mode; //TRUE for 12 hour, same logic as datasheet
j3 0:b00c4699ae6f 133 }ds3231_time_t;
j3 0:b00c4699ae6f 134
j3 0:b00c4699ae6f 135
j3 8:c7484a65fcea 136 /**
j3 8:c7484a65fcea 137 * ds3231_calendar_t - Struct for containing calendar data.
j3 8:c7484a65fcea 138 *
j3 8:c7484a65fcea 139 * Members:
j3 8:c7484a65fcea 140 *
j3 8:c7484a65fcea 141 * - uint8_t day - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 142 *
j3 8:c7484a65fcea 143 * - uint8_t date - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 144 *
j3 8:c7484a65fcea 145 * - uint8_t month - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 146 *
j3 8:c7484a65fcea 147 * - uint8_t year - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 148 */
j3 0:b00c4699ae6f 149 typedef struct
j3 0:b00c4699ae6f 150 {
j3 3:312589d8185c 151 uint8_t day; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 152 uint8_t date; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 153 uint8_t month; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 154 uint8_t year; //Use decimal value. Member fx's convert to BCD
j3 0:b00c4699ae6f 155 }ds3231_calendar_t;
j3 0:b00c4699ae6f 156
j3 0:b00c4699ae6f 157
j3 8:c7484a65fcea 158 /**
j3 8:c7484a65fcea 159 * ds3231_alrm_t - Struct for containing alarm data.
j3 8:c7484a65fcea 160 *
j3 8:c7484a65fcea 161 * Members:
j3 8:c7484a65fcea 162 *
j3 8:c7484a65fcea 163 * - uint8_t seconds - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 164 *
j3 8:c7484a65fcea 165 * - uint8_t minutes - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 166 *
j3 8:c7484a65fcea 167 * - uint8_t hours - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 168 *
j3 8:c7484a65fcea 169 * - uint8_t day - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 170 *
j3 8:c7484a65fcea 171 * - uint8_t date - Use decimal value. Member fx's convert to BCD
j3 8:c7484a65fcea 172 *
j3 8:c7484a65fcea 173 * - bool am1 - Flag for setting alarm rate
j3 8:c7484a65fcea 174 *
j3 8:c7484a65fcea 175 * - bool am2 - Flag for setting alarm rate
j3 8:c7484a65fcea 176 *
j3 8:c7484a65fcea 177 * - bool am3 - Flag for setting alarm rate
j3 8:c7484a65fcea 178 *
j3 8:c7484a65fcea 179 * - bool am4 - Flag for setting alarm rate
j3 8:c7484a65fcea 180 *
j3 8:c7484a65fcea 181 * - bool am_pm - TRUE for PM, same logic as datasheet
j3 8:c7484a65fcea 182 *
j3 8:c7484a65fcea 183 * - bool mode - TRUE for 12 hour, same logic as datasheet
j3 8:c7484a65fcea 184 *
j3 8:c7484a65fcea 185 * - bool dy_dt - TRUE for Day, same logic as datasheet
j3 8:c7484a65fcea 186 */
j3 0:b00c4699ae6f 187 typedef struct
j3 0:b00c4699ae6f 188 {
j3 3:312589d8185c 189 //Seconds and am1 not used for alarm2
j3 3:312589d8185c 190 uint8_t seconds; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 191 uint8_t minutes; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 192 uint8_t hours; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 193 uint8_t day; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 194 uint8_t date; //Use decimal value. Member fx's convert to BCD
j3 3:312589d8185c 195 bool am1;
j3 2:4e6e761c60f2 196 bool am2;
j3 2:4e6e761c60f2 197 bool am3;
j3 2:4e6e761c60f2 198 bool am4;
j3 2:4e6e761c60f2 199 bool am_pm; //TRUE for PM, same logic as datasheet
j3 2:4e6e761c60f2 200 bool mode; //TRUE for 12 hour, same logic as datasheet
j3 2:4e6e761c60f2 201 bool dy_dt; //TRUE for Day, same logic as datasheet
j3 0:b00c4699ae6f 202 }ds3231_alrm_t;
j3 0:b00c4699ae6f 203
j3 0:b00c4699ae6f 204
j3 8:c7484a65fcea 205 /**
j3 8:c7484a65fcea 206 * ds3231_cntl_stat_t - Struct for containing control and status
j3 8:c7484a65fcea 207 * register data.
j3 8:c7484a65fcea 208 *
j3 8:c7484a65fcea 209 * Members:
j3 8:c7484a65fcea 210 *
j3 8:c7484a65fcea 211 * - uint8_t control - Binary data for read/write of control register
j3 8:c7484a65fcea 212 *
j3 8:c7484a65fcea 213 * - uint8_t status - Binary data for read/write of status register
j3 8:c7484a65fcea 214 */
j3 0:b00c4699ae6f 215 typedef struct
j3 0:b00c4699ae6f 216 {
j3 3:312589d8185c 217 uint8_t control; //binary data
j3 3:312589d8185c 218 uint8_t status; //binary data
j3 0:b00c4699ae6f 219 }ds3231_cntl_stat_t;
j3 0:b00c4699ae6f 220
j3 0:b00c4699ae6f 221
j3 0:b00c4699ae6f 222 /******************************************************************//**
j3 0:b00c4699ae6f 223 * Ds3231 Class
j3 0:b00c4699ae6f 224 **********************************************************************/
j3 1:c814af60fdbf 225 class Ds3231 : public I2C
j3 0:b00c4699ae6f 226 {
j3 0:b00c4699ae6f 227 uint8_t w_adrs, r_adrs;
j3 0:b00c4699ae6f 228
j3 2:4e6e761c60f2 229 /**********************************************************//**
j3 2:4e6e761c60f2 230 * Private mmber fx, converts unsigned char to BCD
j3 2:4e6e761c60f2 231 *
j3 2:4e6e761c60f2 232 * On Entry:
j3 2:4e6e761c60f2 233 * @param[in] data - 0-255
j3 2:4e6e761c60f2 234 *
j3 2:4e6e761c60f2 235 * On Exit:
j3 2:4e6e761c60f2 236 * @return bcd_result = BCD representation of data
j3 2:4e6e761c60f2 237 *
j3 2:4e6e761c60f2 238 **************************************************************/
j3 2:4e6e761c60f2 239 uint16_t uchar_2_bcd(uint8_t data);
j3 2:4e6e761c60f2 240
j3 2:4e6e761c60f2 241
j3 2:4e6e761c60f2 242 /**********************************************************//**
j3 2:4e6e761c60f2 243 * Private mmber fx, converts BCD to a uint8_t
j3 2:4e6e761c60f2 244 *
j3 2:4e6e761c60f2 245 * On Entry:
j3 2:4e6e761c60f2 246 * @param[in] bcd - 0-99
j3 2:4e6e761c60f2 247 *
j3 2:4e6e761c60f2 248 * On Exit:
j3 2:4e6e761c60f2 249 * @return rtn_val = integer rep. of BCD
j3 2:4e6e761c60f2 250 *
j3 2:4e6e761c60f2 251 **************************************************************/
j3 2:4e6e761c60f2 252 uint8_t bcd_2_uchar(uint8_t bcd);
j3 2:4e6e761c60f2 253
j3 0:b00c4699ae6f 254 public:
j3 0:b00c4699ae6f 255 /**********************************************************//**
j3 0:b00c4699ae6f 256 * Constructor for Ds3231 Class
j3 0:b00c4699ae6f 257 *
j3 0:b00c4699ae6f 258 * On Entry:
j3 1:c814af60fdbf 259 * @param[in] sda - sda pin of I2C bus
j3 1:c814af60fdbf 260 * @param[in] scl - scl pin of I2C bus
j3 0:b00c4699ae6f 261 *
j3 0:b00c4699ae6f 262 * On Exit:
j3 0:b00c4699ae6f 263 * @return none
j3 0:b00c4699ae6f 264 *
j3 0:b00c4699ae6f 265 * Example:
j3 0:b00c4699ae6f 266 * @code
j3 0:b00c4699ae6f 267 *
j3 0:b00c4699ae6f 268 * //instantiate rtc object
j3 1:c814af60fdbf 269 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 270 *
j3 0:b00c4699ae6f 271 * @endcode
j3 0:b00c4699ae6f 272 **************************************************************/
j3 1:c814af60fdbf 273 Ds3231(PinName sda, PinName scl);
j3 0:b00c4699ae6f 274
j3 0:b00c4699ae6f 275
j3 0:b00c4699ae6f 276 /**********************************************************//**
j3 0:b00c4699ae6f 277 * Sets the time on DS3231
j3 2:4e6e761c60f2 278 * Struct data is in integrer format, not BCD. Fx will convert
j3 2:4e6e761c60f2 279 * to BCD for you.
j3 0:b00c4699ae6f 280 *
j3 0:b00c4699ae6f 281 * On Entry:
j3 0:b00c4699ae6f 282 * @param[in] time - struct cotaining time data;
j3 0:b00c4699ae6f 283 *
j3 0:b00c4699ae6f 284 * On Exit:
j3 0:b00c4699ae6f 285 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 286 *
j3 0:b00c4699ae6f 287 * Example:
j3 0:b00c4699ae6f 288 * @code
j3 0:b00c4699ae6f 289 *
j3 0:b00c4699ae6f 290 * //instantiate rtc object
j3 1:c814af60fdbf 291 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 292 *
j3 4:0beb5e9ac927 293 * //time = 12:00:00 AM 12hr mode
j3 4:0beb5e9ac927 294 * ds3231_time_t time = {12, 0, 0, 0, 1}
j3 0:b00c4699ae6f 295 * uint16_t rtn_val;
j3 0:b00c4699ae6f 296 *
j3 0:b00c4699ae6f 297 * rtn_val = rtc.set_time(time);
j3 0:b00c4699ae6f 298 *
j3 0:b00c4699ae6f 299 * @endcode
j3 0:b00c4699ae6f 300 **************************************************************/
j3 0:b00c4699ae6f 301 uint16_t set_time(ds3231_time_t time);
j3 0:b00c4699ae6f 302
j3 0:b00c4699ae6f 303
j3 0:b00c4699ae6f 304 /**********************************************************//**
j3 0:b00c4699ae6f 305 * Sets the calendar on DS3231
j3 0:b00c4699ae6f 306 *
j3 0:b00c4699ae6f 307 * On Entry:
j3 3:312589d8185c 308 * @param[in] calendar - struct cotaining calendar data
j3 0:b00c4699ae6f 309 *
j3 0:b00c4699ae6f 310 * On Exit:
j3 0:b00c4699ae6f 311 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 312 *
j3 0:b00c4699ae6f 313 * Example:
j3 0:b00c4699ae6f 314 * @code
j3 0:b00c4699ae6f 315 *
j3 0:b00c4699ae6f 316 * //instantiate rtc object
j3 1:c814af60fdbf 317 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 318 *
j3 0:b00c4699ae6f 319 * //see datasheet for calendar format
j3 0:b00c4699ae6f 320 * ds3231_calendar_t calendar = {1, 1, 1, 0};
j3 0:b00c4699ae6f 321 * uint16_t rtn_val;
j3 0:b00c4699ae6f 322 *
j3 0:b00c4699ae6f 323 * rtn_val = rtc.set_calendar(calendar);
j3 0:b00c4699ae6f 324 *
j3 0:b00c4699ae6f 325 * @endcode
j3 0:b00c4699ae6f 326 **************************************************************/
j3 0:b00c4699ae6f 327 uint16_t set_calendar(ds3231_calendar_t calendar);
j3 0:b00c4699ae6f 328
j3 0:b00c4699ae6f 329
j3 0:b00c4699ae6f 330 /**********************************************************//**
j3 0:b00c4699ae6f 331 * Set either Alarm1 or Alarm2 of DS3231
j3 0:b00c4699ae6f 332 *
j3 0:b00c4699ae6f 333 * On Entry:
j3 0:b00c4699ae6f 334 * @param[in] alarm - struct cotaining alarm data
j3 3:312589d8185c 335 *
j3 0:b00c4699ae6f 336 * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
j3 0:b00c4699ae6f 337 * Alarm2
j3 0:b00c4699ae6f 338 *
j3 0:b00c4699ae6f 339 * On Exit:
j3 0:b00c4699ae6f 340 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 341 *
j3 0:b00c4699ae6f 342 * Example:
j3 0:b00c4699ae6f 343 * @code
j3 0:b00c4699ae6f 344 *
j3 0:b00c4699ae6f 345 * //instantiate rtc object
j3 1:c814af60fdbf 346 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 347 *
j3 4:0beb5e9ac927 348 * //see ds3231.h for .members and datasheet for alarm format
j3 4:0beb5e9ac927 349 * ds3231_alrm_t alarm;
j3 0:b00c4699ae6f 350 * uint16_t rtn_val;
j3 0:b00c4699ae6f 351 *
j3 0:b00c4699ae6f 352 * rtn_val = rtc.set_alarm(alarm, FALSE);
j3 0:b00c4699ae6f 353 *
j3 0:b00c4699ae6f 354 * @endcode
j3 0:b00c4699ae6f 355 **************************************************************/
j3 0:b00c4699ae6f 356 uint16_t set_alarm(ds3231_alrm_t alarm, bool one_r_two);
j3 0:b00c4699ae6f 357
j3 0:b00c4699ae6f 358
j3 0:b00c4699ae6f 359 /**********************************************************//**
j3 0:b00c4699ae6f 360 * Set control and status registers of DS3231
j3 0:b00c4699ae6f 361 *
j3 0:b00c4699ae6f 362 * On Entry:
j3 0:b00c4699ae6f 363 * @param[in] data - Struct containing control and status
j3 0:b00c4699ae6f 364 * register data
j3 0:b00c4699ae6f 365 *
j3 0:b00c4699ae6f 366 * On Exit:
j3 0:b00c4699ae6f 367 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 368 *
j3 0:b00c4699ae6f 369 * Example:
j3 0:b00c4699ae6f 370 * @code
j3 0:b00c4699ae6f 371 *
j3 0:b00c4699ae6f 372 * //instantiate rtc object
j3 1:c814af60fdbf 373 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 374 *
j3 0:b00c4699ae6f 375 * //do not use 0xAA, see datasheet for appropriate data
j3 0:b00c4699ae6f 376 * ds3231_cntl_stat_t data = {0xAA, 0xAA};
j3 0:b00c4699ae6f 377 *
j3 0:b00c4699ae6f 378 * rtn_val = rtc.set_cntl_stat_reg(data);
j3 0:b00c4699ae6f 379 *
j3 0:b00c4699ae6f 380 * @endcode
j3 0:b00c4699ae6f 381 **************************************************************/
j3 0:b00c4699ae6f 382 uint16_t set_cntl_stat_reg(ds3231_cntl_stat_t data);
j3 0:b00c4699ae6f 383
j3 0:b00c4699ae6f 384
j3 0:b00c4699ae6f 385 /**********************************************************//**
j3 0:b00c4699ae6f 386 * Gets the time on DS3231
j3 0:b00c4699ae6f 387 *
j3 0:b00c4699ae6f 388 * On Entry:
j3 4:0beb5e9ac927 389 * @param[in] time - pointer to struct for storing time data
j3 0:b00c4699ae6f 390 *
j3 0:b00c4699ae6f 391 * On Exit:
j3 2:4e6e761c60f2 392 * @param[out] time - contains current integrer rtc time
j3 2:4e6e761c60f2 393 * data
j3 0:b00c4699ae6f 394 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 395 *
j3 0:b00c4699ae6f 396 * Example:
j3 0:b00c4699ae6f 397 * @code
j3 0:b00c4699ae6f 398 *
j3 0:b00c4699ae6f 399 * //instantiate rtc object
j3 1:c814af60fdbf 400 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 401 *
j3 4:0beb5e9ac927 402 * //time = 12:00:00 AM 12hr mode
j3 4:0beb5e9ac927 403 * ds3231_time_t time = {12, 0, 0, 0, 1}
j3 0:b00c4699ae6f 404 * uint16_t rtn_val;
j3 0:b00c4699ae6f 405 *
j3 3:312589d8185c 406 * rtn_val = rtc.get_time(&time);
j3 0:b00c4699ae6f 407 *
j3 0:b00c4699ae6f 408 * @endcode
j3 0:b00c4699ae6f 409 **************************************************************/
j3 2:4e6e761c60f2 410 uint16_t get_time(ds3231_time_t* time);
j3 0:b00c4699ae6f 411
j3 0:b00c4699ae6f 412
j3 0:b00c4699ae6f 413 /**********************************************************//**
j3 0:b00c4699ae6f 414 * Gets the calendar on DS3231
j3 0:b00c4699ae6f 415 *
j3 0:b00c4699ae6f 416 * On Entry:
j3 2:4e6e761c60f2 417 * @param[in] calendar - pointer to struct for storing
j3 4:0beb5e9ac927 418 * calendar data
j3 0:b00c4699ae6f 419 *
j3 0:b00c4699ae6f 420 * On Exit:
j3 2:4e6e761c60f2 421 * @param[out] calendar - contains current integer rtc
j3 2:4e6e761c60f2 422 * calendar data
j3 0:b00c4699ae6f 423 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 424 *
j3 0:b00c4699ae6f 425 * Example:
j3 0:b00c4699ae6f 426 * @code
j3 0:b00c4699ae6f 427 *
j3 0:b00c4699ae6f 428 * //instantiate rtc object
j3 1:c814af60fdbf 429 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 430 *
j3 0:b00c4699ae6f 431 * //see datasheet for calendar format
j3 0:b00c4699ae6f 432 * ds3231_calendar_t calendar = {1, 1, 1, 0};
j3 0:b00c4699ae6f 433 * uint16_t rtn_val;
j3 0:b00c4699ae6f 434 *
j3 3:312589d8185c 435 * rtn_val = rtc.get_calendar(&calendar);
j3 0:b00c4699ae6f 436 *
j3 0:b00c4699ae6f 437 * @endcode
j3 0:b00c4699ae6f 438 **************************************************************/
j3 2:4e6e761c60f2 439 uint16_t get_calendar(ds3231_calendar_t* calendar);
j3 0:b00c4699ae6f 440
j3 0:b00c4699ae6f 441
j3 0:b00c4699ae6f 442 /**********************************************************//**
j3 0:b00c4699ae6f 443 * Get either Alarm1 or Alarm2 of DS3231
j3 0:b00c4699ae6f 444 *
j3 0:b00c4699ae6f 445 * On Entry:
j3 2:4e6e761c60f2 446 * @param[in] alarm - pointer to struct for storing alarm
j3 2:4e6e761c60f2 447 * data;
j3 2:4e6e761c60f2 448 *
j3 0:b00c4699ae6f 449 * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
j3 0:b00c4699ae6f 450 * Alarm2
j3 0:b00c4699ae6f 451 *
j3 0:b00c4699ae6f 452 * On Exit:
j3 2:4e6e761c60f2 453 * @param[out] alarm - contains integer alarm data
j3 0:b00c4699ae6f 454 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 455 *
j3 0:b00c4699ae6f 456 * Example:
j3 0:b00c4699ae6f 457 * @code
j3 0:b00c4699ae6f 458 *
j3 0:b00c4699ae6f 459 * //instantiate rtc object
j3 1:c814af60fdbf 460 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 461 *
j3 4:0beb5e9ac927 462 * //see ds3231.h for .members and datasheet for alarm format
j3 4:0beb5e9ac927 463 * ds3231_alrm_t alarm;
j3 0:b00c4699ae6f 464 * uint16_t rtn_val;
j3 0:b00c4699ae6f 465 *
j3 3:312589d8185c 466 * rtn_val = rtc.get_alarm(&alarm, FALSE);
j3 0:b00c4699ae6f 467 *
j3 0:b00c4699ae6f 468 * @endcode
j3 0:b00c4699ae6f 469 **************************************************************/
j3 2:4e6e761c60f2 470 uint16_t get_alarm(ds3231_alrm_t* alarm, bool one_r_two);
j3 0:b00c4699ae6f 471
j3 0:b00c4699ae6f 472
j3 0:b00c4699ae6f 473 /**********************************************************//**
j3 0:b00c4699ae6f 474 * Get control and status registers of DS3231
j3 0:b00c4699ae6f 475 *
j3 0:b00c4699ae6f 476 * On Entry:
j3 2:4e6e761c60f2 477 * @param[in] data - pointer to struct for storing control
j3 4:0beb5e9ac927 478 * and status register data
j3 0:b00c4699ae6f 479 *
j3 0:b00c4699ae6f 480 * On Exit:
j3 0:b00c4699ae6f 481 * @param[out] data - contains control and status registers
j3 0:b00c4699ae6f 482 * data
j3 0:b00c4699ae6f 483 * @return return value = 0 on success, non-0 on failure
j3 0:b00c4699ae6f 484 *
j3 0:b00c4699ae6f 485 * Example:
j3 0:b00c4699ae6f 486 * @code
j3 0:b00c4699ae6f 487 *
j3 0:b00c4699ae6f 488 * //instantiate rtc object
j3 1:c814af60fdbf 489 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 490 *
j3 0:b00c4699ae6f 491 * //do not use 0xAA, see datasheet for appropriate data
j3 0:b00c4699ae6f 492 * ds3231_cntl_stat_t data = {0xAA, 0xAA};
j3 0:b00c4699ae6f 493 *
j3 3:312589d8185c 494 * rtn_val = rtc.get_cntl_stat_reg(&data);
j3 0:b00c4699ae6f 495 *
j3 0:b00c4699ae6f 496 * @endcode
j3 0:b00c4699ae6f 497 **************************************************************/
j3 2:4e6e761c60f2 498 uint16_t get_cntl_stat_reg(ds3231_cntl_stat_t* data);
j3 0:b00c4699ae6f 499
j3 0:b00c4699ae6f 500
j3 0:b00c4699ae6f 501 /**********************************************************//**
j3 0:b00c4699ae6f 502 * Get temperature data of DS3231
j3 0:b00c4699ae6f 503 *
j3 0:b00c4699ae6f 504 * On Entry:
j3 0:b00c4699ae6f 505 *
j3 0:b00c4699ae6f 506 * On Exit:
j3 2:4e6e761c60f2 507 * @return return value = raw temperature data
j3 0:b00c4699ae6f 508 *
j3 0:b00c4699ae6f 509 * Example:
j3 0:b00c4699ae6f 510 * @code
j3 0:b00c4699ae6f 511 *
j3 0:b00c4699ae6f 512 * //instantiate rtc object
j3 1:c814af60fdbf 513 * Ds3231 rtc(D14, D15);
j3 0:b00c4699ae6f 514 *
j3 0:b00c4699ae6f 515 * uint16_t temp;
j3 0:b00c4699ae6f 516 *
j3 2:4e6e761c60f2 517 * temp = rtc.get_temperature();
j3 0:b00c4699ae6f 518 *
j3 0:b00c4699ae6f 519 * @endcode
j3 0:b00c4699ae6f 520 **************************************************************/
j3 2:4e6e761c60f2 521 uint16_t get_temperature(void);
j3 0:b00c4699ae6f 522
j3 5:61dfe2690360 523
j3 5:61dfe2690360 524 /**********************************************************//**
j3 5:61dfe2690360 525 * Get epoch time based on current RTC time and date.
j3 5:61dfe2690360 526 * DS3231 must be configured and running before this fx is
j3 5:61dfe2690360 527 * called
j3 5:61dfe2690360 528 *
j3 5:61dfe2690360 529 * On Entry:
j3 5:61dfe2690360 530 *
j3 5:61dfe2690360 531 * On Exit:
j3 5:61dfe2690360 532 * @return return value = epoch time
j3 5:61dfe2690360 533 *
j3 5:61dfe2690360 534 * Example:
j3 5:61dfe2690360 535 * @code
j3 5:61dfe2690360 536 *
j3 5:61dfe2690360 537 * //instantiate rtc object
j3 5:61dfe2690360 538 * Ds3231 rtc(D14, D15);
j3 5:61dfe2690360 539 *
j3 5:61dfe2690360 540 * time_t epoch_time;
j3 5:61dfe2690360 541 *
j3 5:61dfe2690360 542 * epoch_time = rtc.get_epoch();
j3 5:61dfe2690360 543 *
j3 5:61dfe2690360 544 * @endcode
j3 5:61dfe2690360 545 **************************************************************/
j3 5:61dfe2690360 546 time_t get_epoch(void);
j3 5:61dfe2690360 547
j3 0:b00c4699ae6f 548 };
j3 0:b00c4699ae6f 549 #endif /* DS3231_H*/