Real-time clock unit using PCF8563 compatible chip (BM8563/HYM8563) More...

#include <unit_PCF8563.hpp>

Inheritance diagram for m5::unit::UnitPCF8563:

Classes
struct	config_t
	Settings for begin. More...

Public Types
using	irq_callback_t = void (*)()
	IRQ callback type.

Public Member Functions
	UnitPCF8563 (const uint8_t addr=DEFAULT_ADDRESS)

virtual bool	begin () override

virtual void	update (const bool force=false) override

Settings for begin
config_t	config () const
	Gets the configuration.

void	config (const config_t &cfg)
	Set the configuration.

Date/Time
bool	readTime (pcf8563::rtc_time_t &time)
	Read time from RTC.

bool	writeTime (const pcf8563::rtc_time_t &time)
	Write time to RTC.

bool	readDate (pcf8563::rtc_date_t &date)
	Read date from RTC.

bool	writeDate (const pcf8563::rtc_date_t &date)
	Write date to RTC.

bool	readDateTime (pcf8563::rtc_datetime_t &dt)
	Read date and time from RTC.

bool	writeDateTime (const pcf8563::rtc_datetime_t &dt)
	Write date and time to RTC.

bool	readDateTime (struct tm &t)
	Read date and time from RTC into struct tm.

bool	writeDateTime (const struct tm &t)
	Write date and time to RTC from struct tm.

Alarm/Timer
Note About IRQ/Alarm/Timer: These functions configure the PCF8563 chip's internal alarm/timer registers and interrupt flags via I2C. When triggered, the chip drives its INT pin (open-drain, active LOW). The INT pin is not wired on standard GROVE/Port A/B/C connectors (4-pin: GND, VCC, SDA, SCL only). Two modes are supported via config_t: Polling mode (default, `polling=true`): update() periodically reads the IRQ status register via I2C (every 500ms) and invokes the callback. Works without the INT pin (GROVE compatible). Hardware interrupt mode (`polling=false`, `int_pin` set): begin() calls attachInterrupt() on the specified GPIO. The ISR sets an internal flag; update() detects it and invokes the callback. Requires a direct connection from the PCF8563 INT pin to a host GPIO. In both modes, callbacks (on_alarm / on_timer) are called from update(), never from an ISR context. Set them in config_t before calling begin().
bool	writeAlarm (const pcf8563::rtc_time_t &time, const pcf8563::rtc_date_t &date)
	Set alarm and enable interrupt.

bool	readAlarm (pcf8563::rtc_time_t &time, pcf8563::rtc_date_t &date)
	Read alarm settings.

bool	readAlarmInterrupt (bool &enabled)
	Read alarm interrupt enable state.

bool	writeAlarmInterrupt (const bool enabled)
	Write alarm interrupt enable state.

bool	readAlarmFlag (bool &fired)
	Read alarm flag.

bool	clearAlarmFlag ()
	Clear alarm flag (AF bit)

uint32_t	writeTimer (const uint32_t msec, const bool repeat=false)
	Set countdown timer with millisecond duration.

bool	readTimerControl (bool &enabled, pcf8563::TimerClock &clock)
	Read timer control settings.

bool	writeTimerControl (const bool enabled, const pcf8563::TimerClock clock)
	Write timer control settings.

bool	readTimerValue (uint8_t &count)
	Read timer countdown value.

bool	writeTimerValue (const uint8_t count)
	Write timer countdown value.

bool	readTimerInterrupt (bool &enabled)
	Read timer interrupt enable state.

bool	writeTimerInterrupt (const bool enabled)
	Write timer interrupt enable state.

bool	readTimerFlag (bool &fired)
	Read timer flag.

bool	clearTimerFlag ()
	Clear timer flag (TF bit)

bool	readTimerPeriodic (bool &periodic)
	Read timer periodic mode (TI_TP bit)

bool	writeTimerPeriodic (const bool periodic)
	Write timer periodic mode (TI_TP bit)

Clock Control
bool	readStop (bool &stopped)
	Read RTC clock stop state.

bool	writeStop (const bool stop)
	Write RTC clock stop state.

Status
bool	readVoltLow (bool &low)
	Read voltage-low flag (battery backup status)

Protected Member Functions
bool	read_datetime (pcf8563::rtc_date_t date, pcf8563::rtc_time_t time)
	Read time and/or date registers (nullable pointer support)

bool	write_datetime (const pcf8563::rtc_date_t date, const pcf8563::rtc_time_t time)
	Write time and/or date registers (nullable pointer support)

bool	read_control2 (uint8_t &val)
	Read CONTROL2 register.

