DS3231RTC Class Reference

Communicates with a DS3231 realtime clock chip via I2C. More...

#include <DS3231RTC.h>

Inheritance diagram for DS3231RTC:

Public Member Functions

DS3231RTC (I2CMaster &bus, uint8_t oneHzPin=255)

Attaches to a realtime clock slave device on bus. More...

bool isRealTime () const

Returns true if the realtime clock is on the I2C bus; false if the time and date are simulated.

bool hasUpdates ()

Returns true if there are updates.

void readTime (RTCTime *value)

Reads the current time from the realtime clock into value. More...

void readDate (RTCDate *value)

Reads the current date from the realtime clock into value. More...

void writeTime (const RTCTime *value)

Updates the time in the realtime clock to match value. More...

void writeDate (const RTCDate *value)

Updates the date in the realtime clock to match value. More...

void readAlarm (uint8_t alarmNum, RTCAlarm *value)

Reads the details of the alarm with index alarmNum into value. More...

void writeAlarm (uint8_t alarmNum, const RTCAlarm *value)

 Updates the details of the alarm with index alarmNum from value. More...

bool setAlarm (uint8_t alarmNum, const RTCAlarm *value)

Sets the alarm with index alarmNum from value. More...

int readTemperature ()

Reads the value of the temperature sensor and returns the temperature in quarters of a degree
celcius. More...

void enableAlarmInterrupts ()

Enables the generation of interrupts for alarms 0 and 1. More...

void disableAlarmInterrupts ()

Disables the generation of interrupts for alarms 0 and 1. More...

int firedAlarm ()

Determines which of alarms 0 or 1 have fired since the last call. More...

void enable32kHzOutput ()

Enables the 32 kHz output on the DS3231 chip. More...

void disable32kHzOutput ()

Disables the 32 kHz output on the DS3231 chip. More...

void enableAlarm (uint8_t alarmNum)

Enables a specific alarm. More...

void disableAlarm (uint8_t alarmNum)

Disables a specific alarm. More...

Public Member Functions inherited from RTC

Additional Inherited Members

Public Types inherited from RTC

Day of the week corresponding to a date. More...

Static Public Member Functions inherited from RTC

 Static Public Attributes inherited from RTC

Detailed Description

Communicates with a DS3231 realtime clock chip via I2C.

This class simplifies the process of reading and writing the time and date information in a DS3231 realtime
clock chip. The class also provides support for reading and writing information about alarms and other clock
settings.

If there is no DS3231 chip on the I2C bus, this class will fall back to the RTC class to simulate the current time
and date based on the value of millis().

Alarms 0 and 1 can be set to generate an interrupt when they fire using enableAlarmInterrupts().
The firedAlarm() function can be used to determine which alarm has fired.

The DS3231 uses a 2-digit year so this class is limited to dates between 2000 and 2099 inclusive.

The structure RTCAlarm is used to read and write the alarms. It has a flags field which is analogous to the
alarm mask bits found in the DS3231 manual. Bit 7 signals whether this is an alarm structure with settings for
alarm 0 or 1 (as these are different, see manual).

See Also
RTC, DS3232RTC, DS1307RTC

Definition at line 35 of file DS3231RTC.h.

Constructor & Destructor Documentation

DS3231RTC::DS3231RTC ( I2CMaster & bus,

uint8_t oneHzPin = 255
)

Attaches to a realtime clock slave device on bus.

If oneHzPin is not 255, then it indicates a digital input pin that is connected to the 1 Hz square wave output on
the realtime clock. This input is used by hasUpdates() to determine if the time information has changed in a
non-trivial manner.

If you wish to use enableAlarmInterrupts(), then oneHzPin must be 255.

See Also
hasUpdates(), enableAlarmInterrupts()

Definition at line 125 of file DS3231RTC.cpp.

Member Function Documentation

void DS3231RTC::disable32kHzOutput ( )

Disables the 32 kHz output on the DS3231 chip.

See Also
enable32kHzOutput()

Definition at line 575 of file DS3231RTC.cpp.

void DS3231RTC::disableAlarm ( uint8_t alarmNum )

Disables a specific alarm.

Parameters

alarmNum The alarm to disable.

See Also
enableAlarm()

Definition at line 625 of file DS3231RTC.cpp.

void DS3231RTC::disableAlarmInterrupts ( )

Disables the generation of interrupts for alarms 0 and 1.

