RTC based on the PCF8523 chip connected via I2C and the Wire library. More...

#include <RTClib.h>

Inheritance diagram for RTC_PCF8523:

Public Member Functions
bool	begin (TwoWire *wireInstance=&Wire)
	Start I2C for the PCF8523 and test succesful connection. More...

void	adjust (const DateTime &dt)
	Set the date and time, set battery switchover mode. More...

bool	lostPower (void)
	Check the status register Oscillator Stop flag to see if the PCF8523 stopped due to power loss. More...

bool	initialized (void)
	Check control register 3 to see if we've run adjust() yet (setting the date/time and battery switchover mode) More...

DateTime	now ()
	Get the current date/time. More...

void	start (void)
	Resets the STOP bit in register Control_1.

void	stop (void)
	Sets the STOP bit in register Control_1.

uint8_t	isrunning ()
	Is the PCF8523 running? Check the STOP bit in register Control_1. More...

Pcf8523SqwPinMode	readSqwPinMode ()
	Read the mode of the INT/SQW pin on the PCF8523. More...

void	writeSqwPinMode (Pcf8523SqwPinMode mode)
	Set the INT/SQW pin mode on the PCF8523. More...

void	enableSecondTimer (void)
	Enable the Second Timer (1Hz) Interrupt on the PCF8523. More...

void	disableSecondTimer (void)
	Disable the Second Timer (1Hz) Interrupt on the PCF8523.

void	enableCountdownTimer (PCF8523TimerClockFreq clkFreq, uint8_t numPeriods, uint8_t lowPulseWidth)
	Enable the Countdown Timer Interrupt on the PCF8523. More...

void	enableCountdownTimer (PCF8523TimerClockFreq clkFreq, uint8_t numPeriods)
	Enable Countdown Timer using default interrupt low pulse width. More...

void	disableCountdownTimer (void)
	Disable the Countdown Timer Interrupt on the PCF8523. More...

void	deconfigureAllTimers (void)
	Stop all timers, clear their flags and settings on the PCF8523. More...

void	calibrate (Pcf8523OffsetMode mode, int8_t offset)
	Compensate the drift of the RTC. More...

Detailed Description

RTC based on the PCF8523 chip connected via I2C and the Wire library.

Member Function Documentation

◆ begin()

bool RTC_PCF8523::begin ( TwoWire * wireInstance = &Wire )

Start I2C for the PCF8523 and test succesful connection.

Parameters

wireInstance pointer to the I2C bus

Returns: True if Wire can find PCF8523 or false otherwise.

◆ adjust()

void RTC_PCF8523::adjust ( const DateTime & dt )

Set the date and time, set battery switchover mode.

Parameters

dt	DateTime to set

◆ lostPower()

bool RTC_PCF8523::lostPower ( void )

Check the status register Oscillator Stop flag to see if the PCF8523 stopped due to power loss.

When battery or external power is first applied, the PCF8523's crystal oscillator takes up to 2s to stabilize. During this time adjust() cannot clear the 'OS' flag. See datasheet OS flag section for details.

Returns: True if the bit is set (oscillator is or has stopped) and false only after the bit is cleared, for instance with adjust()

◆ initialized()

bool RTC_PCF8523::initialized ( void )

Check control register 3 to see if we've run adjust() yet (setting the date/time and battery switchover mode)

Returns: True if the PCF8523 has been set up, false if not

◆ now()

DateTime RTC_PCF8523::now ( )

Get the current date/time.

Returns: DateTime object containing the current date/time

◆ isrunning()

uint8_t RTC_PCF8523::isrunning ( void )

Is the PCF8523 running? Check the STOP bit in register Control_1.

Returns: 1 if the RTC is running, 0 if not

◆ readSqwPinMode()

Pcf8523SqwPinMode RTC_PCF8523::readSqwPinMode ( )

Read the mode of the INT/SQW pin on the PCF8523.

Returns: SQW pin mode as a Pcf8523SqwPinMode enum

◆ writeSqwPinMode()

void RTC_PCF8523::writeSqwPinMode ( Pcf8523SqwPinMode mode )

Set the INT/SQW pin mode on the PCF8523.

Parameters

mode	The mode to set, see the Pcf8523SqwPinMode enum for options

