Main class definition with forward declarations. More...

Public Member Functions
	~MCP7940_Class ()
	Unused Class constructor.

bool	begin (const uint32_t i2cSpeed) const
	Unused Class destructor. More...

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<typename T >
uint8_t	readRAM (const uint8_t &addr, T &value) const

template<typename T >
uint8_t	writeRAM (const uint8_t &addr, const T &value) const

template<typename T >
uint8_t	readEUI (const uint8_t &addr, T &value) const

template<typename T >
uint8_t	writeEUI (const uint8_t &addr, T &value) const

Detailed Description

Main class definition with forward declarations.

Member Function Documentation

◆ adjust() [1/2]

void MCP7940_Class::adjust ( )

sets the current date/time (overloaded)

This is an overloaded function. With no parameters then the RTC is set to the date/time when the program was compiled. Since different core version handle these compiler variables differently, the values are copied to temporary strings and then passed to the adjust() function

◆ adjust() [2/2]

void MCP7940_Class::adjust ( const DateTime & dt )

sets the current date/time (overloaded)

This is an overloaded function. Set to the DateTime class instance value. The oscillator is stopped during the process and is restarted upon completion.

◆ begin() [1/2]

bool MCP7940_Class::begin ( const uint32_t i2cSpeed ) const

Unused Class destructor.

Start I2C device communications

Starts I2C comms with the device, using a default speed if one is not specified

Parameters

[in] i2cSpeed defaults to I2C_STANDARD_MODE, otherwise use speed in Herz

Returns: true if successfully started communication, otherwise false

◆ begin() [2/2]

bool MCP7940_Class::begin	(	const uint8_t	sda = `SDA`,
		const uint8_t	scl = `SCL`,
		const uint32_t	i2cSpeed = `I2C_STANDARD_MODE`
	)		const

Start I2C device communications

Starts I2C comms with the device, using default SDA and SCL ports as well as speed if they are not specified

Parameters

[in]	sda	defaults to PIN_WIRE_SDA, otherwise use pin (ignored if not ESP8266)
[in]	scl	defaults to PIN_WIRE_SCL, otherwise use pin (ignored if not ESP8266)
[in]	i2cSpeed	defaults to I2C_STANDARD_MODE, otherwise use speed in Herz

Returns: true if successfully started communication, otherwise false

◆ calibrate() [1/4]

int8_t MCP7940_Class::calibrate ( ) const

Calibrate the MCP7940 (overloaded)

When called with no parameters the internal calibration is reset to 0

Returns: Always returns 0

◆ calibrate() [2/4]

int8_t MCP7940_Class::calibrate ( const int8_t newTrim )

Calibrate the MCP7940 (overloaded)

When called with one int8 parameter that value is used as the new trim value

Parameters

[in] newTrim New signed integer value to use for the trim register

Returns: Returns the input "newTrim" value

◆ calibrate() [3/4]

int8_t MCP7940_Class::calibrate ( const DateTime & dt )

Calibrate the MCP7940 (overloaded)

When called with a DateTime class value then an internal calibration is performed. Accepts a current date/time value and compares that to the current date/time of the RTC and computes a calibration factor depending upon the time difference between the two and how long the timespan between the two is. The longer the period between setting the clock and comparing the difference between real time and indicated time the better the resulting calibration accuracy will be. The datasheet explains the calibration formula on page 28. First, the error in parts-per-million is computed using PPM = (SecDev/ExpectedSeconds) * 10000000. Then the trim register is computed using the formula TRIMVAL = (PPM*32768*60)/(1000000*2). The code below is designed for easy reading, not for performance. The ppm <> 130 is computed by solving the equation for the maximum TRIM value of 127 and computing the corresponding max and min values for ppm. This allows the trim variable to be one byte rather than a long integer.

Parameters

[in] dt Actual Date/time

Returns: Returns the new calculated trim value

◆ calibrate() [4/4]

int8_t MCP7940_Class::calibrate ( const float fMeas ) const

Calibrate the MCP7940 (overloaded)

When called with one floating point value then that is used as the measured frequency

Parameters

[in] fMeas Measured frequency in Herz

Returns: Returns the new trim value

◆ calibrateOrAdjust()

int8_t MCP7940_Class::calibrateOrAdjust ( const DateTime & dt )

