Crate pcf8563[][src]

A platform agnostic Rust driver for the NXP PCF8563 real-time clock, based on the embedded-hal traits.

This driver allows you to:

  • read date and time, see get_datetime()
  • set date and time, see set_datetime()
  • set and enable alarms (minutes, hours, day, weekday)
  • set and enable timer with variable clock frequency
  • enable, disable and clear timer and alarm interrupts
  • enable and disable clock output with variable frequency

The device

The PCF8563 is a CMOS Real-Time Clock (RTC) and calendar optimized for low power consumption. A programmable clock output, interrupt output, and voltage-low detector are also provided. All addresses and data are transferred serially via a two-line bidirectional I2C-bus. Maximum bus speed is 400 kbit/s. The register address is incremented automatically after each written or read data byte.

Provides year, month, day, weekday, hours, minutes, and seconds based on a 32.768 kHz quartz crystal.

  • Century flag
  • Low backup current
  • Programmable clock output for peripheral devices (32.768 kHz, 1.024 kHz, 32 Hz, and 1 Hz)
  • Alarm and timer functions
  • Open-drain interrupt pin

Datasheet: PCF8563

Usage examples (see also examples folder)

Please find additional examples using hardware in this repository: examples


A new instance of the device is created like this:

use pcf8563::*;

let mut rtc = PCF::new(i2c);

The RTC doesn’t need any special setup, you can just start reading from/ writing to it. The wrapper function rtc_init() can be used for initialization of the device:


It clears all the bits in the two control registers, disabling all the interrupts, alarms, timer and special modes (power-on-reset override, external clock). It also sets the timer to the lowest possible frequency (1/60 Hz) for power saving.

Date and time

All the functions regarding setting and reading date and time are defined in the module:

  • set_datetime (sets all the date and time components at once)
  • get_datetime (reads all the date and time components at once)
  • set_time (sets only time components, all at once)

let mut rtc = PCF8563::new(i2c);

let now = DateTime {
    year: 21, 
    month: 4,
    weekday: 0, // Sunday
    day: 4, 
    hours: 7,
    minutes: 15,
    seconds: 00,


TO DO: add description of the century flag


All the alarm-related functions are defined in the module:

  • setting and reading single alarm components (minutes, hours, days, weekdays)
  • enabling and disabling single alarm components
  • enabling and disabling alarm interrupt (interrupt pin set to active when the alarm event occurs)
// set the alarm to 9:25, the alarm flag AF will be set at that time, 
// and the interrupt pin set to active

To check the alarm flag and clear after it’s set:

if rtc.get_alarm_flag().unwrap() {

Each alarm component has to be enabled separately: minutes, hours, day, weekday, but a wrapper function was defined to disable all the alarms at once:



All the timer-related functions are defined in the module

The timer can be set with a value up to 255, and one of the four clock frequencies can be chosen:

  • 4096 Hz
  • 64 Hz
  • 1 Hz (every second)
  • 1/60 Hz (every minute)

When the countdown ends, TF bit flag is set. The timer can also set the interrupt pin to active, and the output mode can be chosen between continuous and pulsating (please consult the datasheet for more information).

NOTE: if both AIE (alarm interrupt) and TIE (timer interrupt) settings are enabled, the status of the interrupt pin will be the result of an OR operation, i.e. will be active when either alarm or timer will trigger the interrupt event.

rtc.set_timer_frequency(TimerFreq::Timer_1Hz).unwrap(); // set frequency to 1 Hz
rtc.set_timer(30).unwrap(); // set timer to 30 ticks 
rtc.control_timer_interrupt(Control::On).unwrap(); // enable timer interrupt
rtc.control_timer(Control::On).unwrap(); // start the timer

// after 30 seconds the timer will set the TF flag and the interrupt pin will become active

rtc.control_timer(Control::Off).unwrap(); // disable the timer
rtc.clear_timer_flag().unwrap(); // clear the timer flag

Clock output

All the clock output-related functions are defined in the module

The clock output is a square wave with 50% duty cycle on the dedicated open drain pin (a 10k pull-up resistor between the pin and 3V3 is necessary). It can be used as input to a charge pump, as an external clock for a microcontroller, etc.

The clock output can be enabled or disabled, and the frequency can be set to:

  • 32768Hz (default setting)
  • 1024 Hz
  • 32 Hz
  • 1 Hz

On reset the clock output is enabled and set to 32768 Hz

rtc.set_clkout_frequency(ClkoutFreq::Clkout_1024Hz).unwrap(); // set the frequency
rtc.control_clkout(Control::On).unwrap(); // enable the clock output

RTC Control

All the other control functions are defined in the module

  • control_clock() - starts and stops the internal clock of the RTC
  • is_clock_running() - checks the STOP flag (if cleared, the clock is running)
  • get_voltage_low_flag() - checks whether the VL flag was triggered (see datasheet for details)
  • clear_voltage_low_flag() - clears the voltage low detection flag
  • control_ext_clk_test_mode() - enables the EXT_CLK test mode (see datasheet for details)
  • control_power_on_reset_override() - enables the POR override mode (see datasheet for details)



Container to hold date and time components.


PCF8563 driver


Container to hold time components only (for clock applications without calendar functions).



The four possible clock output frequency settings


Two possible choices, used for various enable/disable bit flags


All possible errors in this crate


Two possible timer interrupt output modes


Four possible timer frequency settings.