See Also
enableAlarmInterrupts()

Definition at line 508 of file DS3231RTC.cpp.

void DS3231RTC::enable32kHzOutput ( )

Enables the 32 kHz output on the DS3231 chip.

See Also
disable32kHzOutput()

Definition at line 562 of file DS3231RTC.cpp.

void DS3231RTC::enableAlarm ( uint8_t alarmNum )

Enables a specific alarm.

Parameters
 alarmNum The alarm to enable.
See Also
disableAlarm()

Definition at line 606 of file DS3231RTC.cpp.

void DS3231RTC::enableAlarmInterrupts ( )

Enables the generation of interrupts for alarms 0 and 1.

When the interrupt occurs, use firedAlarm() to determine which alarm has fired. The application is
responsible for implementing the interrupt service routine to watch for the interrupt.

Note: this function does nothing if the 1 Hz pin was enabled in the constructor, but firedAlarm() can still be
used to determine which alarm has fired when hasUpdates() reports that there is an update available.

See Also
disableAlarmInterrupts(), firedAlarm()

Definition at line 494 of file DS3231RTC.cpp.

int DS3231RTC::firedAlarm ( )

Determines which of alarms 0 or 1 have fired since the last call.

Returns 0 if alarm 0 has fired, 1 if alarm 1 has fired, 2 if both alarms have fired, or -1 if neither alarm has fired.

The fired alarm state will be cleared, ready for the next call.

This function cannot be used to determine if alarms 2 or 3 have fired as they are stored in NVRAM and are
not handled specially by the DS3231.

See Also
enableAlarmInterrupts()

Definition at line 530 of file DS3231RTC.cpp.

void DS3231RTC::readAlarm ( uint8_t alarmNum,

RTCAlarm * value
) virtual

Reads the details of the alarm with index alarmNum into value.

The alarmNum parameter must be between 0 and ALARM_COUNT - 1.

Alarm details are stored at the end of the realtime clock's non-volatile memory.
See Also
writeAlarm(), alarmCount()

Reimplemented from RTC.

Definition at line 280 of file DS3231RTC.cpp.

void DS3231RTC::readDate ( RTCDate * value ) virtual

Reads the current date from the realtime clock into value.

The time should be read first with readTime() as the default implementation only advances the date when the
time is read and it crosses midnight.

See Also
writeDate(), readTime()

Reimplemented from RTC.

Definition at line 228 of file DS3231RTC.cpp.

int DS3231RTC::readTemperature ( ) virtual

Reads the value of the temperature sensor and returns the temperature in quarters of a degree celcius.

Returns the value NO_TEMPERATURE if the realtime clock chip cannot determine the temperature.

Reimplemented from RTC.

Definition at line 470 of file DS3231RTC.cpp.

void DS3231RTC::readTime ( RTCTime * value ) virtual

Reads the current time from the realtime clock into value.

See Also
writeTime(), readDate()

Reimplemented from RTC.

Definition at line 207 of file DS3231RTC.cpp.

bool DS3231RTC::setAlarm ( uint8_t alarmNum,

const RTCAlarm * value
)

Sets the alarm with index alarmNum from value.

The alarmNum parameter must be between 0 and ALARM_COUNT - 1.

Returns
Returns true if the alarm was set; false otherwise.

See Also
writeAlarm()

Definition at line 408 of file DS3231RTC.cpp.

void DS3231RTC::writeAlarm ( uint8_t alarmNum,

const RTCAlarm * value
) virtual

Updates the details of the alarm with index alarmNum from value.

The alarmNum parameter must be between 0 and ALARM_COUNT - 1.

Alarm details are stored at the end of the realtime clock's non-volatile memory.

See Also
readAlarm(), alarmCount()

Reimplemented from RTC.

Definition at line 374 of file DS3231RTC.cpp.

void DS3231RTC::writeDate ( const RTCDate * value ) virtual

Updates the date in the realtime clock to match value.

See Also
readDate(), writeTime()

Reimplemented from RTC.

Definition at line 266 of file DS3231RTC.cpp.

void DS3231RTC::writeTime ( const RTCTime * value ) virtual

Updates the time in the realtime clock to match value.

See Also
readTime(), writeDate()

Reimplemented from RTC.

Definition at line 252 of file DS3231RTC.cpp.

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

 DS3231RTC.h
 DS3231RTC.cpp