Calibrate the MCP7940 if the ppm deviation is < 130 and > -130 else Adjust the datetime.

If the time had changed significantly (like happens during daylight savings time) then just adjust the time to be the new time and leave the trim value alone. One hour deviation in 6 months is 225 ppm. If the ppm deviation is within -130 to 130 then assume we are just calibrating the clock.

Parameters

[in] dt Actual Date/time

Returns: Returns the trim value

◆ clearAlarm()

bool MCP7940_Class::clearAlarm ( const uint8_t alarmNumber ) const

Clears the given alarm

Parameters

[in] alarmNumber Alarm number 0 or 1

Returns: False if the alarmNumber is out of range, otherwise true

◆ clearPowerFail()

bool MCP7940_Class::clearPowerFail ( ) const

Clears the power failure status flag

Returns: Always returns true

◆ deviceStart()

bool MCP7940_Class::deviceStart ( ) const

Start the MCP7940 device

Sets the status register to turn on the device clock

Returns: Success status true if successful otherwise false

◆ deviceStatus()

bool MCP7940_Class::deviceStatus ( ) const

checks to see if the MCP7940 crystal has been turned on or off Sets the status register to turn on the device clock

Returns: Success status true if the crystal is on, otherwise false if off

◆ deviceStop()

bool MCP7940_Class::deviceStop ( ) const

Stop the MCP7940 device

Sets the status register to turn off the device clock

Returns: true if the oscillator is still running, otherwise 0 if the oscillator has stopped

◆ getAlarm()

DateTime MCP7940_Class::getAlarm	(	const uint8_t	alarmNumber,
		uint8_t &	alarmType
	)		const

Gets the DateTime for the given alarm

update the alarmType parameter with the alarm type that was set

Parameters

[in]	alarmNumber	Alarm number 0 or 1
[out]	alarmType	See detailed description for list of alarm types 0-7

Returns: DateTime value of alarm

◆ getAlarmState()

bool MCP7940_Class::getAlarmState ( const uint8_t alarmNumber ) const

Return whether a given alarm is on or off

Parameters

[in] alarmNumber Alarm number 0 or 1

Returns: False if the alarmNumber is out of range or off, otherwise true

◆ getBattery()

bool MCP7940_Class::getBattery ( ) const

Return the battery backup state

Has no effect on the MCP7940M, only on the MCP7940N

Returns: boolean state of the battery backup mode. "true" for on and "false" for off

◆ getCalibrationTrim()

int8_t MCP7940_Class::getCalibrationTrim ( ) const

Return the TRIMVAL trim value

Since the number in the register can be negative but is not in excess-128 format any negative numbers need to be manipulated before returning

Returns: Returns the current trim value

◆ getMFP()

uint8_t MCP7940_Class::getMFP ( ) const

Gets the MFP (Multifunction Pin) value

On is true and Off is false. This is read from the control register if no alarms are enabled, otherwise the two alarm states must be checked.

Returns: Returns one of the following values;
0 = pin set LOW.
1 = pin set HIGH.
2 = pin controlled by alarms.
3 = pin controlled by square wave output.

◆ getPowerDown()

DateTime MCP7940_Class::getPowerDown ( ) const

returns the date/time that the power went off

This is set back to zero once the power fail flag is reset.

Returns: DateTime class value for the current Date/Time

◆ getPowerFail()

bool MCP7940_Class::getPowerFail ( ) const

Return the power failure status

Returns: boolean state of the power failure status. "true" if a power failure has occured, otherwise "false"

◆ getPowerUp()

DateTime MCP7940_Class::getPowerUp ( ) const

returns the date/time that the power went back on

Returns: DateTime class value for the power-on Date/Time

◆ getPPMDeviation()

int32_t MCP7940_Class::getPPMDeviation ( const DateTime & dt ) const

Calculate the ppm deviation since the last time the clock was set

The internal _SetUniTime value is set when the clock is set. On this call the current time is converted to unitime and compared with the stored value to determine the part-per-million difference. One hour deviation in 6 months is 225 ppm

Parameters

[in] dt Actual Date/time

Returns: difference in ppm

◆ getSetUnixTime()

uint32_t MCP7940_Class::getSetUnixTime ( ) const

