MCP7940.h

Go to the documentation of this file.

// clang-format off
// clang-format on

#include "Arduino.h"  // Arduino data type definitions
#include "Wire.h"     // Standard I2C "Wire" library
#ifndef MCP7940_h

  #define MCP7940_h  // Define the name inside guard code
/***************************************************************************************************
** Declare classes used in within the class                                                       **
***************************************************************************************************/
class TimeSpan;
  /***************************************************************************************************
  ** Declare constants used in the class **
  ***************************************************************************************************/
  #ifndef I2C_MODES  // I2C related constants

    #define I2C_MODES
const uint32_t I2C_STANDARD_MODE{100000};  
const uint32_t I2C_FAST_MODE{400000};      
  #endif
  #if !defined(BUFFER_LENGTH)  // The ESP32 Wire library doesn't currently define BUFFER_LENGTH

    #define BUFFER_LENGTH 32
  #endif

const uint8_t  MCP7940_ADDRESS{0x6F};          
const uint8_t  MCP7940_EUI_ADDRESS{0x57};      
const uint8_t  MCP7940_RTCSEC{0x00};           
const uint8_t  MCP7940_RTCMIN{0x01};           
const uint8_t  MCP7940_RTCHOUR{0x02};          
const uint8_t  MCP7940_RTCWKDAY{0x03};         
const uint8_t  MCP7940_RTCDATE{0x04};          
const uint8_t  MCP7940_RTCMTH{0x05};           
const uint8_t  MCP7940_RTCYEAR{0x06};          
const uint8_t  MCP7940_CONTROL{0x07};          
const uint8_t  MCP7940_OSCTRIM{0x08};          
const uint8_t  MCP7940_EEUNLOCK{0x09};         
const uint8_t  MCP7940_ALM0SEC{0x0A};          
const uint8_t  MCP7940_ALM0MIN{0x0B};          
const uint8_t  MCP7940_ALM0HOUR{0x0C};         
const uint8_t  MCP7940_ALM0WKDAY{0x0D};        
const uint8_t  MCP7940_ALM0DATE{0x0E};         
const uint8_t  MCP7940_ALM0MTH{0x0F};          
const uint8_t  MCP7940_ALM1SEC{0x11};          
const uint8_t  MCP7940_ALM1MIN{0x12};          
const uint8_t  MCP7940_ALM1HOUR{0x13};         
const uint8_t  MCP7940_ALM1WKDAY{0x14};        
const uint8_t  MCP7940_ALM1DATE{0x15};         
const uint8_t  MCP7940_ALM1MTH{0x16};          
const uint8_t  MCP7940_PWRDNMIN{0x18};         
const uint8_t  MCP7940_PWRDNHOUR{0x19};        
const uint8_t  MCP7940_PWRDNDATE{0x1A};        
const uint8_t  MCP7940_PWRDNMTH{0x1B};         
const uint8_t  MCP7940_PWRUPMIN{0x1C};         
const uint8_t  MCP7940_PWRUPHOUR{0x1D};        
const uint8_t  MCP7940_PWRUPDATE{0x1E};        
const uint8_t  MCP7940_PWRUPMTH{0x1F};         
const uint8_t  MCP7940_RAM_ADDRESS{0x20};      
const uint8_t  MCP7940_EUI_RAM_ADDRESS{0xF0};  
const uint8_t  MCP7940_ST{7};                  
const uint8_t  MCP7940_12_24{6};               
const uint8_t  MCP7940_AM_PM{5};               
const uint8_t  MCP7940_OSCRUN{5};              
const uint8_t  MCP7940_PWRFAIL{4};             
const uint8_t  MCP7940_VBATEN{3};              
const uint8_t  MCP7940_LPYR{5};                
const uint8_t  MCP7940_OUT{7};                 
const uint8_t  MCP7940_SQWEN{6};               
const uint8_t  MCP7940_ALM1EN{5};              
const uint8_t  MCP7940_ALM0EN{4};              
const uint8_t  MCP7940_EXTOSC{3};              
const uint8_t  MCP7940_CRSTRIM{2};             
const uint8_t  MCP7940_SQWFS1{1};              
const uint8_t  MCP7940_SQWFS0{0};              
const uint8_t  MCP7940_SIGN{7};                
const uint8_t  MCP7940_ALMPOL{7};              
const uint8_t  MCP7940_ALM0IF{3};              
const uint8_t  MCP7940_ALM1IF{3};              
const uint32_t SECS_1970_TO_2000{946684800};   

