API Reference

pcf8523 - PCF8523 Real Time Clock module

This library supports the use of the PCF8523-based RTC in CircuitPython. It contains a base RTC class used by all Adafruit RTC libraries. This base class is inherited by the chip-specific subclasses.

Functions are included for reading and writing registers and manipulating datetime objects.

Author(s): Philip R. Moyer and Radomir Dopieralski for Adafruit Industries. Date: November 2016 Affiliation: Adafruit Industries

Implementation Notes

Hardware:

Software and Dependencies:

Notes:

  1. Milliseconds are not supported by this RTC.

  2. The alarm does not support seconds. It will always fire on full minutes.

  3. Datasheet: http://cache.nxp.com/documents/data_sheet/PCF8523.pdf

class adafruit_pcf8523.pcf8523.PCF8523(i2c_bus: I2C)

Interface to the PCF8523 RTC.

Parameters:

i2c_bus (I2C) – The I2C bus the device is connected to

Quickstart: Importing and using the device

Here is an example of using the PCF8523 class. First you will need to import the libraries to use the sensor

import time
import board
import adafruit_pcf8523

Once this is done you can define your board.I2C object and define your sensor object

i2c = board.I2C()  # uses board.SCL and board.SDA
rtc = adafruit_pcf8523.PCF8523(i2c)

Now you can give the current time to the device.

t = time.struct_time((2017, 10, 29, 15, 14, 15, 0, -1, -1))
rtc.datetime = t

You can access the current time accessing the datetime attribute.

current_time = rtc.datetime
alarm = 10

Alarm time for the first alarm. Note that the value of the seconds-fields is ignored, i.e. alarms only fire at full minutes. For short-term alarms, use a timer instead.

alarm_interrupt = 0

True if the interrupt pin will output when alarm is alarming.

alarm_status = 1

True if alarm is alarming. Set to False to reset.

battery_low = 2

True if the battery is low and should be replaced.

calibration = 7

Calibration offset to apply, from -64 to +63. See the PCF8523 datasheet figure 18 for the offset calibration calculation workflow.

calibration_schedule_per_minute = 14

False to apply the calibration offset every 2 hours (1 LSB = 4.340ppm); True to offset every minute (1 LSB = 4.069ppm). The default, False, consumes less power. See datasheet figures 28-31 for details.

property datetime: struct_time

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

datetime_register = 3

Current date and time.

high_capacitance = 0

True for high oscillator capacitance (12.5pF), otherwise lower (7pF)

lost_power = 3

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

power_management = 3

Power management state that dictates battery switchover, power sources and low battery detection. Defaults to BATTERY_SWITCHOVER_OFF (0b111).

timer - PCF8523 Timer module

This class supports the timer of the PCF8523-based RTC in CircuitPython.

Functions are included for reading and writing registers and manipulating timer objects.

The PCF8523 support two timers named Tmr_A and Tmr_B in the datasheet. For compatibility with the PCF8563, the Tmr_A is named timer while the second timer is named timerB.

The class supports stand-alone usage. In this case, pass an i2-bus object to the constructor. If used together with the PCF8523 class (rtc), instantiate the rtc-object first and then pass the i2c_device attribute of the rtc to the constructor of the timer.

Author(s): Bernhard Bablok Date: September 2023

Implementation Notes

Hardware:

Software and Dependencies:

Notes:

  1. Milliseconds are not supported by this RTC.

  2. The alarm does not support seconds. It will always fire on full minutes.

  3. Datasheet: http://cache.nxp.com/documents/data_sheet/PCF8523.pdf

class adafruit_pcf8523.timer.Timer(i2c: I2C | adafruit_bus_device.i2c_device.I2CDevice)

Interface to the timer of the PCF8563 RTC.

Parameters:

i2c_bus (I2C) – The I2C bus object

TIMER_FREQ_1HZ = 2

Timer frequency of 1 Hz

TIMER_FREQ_1_3600HZ = 7

Timer frequency of 1/3600 Hz

TIMER_FREQ_1_60HZ = 3

Timer frequency of 1/60 Hz

TIMER_FREQ_4KHZ = 0

Timer frequency of 4 KHz

TIMER_FREQ_64HZ = 1

