MCP79410RK
|
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. | |
MCP79410 & | withTimeSyncMode (uint8_t timeSyncMode) |
Sets the time synchronization mode. More... | |
MCP79410 & | withBatteryEnable (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... | |
MCP79410SRAM & | sram () |
Gets the object to access the SRAM. | |
MCP79410EEPROM & | eeprom () |
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 |
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.
MCP79410::MCP79410 | ( | TwoWire & | wire = Wire | ) |
Constructor for MCP79410 objects.
wire | The I2C interface to use. Optional, default is Wire. On some devices you can use Wire1. |
bool MCP79410::clearAlarm | ( | int | alarmNum = 0 | ) |
Clear the alarm (remove the setting and turn it off)
alarmNum | Default is 0 if this parameter is omitted. Otherwise, must be 0 or 1. |
void MCP79410::clearInterrupt | ( | int | alarmNum = 0 | ) |
Clears the interrupt for the given alarm.
alarmNum | Default 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!
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.
int MCP79410::deviceRead | ( | uint8_t | i2cAddr, |
uint8_t | addr, | ||
uint8_t * | buf, | ||
size_t | bufLen | ||
) | const |
Reads from either registers or an EEPROM register.
i2cAddr | The I2C address, either MCP79410::REG_I2C_ADDR or MCP79410::EEPROM_I2C_ADDR. |
addr | The address in the block. For REG_I2C_ADDR a register address or a SRAM address. |
buf | The buffer to read data into |
bufLen | The length of data to read. Do not read past the end |
uint8_t MCP79410::deviceReadRegisterByte | ( | uint8_t | addr | ) | const |
Read a register byte.
addr | the register address to read from. For example MCP79410::REG_RTCWKDAY. |
This can only be used for registers, not for EEPROM.
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)
addr | The address to read from |
time | A reference to a MCP79410Time to save the data to |
timeMode | the 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 |
int MCP79410::deviceWrite | ( | uint8_t | i2cAddr, |
uint8_t | addr, | ||
const uint8_t * | buf, | ||
size_t | bufLen | ||
) |
Writes to either registers or an EEPROM register.
i2cAddr | The I2C address, either MCP79410::REG_I2C_ADDR or MCP79410::EEPROM_I2C_ADDR. |
addr | The address in the block. For REG_I2C_ADDR a register address or a SRAM address. |
buf | The buffer to write |
bufLen | The length of data to write. Do not write past the end |
You should not use this for writing EEPROM data. Use deviceWriteEEPROM() instead.
int MCP79410::deviceWriteEEPROM | ( | uint8_t | addr, |
const uint8_t * | buf, | ||
size_t | bufLen | ||
) |
Write to EEPROM.
addr | The address 0 <= addr <= 0x7f |
buf | The buffer to write |
bufLen | The 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.
int MCP79410::deviceWriteRegisterByte | ( | uint8_t | addr, |
uint8_t | value | ||
) |
Write a register byte.
addr | the register address to write to. For example MCP79410::REG_RTCWKDAY. |
value | the 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.
int MCP79410::deviceWriteRegisterByteMask | ( | uint8_t | addr, |
uint8_t | andMask, | ||
uint8_t | orMask | ||
) |
Write to a register using bit masks.
addr | the register address to read/write to. For example MCP79410::REG_RTCWKDAY. |
andMask | Logically ANDed to the contents of the register (1st step) |
orMask | Logically 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.
int MCP79410::deviceWriteRegisterFlag | ( | uint8_t | addr, |
uint8_t | value, | ||
bool | set | ||
) |
Set or clear a register flag bit.
addr | the register address to read/write to. For example MCP79410::REG_RTCWKDAY. |
value | The 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. |
set | True 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.
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.
|
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.
|
inline |
Returns true if the given alarm is currently enabled.
alarmNum | Default 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().
|
inline |
Function to get the register base address for a given alarm.
alarmNum | Default is 0 if this parameter is omitted. Otherwise, must be 0 or 1. |
offset | 0 to get the base, or a constant like MCP79410::REG_ALARM_WKDAY_OFFSET (3). |
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)
.
bool MCP79410::getInterrupt | ( | int | alarmNum = 0 | ) |
Returns true if the given alarmNum is in alarm state.
alarmNum | Default 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!
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.
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().
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().
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().
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..
bool MCP79410::setAlarm | ( | const MCP79410Time & | time, |
bool | polarity = true , |
||
int | alarmNum = 0 |
||
) |
Set an alarm.
time | A 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(). |
polarity | Pass 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. |
alarmNum | Default is 0 if this parameter is omitted. Otherwise, must be 0 or 1. |
bool MCP79410::setAlarm | ( | int | secondsFromNow, |
bool | polarity = true , |
||
int | alarmNum = 0 |
||
) |
Set an alarm.
secondsFromNow | The number of seconds from now the alarm should go off. This is typically what you do to emulate the behavior of SLEEP_MODE_DEEP. |
polarity | Pass 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. |
alarmNum | Default is 0 if this parameter is omitted. Otherwise, must be 0 or 1. |
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.
bool MCP79410::setOscTrim | ( | int8_t | trim | ) |
Sets the oscillator trim value.
trim | A signed 8-bit integer: -127 to +127. |
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().
bool MCP79410::setRTCTime | ( | time_t | unixTime | ) |
Set the RTC to a specific unixTime.
unixTime | The Unix time to set to (seconds from January 1, 1970, at UTC). |
You can pass the value returned from Time.now() into this function.
bool MCP79410::setSquareWaveMode | ( | uint8_t | freq | ) |
Enters square wave output mode on MFP.
freq | Frequency, 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.
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.
|
inline |
Sets the battery enable mode.
value | true = 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:
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: