[][src]Crate ds323x

This is a platform agnostic Rust driver for the DS3231, DS3232 and DS3234 extremely accurate real-time clocks, based on the embedded-hal traits.

This driver allows you to:

The devices

This driver is compatible with the DS3231 and DS3232 I2C devices and the DS3234 SPI device.

DS3231

The DS3231 is a low-cost, extremely accurate I2C real-time clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal.

The device incorporates a battery input, and maintains accurate timekeeping when main power to the device is interrupted. The integration of the crystal resonator enhances the long-term accuracy of the device as well as reduces the piece-part count in a manufacturing line. The DS3231 is available in commercial and industrial temperature ranges, and is offered in a 16-pin, 300-mil SO package.

The RTC maintains seconds, minutes, hours, day, date, month, and year information. The date at the end of the month is automatically adjusted for months with fewer than 31 days, including corrections for leap year. The clock operates in either the 24-hour or 12-hour format with an AM/PM indicator. Two programmable time-of-day alarms and a programmable square-wave output are provided. Address and data are transferred serially through an I2C bidirectional bus.

A precision temperature-compensated voltage reference and comparator circuit monitors the status of VCC to detect power failures, to provide a reset output, and to automatically switch to the backup supply when necessary. Additionally, the RST pin is monitored as a pushbutton input for generating a μP reset.

DS3232

The DS3232 is a low-cost temperature-compensated crystal oscillator (TCXO) with a very accurate, temperature-compensated, integrated real-time clock (RTC) and 236 bytes of battery-backed SRAM.

Additionally, the DS3232 incorporates a battery input and maintains accurate timekeeping when main power to the device is interrupted. The integration of the crystal resonator enhances the long-term accuracy of the device as well as reduces the piece-part count in a manufacturing line. The DS3232 is available in commercial and industrial temperature ranges, and is offered in an industry-standard 20-pin, 300-mil SO package.

The RTC maintains seconds, minutes, hours, day, date, month, and year information. The date at the end of the month is automatically adjusted for months with fewer than 31 days, including corrections for leap year. The clock operates in either the 24-hour or 12-hour format with an AM/PM indicator. Two programmable time-of-day alarms and a programmable square-wave output are provided. Address and data are transferred serially through an I2C bidirectional bus.

A precision temperature-compensated voltage reference and comparator circuit monitors the status of VCC to detect power failures, to provide a reset output, and to automatically switch to the backup supply when necessary. Additionally, the RST pin is monitored as a pushbutton input for generating a μP reset.

DS3234

The DS3234 is a low-cost, extremely accurate SPI bus real-time clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal.

The DS3234 incorporates a precision, temperature-compensated voltage reference and comparator circuit to monitor VCC. When VCC drops below the power-fail voltage (VPF), the device asserts the RST output and also disables read and write access to the part when VCC drops below both VPF and VBAT. The RST pin is monitored as a pushbutton input for generating a μP reset. The device switches to the backup supply input and maintains accurate timekeeping when main power to the device is interrupted. The integration of the crystal resonator enhances the long-term accuracy of the device as well as reduces the piece-part count in a manufacturing line. The DS3234 is available in commercial and industrial temperature ranges, and is offered in an industry-standard 300-mil, 20-pin SO package.

The DS3234 also integrates 256 bytes of battery-backed SRAM. In the event of main power loss, the contents of the memory are maintained by the power source connected to the V BAT pin. The RTC maintains seconds, minutes, hours, day, date, month, and year information. The date at the end of the month is automatically adjusted for months with fewer than 31 days, including corrections for leap year. The clock operates in either the 24-hour or 12-hour format with AM/PM indicator. Two programmable time-of-day alarms and a programmable square-wave output are provided. Address and data are transferred serially by an SPI bidirectional bus.

Datasheets:

Usage examples (see also examples folder)

To use this driver, import this crate and an embedded_hal implementation, then instantiate the appropriate device. In the following 3 examples an instance of the devices DS3231, DS3232 and DS3234 will be created as an example. The rest of examples will use the DS3231 as an example, except when using features specific to another IC, for example, RAM access which is not available in the DS3231 device.

Create a driver instance for the DS3231

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let rtc = Ds323x::new_ds3231(dev);
// do something...

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

