rtcc/
lib.rs

1//! Data structures and traits to be implemented by real-time clock / calendar devices.
2//!
3//! Prefer to use only the methods from the `DateTimeAccess` rather than the individual
4//! methods from the `Rtcc` trait to avoid situations where the passing of time
5//! makes the results of the method calls inconsistent if you combine the results
6//! of several methods.
7//!
8//! For example, this can happen at certain timepoints:
9//! 1. The time is `01:59:59`
10//! 2. A call to `hours()` returns 1.
11//! 3. The time is increased to `02:00:00`.
12//! 4. A call to `minutes()` returns 0.
13//! 5. A call to `seconds()` returns 0.
14//! 6. Your system thinks it is `01:00:00`.
15//!
16//! The same applies to the date as well, as well as when calling setter methods.
17//!
18//! # Features
19//!
20//! The optional `defmt` feature implements [defmt::Format] on some types.
21
22#![deny(unsafe_code, missing_docs)]
23#![no_std]
24
25pub use chrono::{DateTime, Datelike, NaiveDate, NaiveDateTime, NaiveTime, Timelike};
26
27/// Hours in either 12-hour (AM/PM) or 24-hour format
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29#[cfg_attr(feature = "defmt", derive(defmt::Format))]
30pub enum Hours {
31    /// AM [1-12]
32    AM(u8),
33    /// PM [1-12]
34    PM(u8),
35    /// 24H format [0-23]
36    H24(u8),
37}
38
39/// Real-Time Clock / Calendar DateTimeAccess trait to read/write a complete
40/// date/time.
41///
42/// Prefer to use only these methods rather than the individual methods from the
43/// `Rtcc` trait to avoid situations where the passing of time makes the results
44/// of the method calls inconsistent if you combine the results of several methods.
45///
46/// For example, this can happen at certain timepoints:
47/// 1. The time is `01:59:59`
48/// 2. A call to `hours()` returns 1.
49/// 3. The time is increased to `02:00:00`.
50/// 4. A call to `minutes()` returns 0.
51/// 5. A call to `seconds()` returns 0.
52/// 6. Your system thinks it is `01:00:00`.
53///
54/// The same applies to the date as well, as well as when calling setter methods.
55pub trait DateTimeAccess {
56    /// Error type
57    type Error;
58
59    /// Read the date and time.
60    fn datetime(&mut self) -> Result<NaiveDateTime, Self::Error>;
61
62    /// Set the date and time.
63    ///
64    /// This will set the hour operating mode to 24h and the weekday to the
65    /// day number starting from Sunday = 1.
66    fn set_datetime(&mut self, datetime: &NaiveDateTime) -> Result<(), Self::Error>;
67}
68
69/// Real-Time Clock / Calendar trait
70///
71/// If you want to combine calls to these methods, prefer to use only
72/// the `DateTimeAccess` trait to avoid situations where the passing of time makes the results
73/// of the method calls inconsistent.
74///
75/// For example, this can happen at certain timepoints:
76/// 1. The time is `01:59:59`
77/// 2. A call to `hours()` returns 1.
78/// 3. The time is increased to `02:00:00`.
79/// 4. A call to `minutes()` returns 0.
80/// 5. A call to `seconds()` returns 0.
81/// 6. Your system thinks it is `01:00:00`.
82///
83/// The same applies to the date, as well as when calling setter methods.
84pub trait Rtcc: DateTimeAccess {
85    /// Read the seconds.
86    fn seconds(&mut self) -> Result<u8, Self::Error>;
87
88    /// Read the minutes.
89    fn minutes(&mut self) -> Result<u8, Self::Error>;
90
91    /// Read the hours.
92    fn hours(&mut self) -> Result<Hours, Self::Error>;
93
94    /// Read the time.
95    fn time(&mut self) -> Result<NaiveTime, Self::Error>;
96
97    /// Read the day of the week [1-7].
98    fn weekday(&mut self) -> Result<u8, Self::Error>;
99
100    /// Read the day of the month [1-31].
101    fn day(&mut self) -> Result<u8, Self::Error>;
102
103    /// Read the month [1-12].
104    fn month(&mut self) -> Result<u8, Self::Error>;
105
106    /// Read the year (e.g. 2000).
107    fn year(&mut self) -> Result<u16, Self::Error>;
108
109    /// Read the date.
110    fn date(&mut self) -> Result<NaiveDate, Self::Error>;
111
112    /// Set the seconds [0-59].
113    fn set_seconds(&mut self, seconds: u8) -> Result<(), Self::Error>;
114
115    /// Set the minutes [0-59].
116    fn set_minutes(&mut self, minutes: u8) -> Result<(), Self::Error>;
117
118    /// Set the hours.
119    ///
120    /// Changes the operating mode to 12h/24h depending on the parameter.
121    fn set_hours(&mut self, hours: Hours) -> Result<(), Self::Error>;
122
123    /// Set the time.
124    fn set_time(&mut self, time: &NaiveTime) -> Result<(), Self::Error>;
125
126    /// Set the day of week [1-7].
127    fn set_weekday(&mut self, weekday: u8) -> Result<(), Self::Error>;
128
129    /// Set the day of month [1-31].
130    fn set_day(&mut self, day: u8) -> Result<(), Self::Error>;
131
132    /// Set the month [1-12].
133    fn set_month(&mut self, month: u8) -> Result<(), Self::Error>;
134
135    /// Set the year. (e.g. 2000)
136    fn set_year(&mut self, year: u16) -> Result<(), Self::Error>;
137
138    /// Set the date.
139    fn set_date(&mut self, date: &NaiveDate) -> Result<(), Self::Error>;
140}
rtcc/lib.rs

rtcc/
lib.rs
