PyPCF8523/README.md

PyPCF8523 - Python Driver for PCF8523 Real Time Clock

A Python 3.8+ driver for the PCF8523 Real Time Clock (RTC) chip, designed for Raspberry Pi and similar Linux boards with I2C support.

This library is a Python conversion of Adafruit's CircuitPython PCF8523 library, adapted to work with standard Python and smbus2.

Features

• Battery-backed RTC: Maintains accurate time even when main power is lost
• Dual voltage support: Works with 3.3V or 5V logic
• Alarm functionality: Set alarms with minute precision
• Calibration support: Adjust clock accuracy with offset calibration
• Low battery detection: Monitor backup battery status
• Power management: Configurable battery switchover modes
• Python 3.8+ compatible: Modern Python with type hints

Hardware Requirements

• Raspberry Pi (any model with I2C) or compatible Linux board
• PCF8523 RTC module (e.g., Adafruit PCF8523 breakout)
• I2C connection to the RTC module

Installation

Prerequisites

Enable I2C on your Raspberry Pi:

sudo raspi-config
# Navigate to: Interface Options > I2C > Enable

Install the package

pip install smbus2
pip install -e /path/to/PyPCF8523

Or install dependencies directly:

cd /path/to/PyPCF8523
pip install -r requirements.txt
pip install -e .

Quick Start

Basic Usage

import time
from pypcf8523 import PCF8523

# Initialize RTC on I2C bus 1 (default for Raspberry Pi)
rtc = PCF8523(i2c_bus=1)

# Set the current time
current_time = time.localtime()
rtc.datetime = current_time

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

Using Context Manager

from pypcf8523 import PCF8523

with PCF8523(1) as rtc:
    print(f"RTC Time: {rtc.datetime}")

    # Check if power was lost
    if rtc.lost_power:
        print("Warning: RTC lost power, time may be incorrect")

Setting an Alarm

from pypcf8523 import PCF8523

rtc = PCF8523(1)

# Set alarm for 8:30 AM every day
rtc.set_alarm(minute=30, hour=8)

# Enable alarm interrupt
rtc.alarm_interrupt = True

# Check if alarm triggered
if rtc.alarm_status:
    print("Alarm triggered!")
    rtc.alarm_status = False  # Clear the alarm

Calibration

from pypcf8523 import PCF8523

rtc = PCF8523(1)

# Set calibration offset (-64 to +63)
# Positive values speed up the clock, negative values slow it down
rtc.calibration = 5

# Set calibration schedule
rtc.calibration_schedule_per_minute = True  # Apply every minute
# or
rtc.calibration_schedule_per_minute = False  # Apply every 2 hours

API Reference

PCF8523 Class

Constructor

PCF8523(i2c_bus=1, address=0x68)

• i2c_bus: I2C bus number (default: 1)
• address: I2C device address (default: 0x68)

Properties

• datetime (struct_time): Get or set the current date and time
• lost_power (bool): True if device lost power since time was set
• power_management (int): Battery switchover mode (0-7)
• alarm_interrupt (bool): Enable/disable alarm interrupt output
• alarm_status (bool): Check if alarm triggered (write False to clear)
• battery_low (bool): True if backup battery is low (read-only)
• high_capacitance (bool): Oscillator capacitance mode
• calibration (int): Clock calibration offset (-64 to +63)
• calibration_schedule_per_minute (bool): Calibration schedule mode

Methods

• set_alarm(minute=None, hour=None, day=None, weekday=None): Set alarm
• clear_alarm(): Disable and clear alarm
• close(): Close I2C bus connection

Pin Connections (Raspberry Pi)

PCF8523	Raspberry Pi
VCC	3.3V (Pin 1)
GND	GND (Pin 6)
SDA	SDA (Pin 3)
SCL	SCL (Pin 5)

Troubleshooting

I2C Device Not Found

Check if the device is detected:

i2cdetect -y 1

You should see 68 in the output grid.

Permission Denied

Add your user to the i2c group:

sudo usermod -a -G i2c $USER

Then log out and back in.

Accuracy Issues

The PCF8523 can drift up to 2 seconds per day. For critical timing applications:

1. Use the calibration feature to compensate for drift
2. Consider periodic synchronization with NTP
3. Monitor temperature (affects crystal oscillator)

Credits

• Original CircuitPython Library: Adafruit Industries
• Original Authors: Philip R. Moyer and Radomir Dopieralski
• Python Conversion: Duncan Tourolle

License

MIT License - See LICENSE file for details

Contributing

This is a conversion of Adafruit's CircuitPython library. For core functionality improvements, please contribute to the original repository.

For Python-specific issues or improvements, feel free to submit issues or pull requests.