Declan Gordon
j
Fork of
ds3231
by 
Maxim Integrated
Diff: ds3231.h
- Revision:
- 0:b00c4699ae6f
- Child:
- 1:c814af60fdbf
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ds3231.h Tue Nov 18 22:28:04 2014 +0000
@@ -0,0 +1,449 @@
+/******************************************************************//**
+* @file ds3231.h
+*
+* @author Justin Jordan
+*
+* @version 0.0
+*
+* Started: 11NOV14
+*
+* Updated:
+*
+* @brief Header file for DS3231 class
+*
+***********************************************************************
+*
+* @copyright
+* Copyright (C) 2013 Maxim Integrated Products, Inc., All Rights Reserved.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a
+* copy of this software and associated documentation files (the "Software"),
+* to deal in the Software without restriction, including without limitation
+* the rights to use, copy, modify, merge, publish, distribute, sublicense,
+* and/or sell copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included
+* in all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+* IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
+* OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+* OTHER DEALINGS IN THE SOFTWARE.
+*
+* Except as contained in this notice, the name of Maxim Integrated
+* Products, Inc. shall not be used except as stated in the Maxim Integrated
+* Products, Inc. Branding Policy.
+*
+* The mere transfer of this software does not imply any licenses
+* of trade secrets, proprietary technology, copyrights, patents,
+* trademarks, maskwork rights, or any other form of intellectual
+* property whatsoever. Maxim Integrated Products, Inc. retains all
+* ownership rights.
+**********************************************************************/
+
+
+#ifndef DS3231_H
+#define DS3231_H
+
+
+#include "mbed.h"
+
+
+#define DS3231_I2C_ADRS 0x68 //7bit, shift left 1 and 'OR' with R/W bit
+#define I2C_WRITE 0
+#define I2C_READ 1
+
+#define AM_PM (1 << 5)
+#define TIME_FORMAT (1 << 6)
+#define DY_DT (1 << 6)
+
+//control register bit masks
+#define A1IE (1 << 0)
+#define A2IE (1 << 1)
+#define INTCN (1 << 2)
+#define RS1 (1 << 3)
+#define RS2 (1 << 4)
+#define CONV (1 << 5)
+#define BBSQW (1 << 6)
+#define EOSC (1 << 7)
+
+//status register bit masks
+#define A1F (1 << 0)
+#define A2F (1 << 1)
+#define BSY (1 << 2)
+#define EN32KHZ (1 << 3)
+#define OSF (1 << 7)
+
+
+typedef enum
+{
+ SECONDS,
+ MINUTES,
+ HOURS,
+ DAY,
+ DATE,
+ MONTH,
+ YEAR,
+ ALRM1_SECONDS,
+ ALRM1_MINUTES,
+ ALRM1_HOURS,
+ ALRM1_DAY_DATE,
+ ALRM2_MINUTES,
+ ALRM2_HOURS,
+ ALRM2_DAY_DATE,
+ CONTROL,
+ STATUS,
+ AGING_OFFSET, //don't touch this register
+ MSB_TEMP,
+ LSB_TEMP
+}ds3231_regs_t;
+
+
+typedef struct
+{
+ uint8_t seconds;
+ uint8_t minutes;
+ uint8_t hours;
+}ds3231_time_t;
+
+
+typedef struct
+{
+ uint8_t day;
+ uint8_t date;
+ uint8_t month;
+ uint8_t year;
+}ds3231_calendar_t;
+
+
+typedef struct
+{
+ uint8_t seconds; //not used for alarm2
+ uint8_t minutes;
+ uint8_t hours;
+ uint8_t day;
+ uint8_t date;
+}ds3231_alrm_t;
+
+
+typedef struct
+{
+ uint8_t control;
+ uint8_t status;
+}ds3231_cntl_stat_t;
+
+
+/******************************************************************//**
+* Ds3231 Class
+**********************************************************************/
+class Ds3231
+{
+ //private members
+ I2C* p_i2c;
+ uint8_t w_adrs, r_adrs;
+
+ public:
+ /**********************************************************//**
+ * Constructor for Ds3231 Class
+ *
+ * On Entry:
+ * @param[in] p_i2c - pointer to I2C object for bus
+ *
+ * On Exit:
+ * @return none
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * @endcode
+ **************************************************************/
+ Ds3231(I2C* ptr_i2c_bus);
+
+
+ /**********************************************************//**
+ * Sets the time on DS3231
+ *
+ * On Entry:
+ * @param[in] time - struct cotaining time data;
+ * seconds, minutes and hours
+ *
+ * On Exit:
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * ds3231_time_t time = {0, 0, 0} // time = 0:0:0 24hr format
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.set_time(time);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t set_time(ds3231_time_t time);
+
+
+ /**********************************************************//**
+ * Sets the calendar on DS3231
+ *
+ * On Entry:
+ * @param[in] calendar - struct cotaining calendar data;
+ * day, date, month, year
+ *
+ * On Exit:
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //see datasheet for calendar format
+ * ds3231_calendar_t calendar = {1, 1, 1, 0};
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.set_calendar(calendar);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t set_calendar(ds3231_calendar_t calendar);
+
+
+ /**********************************************************//**
+ * Set either Alarm1 or Alarm2 of DS3231
+ *
+ * On Entry:
+ * @param[in] alarm - struct cotaining alarm data
+ * seconds, minutes, hours, day, date
+ * seconds used on Alarm1 only
+ * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
+ * Alarm2
+ *
+ * On Exit:
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //see datasheet for alarm format
+ * ds3231_alrm_t alarm = {0, 0, 0, 0, 0};
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.set_alarm(alarm, FALSE);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t set_alarm(ds3231_alrm_t alarm, bool one_r_two);
+
+
+ /**********************************************************//**
+ * Set control and status registers of DS3231
+ *
+ * On Entry:
+ * @param[in] data - Struct containing control and status
+ * register data
+ *
+ * On Exit:
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //do not use 0xAA, see datasheet for appropriate data
+ * ds3231_cntl_stat_t data = {0xAA, 0xAA};
+ *
+ * rtn_val = rtc.set_cntl_stat_reg(data);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t set_cntl_stat_reg(ds3231_cntl_stat_t data);
+
+
+ /**********************************************************//**
+ * Gets the time on DS3231
+ *
+ * On Entry:
+ * @param[in] time - struct for storing time data;
+ * seconds, minutes and hours
+ *
+ * On Exit:
+ * @param[out] time - contains current rtc time data
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * ds3231_time_t time = {0, 0, 0} // time = 0:0:0 24hr format
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.get_time(time);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t get_time(ds3231_time_t time);
+
+
+ /**********************************************************//**
+ * Gets the calendar on DS3231
+ *
+ * On Entry:
+ * @param[in] calendar - struct for storing calendar data;
+ * day, date, month, year
+ *
+ * On Exit:
+ * @param[out] calendar - contains current rtc calendar
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //see datasheet for calendar format
+ * ds3231_calendar_t calendar = {1, 1, 1, 0};
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.get_calendar(calendar);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t get_calendar(ds3231_calendar_t calendar);
+
+
+ /**********************************************************//**
+ * Get either Alarm1 or Alarm2 of DS3231
+ *
+ * On Entry:
+ * @param[in] alarm - struct for storing alarm data
+ * seconds, minutes, hours, day, date
+ * seconds used on Alarm1 only
+ * @param[in] one_r_two - TRUE for Alarm1 and FALSE for
+ * Alarm2
+ *
+ * On Exit:
+ * @param[out] alarm - contains alarm register data
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //see datasheet for alarm format
+ * ds3231_alrm_t alarm = {0, 0, 0, 0, 0};
+ * uint16_t rtn_val;
+ *
+ * rtn_val = rtc.get_alarm(alarm, FALSE);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t get_alarm(ds3231_alrm_t alarm, bool one_r_two);
+
+
+ /**********************************************************//**
+ * Get control and status registers of DS3231
+ *
+ * On Entry:
+ * @param[in] data - Struct for storing control and status
+ * register data
+ *
+ * On Exit:
+ * @param[out] data - contains control and status registers
+ * data
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //do not use 0xAA, see datasheet for appropriate data
+ * ds3231_cntl_stat_t data = {0xAA, 0xAA};
+ *
+ * rtn_val = rtc.get_cntl_stat_reg(data);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t get_cntl_stat_reg(ds3231_cntl_stat_t data);
+
+
+ /**********************************************************//**
+ * Get temperature data of DS3231
+ *
+ * On Entry:
+ * @param[in] temp - Integer for storing temperature data
+ *
+ * On Exit:
+ * @param[out] temp - contains temperature data
+ * @return return value = 0 on success, non-0 on failure
+ *
+ * Example:
+ * @code
+ *
+ * I2C i2c_bus(D14, D15); //instantiate I2C bus
+ * I2C * p_i2c_bus = &i2c_bus; //create pointer to bus
+ *
+ * //instantiate rtc object
+ * Ds3231 rtc(p_i2c_bus);
+ *
+ * //do not use 0xAA, see datasheet for appropriate data
+ * uint16_t temp;
+ *
+ * rtn_val = rtc.get_temperature(data);
+ *
+ * @endcode
+ **************************************************************/
+ uint16_t get_temperature(uint16_t temp);
+
+};
+#endif /* DS3231_H*/