bool	write_control2_bits (const uint8_t mask, const uint8_t bits)
	Write CONTROL2 register with bit mask (read-modify-write)

I2C register access (stop bit centralized here for experimentation)
bool	read_register (const uint8_t reg, uint8_t *buf, const size_t len)

bool	read_register8 (const uint8_t reg, uint8_t &val)

bool	write_register (const uint8_t reg, const uint8_t *buf, const size_t len)

bool	write_register8 (const uint8_t reg, const uint8_t val)

Detailed Description

Real-time clock unit using PCF8563 compatible chip (BM8563/HYM8563)

Member Function Documentation

◆ clearAlarmFlag()

bool m5::unit::UnitPCF8563::clearAlarmFlag ( )

Clear alarm flag (AF bit)

Returns: True if successful

◆ clearTimerFlag()

bool m5::unit::UnitPCF8563::clearTimerFlag ( )

Clear timer flag (TF bit)

Returns: True if successful

◆ readAlarm()

bool m5::unit::UnitPCF8563::readAlarm	(	pcf8563::rtc_time_t &	time,
		pcf8563::rtc_date_t &	date )

Read alarm settings.

Parameters

[out]	time	Alarm time (minutes, hours; seconds always -1). Disabled fields are -1.
[out]	date	Alarm date (date, weekDay; year/month unused). Disabled fields are -1.

Returns: True if successful

◆ readAlarmFlag()

bool m5::unit::UnitPCF8563::readAlarmFlag ( bool & fired )

Read alarm flag.

Parameters

[out] fired True if alarm has fired (AF bit)

Returns: True if successful

◆ readAlarmInterrupt()

bool m5::unit::UnitPCF8563::readAlarmInterrupt ( bool & enabled )

Read alarm interrupt enable state.

Parameters

[out] enabled True if alarm interrupt is enabled (AIE bit)

Returns: True if successful

◆ readDate()

bool m5::unit::UnitPCF8563::readDate ( pcf8563::rtc_date_t & date )

Read date from RTC.

Parameters

[out] date Date (year, month, date, weekDay)

Returns: True if successful

◆ readDateTime() [1/2]

bool m5::unit::UnitPCF8563::readDateTime ( pcf8563::rtc_datetime_t & dt )

Read date and time from RTC.

Parameters

[out] dt DateTime

Returns: True if successful

◆ readDateTime() [2/2]

bool m5::unit::UnitPCF8563::readDateTime ( struct tm & t )

Read date and time from RTC into struct tm.

Parameters

[out] t struct tm (date and time fields are set; tm_isdst = -1)

Returns: True if successful

◆ readStop()

bool m5::unit::UnitPCF8563::readStop ( bool & stopped )

Read RTC clock stop state.

Parameters

[out] stopped True if RTC clock is stopped (STOP bit)

Returns: True if successful

◆ readTime()

bool m5::unit::UnitPCF8563::readTime ( pcf8563::rtc_time_t & time )

Read time from RTC.

Parameters

[out] time Time (hours, minutes, seconds)

Returns: True if successful

◆ readTimerControl()

bool m5::unit::UnitPCF8563::readTimerControl	(	bool &	enabled,
		pcf8563::TimerClock &	clock )

Read timer control settings.

Parameters

[out]	enabled	True if timer is enabled (TE bit)
[out]	clock	Timer clock source (TD bits)

Returns: True if successful

◆ readTimerFlag()

bool m5::unit::UnitPCF8563::readTimerFlag ( bool & fired )

Read timer flag.

Parameters

[out] fired True if timer has fired (TF bit)

Returns: True if successful

◆ readTimerInterrupt()

bool m5::unit::UnitPCF8563::readTimerInterrupt ( bool & enabled )

Read timer interrupt enable state.

Parameters

[out] enabled True if timer interrupt is enabled (TIE bit)

Returns: True if successful

◆ readTimerPeriodic()

bool m5::unit::UnitPCF8563::readTimerPeriodic ( bool & periodic )

Read timer periodic mode (TI_TP bit)

Parameters

[out] periodic True if periodic (auto-reload), false if one-shot

Returns: True if successful

Note: When periodic, the countdown timer automatically restarts from the preset value each time it reaches zero. TF flag is set each time.

◆ readTimerValue()

bool m5::unit::UnitPCF8563::readTimerValue ( uint8_t & count )

Read timer countdown value.

Parameters

[out] count Countdown value (0-255)

Returns: True if successful

◆ readVoltLow()

bool m5::unit::UnitPCF8563::readVoltLow ( bool & low )

Read voltage-low flag (battery backup status)

Parameters

[out] low True if voltage is low (VL bit in seconds register)

Returns: True if successful

◆ writeAlarm()

