embedded_onewire/
traits.rs

1use crate::{OneWireError, OneWireResult};
2
3/// Trait describing the status of a 1-Wire bus.
4/// This trait is used to encapsulate the status of the bus after a reset operation.
5pub trait OneWireStatus {
6    /// Returns true if a device is present on the bus, false otherwise.
7    fn presence(&self) -> bool;
8    /// Returns true if a short circuit is detected on the bus, false otherwise.
9    fn shortcircuit(&self) -> bool;
10    /// Returns the direction taken in the [OneWire::read_triplet] operation.
11    #[cfg(feature = "triplet-read")]
12    #[cfg_attr(docsrs, doc(cfg(feature = "triplet-read")))]
13    fn direction(&self) -> Option<bool> {
14        None
15    }
16    /// Returns the logic state of the active 1-Wire line without initiating any 1-Wire communication.
17    fn logic_level(&self) -> Option<bool> {
18        None
19    }
20}
21
22/// Trait for 1-Wire communication.
23/// This trait defines the basic operations required for 1-Wire communication, such as resetting the bus,
24/// writing and reading bytes, and writing and reading bits.
25pub trait OneWire {
26    /// The status type returned by the reset operation.
27    /// This type must implement the [OneWireStatus] trait.
28    type Status: OneWireStatus;
29    /// The error type returned by the operations of this trait.
30    /// This type is used to indicate errors in the underlying hardware or communication.
31    type BusError;
32
33    /// Resets the 1-Wire bus and returns the status of the bus.
34    ///
35    /// # Returns
36    /// A result containing the status of the bus after the reset operation.
37    ///
38    /// # Errors
39    /// This method returns an error if the reset operation fails.
40    fn reset(&mut self) -> OneWireResult<Self::Status, Self::BusError>;
41
42    /// Writes a byte to the 1-Wire bus.
43    /// # Arguments
44    /// * `byte` - The byte to write to the bus.
45    ///
46    /// # Errors
47    /// This method returns an error if the write operation fails.
48    fn write_byte(&mut self, byte: u8) -> OneWireResult<(), Self::BusError>;
49
50    /// Reads a byte from the 1-Wire bus.
51    /// # Returns
52    /// Byte read from the bus.
53    ///
54    /// # Errors
55    /// This method returns an error if the read operation fails.
56    fn read_byte(&mut self) -> OneWireResult<u8, Self::BusError>;
57
58    /// Reads a byte from the 1-Wire bus, with an option to write a byte before reading.
59    /// # Arguments
60    ///
61    /// * `bit` - The byte to write.
62    ///
63    /// # Errors
64    /// This method returns an error if the read operation fails.
65    fn write_bit(&mut self, bit: bool) -> OneWireResult<(), Self::BusError>;
66
67    /// Reads a single bit from the 1-Wire bus.
68    /// # Returns
69    /// The bit read from the bus.
70    /// # Errors
71    /// This method returns an error if the read operation fails.
72    fn read_bit(&mut self) -> OneWireResult<bool, Self::BusError>;
73
74    /// # Note: Not intended for public API use.
75    /// ## This method is internally used to performa [1-wire search ROM sequence](https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html). A full sequence requires this command to be executed 64 times to identify and address one device.
76    /// ## This method is internally used by the [search algorithm](https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html).
77    ///
78    /// Generates three time slots: two read time slots and one write time slot at the 1-Wire line. The
79    /// type of write time slot depends on the result of the read time slots and the direction byte. The
80    /// direction byte determines the type of write time slot if both read time slots are 0 (a typical
81    /// case). In this case, a write-one time slot is generated if V = 1 and a write-zero time
82    /// slot if V = 0.
83    /// If the read time slots are 0 and 1, they are followed by a write-zero time slot.
84    /// If the read time slots are 1 and 0, they are followed by a write-one time slot.
85    /// If the read time slots are both 1 (error case), the subsequent write time slot is a write-one.
86    ///
87    ///
88    /// # Arguments
89    /// * `direction` - A boolean indicating the direction of the search. If true, the search is in the forward direction; if false, it is in the backward direction.
90    ///
91    /// # Returns
92    /// A result containing a tuple of two booleans:
93    /// * The first boolean indicates the id bit read from the bus.
94    /// * The second boolean indicates the complement bit read from the bus.
95    ///
96    /// # Errors
97    /// This method returns an error if the triplet read operation is not implemented or if any other error occurs.
98    #[cfg(feature = "triplet-read")]
99    #[cfg_attr(docsrs, doc(cfg(feature = "triplet-read")))]
100    fn read_triplet(&mut self) -> OneWireResult<(bool, bool, bool), Self::BusError>;
101
102    /// Check if the 1-Wire bus is in overdrive mode.
103    /// # Returns
104    /// A result containing a boolean indicating whether the bus is in overdrive mode.
105    fn get_overdrive_mode(&mut self) -> OneWireResult<bool, Self::BusError>;
106
107    /// Set the 1-Wire bus to overdrive mode.
108    /// # Arguments
109    /// * `enable` - A boolean indicating whether to enable or disable overdrive mode.
110    /// # Returns
111    /// A result indicating the success or failure of the operation.
112    fn set_overdrive_mode(&mut self, _enable: bool) -> OneWireResult<(), Self::BusError> {
113        Err(OneWireError::Unimplemented)
114    }
115}
embedded_onewire/traits.rs

embedded_onewire/
traits.rs
