DS3231 RTC class. More...

#include <ErriezDS3231.h>

Public Member Functions
bool	begin ()
	Initialize and detect DS3231 RTC. More...

bool	isRunning ()
	Read RTC OSF (Oscillator Stop Flag) from status register. More...

bool	clockEnable (bool enable=true)
	Enable or disable oscillator when running on V-BAT. More...

time_t	getEpoch ()
	Read Unix UTC epoch time_t. More...

bool	setEpoch (time_t t)
	Write Unix epoch UTC time to RTC. More...

bool	read (struct tm *dt)
	Read date and time from RTC. More...

bool	write (const struct tm *dt)
	Write date and time to RTC. More...

bool	setTime (uint8_t hour, uint8_t min, uint8_t sec)
	Write time to RTC. More...

bool	getTime (uint8_t hour, uint8_t min, uint8_t *sec)
	Read time from RTC. More...

bool	setDateTime (uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t wday)
	Set date time. More...

bool	getDateTime (uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t *wday)
	Get date time. More...

bool	setAlarm1 (Alarm1Type alarmType, uint8_t dayDate, uint8_t hours, uint8_t minutes, uint8_t seconds)
	Set Alarm 1. More...

bool	setAlarm2 (Alarm2Type alarmType, uint8_t dayDate, uint8_t hours, uint8_t minutes)
	Set Alarm 2. More...

bool	alarmInterruptEnable (AlarmId alarmId, bool enable)
	Enable or disable Alarm 1 or 2 interrupt. More...

bool	getAlarmFlag (AlarmId alarmId)
	Get Alarm 1 or 2 flag. More...

bool	clearAlarmFlag (AlarmId alarmId)
	Clear alarm flag. More...

bool	setSquareWave (SquareWave squareWave)
	Configure SQW (Square Wave) output pin. More...

bool	outputClockPinEnable (bool enable)
	Enable or disable 32kHz output clock pin. More...

bool	setAgingOffset (int8_t val)
	Set aging offset register. More...

int8_t	getAgingOffset ()
	Get aging offset register. More...

bool	startTemperatureConversion ()
	Start temperature conversion. More...

bool	getTemperature (int8_t temperature, uint8_t fraction)
	Read temperature. More...

uint8_t	bcdToDec (uint8_t bcd)
	BCD to decimal conversion. More...

uint8_t	decToBcd (uint8_t dec)
	Decimal to BCD conversion. More...

uint8_t	readRegister (uint8_t reg)
	Read register. More...

bool	writeRegister (uint8_t reg, uint8_t value)
	Write register. More...

bool	readBuffer (uint8_t reg, void *buffer, uint8_t len)
	Read buffer from RTC. More...

bool	writeBuffer (uint8_t reg, void *buffer, uint8_t len)
	Write buffer to RTC. More...

Detailed Description

DS3231 RTC class.

Definition at line 149 of file ErriezDS3231.h.

Member Function Documentation

◆ alarmInterruptEnable()

bool ErriezDS3231::alarmInterruptEnable	(	AlarmId	alarmId,
		bool	enable
	)

Enable or disable Alarm 1 or 2 interrupt.

Enabling the alarm interrupt will disable the Square Wave output on the INT/SQW pin. The INT pin remains high until an alarm match occurs.

Parameters

alarmId	Alarm1 or Alarm2 enum.
enable	true: Enable alarm interrupt. false: Disable alarm interrupt.

Return values

true	Success
false	Alarm interrupt enable failed.

Definition at line 534 of file ErriezDS3231.cpp.

◆ bcdToDec()

uint8_t ErriezDS3231::bcdToDec ( uint8_t bcd )

BCD to decimal conversion.

Parameters

bcd	BCD encoded value.

Returns: Decimal value.

Definition at line 799 of file ErriezDS3231.cpp.

◆ begin()

bool ErriezDS3231::begin ( )

Initialize and detect DS3231 RTC.

Call this function from setup().

Return values

true	RTC detected.
false	RTC not detected.

Definition at line 52 of file ErriezDS3231.cpp.

◆ clearAlarmFlag()

bool ErriezDS3231::clearAlarmFlag ( AlarmId alarmId )

