Skip to content

adafruit_pcf8523

Works with

Any board with I2C. Requires a CR1220 coin cell battery for backup power (battery holder is included on the Adafruit breakout).

What it does

adafruit_pcf8523 drives the PCF8523 real-time clock chip. It is a practical choice when battery life is a priority — the PCF8523 draws significantly less current than the DS3231, which matters in low-power deployments where the RTC module needs to run for months or years on a coin cell. The chip includes an alarm, a timer, and a battery_low flag that warns you when the backup battery is getting weak. The tradeoff is accuracy: without temperature compensation, the PCF8523 drifts more than the DS3231 over time, typically around ±2 minutes per month. For projects where occasional drift is acceptable and battery life matters more than sub-minute accuracy, the PCF8523 is the better fit.

Installing the library

Copy all of the following to CIRCUITPY/lib/:

  • adafruit_pcf8523/ (folder)
  • adafruit_bus_device/ (folder)

Quick start

import time
import board
import adafruit_pcf8523

i2c = board.I2C()
rtc = adafruit_pcf8523.PCF8523(i2c)

# Set the time once (comment out after first run)
# time.struct_time: (year, month, day, hour, min, sec, weekday, yearday, dst)
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}")

# Check battery status
if rtc.battery_low:
    print("Warning: RTC backup battery is low — replace the CR1220")

# Sync the CircuitPython software RTC
import rtc as builtin_rtc
builtin_rtc.RTC().datetime = rtc.datetime

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
Check for low battery rtc.battery_low — True when the CR1220 needs replacement
Sync the software RTC builtin_rtc.RTC().datetime = rtc.datetime
Set an alarm rtc.alarm1 = (datetime, match_mode)
Check if alarm fired rtc.alarm1_status (bool)
Clear the alarm rtc.alarm1_status = False
Enable the alarm interrupt pin rtc.alarm1_interrupt = True — pulls INT pin low when alarm fires

Reading the official docs

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

Projects using this library