MD_DS3231 Real Time Clock Library  1.3
Library to control DS3231 high precision clock with alarms
Software Overview

Using the Library

The library has a simple interface to the RTC hardware implemented through:

  • a set of time (h, m, s and dow) and date (yyyy, mm, dd) variables. All data to and from the RTC passes through these. Clock or alarm time data is read or written to these interface registers before the appropriate methods are invoke to act on that data.
  • control() and status() methods to set and query the functionality of the RTC.
  • specific functions to set and test for each of the two alarms.

Alarms may be operated in either polled mode or interrupt mode, as described below.

The Control and Status Methods

The control() and status() methods are the main interface to action setting parameters or status values. The parameters used for each are similar, but not symmetrical, due to the way the hardware is implemented. The table below highlights the combinations of valid parameters for the control() method and whether a parameter can be changed by user code.

The status() method will return the current value from the parameter nominated and is guaranteed to be in the valid set.

Function R W Write value ------------------—
DS3231_CLOCK_HALT Y Y DS3231_ON, DS3231_OFF
DS3231_SQW_ENABLE Y Y DS3231_ON, DS3231_OFF
DS3231_SQW_TYPE Y Y DS3231_SQW_1HZ, DS3231_SQW_1KHZ, DS3231_SQW_4KHZ, DS3231_SQW_8KHZ
DS3231_12H Y Y DS3231_ON, DS3231_OFF
DS3231_TCONV Y Y DS3231_ON, DS3231_OFF
DS3231_INT_ENABLE Y Y DS3231_ON, DS3231_OFF
DS3231_A1_INT_ENABLE Y Y DS3231_ON, DS3231_OFF
DS3231_A2_INT_ENABLE Y Y DS3231_ON, DS3231_OFF
DS3231_HALTED_FLAG Y Y DS3231_OFF
DS3231_32KHZ_ENABLE Y Y DS3231_ON, DS3231_OFF
DS3231_BUSY_FLAG Y N N/A
DS3231_A1_FLAG Y Y DS3231_OFF
DS3231_A2_FLAG Y Y DS3231_OFF
DS3231_AGING_OFFSET Y Y 0x00 - 0xff

Working with the Current Time

Reading the current time from the clock is a call to the readTime() method. The current date and time is then available in the interface registers.

Writing the current time is a sequence of writing to the interface registers followed by a call to the writeTime() method.

Working with Alarms

Writing the alarm trigger time data is achieve by writing to the interface registers followed by a call to the setAlarm1() or setAlarm2() method. The alarm type is specified when the method is invoked, and is one of the almType_t values, noting that values are specific to alarm 1 and alarm 2.

Reading the alarm trigger set is by invoking the getAlarm1() or getAlarm2() methods to load the interface registers, from which the data can be read. The alarm trigger type is obtained separately using the getAlarm1Type() or getAlarm2Type() methods.

Checking if an alarm has triggered can be done in two ways, depending on whether it is a polled alarm or interrupts have been enabled.

  • Polled Alarms are implemented by calling the checkAlarm1() or checkAlarm2() method. If a callback function is defined (using setAlarm1Callback() or setAlarm2Callback()) the callback function will be invoked. These methods encapsulate a check for the alarm trigger, invoke the callback function if triggered and reset the alarm flag, effectively providing an interrupt-like operation without the restrictions of being in an interrupt routine. If no callback function is defined, the return status from the checkAlarm1() or checkAlarm2() should be used instead.
  • Interrupt Alarms are configured by invoking the control() method to enable interrupts (INT_ENABLE), followed by enabling the interrupt for the required alarm (A1_INT_ENABLE or A2_INT_ENABLE). The alarm flag (control() with A1FLAG or A2_FLAG) should be rest to initialise a 'zero' start for the interrupt cycles. Once the interrupt cycle has completed, the alarm flag must be reset to re-enable the interrupt (control() with parameter A1_FLAG or A2_FLAG). The interrupt handler must be set up externally from the library and the hardware properly configured to accept the interrupt. Note, however:
    • the interrupt line from the DS3231 will be held logic HIGH and the interrupt is at logic LOW, so a HIGH to LOW transition (FALLING) should be specified as the interrupt trigger.
    • during the interrupt there can be no I2C communications as this uses interrupts. So checking a RTC status in the Interrupt Service Routine (ISR) is not possible.

The DS3231_LCD_Time example has examples of the different ways of interacting with the RTC.