Crate mcp794xx

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:

Read and set date and time. See: datetime().
Read and set date. See: date().
Read and set time. See: time().
Read and set date and time individual elements. For example, see: year().
Enable and disable the real-time clock. See: enable().
Read whether the oscillator is running. See: is_oscillator_running().
Read whether the current year is a leap year. See: is_leap_year().
Enable and disable the usage of an external oscillator source. See: enable_external_oscillator().
Set the output pin logic level. See: set_output_pin().
Enable and disable coarse trim. See: enable_coarse_trim().
Set trimming value. See: set_trimming().
Power:
- Read whether the power has failed. See: has_power_failed().
- Clear the has-power-failed flag. See: clear_power_failed().
- Read the date/time when power went down. See: get_power_down_datetime().
- Read the date/time when power went back up. See: get_power_up_datetime().
- Enable and disable usage of backup battery power. See: enable_backup_battery_power().
SRAM:
- Read and write byte to SRAM. See: read_sram_byte().
- Read and write byte array to SRAM. See: read_sram_data().
- Read current position from SRAM. See: read_sram_current_byte().
Alarms:
- Enable and disable alarms. See: enable_alarm().
- Set alarms with several matching policies and output pin polarities. See: set_alarm().
- Read whether alarms have matched. See: has_alarm_matched().
- Clear flag indicating that alarms have matched. See: clear_alarm_matched_flag().
Wave generation:
- Enable and disable the square-wave generation. See: enable_square_wave().
- Select the square-wave frequency. See: set_square_wave_frequency().
Protected EEPROM:
- Read and write byte to the protected EEPROM. See: read_protected_eeprom_byte().
- Read and write byte array to the protected EEPROM. See: read_protected_eeprom_data().
- Read EUI-48. See: read_eui48().
- Read EUI-64. See: read_eui64().
EEPROM:
- Read and write byte to the EEPROM. See: read_eeprom_byte().
- Read and write byte array to the EEPROM. See: read_eeprom_data().
- Set EEPROM block write protection. See: set_eeprom_write_protection().
- Read current position from the EEPROM. See: read_eeprom_current_byte().

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