Rust PCF8563 Real-Time Clock Driver

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

This driver allows you to: - Read and set date and time. See: get_datetime and set_datetime - Set only the time (HH:MM:SS) for clock applications without the calendar function - Read and set the alarm minutes, hours, day and weekday - Enable the alarm components separately - Disable the alarm components separately or all at once - Set the timer and timer frequency - Set clock output frequency and enable/disable clock output - Enable and disable alarm interrupt and timer interrupt - Read and set various other control functions

TO DO:

[ ] test with other MCUs
[ ] add get_timer_frequency function
[ ] add get_timer_interrupt_mode function
[ ] add get_clkout_frequency function
[ ] add an nRF example
[ ] add a Linux example (Rasberry Pi)

How this driver was ~~won~~ written

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

To use this driver, import this crate and an embedded_hal implementation, then instantiate the device.

Please find additional examples using hardware in this repository: [examples]

```rust

![no_main]

![no_std]

use cortexm; use cortexmrt::entry; use panichalt as ; use stm32l4xxhal::{ delay::Delay, prelude::*, serial::{Config, Serial}, i2c::I2c, };

use pcf8563::*;

use core::fmt::Write;

[entry]

fn main() -> ! { let cp = cortexm::Peripherals::take().unwrap(); let dp = stm32l4xxhal::stm32::Peripherals::take().unwrap();

// set up the flash, reset & clock control, and power control
// set up the clocks    
// set up GPIO ports
// set up LED for some blinking
// set up USART
// get the delay provider    
// set up I2C bus

// set up the PCF8563 device
let mut rtc = PCF8563::new(i2c); 

// prepare date and time to be set
let now = DateTime {
    year: 21, // 2021
    month: 4, // April
    weekday: 0, // Sunday
    day: 4, 
    hours: 16,
    minutes: 52,
    seconds: 00,
};

// set date and time in one go
rtc.set_datetime(&now).unwrap();

loop {
    led.set_high().ok();
    delay.delay_ms(500 as u32);

    //get date and time in one go
    let time = rtc.get_datetime().unwrap();

    writeln!(tx, "{:02}/{:02}/{:02} {:02}:{:02}:{:02} day {}\r", 
            time.year, time.month, time.day, 
            time.hours, time.minutes, time.seconds,
            time.weekday).unwrap();

    led.set_low().ok();
    delay.delay_ms(500 as u32);

    }

} ```

Support

For questions, issues, feature requests, and other changes, please file an issue in the github project.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.