Struct Ds3231 

pub struct Ds3231<I2C> { /* private fields */ }

DS3231 Real-Time Clock driver

Implementations

impl<I2C, E> Ds3231<I2C>

where I2C: I2c<Error = E>, E: Debug,

pub fn new(i2c: I2C) -> Self

Create a new DS3231 driver instance

Parameters

• i2c - I2C peripheral that implements the embedded-hal I2c trait

Returns

New DS3231 driver instance

pub fn set_base_century(&mut self, base_century: u8) -> Result<(), Error<E>>

Sets the base century for year calculations.

The DS3231 stores years as 00-99 in BCD format. This base century determines how those 2-digit years are interpreted as full 4-digit years.

Arguments

• base_century - The century to use (e.g., 20 for 2000-2099, 21 for 2100-2199)

Returns

Returns Err(Error::InvalidBaseCentury) if base_century is less than 19.

Examples

// Years 00-99 will be interpreted as 2000-2099
let rtc = Ds3231::new(i2c).with_base_century(20)?;

// Years 00-99 will be interpreted as 2100-2199
let rtc = Ds3231::new(i2c).with_base_century(21)?;

pub fn release_i2c(self) -> I2C

Returns the underlying I2C bus instance, consuming the driver.

This allows the user to reuse the I2C bus for other purposes after the driver is no longer needed.

However, if you are using embedded-hal-bus, you typically do not need release_i2c. In that case the crate takes care of the sharing

Trait Implementations

impl<I2C: I2c> ErrorType for Ds3231<I2C>

type Error = Error<<I2C as ErrorType>::Error>

Error type

impl<I2C> Rtc for Ds3231<I2C>

where I2C: I2c,

fn get_datetime(&mut self) -> Result<DateTime, Self::Error>

Read the current date and time from the DS3231.

fn set_datetime(&mut self, datetime: &DateTime) -> Result<(), Self::Error>

Set the current date and time in the DS3231.

The DS3231 stores years as 2-digit values (00-99). This method interprets the provided year based on the configured base century and its successor.

Year Range

The year must be within one of these ranges:

• Base century: base_century * 100 to (base_century * 100) + 99
• Next century: (base_century + 1) * 100 to (base_century + 1) * 100 + 99

For example, with base_century = 20:

• Allowed years: 2000-2099 (stored as 00-99, century bit = 0)
• Allowed years: 2100-2199 (stored as 00-99, century bit = 1)
• Rejected years: 1900-1999, 2200+

Century Bit Handling

The method automatically sets the DS3231’s century bit based on which century range the year falls into, avoiding the ambiguity issues with this hardware feature.

Time Format

The DS3231 is configured to use 24-hour time format. The weekday is calculated from the date and stored in the day register (1=Sunday, 7=Saturday).

Arguments

• datetime - The date and time to set

Returns

Returns Err(Error::DateTime(DateTimeError::InvalidYear)) if the year is outside the supported range.

Examples

// With base_century = 20, you can set dates from 2000-2199
let datetime = DateTime::new(2023, 12, 25, 15, 30, 0)?;
rtc.set_datetime(&datetime)?;

// To set dates in a different century, update base_century first
let rtc = rtc.with_base_century(21)?; // Now supports 2100-2299
let datetime = DateTime::new(2150, 1, 1, 0, 0, 0)?;
rtc.set_datetime(&datetime)?;

impl<I2C> RtcPowerControl for Ds3231<I2C>

where I2C: I2c,

fn start_clock(&mut self) -> Result<(), Self::Error>

Start or resume the RTC oscillator so that timekeeping can continue.

This clears the EOSC bit (sets to logic 0) to enable the oscillator. The operation is idempotent - calling it when already running has no effect.

Note: When powered by VCC, the oscillator runs regardless of this setting.

fn halt_clock(&mut self) -> Result<(), Self::Error>

Halt the RTC oscillator to conserve power during battery backup operation.

This sets the EOSC bit (sets to logic 1) to disable the oscillator.

Important: This only takes effect when the DS3231 switches to battery backup power (VBAT). When powered by VCC, the oscillator continues running regardless of this setting.

impl<I2C> SquareWave for Ds3231<I2C>

where I2C: I2c,

fn enable_square_wave(&mut self) -> Result<(), Self::Error>

Enable the square wave output

fn disable_square_wave(&mut self) -> Result<(), Self::Error>

Disable the square wave output.

fn set_square_wave_frequency( &mut self, freq: SquareWaveFreq, ) -> Result<(), Self::Error>

Set the frequency (without enabling/disabling)

fn start_square_wave(&mut self, freq: SquareWaveFreq) -> Result<(), Self::Error>

Configure Frequency and enable square wave