Adafruit’s DS3231 RTC LibraryDocumentation

Release 1.0

Philip Moyer

Mar 19, 2021

Contents

1 Dependencies 3

2 Installing from PyPI 5

3 Usage Notes 73.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Date and time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3 Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Contributing 9

5 Documentation 11

6 Table of Contents 136.1 Simple test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136.2 adafruit_ds3231 - DS3231 Real Time Clock module . . . . . . . . . . . . . . . . . . . . . . . 14

6.2.1 Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

7 Indices and tables 17

Python Module Index 19

Index 21

i

ii

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

The datasheet for the DS3231 explains that this part is an “Extremely Accurate I2C-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 asmall, 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 welland good, but those crystals have slight drift, particularly when the temperature changes (the temperature changes theoscillation frequency very very very slightly but it does add up!) This RTC is in a beefy package because the crystalis inside the chip! And right next to the integrated crystal is a temperature sensor. That sensor compensates for thefrequency 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 cellplugged into the back, you can get years of precision timekeeping, even when main power is lost. Great for dataloggingand clocks, or anything where you need to really know the time.

Contents 1

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

2 Contents

CHAPTER 1

Dependencies

This driver depends on:

• Adafruit CircuitPython

• Bus Device

• Register

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloadingthe Adafruit library and driver bundle.

3

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

4 Chapter 1. Dependencies

CHAPTER 2

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install forcurrent user:

pip3 install adafruit-circuitpython-ds3231

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-ds3231

To install in a virtual environment in your current project:

mkdir project-name && cd project-namepython3 -m venv .envsource .env/bin/activatepip3 install adafruit-circuitpython-ds3231

5

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

6 Chapter 2. Installing from PyPI

CHAPTER 3

Usage Notes

3.1 Basics

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

import busioimport adafruit_ds3231import time

All the Adafruit RTC libraries take an instantiated and active I2C object (from the busio library) as an argument totheir constructor. The way to create an I2C object depends on the board you are using. For boards with labeled SCLand SDA pins, you can:

from board import *

You can also use pins defined by the onboard microcontroller through the microcontroller.pin module.

Now, to initialize the I2C bus:

myI2C = busio.I2C(SCL, SDA)

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

rtc = adafruit_ds3231.DS3231(myI2C)

3.2 Date and time

To set the time, you need to set datetime to a time.struct_time object:

rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))

7

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

After the RTC is set, you retrieve the time by reading the datetime attribute and access the standard attributes of astruct_time such as tm_year, tm_hour and tm_min.

t = rtc.datetimeprint(t)print(t.tm_hour, t.tm_min)

3.3 Alarm

To set the time, you need to set alarm1 or alarm2 to a tuple with a time.struct_time object and stringrepresenting the frequency such as “hourly”:

rtc.alarm1 = (time.struct_time((2017,1,9,15,6,0,0,9,-1)), "daily")

After the RTC is set, you retrieve the alarm status by reading the corresponding alarm1_status oralarm2_status attributes. Once True, set it back to False to reset.

if rtc.alarm1_status:print("wake up!")rtc.alarm1_status = False

8 Chapter 3. Usage Notes

CHAPTER 4

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

9

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

10 Chapter 4. Contributing

CHAPTER 5

Documentation

For information on building library documentation, please check out this guide.

11

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

12 Chapter 5. Documentation

CHAPTER 6

Table of Contents

6.1 Simple test

Ensure your device works with this simple test.

Listing 1: examples/ds3231_simpletest.py

1 # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries2 # SPDX-License-Identifier: MIT3

4 # Simple demo of reading and writing the time for the DS3231 real-time clock.5 # Change the if False to if True below to set the time, otherwise it will just6 # print the current date and time every second. Notice also comments to adjust7 # for working with hardware vs. software I2C.8

9 import time10 import board11

12 # For hardware I2C (M0 boards) use this line:13 import busio as io14

15 # Or for software I2C (ESP8266) use this line instead:16 # import bitbangio as io17

18 import adafruit_ds323119

20

21 i2c = io.I2C(board.SCL, board.SDA) # Change to the appropriate I2C clock & data22 # pins here!23

24 # Create the RTC instance:25 rtc = adafruit_ds3231.DS3231(i2c)26

27 # Lookup table for names of days (nicer printing).

(continues on next page)

13

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

(continued from previous page)

28 days = ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday")29

30

