MCP79410RK
Public Member Functions | Static Public Attributes | Protected Attributes | Static Protected Attributes | Friends
MCP79410 Class Reference

Class for managing the MCP79410 real-time clock chip with SRAM and EEPROM. More...

#include <MCP79410RK.h>

Public Member Functions

 MCP79410 (TwoWire &wire=Wire)
 Constructor for MCP79410 objects. More...
 
virtual ~MCP79410 ()
 Destructor. Not typically deleted as it's normally instantiated as a global variable.
 
MCP79410withTimeSyncMode (uint8_t timeSyncMode)
 Sets the time synchronization mode. More...
 
MCP79410withBatteryEnable (bool value)
 Sets the battery enable mode. More...
 
void setup ()
 setup call, call during setup()
 
void loop ()
 loop call, call on every time through loop()
 
bool setRTCFromCloud ()
 Set the RTC from the cloud time (if valid) More...
 
bool setRTCTime (time_t unixTime)
 Set the RTC to a specific unixTime. More...
 
bool isRTCValid () const
 Returns true if the RTC time is believed to be valid.
 
time_t getRTCTime () const
 Get the RTC time as a Unix time value. More...
 
bool getRTCTime (MCP79410Time &time) const
 Get the RTC time as a MCP79410Time object. More...
 
bool getPowerDownTime (MCP79410Time &time) const
 Get the power down time. More...
 
bool getPowerUpTime (MCP79410Time &time) const
 Get the power up time. More...
 
bool getPowerFail () const
 Get the power failure bit. If there are stored power up and down times, this will be true.
 
void clearPowerFail ()
 Clear the power failure times. More...
 
bool getOscillatorRunning () const
 Returns true of the oscillator is running. More...
 
bool getBatteryEnable () const
 Get the battery enable flag. More...
 
bool setBatteryEnable (bool value=true)
 Set the battery enable state. More...
 
bool clearAlarm (int alarmNum=0)
 Clear the alarm (remove the setting and turn it off) More...
 
bool setAlarm (const MCP79410Time &time, bool polarity=true, int alarmNum=0)
 Set an alarm. More...
 
bool setAlarm (int secondsFromNow, bool polarity=true, int alarmNum=0)
 Set an alarm. More...
 
bool getInterrupt (int alarmNum=0)
 Returns true if the given alarmNum is in alarm state. More...
 
void clearInterrupt (int alarmNum=0)
 Clears the interrupt for the given alarm. More...
 
uint8_t getAlarmEnableBit (int alarmNum)
 Returns true if the given alarm is currently enabled. More...
 
uint8_t getAlarmRegister (int alarmNum, int offset=0)
 Function to get the register base address for a given alarm. More...
 
MCP79410SRAMsram ()
 Gets the object to access the SRAM.
 
MCP79410EEPROMeeprom ()
 Gets the object to access the EEPROM.
 
bool setSquareWaveMode (uint8_t freq)
 Enters square wave output mode on MFP. More...
 
bool clearSquareWaveMode ()
 Leaves square wave output mode on MFP, allowing alarms to be set again.
 
bool setOscTrim (int8_t trim)
 Sets the oscillator trim value. More...
 
int deviceReadTime (uint8_t addr, MCP79410Time &time, int timeMode) const
 Read a time value (RTC time, alarm time, or power failure or restore time) More...
 
int deviceWriteRTCTime (uint8_t addr, const MCP79410Time &time)
 Write RTC time. More...
 
uint8_t deviceReadRegisterByte (uint8_t addr) const
 Read a register byte. More...
 
int deviceWriteRegisterByte (uint8_t addr, uint8_t value)
 Write a register byte. More...
 
int deviceWriteRegisterFlag (uint8_t addr, uint8_t value, bool set)
 Set or clear a register flag bit. More...
 
int deviceWriteRegisterByteMask (uint8_t addr, uint8_t andMask, uint8_t orMask)
 Write to a register using bit masks. More...
 
int deviceRead (uint8_t i2cAddr, uint8_t addr, uint8_t *buf, size_t bufLen) const
 Reads from either registers or an EEPROM register. More...
 
int deviceWrite (uint8_t i2cAddr, uint8_t addr, const uint8_t *buf, size_t bufLen)
 Writes to either registers or an EEPROM register. More...
 
