[−][src]Crate mcp794xx

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 in 12-hour and 24-hour format. See: get_datetime().
Read and set date and time individual elements. For example, see: get_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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{Mcp794xx, DateTime, Hours, Rtcc};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let datetime = DateTime {
                          year: 2018,
                          month: 8,
                          day: 15,
                          weekday: 4,
                          hour: Hours::H24(19),
                          minute: 59,
                          second: 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.

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{Mcp794xx, DateTime, Hours, Rtcc};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
let datetime = DateTime {
                          year: 2018,
                          month: 8,
                          day: 15,
                          weekday: 4,
                          hour: Hours::H24(19),
                          minute: 59,
                          second: 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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{Mcp794xx, Hours, Rtcc};

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

let dt = rtc.get_datetime().unwrap();

// The hours depend on the RTC running mode
match  dt.hour {
    Hours::H24(h) => println!("{}-{}-{}, {} {}:{}:{}", dt.year,
                              dt.month, dt.day, dt.weekday,
                              h, dt.minute, dt.second),
    Hours::AM(h) => println!("{}-{}-{}, {} {}:{}:{} AM", dt.year,
                             dt.month, dt.day, dt.weekday,
                             h, dt.minute, dt.second),
    Hours::PM(h) => println!("{}-{}-{}, {} {}:{}:{} PM", dt.year,
                             dt.month, dt.day, dt.weekday,
                             h, dt.minute, dt.second),
}
// This will print something like: 2018-08-15, 4 19:59:58

Set / Get the year

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{ Mcp794xx, Hours, Rtcc };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Mcp794xx::new_mcp7940n(dev);
rtc.set_year(2019).unwrap();
let year = rtc.get_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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{ Mcp794xx, SqWFreq };

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{Mcp794xx, Hours, Alarm, AlarmDateTime, AlarmMatching, AlarmOutputPinPolarity};

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::{Mcp794xx, OutputPinLevel};

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

Set trimming

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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

extern crate linux_embedded_hal as hal;
extern crate mcp794xx;
use mcp794xx::Mcp794xx;

let dev = hal::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
DateTime	Date and time
Mcp794xx	MCP794xx RTCC driver
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

Rtcc	Real-Time Clock / Calendar