Timer frequency of 64 Hz

timerB_enabled = 15

True if the timerB is enabled. Default is False.

timerB_frequency = 3

TimerB clock frequency. Default is 1/3600Hz. Possible values are as shown (selection value - frequency). 000 - 4.096kHz 001 - 64Hz 010 - 1Hz 011 - 1/60Hz 111 - 1/3600Hz

timerB_interrupt = 1

True if the interrupt pin will assert when timerB has elapsed. Defaults to False.

timerB_pulsed = 15

True if timerB asserts INT as a pulse. The default value False asserts INT permanently.

timerB_status = 1

True if timerB has elapsed. Set to False to reset.

timerB_value = 8

TimerB value (0-255). The default is undefined. The total countdown duration is calcuated by timerB_value/timerB_frequency. For a higher precision, use higher values and frequencies, e.g. for a one minute timer you could use value=1, frequency=1/60Hz or value=60, frequency=1Hz. The latter will give better results. See the PCF85x3 User’s Manual for details.

timer_enabled = 2

Configures timer. Possible values: 00 - disabled 01 - enabled as countdown timer 10 - enabled as watchdog timer 11 - disabled

timer_frequency = 3

TimerA clock frequency. Default is 1/3600Hz. Possible values are as shown (selection value - frequency). 000 - 4.096kHz 001 - 64Hz 010 - 1Hz 011 - 1/60Hz 111 - 1/3600Hz

timer_interrupt = 1

True if the interrupt pin will assert when timer has elapsed. Defaults to False.

timer_pulsed = 15

True if timer asserts INT as a pulse. The default value False asserts INT permanently.

timer_status = 1

True if timer has elapsed. Set to False to reset.

timer_value = 8

TimerA value (0-255). The default is undefined. The total countdown duration is calcuated by timer_value/timer_frequency. For a higher precision, use higher values and frequencies, e.g. for a one minute timer you could use value=1, frequency=1/60Hz or value=60, frequency=1Hz. The latter will give better results. See the PCF85x3 User’s Manual for details.

timer_watchdog = 1

True if the interrupt pin will output when timer generates a watchdog-alarm. Defaults to False.

clock - PCF8523 Clock module

This class supports the clkout-feature of the PCF8523-based RTC in CircuitPython.

Functions are included for reading and writing registers to configure clklout frequency.

The class supports stand-alone usage. In this case, pass an i2-bus object to the constructor. If used together with the PCF8523 class (rtc), instantiate the rtc-object first and then pass the i2c_device attribute of the rtc to the constructor of the clock.

Author(s): Bernhard Bablok Date: September 2023

Implementation Notes

Hardware:

Software and Dependencies:

Notes:

  1. Milliseconds are not supported by this RTC.

  2. The alarm does not support seconds. It will always fire on full minutes.

  3. Datasheet: http://cache.nxp.com/documents/data_sheet/PCF8523.pdf

class adafruit_pcf8523.clock.Clock(i2c: I2C | adafruit_bus_device.i2c_device.I2CDevice)

Interface to the clkout of the PCF8523 RTC.

Parameters:

i2c_bus (I2C) – The I2C bus object

CLOCKOUT_FREQ_16KHZ = 1

Clock frequency of 16 KHz

CLOCKOUT_FREQ_1HZ = 6

Clock frequency of 1 Hz

CLOCKOUT_FREQ_1KHZ = 4

Clock frequency of 4 KHz

CLOCKOUT_FREQ_32HZ = 5

Clock frequency of 32 Hz

CLOCKOUT_FREQ_32KHZ = 0

Clock frequency of 32 KHz

CLOCKOUT_FREQ_4KHZ = 3

Clock frequency of 4 KHz

CLOCKOUT_FREQ_8KHZ = 2

Clock frequency of 8 KHz

CLOCKOUT_FREQ_DISABLED = 7

Clock output disabled

clockout_frequency = 3

Clock output frequencies generated. Default is 32.768kHz. Possible values are as shown (selection value - frequency). 000 - 32.768khz 001 - 16.384khz 010 - 8.192kHz 011 - 4.096kHz 100 - 1.024kHz 101 - 0.032kHz (32Hz) 110 - 0.001kHz (1Hz) 111 - Disabled