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, Ocillator};

// 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: Ocillator::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()?;

§Async Usage

Enable the async feature in your Cargo.toml:

[dependencies]
ds3231 = { version = "0.1", features = ["async"] }

Then use with async/await:

ⓘ
use ds3231::asynch::DS3231;

// 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?;

§Features

  • async - Enables optional async I²C support
  • log - Enables logging via the log crate
  • defmt - Enables logging via the defmt crate

§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

§Safety

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

  • Strong typing for all register operations
  • Validation of all datetime values
  • Proper error propagation

Structs§

AgingOffset
Aging offset register for oscillator adjustment.
Config
Configuration for the DS3231 RTC device.
Control
Control register for device configuration.
DS3231
DS3231 Real-Time Clock driver.
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§

DS3231Error
Error type for DS3231 operations.
InterruptControl
Interrupt control mode for the DS3231.
Ocillator
Oscillator control for the DS3231.
SquareWaveFrequency
Square wave output frequency options.
TimeRepresentation
Time representation format for the DS3231.