Introduction

The datasheet for the DS3231 explains that this part is an "Extremely Accurate I²C-Integrated RTC/TCXO/Crystal". And, hey, it does exactly what it says on the tin! This Real Time Clock (RTC) is the most precise you can get in a small, low power package.

Most RTCs use an external 32kHz timing crystal that is used to keep time with low current draw. And that's all well and good, but those crystals have slight drift, particularly when the temperature changes (the temperature changes the oscillation frequency very very very slightly but it does add up!) This RTC is in a beefy package because the crystal is inside the chip! And right next to the integrated crystal is a temperature sensor. That sensor compensates for the frequency changes by adding or removing clock ticks so that the timekeeping stays on schedule.

This is the finest RTC you can get, and now we have it in a compact, breadboard-friendly breakout. With a coin cell plugged into the back, you can get years of precision timekeeping, even when main power is lost. Great for datalogging and clocks, or anything where you need to really know the time.

Implementation Details

Background

This page contains the details of the functions, classes, and methods available in the DS3231 library.

The DS3231 library consists of three major sections:

1. Functions
2. The base class _BaseRTC
3. The subclass DS1307

Functions

The only library functions of which you need to be aware of for the DS1307 are datetime_tuple() and alarm_tuple().

The first is the function that creates an object you use to set the clock time. It takes eight arguments and returns a datetimetuple object containing the new time settings. The arguments are positional rather than keyword arguments. They are, in order:

• Year (4-digit)
• Month (2-digit)
• Day of the month (2-digit)
• Day of the week (1 digit, 0 = Sunday)
• Hour (24 hour clock, 2-digit)
• Minute (2-digit)
• Seconds (2-digits)
• The digit 0 (representing milliseconds, which are not supported by this RTC)

The second is the function that returns an alarmtuple structure to set the alarm on the RTC. It takes four arguments:

• Day of the week
• Day of the month
• hour
• minute

See the section, below, on usage for examples.

Class Methods

Here are the important class methods for you to know:

• datetime() - sets or returns the RTC clock time
• alarm_time() - sets or returns the current alarm setting
• _register() - returns the contents of a register in the RTC chip
• stop() - suspends RTC operation or, if the argument is None, returns the current setting.
• lost_power() - returns true or false depending on whether the board has lost power. Passing the value "False" will reset the flag.
• alarm() - returns the alarm state (True or False). Passing False as the argument will reset the flag.
• interruptEnable() - determines whether an alarm generates an interrupt on the INT/SQW pin

Usage Notes

Of course, you must import the library to use it:

import machine

import adafruit_ds3231

All the Adafruit RTC libraries take an instantiated and active I2C object (from the machine library) as an argument to their constructor. The way to create an I2C object depends on the board you are using. If you are using the ATSAMD21-based board, like the Feather M0, you must initialize the object after you create it:

myI2C = machine.I2C(machine.Pin('SCL'), machine.Pin('SDA'))

myI2C.init()

If you are using the ESP8266-based boards, however, you do not need to init() the object after creating it:

myI2C = machine.I2C(machine.Pin(5), machine.Pin(4))

Once you have created the I2C interface object, you can use it to instantiate the RTC object:

rtc = adafruit_ds3231.DS3231(myI2C)

To set the time, you need to pass datetime() a datetimetuple object:

newTime = adafruit_ds3231.datetime_tuple(2016,11,18,6,9,36,0,0)

rtc.datetime(newTime)

After the RTC is set, you retrieve the time by calling the datetime() method without any arguments.

curTime = rtc.datetime()

The DS3231 supports an alarm function. You set the alarm very similarly to the way you set the datetime.

newAlarm = adafruit_ds3231.alarm_tuple(6,18,10,41)

rtc.alarm_time(newAlarm)

Many more details can be found in the Docs/_build directory.