class DateTime {
 public:
  DateTime(uint32_t t = SECS_1970_TO_2000);
  DateTime(uint16_t year, uint8_t month, uint8_t day, uint8_t hour = 0, uint8_t min = 0,
           uint8_t sec = 0);
  DateTime(const DateTime& copy);
  DateTime(const char* date, const char* time);
  DateTime(const __FlashStringHelper* date, const __FlashStringHelper* time);
  uint16_t year() const { 
    return 2000U + yOff;
  }
  uint8_t month() const { 
    return m;
  }
  uint8_t day() const { 
    return d;
  }
  uint8_t hour() const { 
    return hh;
  }
  uint8_t minute() const { 
    return mm;
  }
  uint8_t second() const { 
    return ss;
  }
  uint8_t  dayOfTheWeek() const;            
  long     secondstime() const;             
  uint32_t unixtime(void) const;            
  bool     equals(const DateTime* other);   
  DateTime operator+(const TimeSpan& span); 
  DateTime operator-(const TimeSpan& span); 
  TimeSpan operator-(
      const DateTime& right); 
 protected:
  uint8_t yOff;  
  uint8_t m;     
  uint8_t d;     
  uint8_t hh;    
  uint8_t mm;    
  uint8_t ss;    
};               // of class DateTime definition
class TimeSpan {
 public:
  TimeSpan(int32_t seconds = 0);                                         
  TimeSpan(int16_t days, int8_t hours, int8_t minutes, int8_t seconds);  
  TimeSpan(const TimeSpan& copy);                                        
  int16_t  days() const { return _seconds / 86400L; }      
  int8_t   hours() const { return _seconds / 3600 % 24; }  
  int8_t   minutes() const { return _seconds / 60 % 60; }  
  int8_t   seconds() const { return _seconds % 60; }       
  int32_t  totalseconds() const { return _seconds; }       
  TimeSpan operator+(const TimeSpan& right);               
  TimeSpan operator-(const TimeSpan& right);               
 protected:
  int32_t _seconds;  
};                   // of class TimeSpan definition

class MCP7940_Class {
 public:
  MCP7940_Class(){};   
  ~MCP7940_Class(){};  
  bool     begin(const uint32_t i2cSpeed) const;
  bool     begin(const uint8_t sda = SDA, const uint8_t scl = SCL,
                 const uint32_t i2cSpeed = I2C_STANDARD_MODE) const;
  bool     deviceStatus() const;
  bool     deviceStart() const;
  bool     deviceStop() const;
  DateTime now() const;
  void     adjust();
  void     adjust(const DateTime& dt);
  int8_t   calibrate() const;
  int8_t   calibrate(const int8_t newTrim);
  int8_t   calibrate(const DateTime& dt);
  int8_t   calibrate(const float fMeas) const;
  int8_t   getCalibrationTrim() const;
  uint8_t  weekdayRead() const;
  uint8_t  weekdayWrite(const uint8_t dow) const;
  bool     setMFP(const bool value) const;
  uint8_t  getMFP() const;
  bool     setAlarm(const uint8_t alarmNumber, const uint8_t alarmType, const DateTime& dt,
                    const bool state = true) const;
  void     setAlarmPolarity(const bool polarity) const;
  DateTime getAlarm(const uint8_t alarmNumber, uint8_t& alarmType) const;
  bool     clearAlarm(const uint8_t alarmNumber) const;
  bool     setAlarmState(const uint8_t alarmNumber, const bool state) const;
  bool     getAlarmState(const uint8_t alarmNumber) const;
  bool     isAlarm(const uint8_t alarmNumber) const;
  uint8_t  getSQWSpeed() const;
  bool     setSQWSpeed(uint8_t frequency, bool state = true) const;
  bool     setSQWState(const bool state) const;
  bool     getSQWState() const;
  bool     setBattery(const bool state) const;
  bool     getBattery() const;
  bool     getPowerFail() const;
  bool     clearPowerFail() const;
  DateTime getPowerDown() const;
  DateTime getPowerUp() const;
  int8_t   calibrateOrAdjust(const DateTime& dt);
  int32_t  getPPMDeviation(const DateTime& dt) const;
  void     setSetUnixTime(uint32_t aTime);
  uint32_t getSetUnixTime() const;