Clear alarm flag.

This function should be called when the alarm flag has been handled in polling and interrupt mode. The INT pin changes to high when both alarm flags are cleared and alarm interrupts are enabled.

Parameters

alarmId Alarm1 or Alarm2 enum.

Return values

true	Success
false	Incorrect alarm ID.

Definition at line 596 of file ErriezDS3231.cpp.

◆ clockEnable()

bool ErriezDS3231::clockEnable ( bool enable = true )

Enable or disable oscillator when running on V-BAT.

Parameters

enable true: Enable RTC clock when running on V-BAT.
false: Stop RTC clock when running on V-BAT. Oscillator Stop Flag (OSF) bit will be set in status register which can be read on next power-on.

Return values

true	Success.
false	Oscillator enable failed.

Definition at line 74 of file ErriezDS3231.cpp.

◆ decToBcd()

uint8_t ErriezDS3231::decToBcd ( uint8_t dec )

Decimal to BCD conversion.

Parameters

dec	Decimal value.

Returns: BCD encoded value.

Definition at line 811 of file ErriezDS3231.cpp.

◆ getAgingOffset()

int8_t ErriezDS3231::getAgingOffset ( )

Get aging offset register.

The aging offset register capacitance value is added or subtracted from the capacitance value that the device calculates for each temperature compensation.

Returns: val Aging offset value.

Definition at line 714 of file ErriezDS3231.cpp.

◆ getAlarmFlag()

bool ErriezDS3231::getAlarmFlag ( AlarmId alarmId )

Get Alarm 1 or 2 flag.

Call this function to retrieve the alarm status flag. This function can be used in polling as well as with interrupts enabled.

The INT pin changes to low when an Alarm 1 or Alarm 2 match occurs and the interrupt is enabled. The pin remains low until both alarm flags are cleared by the application.

Parameters

alarmId Alarm1 or Alarm2 enum.

Return values

true	Alarm interrupt flag set.
false	Alarm interrupt flag cleared.

Definition at line 573 of file ErriezDS3231.cpp.

◆ getDateTime()

bool ErriezDS3231::getDateTime	(	uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec,
		uint8_t *	mday,
		uint8_t *	mon,
		uint16_t *	year,
		uint8_t *	wday
	)

Get date time.

Parameters

hour	Hours 0..23
min	Minutes 0..59
sec	Seconds 0..59
mday	Day of the month 1..31
mon	Month 1..12 (1=January)
year	Year 2000..2099
wday	Day of the week 0..6 (0=Sunday, .. 6=Saturday)

Return values

true	Success.
false	Get date/time failed.

Definition at line 394 of file ErriezDS3231.cpp.

◆ getEpoch()

time_t ErriezDS3231::getEpoch ( )

Read Unix UTC epoch time_t.

Returns: Unix epoch time_t seconds since 1970.

Definition at line 127 of file ErriezDS3231.cpp.

◆ getTemperature()

bool ErriezDS3231::getTemperature	(	int8_t *	temperature,
		uint8_t *	fraction
	)

Read temperature.

Parameters

temperature	8-bit signed temperature in degree Celsius.
fraction	Temperature fraction in steps of 0.25 degree Celsius. The returned value is a decimal value to prevent floating point usage. The application should divided the fraction by 100.

Return values

true	Success
false	Set get temperature failed.

Definition at line 769 of file ErriezDS3231.cpp.

◆ getTime()

bool ErriezDS3231::getTime	(	uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec
	)

Read time from RTC.

Read hour, minute and second registers from RTC.

Parameters

hour	Hours 0..23.
min	Minutes 0..59.
sec	Seconds 0..59.

Return values

true	Success.
false	Invalid second, minute or hour read from RTC. The time is set to zero.

Definition at line 306 of file ErriezDS3231.cpp.

◆ isRunning()

bool ErriezDS3231::isRunning ( )

Read RTC OSF (Oscillator Stop Flag) from status register.

The application is responsible for checking the Oscillator Stop Flag (OSF) before reading date/time date. This function may be used to judge the validity of the date/time registers.

Return values

