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

Initialization

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:

rtc.rtc_init().unwrap();

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 datetime.rs 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,
};

rtc.set_datetime(&now).unwrap();

TO DO: add description of the century flag

Alarm

All the alarm-related functions are defined in the alarm.rs 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
rtc.set_alarm_minutes(25).unwrap();
rtc.set_alarm_hours(9).unwrap();
rtc.control_alarm_minutes(Control::On).unwrap();
rtc.control_alarm_hours(Control::On).unwrap();
rtc.control_alarm_interrupt(Control::On).unwrap();

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

if rtc.get_alarm_flag().unwrap() {
    rtc.clear_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:

rtc.disable_all_alarms().unwrap();

Timer

All the timer-related functions are defined in the timer.rs 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 clkout.rs 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 control.rs 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)

Structs

DateTime	Container to hold date and time components.
PCF8563	PCF8563 driver
Time	Container to hold time components only (for clock applications without calendar functions).

Enums

ClkoutFreq	The four possible clock output frequency settings
Control	Two possible choices, used for various enable/disable bit flags
Error	All possible errors in this crate
InterruptOutput	Two possible timer interrupt output modes
TimerFreq	Four possible timer frequency settings.

Crate pcf8563⎘[−][src]

Crate pcf8563[−][src]