◆ enableSecondTimer()

void RTC_PCF8523::enableSecondTimer ( void )

Enable the Second Timer (1Hz) Interrupt on the PCF8523.

The INT/SQW pin will pull low for a brief pulse once per second.

◆ enableCountdownTimer() [1/2]

void RTC_PCF8523::enableCountdownTimer	(	PCF8523TimerClockFreq	clkFreq,
		uint8_t	numPeriods,
		uint8_t	lowPulseWidth
	)

Enable the Countdown Timer Interrupt on the PCF8523.

The INT/SQW pin will be pulled low at the end of a specified countdown period ranging from 244 microseconds to 10.625 days. Uses PCF8523 Timer B. Any existing CLKOUT square wave, configured with writeSqwPinMode(), will halt. The interrupt low pulse width is adjustable from 3/64ths (default) to 14/64ths of a second.

Parameters

clkFreq	One of the PCF8523's Timer Source Clock Frequencies. See the PCF8523TimerClockFreq enum for options and associated time ranges.
numPeriods	The number of clkFreq periods (1-255) to count down.
lowPulseWidth	Optional: the length of time for the interrupt pin low pulse. See the PCF8523TimerIntPulse enum for options.

◆ enableCountdownTimer() [2/2]

void RTC_PCF8523::enableCountdownTimer	(	PCF8523TimerClockFreq	clkFreq,
		uint8_t	numPeriods
	)

Enable Countdown Timer using default interrupt low pulse width.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

clkFreq	One of the PCF8523's Timer Source Clock Frequencies. See the PCF8523TimerClockFreq enum for options and associated time ranges.
numPeriods	The number of clkFreq periods (1-255) to count down.

◆ disableCountdownTimer()

void RTC_PCF8523::disableCountdownTimer ( void )

Disable the Countdown Timer Interrupt on the PCF8523.

For simplicity, this function strictly disables Timer B by setting TBC to 0. The datasheet describes TBC as the Timer B on/off switch. Timer B is the only countdown timer implemented at this time. The following flags have no effect while TBC is off, they are not cleared:

TBM: Timer B will still be set to pulsed mode.
CTBIE: Timer B interrupt would be triggered if TBC were on.
CTBF: Timer B flag indicates that interrupt was triggered. Though typically used for non-pulsed mode, user may wish to query this later.

◆ deconfigureAllTimers()

void RTC_PCF8523::deconfigureAllTimers ( void )

Stop all timers, clear their flags and settings on the PCF8523.

This includes the Countdown Timer, Second Timer, and any CLKOUT square wave configured with writeSqwPinMode().

◆ calibrate()

void RTC_PCF8523::calibrate	(	Pcf8523OffsetMode	mode,
		int8_t	offset
	)

Compensate the drift of the RTC.

This method sets the "offset" register of the PCF8523, which can be used to correct a previously measured drift rate. Two correction modes are available:

PCF8523_TwoHours: Clock adjustments are performed on offset consecutive minutes every two hours. This is the most energy-efficient mode.
PCF8523_OneMinute: Clock adjustments are performed on offset consecutive seconds every minute. Extra adjustments are performed on the last second of the minute is abs(offset)>60.

The offset parameter sets the correction amount in units of roughly 4 ppm. The exact unit depends on the selected mode:

mode	offset unit
`PCF8523_TwoHours`	4.340 ppm = 0.375 s/day = 2.625 s/week
`PCF8523_OneMinute`	4.069 ppm = 0.352 s/day = 2.461 s/week

See the accompanying sketch pcf8523.ino for an example on how to use this method.

Parameters

mode	Correction mode, either `PCF8523_TwoHours` or `PCF8523_OneMinute`.
offset	Correction amount, from -64 to +63. A positive offset makes the clock slower.

The documentation for this class was generated from the following files:

src/RTClib.h
src/RTC_PCF8523.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ adjust()

◆ lostPower()

◆ initialized()

◆ now()

◆ isrunning()

◆ readSqwPinMode()

◆ writeSqwPinMode()

◆ enableSecondTimer()

◆ enableCountdownTimer() [1/2]

◆ enableCountdownTimer() [2/2]

◆ disableCountdownTimer()

◆ deconfigureAllTimers()

◆ calibrate()