rtc_hal/
rtc.rs

1//! # RTC Trait Interface
2//!
3//! This module defines the core trait for Real-Time Clock (RTC) devices in embedded systems.
4//!
5//! ## Features
6//! - Provides a platform-independent interface for reading and writing date/time values to hardware RTC chips.
7//! - Compatible with the design patterns of `embedded-hal`, focusing on trait-based abstraction.
8//! - Uses the hardware-agnostic `DateTime` struct for representing calendar date and time.
9//!
10//! ## Usage Notes
11//! - Each RTC driver should implement its own error type conforming to the `RtcError` trait, allowing accurate hardware-specific error reporting.
12//! - Drivers are responsible for validating that all `DateTime` values provided are within the supported range of their underlying hardware (for example, some chips only support years 2000-2099).
13//! - This trait is intended for use in platform implementors and applications needing unified RTC access across hardware targets.
14//!
15//! ## Example
16//! ```ignore
17//! use crate::{datetime::DateTime, error::RtcError, rtc::Rtc};
18//!
19//! let mut rtc = Ds1307::new(i2c);
20//! let now = rtc.get_datetime()?;
21//! rtc.set_datetime(&DateTime::new(2024, 8, 16, 12, 0, 0)?)?;
22//! ```
23use crate::{datetime::DateTime, error::RtcError};
24
25/// Core trait for Real-Time Clock (RTC) devices.
26///
27/// This trait provides a platform-agnostic interface for reading and
28/// writing date/time values from hardware RTC chips. It is designed
29/// to be similar in style to `embedded-hal` traits.
30///
31/// Each RTC implementation should define:
32/// - An associated error type for hardware-specific errors
33///
34/// The `DateTime` struct used here is hardware-agnostic. Drivers must
35/// validate that provided values fall within the supported range.
36///
37/// # Example
38///
39/// ```ignore
40/// let mut rtc = Ds1307::new(i2c);
41/// let now = rtc.get_datetime()?;
42/// rtc.set_datetime(&DateTime::new(2024, 8, 16, 12, 0, 0)?)?;
43pub trait Rtc {
44    /// Error type for RTC operations
45    type Error: RtcError;
46
47    /// Get the current date and time atomically.
48    ///
49    /// # Errors
50    ///
51    /// Returns `Self::Error` if communication with the RTC fails.
52    fn get_datetime(&mut self) -> Result<DateTime, Self::Error>;
53
54    /// Set the current date and time atomically.
55    ///
56    /// # Errors
57    ///
58    /// Returns `Self::Error` if communication with the RTC fails or
59    /// if the provided `DateTime` is out of range for this device.
60    fn set_datetime(&mut self, datetime: &DateTime) -> Result<(), Self::Error>;
61}
rtc_hal/rtc.rs

rtc_hal/
rtc.rs