Get the time the clock was last calibrated or adjusted.

Returns the internal variable _SetUnixTime. This is the time the clock was last calibrated or adjusted. This should only used to testing.

Returns: Returns the internal variable _SetUnixTime.

◆ getSQWSpeed()

uint8_t MCP7940_Class::getSQWSpeed ( ) const

returns the list value for the frequency of the square wave

Returns: Integer value index for the square wave frequency:
0 = 1Hz
1 = 4.096KHz
2 = 8.192KHz
3 32.768KHz
If square wave is not turned on then a 0 is returned

◆ getSQWState()

bool MCP7940_Class::getSQWState ( ) const

Get the square wave generator state

Returns: boolean state of the square wave, "true" for on and "false" for off

◆ isAlarm()

bool MCP7940_Class::isAlarm ( const uint8_t alarmNumber ) const

Return whether a given alarm is active or not

Parameters

[in] alarmNumber Alarm number 0 or 1

Returns: False if the alarmNumber is out of range or off, otherwise true

◆ now()

DateTime MCP7940_Class::now ( ) const

returns the current date/time

If the device is stopped then the stop time is returned

Returns: DateTime class value for the current Date/Time

◆ readEUI()

template<typename T >

uint8_t MCP7940_Class::readEUI	(	const uint8_t &	addr,
		T &	value
	)		const

inline

Template for readEUI()

As a template it can support compile-time data type definitions. This is a special call as it access a different I2C address and a different memory block

Parameters

[in]	addr	Memory address
[in]	value	Data Type "T" to read

Returns: Pointer to return data structure

◆ readRAM()

template<typename T >

uint8_t MCP7940_Class::readRAM	(	const uint8_t &	addr,
		T &	value
	)		const

inline

Template for readRAM()

As a template it can support compile-time data type definitions

Parameters

[in]	addr	Memory address
[in]	value	Data Type "T" to read

Returns: Pointer to return data structure

◆ setAlarm()

bool MCP7940_Class::setAlarm	(	const uint8_t	alarmNumber,
		const uint8_t	alarmType,
		const DateTime &	dt,
		const bool	state = `true`
	)		const

Sets one of the 2 alarms

In order to configure the alarm modules, the following steps need to be performed in order:

Load the timekeeping registers and enable the oscillator
Configure the ALMxMSK<2:0> bits to select the desired alarm mask
Set or clear the ALMPOL bit according to the desired output polarity
Ensure the ALMxIF flag is cleared
Based on the selected alarm mask, load the alarm match value into the appropriate register(s)

Enable the alarm module by setting the ALMxEN bit
There are two ALMPOL bits - one in the ALM0WKDAY register which can be written, one in the ALM1WKDAY register which is read-only and reflects the value of the ALMPOL in ALM0WKDAY.

Parameters

[in]	alarmNumber	Alarm 0 or Alarm 1
[in]	alarmType	Alarm type from 0 to 7, see detailed description
[in]	dt	DateTime alarm value used to set the alarm
[in]	state	Alarm state to set to (0 for "off" and 1 for "on")

Returns: Returns true for success otherwise false

◆ setAlarmPolarity()

void MCP7940_Class::setAlarmPolarity ( const bool polarity ) const

Sets the alarm polarity

Alarm polarity (see also TABLE 5-10 on p.27 of the datasheet). Note: the MFP pin is open collector, it needs an external pull-up resistor.
If only one alarm is set:
polarity = 0: MFP high when no alarm, low when alarm.
polarity = 1: MFP low when no alarm, high when alarm.

If both alarms are set:
polarity = 0: MFP high when no alarm or one alarm, low when both alarms go off.
polarity = 1: MFP low when no alarm, high when eihter or both alarms go off.

In most situations you will want to set polarity to 1 if you have two alarms set, to be able to see when an alarm goes off using the MFP pin.

Parameters

[in] polarity Boolean value to for polarity

◆ setAlarmState()

bool MCP7940_Class::setAlarmState	(	const uint8_t	alarmNumber,
		const bool	state
	)		const

Turns an alarm on or off without changing the alarm condition

Parameters

[in]	alarmNumber	Alarm number 0 or 1
[in]	state	State to the set the alarm to

Returns: False if the alarmNumber is out of range, otherwise true