true	RTC clock is running.
false	RTC oscillator was stopped: The date/time data is invalid. The application should synchronize and program a new date/time.

Definition at line 110 of file ErriezDS3231.cpp.

◆ outputClockPinEnable()

bool ErriezDS3231::outputClockPinEnable ( bool enable )

Enable or disable 32kHz output clock pin.

Parameters

enable true: Enable 32kHz output clock pin.
false: Disable 32kHz output clock pin.

Return values

true	Success
false	Set output clock pin failed.

Definition at line 653 of file ErriezDS3231.cpp.

◆ read()

bool ErriezDS3231::read ( struct tm * dt )

Read date and time from RTC.

Read all RTC registers at once to prevent a time/date register change in the middle of the register read operation.

Parameters

dt	Date and time struct tm.

Return values

true	Success
false	Read failed.

Definition at line 187 of file ErriezDS3231.cpp.

◆ readBuffer()

bool ErriezDS3231::readBuffer	(	uint8_t	reg,
		void *	buffer,
		uint8_t	readLen
	)

Read buffer from RTC.

Parameters

reg	RTC register number 0x00..0x12.
buffer	Buffer.
readLen	Buffer length. Reading is only allowed within valid RTC registers.

Return values

true	Success
false	I2C read failed.

Definition at line 897 of file ErriezDS3231.cpp.

◆ readRegister()

uint8_t ErriezDS3231::readRegister ( uint8_t reg )

Read register.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x12.

Returns: value 8-bit unsigned register value.

Definition at line 825 of file ErriezDS3231.cpp.

◆ setAgingOffset()

bool ErriezDS3231::setAgingOffset ( int8_t val )

Set aging offset register.

The aging offset register capacitance value is added or subtracted from the capacitance value that the device calculates for each temperature compensation.

Parameters

val	Aging offset value -127..127, 0.1ppm per LSB (Factory default value: 0). Negative values increases the RTC oscillator frequency.

Return values

true	Success
false	Set aging offset failed.

Definition at line 684 of file ErriezDS3231.cpp.

◆ setAlarm1()

bool ErriezDS3231::setAlarm1	(	Alarm1Type	alarmType,
		uint8_t	dayDate,
		uint8_t	hours,
		uint8_t	minutes,
		uint8_t	seconds
	)

Set Alarm 1.

Alarm 1 contains several alarm modes which can be configured with the alarmType parameter. Unused matches can be set to zero. The alarm interrupt must be enabled after setting the alarm, followed by clearing the alarm interrupt flag.

Parameters

alarmType	Alarm 1 types: Alarm1EverySecond Alarm1MatchSeconds Alarm1MatchMinutes Alarm1MatchHours Alarm1MatchDay Alarm1MatchDate
dayDate	Alarm match day of the week or day of the month. This depends on alarmType.
hours	Alarm match hours.
minutes	Alarm match minutes.
seconds	Alarm match seconds.

Return values

true	Success.
false	Set alarm 1 failed.

Definition at line 444 of file ErriezDS3231.cpp.

◆ setAlarm2()

bool ErriezDS3231::setAlarm2	(	Alarm2Type	alarmType,
		uint8_t	dayDate,
		uint8_t	hours,
		uint8_t	minutes
	)

Set Alarm 2.

Alarm 2 contains different alarm modes which can be configured with the alarmType parameter. Unused matches can be set to zero. The alarm interrupt must be enabled after setting the alarm, followed by clearing the alarm interrupt flag.

Parameters

alarmType	Alarm 2 types: Alarm2EveryMinute Alarm2MatchMinutes Alarm2MatchHours Alarm2MatchDay Alarm2MatchDate
dayDate	Alarm match day of the week or day of the month. This depends on alarmType.
hours	Alarm match hours.
minutes	Alarm match minutes.

Return values

true	Success.
false	Set alarm 2 failed.

Definition at line 495 of file ErriezDS3231.cpp.

◆ setDateTime()

bool ErriezDS3231::setDateTime	(	uint8_t	hour,
		uint8_t	min,
		uint8_t	sec,
		uint8_t	mday,
		uint8_t	mon,
		uint16_t	year,
		uint8_t	wday
	)