  /*************************************************************************************************
  ** Template functions definitions are done in the header file                                   **
  ** ============================================================================================ **
  ** readRAM   read any number of bytes from the MCP7940 SRAM area                                **
  ** writRAM   write any number of bytes to the MCP7940 SRAM area                                 **
  ** readEUI   read any number of bytes from the special protected SRAM area for 79400/401/402    **
  *************************************************************************************************/
  template <typename T>
  uint8_t readRAM(const uint8_t& addr, T& value) const {
    return I2C_read((addr % 64) + MCP7940_RAM_ADDRESS, value);
  }  // of method readRAM()
  template <typename T>
  uint8_t writeRAM(const uint8_t& addr, const T& value) const {
    uint8_t i = I2C_write((addr % 64) + MCP7940_RAM_ADDRESS, value);
    return i;
  }  // of method writeRAM()
  template <typename T>
  uint8_t readEUI(const uint8_t& addr, T& value) const {
    uint8_t i{0};                                        // return number of bytes read
    Wire.beginTransmission(MCP7940_EUI_ADDRESS);         // Address the special I2C address
    Wire.write((addr % 8) + MCP7940_EUI_RAM_ADDRESS);    // Send register address to read from
    if (Wire.endTransmission() == 0) {                   // Close transmission and check error code
      Wire.requestFrom(MCP7940_EUI_ADDRESS, sizeof(T));  // Request a block of data, max 61 bits
      uint8_t* bytePtr = (uint8_t*)&value;               // Declare pointer to start of structure
      for (i = 0; i < sizeof(T); i++) {                  // Loop for each byte to be read
        *bytePtr++ = Wire.read();                        // Read a byte
      }                                                  // of for-next each byte
    }                                                    // if-then success
    return i;                                            // return number of bytes read
  }                                                      // of method readEUI()
  template <typename T>
  uint8_t writeEUI(const uint8_t& addr, T& value) const {
    uint8_t i{0};                                      // return number of bytes read
    Wire.beginTransmission(MCP7940_EUI_ADDRESS);       // Address the special I2C address
    Wire.write(MCP7940_EEUNLOCK);                      // Send special register address to write to
    Wire.write(0x55);                                  // Special write value to start unlock
    i = Wire.endTransmission();                        // close transmission of first byte
    Wire.beginTransmission(MCP7940_EUI_ADDRESS);       // Address the special I2C address
    Wire.write(MCP7940_EEUNLOCK);                      // Send special register address to write to
    Wire.write(0x55);                                  // Special write value to complete unlock
    i = Wire.endTransmission();                        // close transmission of second byte
    Wire.beginTransmission(MCP7940_EUI_ADDRESS);       // Address the special I2C address
    Wire.write((addr % 8) + MCP7940_EUI_RAM_ADDRESS);  // Send register address to read from
    Wire.write((uint8_t*)&value, sizeof(T));           // write the data
    i = Wire.endTransmission();                        // close transmission of actual write
    if (i == 0) i = sizeof(T);                         // return number of bytes on success
    return i;                                          // return number of bytes read
  }                                                    // of method writeEUI()

 private:
  uint32_t _SetUnixTime{0};  
  /*************************************************************************************************
  ** Template functions definitions are done in the header file                                   **
  ** ============================================================================================ **
  **                                                                                              **
  ** I2C_read  read any number of bytes from the MCP7940                                          **
  ** I2C_write write any number of bytes to the MCP7940                                           **
  *************************************************************************************************/
  template <typename T>
  uint8_t I2C_read(const uint8_t address, T& value) const {
    uint8_t i{0};                                    // return number of bytes read
    Wire.beginTransmission(MCP7940_ADDRESS);         // Address the I2C device
    Wire.write(address);                             // Send register address to read from
    if (Wire.endTransmission() == 0) {               // Close transmission and check error code
      Wire.requestFrom(MCP7940_ADDRESS, sizeof(T));  // Request a block of data
      uint8_t* bytePtr = (uint8_t*)&value;           // Declare pointer to start of structure
      for (i = 0; i < sizeof(T); i++) {              // Loop for each byte to be read
        *bytePtr++ = Wire.read();                    // Read a byte
      }                                              // of for-next each byte
    }                                                // if-then success
    return i;                                        // return number of bytes read
  }                                                  // end of template method "I2C_read"
  template <typename T>
  uint8_t I2C_write(const uint8_t address, const T& value) const {
    Wire.beginTransmission(MCP7940_ADDRESS);   // Address the I2C device
    Wire.write(address);                       // Send register address to read from
    Wire.write((uint8_t*)&value, sizeof(T));   // write the data
    uint8_t i = Wire.endTransmission();        // close transmission and save status
    if (i == 0) i = sizeof(T);                 // return number of bytes on success
    return i;                                  // return the number of bytes written
  }                                            // end of template method "I2C_write()"
  uint8_t readByte(const uint8_t addr) const;  // Read 1 byte from address on I2C
  uint8_t bcd2int(const uint8_t bcd) const;    // convert BCD digits to integer
  uint8_t int2bcd(const uint8_t dec) const;    // convert integer to BCD
  void    clearRegisterBit(const uint8_t reg, const uint8_t b) const;  // Clear a bit, values 0-7
  void    setRegisterBit(const uint8_t reg, const uint8_t b) const;    // Set   a bit, values 0-7
  void    writeRegisterBit(const uint8_t reg, const uint8_t b,
                           bool bitvalue) const;                      // Clear a bit, values 0-7
  uint8_t readRegisterBit(const uint8_t reg, const uint8_t b) const;  // Read  a bit, values 0-7
};                                                                    // of MCP7940 class definition
#endif