Create a driver instance for the DS3232

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let rtc = Ds323x::new_ds3232(dev);
// do something...

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

Create a driver instance for the DS3234

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::Spidev::open("/dev/spidev0.0").unwrap();
let chip_select = hal::Pin::new(24);
let rtc = Ds323x::new_ds3234(dev, chip_select);
// do something...

// get the SPI device and chip select pin back
let (dev, chip_select) = rtc.destroy_ds3234();

Set the current date and time at once

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, DateTime, Hours };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let datetime = DateTime {
                          year: 2018,
                          month: 08,
                          day: 15,
                          weekday: 4,
                          hour: Hours::H24(19),
                          minute: 59,
                          second: 58
               };
rtc.set_datetime(&datetime).unwrap();

Get the current date and time at once

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, Hours };

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

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

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

Get the year

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, Hours };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let year = rtc.get_year().unwrap();
println!("Year: {}", year);

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

Set the year

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, Hours };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
rtc.set_year(2018).unwrap();

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

Enable/disable the device

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
rtc.disable().unwrap(); // stops the clock
let is_running = rtc.is_running().unwrap();
println!("Is running: {}", is_running); // will print false
rtc.enable().unwrap(); // set clock to run
println!("Is running: {}", is_running); // will print true

Read the temperature

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let temperature = rtc.get_temperature().unwrap();

Read busy status

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let is_busy = rtc.is_busy().unwrap();

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

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, SqWFreq };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
rtc.set_square_wave_frequency(SqWFreq::_4_096Hz).unwrap();
// The same output pin can be used for interrupts or as square-wave output
rtc.use_int_sqw_output_as_square_wave().unwrap();
rtc.enable_square_wave().unwrap();

Enable the 32kHz output except when on battery power

Additionally enabling the output depending on the power source is only available for the devices DS3232 and DS3234.

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, SqWFreq };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3232(dev);
rtc.disable_32khz_output_on_battery().unwrap(); // only available for DS3232 and DS3234
rtc.enable_32khz_output().unwrap();

Set the aging offset

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::Ds323x;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
rtc.set_aging_offset(-15).unwrap();

Set the temperature conversion rate to once every 128 seconds

This is only available for the devices DS3232 and DS3234.

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, TempConvRate };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3232(dev);
rtc.set_temperature_conversion_rate(TempConvRate::_128s).unwrap();

Set the Alarm1 to each week on a week day at a specific time

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, Hours, WeekdayAlarm1, Alarm1Matching };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let alarm1 = WeekdayAlarm1 {
    weekday: 1,
    hour: Hours::H24(7),
    minute: 2,
    second: 15
};
rtc.set_alarm1_weekday(alarm1, Alarm1Matching::AllMatch).unwrap();

Set the Alarm2 to each day at the same time and enable interrupts on output

The INT/SQW output pin will be set to 1 when it the alarm matches.

extern crate linux_embedded_hal as hal;
extern crate ds323x;
use ds323x::{ Ds323x, Hours, DayAlarm2, Alarm2Matching };

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let mut rtc = Ds323x::new_ds3231(dev);
let alarm2 = DayAlarm2 {
    day: 1, // does not matter given the chosen matching
    hour: Hours::AM(11),
    minute: 2
};
rtc.set_alarm2_day(alarm2, Alarm2Matching::HoursAndMinutesMatch).unwrap();
rtc.use_int_sqw_output_as_interrupt().unwrap();
rtc.enable_alarm2_interrupts().unwrap();

Modules

ic

IC markers

interface

I2C/SPI interfaces

Structs

DateTime

Date and time

DayAlarm1

Parameters for setting Alarm1 on a day of the month

DayAlarm2

Parameters for setting Alarm2 on a day of the month

Ds323x

DS3231, DS3232 and DS3234 RTC driver

WeekdayAlarm1

Parameters for setting Alarm1 on a weekday

WeekdayAlarm2

Parameters for setting Alarm2 on a weekday

Enums

Alarm1Matching

Alarm1 trigger rate

Alarm2Matching

Alarm2 trigger rate

Error

All possible errors in this crate

Hours

Hours in either 12-hour (AM/PM) or 24-hour format

SqWFreq

Square-wave output frequency

TempConvRate

Temperature conversion rate