◆ setBattery()

bool MCP7940_Class::setBattery ( const bool state ) const

Enable or disable the battery backup

Has no effect on the MCP7940M, only on the MCP7940N

Parameters

[in] state True for "on", False for "off"

Returns: boolean state of the battery backup. "true" for on and "false" for off

◆ setMFP()

bool MCP7940_Class::setMFP ( const bool value ) const

Sets the MFP (Multifunction Pin) to the requested state

Returns: Returns true on success otherwise false

◆ setSetUnixTime()

void MCP7940_Class::setSetUnixTime ( uint32_t aTime )

Set the time the clock was last calibrated or adjusted.

Set the internal variable _SetUnixTime. This is the time the clock was last calibrated or adjusted. This should only used to testing.

Parameters

[in] aTime is the Unix time to set the time the clock was last calibrated or adjusted to.

Returns: void

◆ setSQWSpeed()

bool MCP7940_Class::setSQWSpeed	(	uint8_t	frequency,
		bool	state = `true`
	)		const

set the square wave speed to a value

Parameters

[in]	frequency	Integer value index for the square wave frequency: 0 = 1Hz 1 = 4.096KHz 2 = 8.192KHz 3 = 32.768KHz 4 = 64Hz
[in]	state	Boolean value set to false if square wave is to be turned off, otherwise true

Returns: boolean state of the square wave

◆ setSQWState()

bool MCP7940_Class::setSQWState ( const bool state ) const

set the square wave generator on or off

Parameters

[in] state Boolean value set to false if square wave is to be turned off, otherwise true

Returns: boolean state of the square wave

◆ weekdayRead()

uint8_t MCP7940_Class::weekdayRead ( ) const

return the weekday number from the RTC

This number is user-settable and is incremented when the day shifts. It is set as part of the adjust() method where Monday is weekday 1

Returns: Values 1-7 for the current weekday

◆ weekdayWrite()

uint8_t MCP7940_Class::weekdayWrite ( const uint8_t dow ) const

set the RTC weekday number

This number is user-settable and is incremented when the day shifts. The library uses 1 for Monday and 7 for Sunday

Parameters

[in] dow Day of week (1-7)

Returns: Values 1-7 for the day set, returns MCP7940 value if "dow" is out of range

◆ writeEUI()

template<typename T >

uint8_t MCP7940_Class::writeEUI	(	const uint8_t &	addr,
		T &	value
	)		const

inline

Template for writeEUI()

As a template it can support compile-time data type definitions. This is a special call as it access a different I2C address and a different memory block and also has to unlock the area prior to writing

Parameters

[in]	addr	Memory address
[in]	value	Data Type "T" to read

Returns: Pointer to data structure to write

◆ writeRAM()

template<typename T >

uint8_t MCP7940_Class::writeRAM	(	const uint8_t &	addr,
		const T &	value
	)		const

inline

Template for writeRAM()

As a template it can support compile-time data type definitions

Parameters

[in]	addr	Memory address
[in]	value	Data Type "T" to write

Returns: True if successful, otherwise false

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

src/MCP7940.h
src/MCP7940.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ adjust() [1/2]

◆ adjust() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ calibrate() [1/4]

◆ calibrate() [2/4]

◆ calibrate() [3/4]

◆ calibrate() [4/4]

◆ calibrateOrAdjust()

◆ clearAlarm()

◆ clearPowerFail()

◆ deviceStart()

◆ deviceStatus()

◆ deviceStop()

◆ getAlarm()

◆ getAlarmState()

◆ getBattery()

◆ getCalibrationTrim()

◆ getMFP()

◆ getPowerDown()

◆ getPowerFail()

◆ getPowerUp()

◆ getPPMDeviation()

◆ getSetUnixTime()

◆ getSQWSpeed()

◆ getSQWState()

◆ isAlarm()

◆ now()

◆ readEUI()

◆ readRAM()

◆ setAlarm()

◆ setAlarmPolarity()

◆ setAlarmState()

◆ setBattery()

◆ setMFP()

◆ setSetUnixTime()

◆ setSQWSpeed()

◆ setSQWState()

◆ weekdayRead()

◆ weekdayWrite()

◆ writeEUI()

◆ writeRAM()