31 # pylint: disable-msg=using-constant-test32 if False: # change to True if you want to set the time!33 # year, mon, date, hour, min, sec, wday, yday, isdst34 t = time.struct_time((2017, 10, 29, 15, 14, 15, 0, -1, -1))35 # you must set year, mon, date, hour, min, sec and weekday36 # yearday is not supported, isdst can be set but we don't do anything with it at

→˓this time37 print("Setting time to:", t) # uncomment for debugging38 rtc.datetime = t39 print()40 # pylint: enable-msg=using-constant-test41

42 # Main loop:43 while True:44 t = rtc.datetime45 # print(t) # uncomment for debugging46 print(47 "The date is {} {}/{}/{}".format(48 days[int(t.tm_wday)], t.tm_mday, t.tm_mon, t.tm_year49 )50 )51 print("The time is {}:{:02}:{:02}".format(t.tm_hour, t.tm_min, t.tm_sec))52 time.sleep(1) # wait a second

6.2 adafruit_ds3231 - DS3231 Real Time Clock module

CircuitPython library to support DS3231 Real Time Clock (RTC).

This library supports the use of the DS3231-based RTC in CircuitPython.

Author(s): Philip R. Moyer and Radomir Dopieralski for Adafruit Industries.

6.2.1 Implementation Notes

Hardware:

• Adafruit DS3231 Precision RTC FeatherWing (Product ID: 3028)

• Adafruit DS3231 RTC breakout (Product ID: 3013)

• Adafruit ChronoDot - Ultra-precise Real Time Clock - v2.1 (Product ID: 3013)

Software and Dependencies:

• Adafruit CircuitPython firmware for the ESP8622 and M0-based boards: https://github.com/adafruit/circuitpython/releases

• Adafruit’s Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register

• Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice

Notes:

1. Milliseconds are not supported by this RTC.

14 Chapter 6. Table of Contents

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

2. Datasheet: https://datasheets.maximintegrated.com/en/ds/DS3231.pdf

class adafruit_ds3231.DS3231(i2c)Interface to the DS3231 RTC.

alarm1Alarm time for the first alarm.

alarm1_interruptTrue if the interrupt pin will output when alarm1 is alarming.

alarm1_statusTrue if alarm1 is alarming. Set to False to reset.

alarm2Alarm time for the second alarm.

alarm2_interruptTrue if the interrupt pin will output when alarm2 is alarming.

alarm2_statusTrue if alarm2 is alarming. Set to False to reset.

calibrationCalibrate the frequency of the crystal oscillator by adding or removing capacitance. The datasheet callsthis the Aging Offset. Calibration values range from -128 to 127; each step is approximately 0.1ppm, andpositive values decrease the frequency (increase the period). When set, a temperature conversion is forcedso the result of calibration can be seen directly at the 32kHz pin immediately

datetimeGets the current date and time or sets the current date and time then starts the clock.

datetime_registerCurrent date and time.

disable_oscillatorTrue if the oscillator is disabled.

force_temperature_conversion()Forces a conversion and returns the new temperature

lost_powerTrue if the device has lost power since the time was set.

temperatureReturns the last temperature measurement. Temperature is updated only every 64 seconds, or when aconversion is forced.

6.2. adafruit_ds3231 - DS3231 Real Time Clock module 15

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

16 Chapter 6. Table of Contents

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

17

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

18 Chapter 7. Indices and tables

Python Module Index

aadafruit_ds3231, 14

19

Adafruit’s DS3231 RTC Library Documentation, Release 1.0

20 Python Module Index

Index

Aadafruit_ds3231 (module), 14alarm1 (adafruit_ds3231.DS3231 attribute), 15alarm1_interrupt (adafruit_ds3231.DS3231

attribute), 15alarm1_status (adafruit_ds3231.DS3231 attribute),

15alarm2 (adafruit_ds3231.DS3231 attribute), 15alarm2_interrupt (adafruit_ds3231.DS3231

attribute), 15alarm2_status (adafruit_ds3231.DS3231 attribute),

15

Ccalibration (adafruit_ds3231.DS3231 attribute), 15

Ddatetime (adafruit_ds3231.DS3231 attribute), 15datetime_register (adafruit_ds3231.DS3231 at-

tribute), 15disable_oscillator (adafruit_ds3231.DS3231 at-

tribute), 15DS3231 (class in adafruit_ds3231), 15

Fforce_temperature_conversion()

(adafruit_ds3231.DS3231 method), 15

Llost_power (adafruit_ds3231.DS3231 attribute), 15

Ttemperature (adafruit_ds3231.DS3231 attribute), 15

21