ErriezDS3231.h

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2020 Erriez
 *
 * 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 THE
 * AUTHORS OR COPYRIGHT HOLDERS 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.
 */

#ifndef ERRIEZ_DS3231_H_
#define ERRIEZ_DS3231_H_

#include <stdint.h>
#include <time.h>

#define DS3231_REG_SECONDS      0x00    
#define DS3231_REG_MINUTES      0x01    
#define DS3231_REG_HOURS        0x02    
#define DS3231_REG_DAY_WEEK     0x03    
#define DS3231_REG_DAY_MONTH    0x04    
#define DS3231_REG_MONTH        0x05    
#define DS3231_REG_YEAR         0x06    

#define DS3231_REG_ALARM1_SEC   0x07    
#define DS3231_REG_ALARM1_MIN   0x08    
#define DS3231_REG_ALARM1_HOUR  0x09    
#define DS3231_REG_ALARM1_DD    0x0A    
#define DS3231_REG_ALARM2_MIN   0x0B    
#define DS3231_REG_ALARM2_HOUR  0x0C    
#define DS3231_REG_ALARM2_DD    0x0D    

#define DS3231_REG_CONTROL      0x0E    
#define DS3231_REG_STATUS       0x0F    
#define DS3231_REG_AGING_OFFSET 0x10    
#define DS3231_REG_TEMP_MSB     0x11    
#define DS3231_REG_TEMP_LSB     0x12    

#define DS3231_NUM_REGS         19      

#define DS3231_HOUR_12H_24H     6       
#define DS3231_HOUR_AM_PM       5       

#define DS3231_MONTH_CENTURY    7       

#define DS3231_CTRL_EOSC        7       
#define DS3231_CTRL_BBSQW       6       
#define DS3231_CTRL_CONV        5       
#define DS3231_CTRL_RS2         4       
#define DS3231_CTRL_RS1         3       
#define DS3231_CTRL_INTCN       2       
#define DS3231_CTRL_A2IE        1       
#define DS3231_CTRL_A1IE        0       

#define DS3231_STAT_OSF         7       
#define DS3231_STAT_EN32KHZ     3       
#define DS3231_STAT_BSY         2       
#define DS3231_STAT_A2F         1       
#define DS3231_STAT_A1F         0       

#define DS3231_A1M1             7       
#define DS3231_A1M2             7       
#define DS3231_A1M3             7       
#define DS3231_A1M4             7       
#define DS3231_A2M2             7       
#define DS3231_A2M3             7       
#define DS3231_A2M4             7       
#define DS3231_DYDT             6       

#define DS3231_ADDR             (0xD0 >> 1)

#define SECONDS_FROM_1970_TO_2000 946684800

typedef enum {
    Alarm1 = 1,                 
    Alarm2 = 2                  
} AlarmId;

typedef enum
{
    Alarm1EverySecond = 0x0F,   
    Alarm1MatchSeconds = 0x0E,  
    Alarm1MatchMinutes = 0x0C,  
    Alarm1MatchHours = 0x08,    
    Alarm1MatchDay = 0x10,      
    Alarm1MatchDate = 0x00,     
} Alarm1Type;

typedef enum
{
    Alarm2EveryMinute = 0x0E,   
    Alarm2MatchMinutes = 0x0C,  
    Alarm2MatchHours = 0x08,    
    Alarm2MatchDay = 0x10,      
    Alarm2MatchDate = 0x00,     
} Alarm2Type;

typedef enum {
    SquareWaveDisable = (1 << DS3231_CTRL_INTCN),                           
    SquareWave1Hz = ((0 << DS3231_CTRL_RS2) | (0 << DS3231_CTRL_RS1)),      
    SquareWave1024Hz = ((0 << DS3231_CTRL_RS2) | (1 << DS3231_CTRL_RS1)),   
    SquareWave4096Hz = ((1 << DS3231_CTRL_RS2) | (0 << DS3231_CTRL_RS1)),   
    SquareWave8192Hz = ((1 << DS3231_CTRL_RS2) | (1 << DS3231_CTRL_RS1)),   
} SquareWave;


class ErriezDS3231
{
public:
    // Initialize
    bool begin();

    // Oscillator functions
    bool isRunning();
    bool clockEnable(bool enable=true);

    // Set/get date/time
    time_t getEpoch();
    bool setEpoch(time_t t);
    bool read(struct tm *dt);
    bool write(const struct tm *dt);
    bool setTime(uint8_t hour, uint8_t min, uint8_t sec);
    bool getTime(uint8_t *hour, uint8_t *min, uint8_t *sec);
    bool setDateTime(uint8_t hour, uint8_t min, uint8_t sec,
                     uint8_t mday, uint8_t mon, uint16_t year,
                     uint8_t wday);
    bool getDateTime(uint8_t *hour, uint8_t *min, uint8_t *sec,
                     uint8_t *mday, uint8_t *mon, uint16_t *year,
                     uint8_t *wday);

    // Alarm functions
    bool setAlarm1(Alarm1Type alarmType,
                          uint8_t dayDate, uint8_t hours, uint8_t minutes, uint8_t seconds);
    bool setAlarm2(Alarm2Type alarmType, uint8_t dayDate, uint8_t hours, uint8_t minutes);
    bool alarmInterruptEnable(AlarmId alarmId, bool enable);
    bool getAlarmFlag(AlarmId alarmId);
    bool clearAlarmFlag(AlarmId alarmId);

    // Output signal control
    bool setSquareWave(SquareWave squareWave);
    bool outputClockPinEnable(bool enable);

    // Aging offset compensation
    bool setAgingOffset(int8_t val);
    int8_t getAgingOffset();

    // Temperature functions
    bool startTemperatureConversion();
    bool getTemperature(int8_t *temperature, uint8_t *fraction);

    // BCD conversions
    uint8_t bcdToDec(uint8_t bcd);
    uint8_t decToBcd(uint8_t dec);

    // Read/write register
    uint8_t readRegister(uint8_t reg);
    bool writeRegister(uint8_t reg, uint8_t value);

    // Read/write buffer
    bool readBuffer(uint8_t reg, void *buffer, uint8_t len);
    bool writeBuffer(uint8_t reg, void *buffer, uint8_t len);
};

#endif // ERRIEZ_DS3231_H_