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 /// Write a single bit to the 1-Wire bus.
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
116 /// Addresses devices on the 1-Wire bus.
117 /// The first [`OneWire::read_byte`], [`OneWire::read_bit`], [`OneWire::write_byte`], [`OneWire::write_bit`] operation should be preceded by this method to address devices on the bus.
118 /// Note: A [`OneWire::read_byte`] or [`OneWire::read_bit`] call will return garbage data if this method is called without specifying a ROM address on a bus with multiple devices.
119 /// # Arguments
120 /// * `rom` - The ROM address of the device to address. Pass [`None`] to skip ROM addressing and address all devices on the bus.
121 ///
122 /// # Returns
123 /// A result indicating the success or failure of the operation.
124 /// If the device is successfully addressed, the method returns `Ok(())`.
125 fn addrss(&mut self, rom: Option<u64>) -> OneWireResult<(), Self::BusError> {
126 let od = self.get_overdrive_mode()?;
127 let cmd = if rom.is_some() {
128 if od {
129 crate::consts::ONEWIRE_MATCH_ROM_CMD_OD
130 } else {
131 crate::consts::ONEWIRE_MATCH_ROM_CMD
132 }
133 } else if od {
134 crate::consts::ONEWIRE_SKIP_ROM_CMD_OD
135 } else {
136 crate::consts::ONEWIRE_SKIP_ROM_CMD
137 };
138 self.reset()?; // Reset the bus before addressing
139 self.write_byte(cmd)?; // Send the match ROM command
140 if let Some(rom) = rom {
141 for &b in rom.to_le_bytes().iter() {
142 self.write_byte(b)?; // Write each byte of the ROM address
143 }
144 }
145 Ok(())
146 }
147}