int deviceWriteEEPROM (uint8_t addr, const uint8_t *buf, size_t bufLen)
 Write to EEPROM. More...
 
void waitForEEPROM ()
 Function to wait for an EEPROM write to complete. More...
 
bool eepromProtectedBlockWrite (const uint8_t *buf)
 Write to the 8-byte protected block in EEPROM. More...
 

Static Public Attributes

static const uint8_t TIME_SYNC_NONE = 0b00
 No automatic time synchronization.
 
static const uint8_t TIME_SYNC_CLOUD_TO_RTC = 0b01
 RTC is set from cloud time at startup.
 
static const uint8_t TIME_SYNC_RTC_TO_TIME = 0b10
 Time object is set from RTC at startup (if RTC appears valid)
 
static const uint8_t TIME_SYNC_AUTOMATIC = 0b11
 Time is synchronized in both directions (the default value)
 
static const uint8_t EEPROM_PROTECTED_BLOCK_SIZE = 8
 EEPROM protected block size in bytes.
 
static const uint8_t EEPROM_PROTECT_NONE = 0x0
 EEPROM write protection disabled.
 
static const uint8_t EEPROM_PROTECT_UPPER_QUARTER = 0x1
 EEPROM write protection protects addresses 0x60 to 0x7f from writing.
 
static const uint8_t EEPROM_PROTECT_UPPER_HALF = 0x2
 EEPROM write protection protects addresses 0x40 to 0x7f from writing.
 
static const uint8_t EEPROM_PROTECT_ALL = 0x3
 EEPROM write protection fully enabled.
 
static const uint8_t SQUARE_WAVE_1_HZ = 0x0
 Set the square wave output frequency on the MFP to 1 Hz. This is affected by digital trimming.
 
static const uint8_t SQUARE_WAVE_4096_HZ = 0x1
 Set the square wave output frequency on the MFP to 4.096 kHz (4096 Hz). This is affected by digital trimming.
 
static const uint8_t SQUARE_WAVE_8192_HZ = 0x2
 Set the square wave output frequency on the MFP to 8.192 kHz (8192 Hz). This is affected by digital trimming.
 
static const uint8_t SQUARE_WAVE_32768_HZ = 0x3
 Set the square wave output frequency on the MFP to 32.767 kHz. This is the direct crystal output and not affected by trimming.
 
static const uint8_t SQUARE_WAVE_MASK = 0x3
 All of the bits used for square wave output frequency.
 
static const int TIME_MODE_RTC = 0
 Mode for deviceReadTime when reading the RTC.
 
static const int TIME_MODE_ALARM = 1
 Mode for deviceReadTime when reading the alarm times.
 
static const int TIME_MODE_POWER = 2
 Mode for deviceReadTime when reading the power failure times.
 

Protected Attributes

TwoWire & wire
 The I2C interface to use. Typically Wire (the default) but could be Wire1 on some devices.
 
bool setupDone = false
 True after rtc.setup() has been called.
 
bool timeSet = false
 True after the RTC has been set from cloud time the first time.
 
bool batteryEnable = true
 True if the battery should be enabled.
 
uint8_t timeSyncMode = TIME_SYNC_AUTOMATIC
 Time synchronization mode. Default is automatic.
 
MCP79410SRAM sramObj
 Object to access the SRAM (static non-volatile RAM). Use the public sram() method to access it.
 
MCP79410EEPROM eepromObj
 Object to access the EEPROM. Use the public eeprom() method to access it.
 

Static Protected Attributes

static const uint8_t REG_I2C_ADDR = 0b1101111
 I2C address (0x6f) for reading and writing the registers and SRAM.
 
static const uint8_t REG_DATE_TIME = 0x00
 Start of date and time register.
 
static const uint8_t REG_DATE_RTCSEC = 0x00
 Second value and oscillator start/stop bit.
 
static const uint8_t REG_DATE_RTCSEC_ST = 0x80
 Oscillator start/stop bit (1 = run, 0 = stop)
 
static const uint8_t REG_RTCWKDAY = 0x03
 Day of week and status bits register.
 
