Crate mcp794xx

Source
Expand description

This is a platform agnostic Rust driver for the MCP794xx real-time clock / calendar family, based on the embedded-hal traits.

This driver allows you to:

Introductory blog post

§The devices

This driver is compatible with the devices: MCP7940N, MCP7940M, MCP79400, MCP79401, MCP79402, MCP79410, MCP79411 and MCP79412.

The Real-Time Clock/Calendar (RTCC) tracks time using internal counters for hours, minutes, seconds, days, months, years, and day of week. Alarms can be configured on all counters up to and including months. For usage and configuration, the devices support I2C communications up to 400 kHz.

The open-drain, multi-functional output can be configured to assert on an alarm match, to output a selectable frequency square wave, or as a general purpose output.

The devices are designed to operate using a 32.768 kHz tuning fork crystal with external crystal load capacitors. On-chip digital trimming can be used to adjust for frequency variance caused by crystal tolerance and temperature.

SRAM and timekeeping circuitry are powered from the back-up supply when main power is lost, allowing the device to maintain accurate time and the SRAM contents. The times when the device switches over to the back-up supply and when primary power returns are both logged by the power-fail time-stamp.

Some of the devices feature 1 Kbit of internal non-volatile EEPROM with software write-protectable regions. There is an additional 64 bits of protected non-volatile memory which is only writable after an unlock sequence, making it ideal for storing a unique ID or other critical information.

Some of the devices offer a pre-programmed with EUI-48 and EUI-64 addresses. Custom programming is also available.

Datasheets:

§Usage examples (see also examples folder)

To use this driver, import this crate and an embedded_hal implementation, then instantiate the appropriate device. The following examples use an instance of the device MCP7940N except when using features specific to another IC.

Please find additional examples using hardware in this repository: driver-examples

§Create a driver instance for the MCP7940N

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let rtc = Mcp794xx::new_mcp7940n(dev);
// do something...

// get the I2C device back
let dev = rtc.destroy();

§Set the current date and time at once

use linux_embedded_hal::I2cdev;
use mcp794xx::{Mcp794xx, NaiveDate, Hours, DateTimeAccess};

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let datetime = NaiveDate::from_ymd(2018, 8, 20).and_hms(19, 59, 58);
rtc.set_datetime(&datetime).unwrap();
rtc.enable().unwrap();

§Change the date and time at once

Note that before changing the date/time the oscillators must be disabled and you must be wait unter the oscillator reports not to be running anymore.

use linux_embedded_hal::I2cdev;
use mcp794xx::{Mcp794xx, NaiveDate, Hours, DateTimeAccess};

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let datetime = NaiveDate::from_ymd(2018, 8, 20).and_hms(19, 59, 58);
rtc.set_datetime(&datetime).unwrap();
rtc.enable().unwrap();
// ...
// after running for a while disable before changing the time.

rtc.disable().unwrap();
while (rtc.is_oscillator_running().unwrap()) {
    // some delay...
}
// now you can change the date/time
rtc.set_datetime(&datetime).unwrap();
rtc.enable().unwrap();

§Get the current date and time at once

use linux_embedded_hal::I2cdev;
use mcp794xx::{Mcp794xx, DateTimeAccess, Datelike, Timelike};

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);

let dt = rtc.datetime().unwrap();
println!("{}-{}-{}, {} {}:{}:{}", dt.year(),
         dt.month(), dt.day(), dt.weekday().number_from_sunday(),
         dt.hour(), dt.minute(), dt.second());
// This will print something like: 2018-08-15, 4 19:59:58

§Set / Get the year

use linux_embedded_hal::I2cdev;
use mcp794xx::{ Mcp794xx, Hours, Rtcc };

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.set_year(2019).unwrap();
let year = rtc.year().unwrap();
println!("Year: {}", year);

Similar methods exist for month, day, weekday, hours, minutes and seconds.

§Enable the square-wave output with a frequency of 4.096Hz

use linux_embedded_hal::I2cdev;
use mcp794xx::{ Mcp794xx, SqWFreq };

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.set_square_wave_frequency(SqWFreq::Hz4_096).unwrap();
rtc.enable_square_wave().unwrap();

§Set the alarm 1 to each week on a week day at a specific time

use linux_embedded_hal::I2cdev;
use mcp794xx::{Mcp794xx, Hours, Alarm, AlarmDateTime, AlarmMatching, AlarmOutputPinPolarity};

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let datetime = AlarmDateTime {
    month: 9,
    day: 17,
    weekday: 1,
    hour: Hours::H24(7),
    minute: 2,
    second: 15
};
rtc.set_alarm(
    Alarm::One,
    datetime,
    AlarmMatching::WeekdayMatches,
    AlarmOutputPinPolarity::High
).unwrap();
rtc.enable_alarm(Alarm::One).unwrap();

§Set output pin

use linux_embedded_hal::I2cdev;
use mcp794xx::{Mcp794xx, OutputPinLevel};

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.set_output_pin(OutputPinLevel::High).unwrap();

§Set trimming

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.set_trimming(-50).unwrap();
rtc.enable_coarse_trim().unwrap();

§Check power down date and time

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.enable_backup_battery_power().unwrap();
loop {
    if rtc.has_power_failed().unwrap() {
        let datetime = rtc.get_power_down_datetime().unwrap();
        rtc.clear_power_failed().unwrap();
        //...
    }
    //...
}

§Read/write SRAM

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let value = rtc.read_sram_byte(0x20).unwrap();
let data = [1, 2, 3, 4, 5];
rtc.write_sram_data(0x25, &data).unwrap();

§Read/write EEPROM and protected EEPROM

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp79410(dev);
let value = rtc.read_eeprom_byte(0x01).unwrap();
let data = [1, 2, 3, 4, 5];
rtc.write_eeprom_data(0x01, &data).unwrap();

rtc.write_protected_eeprom_data(0xF0, &data).unwrap();

§Read EUI-64

use linux_embedded_hal::I2cdev;
use mcp794xx::Mcp794xx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp79402(dev);
let value = rtc.read_eui64().unwrap();

Modules§

ic
IC markers
interface
Communication interface
marker
Feature markers

Structs§

AlarmDateTime
Alarm date/time
Mcp794xx
MCP794xx RTCC driver
NaiveDate
ISO 8601 calendar date without timezone. Allows for every proleptic Gregorian date from Jan 1, 262145 BCE to Dec 31, 262143 CE. Also supports the conversion from ISO 8601 ordinal and week date.
NaiveDateTime
ISO 8601 combined date and time without timezone.
NaiveTime
ISO 8601 time without timezone. Allows for the nanosecond precision and optional leap second representation.
PowerFailDateTime
Power fail date/time

Enums§

Alarm
Alarm selection
AlarmMatching
Alarm trigger rate
AlarmOutputPinPolarity
Alarm interrupt output pin polarity
EepromWriteProtection
EEPROM block write protection
Error
All possible errors in this crate
Hours
Hours in either 12-hour (AM/PM) or 24-hour format
OutputPinLevel
General purpose output pin logic level
SqWFreq
Square-wave output frequency

Traits§

DateTimeAccess
Real-Time Clock / Calendar DateTimeAccess trait to read/write a complete date/time.
Datelike
The common set of methods for date component.
Rtcc
Real-Time Clock / Calendar trait
Timelike
The common set of methods for time component.