Set date time.

Parameters

hour	Hours 0..23
min	Minutes 0..59
sec	Seconds 0..59
mday	Day of the month 1..31
mon	Month 1..12 (1=January)
year	Year 2000..2099
wday	Day of the week 0..6 (0=Sunday, .. 6=Saturday)

Return values

true	Success.
false	Set date/time failed.

Definition at line 354 of file ErriezDS3231.cpp.

◆ setEpoch()

bool ErriezDS3231::setEpoch ( time_t t )

Write Unix epoch UTC time to RTC.

Parameters

t	time_t time

Return values

true	Success.
false	Set epoch failed.

Definition at line 159 of file ErriezDS3231.cpp.

◆ setSquareWave()

bool ErriezDS3231::setSquareWave ( SquareWave squareWave )

Configure SQW (Square Wave) output pin.

This will disable or initialize the SQW clock pin. The alarm interrupt INT pin will be disabled.

Parameters

squareWave SquareWave configuration:
Disable: SquareWaveDisable
1Hz: SquareWave1Hz
1024Hz: SquareWave1024Hz
4096Hz: SquareWave4096Hz
8192Hz: SquareWave8192Hz

Return values

true	Success
false	Set squareWave failed.

Definition at line 627 of file ErriezDS3231.cpp.

◆ setTime()

bool ErriezDS3231::setTime	(	uint8_t	hour,
		uint8_t	min,
		uint8_t	sec
	)

Write time to RTC.

Write hour, minute and second registers to RTC.

Parameters

hour	Hours 0..23.
min	Minutes 0..59.
sec	Seconds 0..59.

Return values

true	Success.
false	Set time failed.

Definition at line 280 of file ErriezDS3231.cpp.

◆ startTemperatureConversion()

bool ErriezDS3231::startTemperatureConversion ( )

Start temperature conversion.

Starting a conversion is only needed when the application requires temperature reads within 64 seconds, or changing the aging offset register.

Return values

true	Success
false	Start temperature conversion failed.

Definition at line 741 of file ErriezDS3231.cpp.

◆ write()

bool ErriezDS3231::write ( const struct tm * dt )

Write date and time to RTC.

Write all RTC registers at once to prevent a time/date register change in the middle of the register write operation. This function enables the oscillator and clear the Oscillator Stop Flag (OSF) in the status register.

Parameters

dt	Date/time struct tm. Providing invalid date/time data may result in unpredictable behavior.

Return values

true	Success.
false	Write failed.

Definition at line 243 of file ErriezDS3231.cpp.

◆ writeBuffer()

bool ErriezDS3231::writeBuffer	(	uint8_t	reg,
		void *	buffer,
		uint8_t	writeLen
	)

Write buffer to RTC.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x12.
buffer	Buffer.
writeLen	Buffer length. Writing is only allowed within valid RTC registers.

Return values

true	Success
false	I2C write failed.

Definition at line 869 of file ErriezDS3231.cpp.

◆ writeRegister()

bool ErriezDS3231::writeRegister	(	uint8_t	reg,
		uint8_t	value
	)

Write register.

Please refer to the RTC datasheet.

Parameters

reg	RTC register number 0x00..0x12.
value	8-bit unsigned register value.

Return values

true	Success
false	Write register failed

Definition at line 848 of file ErriezDS3231.cpp.

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

src/ErriezDS3231.h
src/ErriezDS3231.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ alarmInterruptEnable()

◆ bcdToDec()

◆ begin()

◆ clearAlarmFlag()

◆ clockEnable()

◆ decToBcd()

◆ getAgingOffset()

◆ getAlarmFlag()

◆ getDateTime()

◆ getEpoch()

◆ getTemperature()

◆ getTime()

◆ isRunning()

◆ outputClockPinEnable()

◆ read()

◆ readBuffer()

◆ readRegister()

◆ setAgingOffset()

◆ setAlarm1()

◆ setAlarm2()

◆ setDateTime()

◆ setEpoch()

◆ setSquareWave()

◆ setTime()

◆ startTemperatureConversion()

◆ write()

◆ writeBuffer()

◆ writeRegister()