static const uint8_t REG_RTCWKDAY_OSCRUN = 0x20
 Bit for oscillator currently running (1 = running)
 
static const uint8_t REG_RTCWKDAY_PWRFAIL = 0x10
 Bit for power failure set (1 = values are set)
 
static const uint8_t REG_RTCWKDAY_VBATEN = 0x08
 Bit for battery enabled (1 = battery enabled)
 
static const uint8_t REG_CONTROL = 0x07
 Control register.
 
static const uint8_t REG_CONTROL_SQWEN = 0x40
 Square wave enabled (used for calibration)
 
static const uint8_t REG_CONTROL_ALM1EN = 0x20
 Alarm 1 enabled.
 
static const uint8_t REG_CONTROL_ALM0EN = 0x10
 Alarm 0 enabled.
 
static const uint8_t REG_OSCTRIM = 0x08
 Oscillator trim register.
 
static const uint8_t REG_EE_UNLOCK = 0x09
 EEPROM protected block unlock register.
 
static const uint8_t REG_ALARM0 = 0x0a
 Start of alarm 0 regiseters.
 
static const uint8_t REG_ALARM1 = 0x11
 Start of alarm 1 regiseters.
 
static const uint8_t REG_ALARM_WKDAY_OFFSET = 3
 Offset of alarm WKDAY register, relative to REG_ALARM0 or REG_ALARM1. Actual address 0x0d, 0x14.
 
static const uint8_t REG_ALARM_WKDAY_ALMPOL = 0x80
 Bit for alarm polarity.
 
static const uint8_t REG_ALARM_WKDAY_ALMIF = 0x08
 Alarm interrupt flag (1 = alarm triggered).
 
static const uint8_t REG_POWER_DOWN = 0x18
 Time of last power down register.
 
static const uint8_t REG_POWER_UP = 0x1c
 Time of last power up register.
 
static const uint8_t REG_SRAM = 0x20
 Beginning of SRAM data (64 bytes)
 
static const uint8_t EEPROM_I2C_ADDR = 0b1010111
 I2C address (0x57) for reading and writing the EEPROM.
 
static const uint8_t EEPROM_PROTECTED = 0xf0
 Beginning of the 8-byte protected area of the EEPROM.
 
static const uint8_t EEPROM_STATUS = 0xff
 Bits to write protect the main EEPROM.
 

Friends

class MCP79410SRAM
 
class MCP79410EEPROM
 

Detailed Description

Class for managing the MCP79410 real-time clock chip with SRAM and EEPROM.

You typically instantiate one of these as a global variable in your program.

#include "MCP79410RK.h"
void setup() {
rtc.setup();
}
void loop() {
rtc.loop();
}

Constructor & Destructor Documentation

◆ MCP79410()

MCP79410::MCP79410 ( TwoWire &  wire = Wire)

Constructor for MCP79410 objects.

Parameters
wireThe I2C interface to use. Optional, default is Wire. On some devices you can use Wire1.

Member Function Documentation

◆ clearAlarm()

bool MCP79410::clearAlarm ( int  alarmNum = 0)

Clear the alarm (remove the setting and turn it off)

Parameters
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.

◆ clearInterrupt()

void MCP79410::clearInterrupt ( int  alarmNum = 0)

Clears the interrupt for the given alarm.

Parameters
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.

You must clear the alarm using clearInterrupt() or it won't fire again!

◆ clearPowerFail()

void MCP79410::clearPowerFail ( )

Clear the power failure times.

This will clear the times returned for getPowerUpTime() and getPowerDownTime() and allow new times to be stored. If you don't call this, the old times will be preserved, even if there is another power failure.

◆ deviceRead()

int MCP79410::deviceRead ( uint8_t  i2cAddr,
uint8_t  addr,
uint8_t *  buf,
size_t  bufLen 
) const

Reads from either registers or an EEPROM register.

Parameters
i2cAddrThe I2C address, either MCP79410::REG_I2C_ADDR or MCP79410::EEPROM_I2C_ADDR.
addrThe address in the block. For REG_I2C_ADDR a register address or a SRAM address.
bufThe buffer to read data into
bufLenThe length of data to read. Do not read past the end

◆ deviceReadRegisterByte()

