RTClib
Public Member Functions | Static Public Member Functions | List of all members
RTC_PCF8523 Class Reference

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

#include <RTClib.h>

Public Member Functions

boolean begin (void)
 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...
 
boolean lostPower (void)
 Check the status register Oscillator Stop flag to see if the PCF8523 stopped due to power loss. More...
 
boolean initialized (void)
 Check control register 3 to see if we've run adjust() yet (setting the date/time and battery switchover mode) 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...
 

Static Public Member Functions

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

Detailed Description

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

Member Function Documentation

◆ begin()

boolean RTC_PCF8523::begin ( void  )

Start I2C for the PCF8523 and test succesful connection.

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
dtDateTime to set

◆ lostPower()

boolean 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()

boolean 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 ( )
static

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
modeThe 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
clkFreqOne of the PCF8523's Timer Source Clock Frequencies. See the PCF8523TimerClockFreq enum for options and associated time ranges.
numPeriodsThe number of clkFreq periods (1-255) to count down.
lowPulseWidthOptional: 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
clkFreqOne of the PCF8523's Timer Source Clock Frequencies. See the PCF8523TimerClockFreq enum for options and associated time ranges.
numPeriodsThe 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
modeCorrection mode, either PCF8523_TwoHours or PCF8523_OneMinute.
offsetCorrection amount, from -64 to +63. A positive offset makes the clock slower.

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