Skip to content

adafruit_ds3231

Works with

Any board with I2C. The DS3231 module requires a CR2032 coin cell battery for backup power.

What it does

adafruit_ds3231 drives the DS3231 real-time clock, which is among the most accurate RTCs available for embedded use. The chip uses a temperature-compensated crystal oscillator (TCXO) that automatically adjusts for temperature-related frequency drift, achieving accuracy of ±2 ppm — losing or gaining less than one minute per year. A battery on the module keeps the clock running when your board loses power. The chip also includes a built-in temperature sensor accurate to ±3°C, and two configurable alarms that can trigger an interrupt pin. This is the right RTC when you need reliable timekeeping in a battery-backed deployment without WiFi for NTP syncing.

Installing the library

Copy all of the following to CIRCUITPY/lib/:

  • adafruit_ds3231.mpy
  • adafruit_bus_device/ (folder)

Quick start

import time
import board
import adafruit_ds3231

i2c = board.I2C()
rtc = adafruit_ds3231.DS3231(i2c)

# Set the time once (comment out after first run)
# time.struct_time: (year, month, day, hour, min, sec, weekday, yearday, dst)
# weekday: 0=Monday ... 6=Sunday; yearday and dst are ignored (-1)
rtc.datetime = time.struct_time((2025, 6, 15, 14, 30, 0, 6, -1, -1))

# Read the current time
t = rtc.datetime
print(f"Date: {t.tm_year}-{t.tm_mon:02d}-{t.tm_mday:02d}")
print(f"Time: {t.tm_hour:02d}:{t.tm_min:02d}:{t.tm_sec:02d}")

# Read the temperature
print(f"Temperature: {rtc.temperature:.1f} C")

# Sync the CircuitPython software RTC from the DS3231
import rtc as builtin_rtc
builtin_rtc.RTC().datetime = rtc.datetime
# Now time.localtime() returns the correct time

Key things you can do

What you want How to do it
Set the date and time rtc.datetime = time.struct_time((year, month, day, hour, min, sec, weekday, -1, -1))
Read the date and time t = rtc.datetime
Get the hour rtc.datetime.tm_hour
Get the minute rtc.datetime.tm_min
Get the second rtc.datetime.tm_sec
Get the date rtc.datetime.tm_year, .tm_mon, .tm_mday
Read the temperature sensor rtc.temperature (°C, float)
Sync the software RTC rtc_builtin.RTC().datetime = rtc.datetime
Check if battery is low rtc.lost_power — True if the chip lost power and time may be wrong
Set alarm 1 rtc.alarm1 = (datetime, match_mode)
Check if alarm 1 fired rtc.alarm1_status (bool)
Clear alarm 1 rtc.alarm1_status = False

Reading the official docs

Full API reference: https://docs.circuitpython.org/projects/ds3231/en/latest/

Projects using this library