uint8_t MCP79410::deviceReadRegisterByte ( uint8_t  addr) const

Read a register byte.

Parameters
addrthe register address to read from. For example MCP79410::REG_RTCWKDAY.

This can only be used for registers, not for EEPROM.

◆ deviceReadTime()

int MCP79410::deviceReadTime ( uint8_t  addr,
MCP79410Time time,
int  timeMode 
) const

Read a time value (RTC time, alarm time, or power failure or restore time)

Parameters
addrThe address to read from
timeA reference to a MCP79410Time to save the data to
timeModethe format of the time at that address, one of the constant below:
Constant Value
MCP79410::TIME_MODE_RTC 0 Mode for deviceReadTime when reading the RTC
MCP79410::TIME_MODE_ALARM 1 Mode for deviceReadTime when reading the alarm times
MCP79410::TIME_MODE_POWER 2 Mode for deviceReadTime when reading the power failure times

◆ deviceWrite()

int MCP79410::deviceWrite ( uint8_t  i2cAddr,
uint8_t  addr,
const uint8_t *  buf,
size_t  bufLen 
)

Writes to either registers or an EEPROM register.

Parameters
i2cAddrThe I2C address, either MCP79410::REG_I2C_ADDR or MCP79410::EEPROM_I2C_ADDR.
addrThe address in the block. For REG_I2C_ADDR a register address or a SRAM address.
bufThe buffer to write
bufLenThe length of data to write. Do not write past the end

You should not use this for writing EEPROM data. Use deviceWriteEEPROM() instead.

◆ deviceWriteEEPROM()

int MCP79410::deviceWriteEEPROM ( uint8_t  addr,
const uint8_t *  buf,
size_t  bufLen 
)

Write to EEPROM.

Parameters
addrThe address 0 <= addr <= 0x7f
bufThe buffer to write
bufLenThe length of data to write. Do not write past the end; (addr + bufLen) < 0x80 must be true.

This is a separate function from deviceWrite because writing bulk EEPROM data requires special handling. The number of bytes you can write at once is limited, and you need to check for completion before continuing.

◆ deviceWriteRegisterByte()

int MCP79410::deviceWriteRegisterByte ( uint8_t  addr,
uint8_t  value 
)

Write a register byte.

Parameters
addrthe register address to write to. For example MCP79410::REG_RTCWKDAY.
valuethe value to set

This can only be used for registers, not for EEPROM. To set certain bits (read then write), use deviceWriteRegisterFlag() or deviceWriteRegisterByteMask() instead.

◆ deviceWriteRegisterByteMask()

int MCP79410::deviceWriteRegisterByteMask ( uint8_t  addr,
uint8_t  andMask,
uint8_t  orMask 
)

Write to a register using bit masks.

Parameters
addrthe register address to read/write to. For example MCP79410::REG_RTCWKDAY.
andMaskLogically ANDed to the contents of the register (1st step)
orMaskLogically ORed to the content of the register (2nd step)

To clear a flag you'd pass a bitwise negation of the flag it in the andMask. For example: ~ MCP79410::REG_RTCWKDAY_VBATEN in andMask. Note the bitwise negation ~. And 0 in orMask.

To set a flag you'd pass the 0xff in andMask and the flag in orMask (for example, MCP79410::REG_RTCWKDAY_VBATEN).

However you'd normally use deviceWriteRegisterFlag() which generates the masks for you instead.

◆ deviceWriteRegisterFlag()

int MCP79410::deviceWriteRegisterFlag ( uint8_t  addr,
uint8_t  value,
bool  set 
)

Set or clear a register flag bit.

Parameters
addrthe register address to read/write to. For example MCP79410::REG_RTCWKDAY.
valueThe value. Typically this is a single bit set, for example MCP79410::REG_RTCWKDAY_VBATEN = 0x08 to set or clear the MCP79410::REG_RTCWKDAY_VBATEN in the MCP79410::REG_RTCWKDAY register.
setTrue to set the flag, false to clear the flag.

This is a convenience method built over deviceWriteRegisterByteMask() to make it easier to set or clear flag bits.

◆ deviceWriteRTCTime()

int MCP79410::deviceWriteRTCTime ( uint8_t  addr,
const MCP79410Time time 
)