bool m5::unit::UnitPCF8563::writeAlarm	(	const pcf8563::rtc_time_t &	time,
		const pcf8563::rtc_date_t &	date )

Set alarm and enable interrupt.

Parameters

time	Alarm time (minutes, hours). Negative fields are disabled.
date	Alarm date (date, weekDay). Negative fields are disabled.

Returns: True if successful

Note: Clears alarm flag, writes alarm registers, and enables alarm interrupt if any field is non-negative. Disables alarm interrupt if all fields are negative.

◆ writeAlarmInterrupt()

bool m5::unit::UnitPCF8563::writeAlarmInterrupt ( const bool enabled )

Write alarm interrupt enable state.

Parameters

enabled True to enable alarm interrupt (AIE bit)

Returns: True if successful

◆ writeDate()

bool m5::unit::UnitPCF8563::writeDate ( const pcf8563::rtc_date_t & date )

Write date to RTC.

Parameters

date	Date (year, month, date, weekDay)

Returns: True if successful

◆ writeDateTime() [1/2]

bool m5::unit::UnitPCF8563::writeDateTime ( const pcf8563::rtc_datetime_t & dt )

Write date and time to RTC.

Parameters

dt DateTime

Returns: True if successful

◆ writeDateTime() [2/2]

bool m5::unit::UnitPCF8563::writeDateTime ( const struct tm & t )

Write date and time to RTC from struct tm.

Parameters

t struct tm

Returns: True if successful

◆ writeStop()

bool m5::unit::UnitPCF8563::writeStop ( const bool stop )

Write RTC clock stop state.

Parameters

stop	True to stop RTC clock, false to start

Returns: True if successful

Note: While stopped, the prescaler (F2-F14) is held in reset and no 1 Hz ticks are generated. The first increment after restart occurs approximately 0.508 seconds later. CLKOUT 32.768 kHz is unaffected.

◆ writeTime()

bool m5::unit::UnitPCF8563::writeTime ( const pcf8563::rtc_time_t & time )

Write time to RTC.

Parameters

time	Time (hours, minutes, seconds)

Returns: True if successful

◆ writeTimer()

uint32_t m5::unit::UnitPCF8563::writeTimer	(	const uint32_t	msec,
		const bool	repeat = false )

Set countdown timer with millisecond duration.

Parameters

msec	Duration in milliseconds (0 to disable)
repeat	True for periodic (auto-reload via TI_TP), false for one-shot

Returns: Actual duration in milliseconds (0 if disabled)

Note: Automatically selects Hz1 (< 270s) or HzPM (>= 270s) clock source. Clears timer/alarm flags, enables timer and timer interrupt. Maximum: 255 minutes (15,300,000 ms).

◆ writeTimerControl()

bool m5::unit::UnitPCF8563::writeTimerControl	(	const bool	enabled,
		const pcf8563::TimerClock	clock )

Write timer control settings.

Parameters

enabled	True to enable timer (TE bit)
clock	Timer clock source (TD bits)

Returns: True if successful

◆ writeTimerInterrupt()

bool m5::unit::UnitPCF8563::writeTimerInterrupt ( const bool enabled )

Write timer interrupt enable state.

Parameters

enabled True to enable timer interrupt (TIE bit)

Returns: True if successful

◆ writeTimerPeriodic()

bool m5::unit::UnitPCF8563::writeTimerPeriodic ( const bool periodic )

Write timer periodic mode (TI_TP bit)

Parameters

periodic True for periodic (auto-reload), false for one-shot

Returns: True if successful

Note: When periodic, the countdown timer automatically restarts from the preset value each time it reaches zero. TF flag is set each time.

◆ writeTimerValue()

bool m5::unit::UnitPCF8563::writeTimerValue ( const uint8_t count )

Write timer countdown value.

Parameters

count Countdown value (0-255)

Returns: True if successful

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ clearAlarmFlag()

◆ clearTimerFlag()

◆ readAlarm()

◆ readAlarmFlag()

◆ readAlarmInterrupt()

◆ readDate()

◆ readDateTime() [1/2]

◆ readDateTime() [2/2]

◆ readStop()

◆ readTime()

◆ readTimerControl()

◆ readTimerFlag()

◆ readTimerInterrupt()

◆ readTimerPeriodic()

◆ readTimerValue()

◆ readVoltLow()

◆ writeAlarm()

◆ writeAlarmInterrupt()

◆ writeDate()

◆ writeDateTime() [1/2]

◆ writeDateTime() [2/2]

◆ writeStop()

◆ writeTime()

◆ writeTimer()

◆ writeTimerControl()

◆ writeTimerInterrupt()

◆ writeTimerPeriodic()

◆ writeTimerValue()