Crate ds3231

Source
Expand description

§DS3231 Real-Time Clock (RTC) Driver

A platform-agnostic Rust driver for the DS3231 Real-Time Clock, built on the embedded-hal ecosystem. The DS3231 is a low-cost, extremely accurate I²C real-time clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal.

§Features

  • Both blocking and async I²C operation support
  • Optional logging support via log or defmt

§Blocking Usage

ⓘ
use ds3231::{DS3231, Config, TimeRepresentation, SquareWaveFrequency, InterruptControl, Oscillator, Alarm1Config, Alarm2Config};

// Create configuration
let config = Config {
    time_representation: TimeRepresentation::TwentyFourHour,
    square_wave_frequency: SquareWaveFrequency::Hz1,
    interrupt_control: InterruptControl::SquareWave,
    battery_backed_square_wave: false,
    oscillator_enable: Oscillator::Enabled,
};

// Initialize device with I2C
let mut rtc = DS3231::new(i2c, 0x68);

// Configure the device
rtc.configure(&config)?;

// Get current date/time
let datetime = rtc.datetime()?;

// Set a daily alarm for 9:30 AM
let alarm1 = Alarm1Config::AtTime {
    hours: 9,
    minutes: 30,
    seconds: 0,
    is_pm: None, // 24-hour mode
};
rtc.set_alarm1(&alarm1)?;

// Set a weekly alarm for Friday at 5:00 PM
let alarm2 = Alarm2Config::AtTimeOnDay {
    hours: 5,
    minutes: 0,
    day: 6, // Friday
    is_pm: Some(true), // 12-hour mode
};
rtc.set_alarm2(&alarm2)?;

§Async Usage

Enable the async feature on ds3231in your Cargo.toml and use with async/await:

ⓘ
use ds3231::{DS3231, Alarm1Config, Alarm2Config};

// Initialize device
let mut rtc = DS3231::new(i2c, 0x68);

// Configure asynchronously
rtc.configure(&config).await?;

// Get current date/time asynchronously
let datetime = rtc.datetime().await?;

// Set alarms asynchronously
let alarm1 = Alarm1Config::AtTime {
    hours: 9,
    minutes: 30,
    seconds: 0,
    is_pm: None,
};
rtc.set_alarm1(&alarm1).await?;

let alarm2 = Alarm2Config::EveryMinute;
rtc.set_alarm2(&alarm2).await?;

§Features

  • async - Enables optional async I²C support
  • log - Enables logging via the log crate
  • defmt - Enables logging via the defmt crate
  • temperature_f32 - Enables temperature reading as f32

§Register Map

The driver provides access to all DS3231 registers:

  • Time/Date: seconds, minutes, hours, day, date, month, year
  • Alarms: alarm1 (seconds to day/date), alarm2 (minutes to day/date)
  • Control: oscillator, square wave, interrupts
  • Status: oscillator stop, 32kHz output, busy flags
  • Aging offset
  • Temperature

§Error Handling

The driver uses a custom error type DS3231Error that wraps:

  • I²C communication errors
  • DateTime validation errors
  • Alarm configuration errors
  • Proper error propagation

§Safety

This driver uses no unsafe code and ensures type safety through:

  • Strong typing for all register operations
  • Validation of all datetime values

Structs§

AgingOffset
Aging offset register for oscillator adjustment.
AlarmDayDate
Alarm Day/Date register with mask bit and DY/DT control (used by both Alarm 1 and Alarm 2).
AlarmHours
Alarm Hours register with mask bit and time format control (used by both Alarm 1 and Alarm 2).
AlarmMinutes
Alarm Minutes register with mask bit (used by both Alarm 1 and Alarm 2).
AlarmSeconds
Alarm Seconds register with mask bit (only used by Alarm 1).
Config
Configuration for the DS3231 RTC device.
Control
Control register for device configuration.
DS3231
DS3231 Real-Time Clock driver.
DS3231Alarm1
Internal representation of DS3231 Alarm 1 registers.
DS3231Alarm2
Internal representation of DS3231 Alarm 2 registers.
Date
Date register (1-31) with BCD encoding.
Day
Day of week register (1-7).
Hours
Hours register with format selection and BCD encoding.
Minutes
Minutes register (0-59) with BCD encoding.
Month
Month register (1-12) with century flag and BCD encoding.
Seconds
Seconds register (0-59) with BCD encoding.
Status
Status register for device state and flags.
Temperature
Temperature register (integer part).
TemperatureFraction
Temperature fraction register (decimal part).
Year
Year register (0-99) with BCD encoding.

Enums§

Alarm1Config
Alarm 1 specific configurations.
Alarm2Config
Alarm 2 specific configurations.
AlarmError
Error type for alarm configuration operations.
DS3231Error
Error type for DS3231 operations.
DayDateSelect
Day/Date select for alarm registers (DY/DT bit).
InterruptControl
Interrupt control mode for the DS3231.
Oscillator
Oscillator control for the DS3231.
SquareWaveFrequency
Square wave output frequency options.
TimeRepresentation
Time representation format for the DS3231.