Write RTC time.

Sets the current time in the real-time clock. time should specify a time value at UTC. Normally you'd use setRTCFromCloud() or setRTCTime() instead. Those functions eventually call this.

◆ eepromProtectedBlockWrite()

bool MCP79410::eepromProtectedBlockWrite ( const uint8_t *  buf)
inline

Write to the 8-byte protected block in EEPROM.

Note the 8-byte protected block is different than the block protection mode for the main 128 byte EEPROM!

This is normally disabled, to minimize the chance of writing the protected block.

This is typically used to store things like MAC addresses, though I think it would be a great place to put board identification information.

The constant MCP79410::EEPROM_PROTECTED_BLOCK_SIZE is the value 8 so you don't have to hardcode it.

You must #define MCP79410_ENABLE_PROTECTED_WRITE before including MCP79410RK.h in order to enable use of this function.

◆ getAlarmEnableBit()

uint8_t MCP79410::getAlarmEnableBit ( int  alarmNum)
inline

Returns true if the given alarm is currently enabled.

Parameters
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.

To enable an alarm, use setAlarm(). To disable an alarm, use clearAlarm().

◆ getAlarmRegister()

uint8_t MCP79410::getAlarmRegister ( int  alarmNum,
int  offset = 0 
)
inline

Function to get the register base address for a given alarm.

Parameters
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.
offset0 to get the base, or a constant like MCP79410::REG_ALARM_WKDAY_OFFSET (3).
Returns
Returns either MCP79410::REG_ALARM0 or MCP79410::REG_ALARM1 plus the given offset

◆ getBatteryEnable()

bool MCP79410::getBatteryEnable ( ) const

Get the battery enable flag.

This is false when the RTC is started it up the first time. However, once you sync time from the cloud the first time, the battery will be enabled unless you explicitly setBatteryEnable(false).

◆ getInterrupt()

bool MCP79410::getInterrupt ( int  alarmNum = 0)

Returns true if the given alarmNum is in alarm state.

Parameters
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.

When using both alarms this is how you determine which one has gone off. You must clear the alarm using clearInterrupt() or it won't fire again!

◆ getOscillatorRunning()

bool MCP79410::getOscillatorRunning ( ) const

Returns true of the oscillator is running.

The oscillator is off after a cold boot from no battery, no 3V3 power. It will stay off until you set the time (manually or from the cloud time).

As long as the CR1220 battery power is applied, the oscillator will continue to run.

To determine if the clock time is valid you should use isRTCValid() which checks both the oscillator and the year.

◆ getPowerDownTime()

bool MCP79410::getPowerDownTime ( MCP79410Time time) const

Get the power down time.

This isn't as useful as you'd think. The time does not include a second or year. Only the first power failure is stored until reset using clearPowerFail(). Also, setting the RTC time (as we tend to do upon connecting to the cloud), resets the power fail times.

If you still want to use the power failure times, read them right after calling rtc.setup().

◆ getPowerUpTime()

bool MCP79410::getPowerUpTime ( MCP79410Time time) const

Get the power up time.

This isn't as useful as you'd think. The time does not include a second or year. Only the first power failure is stored until reset using clearPowerFail(). Also, setting the RTC time (as we tend to do upon connecting to the cloud), resets the power fail times.

If you still want to use the power failure times, read them right after calling rtc.setup().

◆ getRTCTime() [1/2]

time_t MCP79410::getRTCTime ( ) const

Get the RTC time as a Unix time value.

The Unix time, seconds from January 1, 1970, at UTC. This has the same semantics as Time.now().

◆ getRTCTime() [2/2]

bool MCP79410::getRTCTime ( MCP79410Time time) const

Get the RTC time as a MCP79410Time object.

This is handy if you want to get the second, hour, minute, dayOfMonth, etc..

◆ setAlarm() [1/2]

bool MCP79410::setAlarm ( const MCP79410Time time,
bool  polarity = true,
int  alarmNum = 0 
)

Set an alarm.

Parameters
timeA MCP79410Time object for when the alarm should go off. This can be a specific time or a repeating time but you must have set it using one of the methods like setAlarmSecond(), setAlarmMinute(), ..., setAlarmTime().
polarityPass true (the default) for compatibility with D8 to wake from SLEEP_MODE_DEEP. false = active low, falling to wake. true = active high, rising to wake.
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.
Returns
true on success. This call will fail and return false if the RTC has not been set or alarmNum is not valid.

◆ setAlarm() [2/2]

bool MCP79410::setAlarm ( int  secondsFromNow,
bool  polarity = true,
int  alarmNum = 0 
)

Set an alarm.

Parameters
secondsFromNowThe number of seconds from now the alarm should go off. This is typically what you do to emulate the behavior of SLEEP_MODE_DEEP.
polarityPass true (the default) for compatibility with D8 to wake from SLEEP_MODE_DEEP. false = active low, falling to wake. true = active high, rising to wake.
alarmNumDefault is 0 if this parameter is omitted. Otherwise, must be 0 or 1.
Returns
true on success. This call will fail and return false if the RTC has not been set or alarmNum is not valid.

◆ setBatteryEnable()

bool MCP79410::setBatteryEnable ( bool  value = true)

Set the battery enable state.

Normally the battery is enabled, but if you're using the RTC without a battery you can set this to false. The RTC will still work, as long as you have 3V3 power. Since 3V3 is still supplied in SLEEP_MODE_DEEP this is not unreasonable.

◆ setOscTrim()

bool MCP79410::setOscTrim ( int8_t  trim)

Sets the oscillator trim value.

Parameters
trimA signed 8-bit integer: -127 to +127.

◆ setRTCFromCloud()

bool MCP79410::setRTCFromCloud ( )

Set the RTC from the cloud time (if valid)

You normally don't need to do this, as it's done automatically from loop().

◆ setRTCTime()

bool MCP79410::setRTCTime ( time_t  unixTime)

Set the RTC to a specific unixTime.

Parameters
unixTimeThe Unix time to set to (seconds from January 1, 1970, at UTC).

You can pass the value returned from Time.now() into this function.

◆ setSquareWaveMode()

bool MCP79410::setSquareWaveMode ( uint8_t  freq)

Enters square wave output mode on MFP.

Parameters
freqFrequency, one of the constants below
Constant Value Description Trimming
MCP79410::SQUARE_WAVE_1_HZ 0x0 Set the square wave output frequency on the MFP to 1 Hz Yes
MCP79410::SQUARE_WAVE_4096_HZ 0x1 Set the square wave output frequency on the MFP to 4.096 kHz (4096 Hz) Yes
MCP79410::SQUARE_WAVE_8192_HZ 0x2 Set the square wave output frequency on the MFP to 8.192 kHz (8192 Hz) Yes
MCP79410::SQUARE_WAVE_32768_HZ 0x3 Set the square wave output frequency on the MFP to 32.767 kHz No

Trimming: Yes if affected by digital trimming or false if not.

This mode is typically used to test or calibrate the clock. See section 5.6 (p. 30) in the datasheet. See also examples/6-oscillator-trim.

◆ waitForEEPROM()

void MCP79410::waitForEEPROM ( )

Function to wait for an EEPROM write to complete.

This is used by setBlockProtection() and deviceWriteEEPROM(). It's unlikely that you would ever call it manually.

◆ withBatteryEnable()

MCP79410& MCP79410::withBatteryEnable ( bool  value)
inline

Sets the battery enable mode.

Parameters
valuetrue = enable the ues of the backup battery, false = disable

The default is true so you only normally have to do this if you want to disable. You can call this early, before setup() or at any time to make an immediate change.

The withXXX() syntax allows you to chain multiple options, fluent-style:

◆ withTimeSyncMode()

MCP79410& MCP79410::withTimeSyncMode ( uint8_t  timeSyncMode)

Sets the time synchronization mode.

Constant Value Description
TIME_SYNC_NONE 0b00 No automatic time synchronization
TIME_SYNC_CLOUD_TO_RTC 0b01 RTC is set from cloud time at startup
TIME_SYNC_RTC_TO_TIME 0b10 Time object is set from RTC at startup (if RTC appears valid)
TIME_SYNC_AUTOMATIC 0b11 Time is synchronized in both directions (default value)

The withXXX() syntax allows you to chain multiple options, fluent-style:


The documentation for this class was generated from the following files: