embedded_onewire/traits.rs
1use crate::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 /// Addresses devices on the 1-Wire bus.
43 /// 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.
44 /// 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.
45 /// # Arguments
46 /// * `rom` - The ROM address of the device to address. Pass [`None`] to skip ROM addressing and address all devices on the bus.
47 ///
48 /// # Returns
49 /// A result indicating the success or failure of the operation.
50 /// If the device is successfully addressed, the method returns `Ok(())`.
51 fn address(&mut self, rom: Option<u64>) -> OneWireResult<(), Self::BusError> {
52 let od = self.get_overdrive_mode();
53 let cmd = if rom.is_some() {
54 if od {
55 crate::consts::ONEWIRE_MATCH_ROM_CMD_OD
56 } else {
57 crate::consts::ONEWIRE_MATCH_ROM_CMD
58 }
59 } else if od {
60 crate::consts::ONEWIRE_SKIP_ROM_CMD_OD
61 } else {
62 crate::consts::ONEWIRE_SKIP_ROM_CMD
63 };
64 self.reset()?; // Reset the bus before addressing
65 self.write_byte(cmd)?; // Send the match ROM command
66 if let Some(rom) = rom {
67 for &b in rom.to_le_bytes().iter() {
68 self.write_byte(b)?; // Write each byte of the ROM address
69 }
70 }
71 Ok(())
72 }
73
74 /// Writes a byte to the device addressed using [`OneWire::address`] on the 1-Wire bus.
75 /// Multiple bytes can be written in succession after addressing the device.
76 ///
77 /// # Arguments
78 /// * `byte` - The byte to write to the bus.
79 ///
80 /// # Errors
81 /// This method returns an error if the write operation fails.
82 fn write_byte(&mut self, byte: u8) -> OneWireResult<(), Self::BusError>;
83
84 /// Reads a byte from the device addressed using [`OneWire::address`] on the 1-Wire bus.
85 /// Multiple bytes can be read in succession after addressing the device.
86 ///
87 /// # Note
88 /// If there are more than one devices on the bus and [`OneWire::address`] was not called
89 /// with a specific ROM address, the read operation will return garbage data.
90 ///
91 /// # Returns
92 /// Byte read from the bus.
93 ///
94 /// # Errors
95 /// This method returns an error if the read operation fails.
96 fn read_byte(&mut self) -> OneWireResult<u8, Self::BusError>;
97
98 /// Write a single bit to the device addressed using [`OneWire::address`] on the 1-Wire bus.
99 /// Multiple bits can be written in succession after addressing the device.
100 /// # Arguments
101 ///
102 /// * `bit` - The byte to write.
103 ///
104 /// # Errors
105 /// This method returns an error if the read operation fails.
106 fn write_bit(&mut self, bit: bool) -> OneWireResult<(), Self::BusError>;
107
108 /// Reads a single bit from the device addressed using [`OneWire::address`] on the 1-Wire bus.
109 /// Multiple bits can be read in succession after addressing the device.
110 ///
111 /// # Note
112 /// If there are more than one devices on the bus and [`OneWire::address`] was not called
113 /// with a specific ROM address, the read operation will return garbage data.
114 ///
115 /// # Returns
116 /// The bit read from the bus.
117 /// # Errors
118 /// This method returns an error if the read operation fails.
119 fn read_bit(&mut self) -> OneWireResult<bool, Self::BusError>;
120
121 /// # Note: Not intended for public API use.
122 /// ## 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.
123 /// ## This method is internally used by the [search algorithm](https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html).
124 ///
125 /// Generates three time slots: two read time slots and one write time slot at the 1-Wire line. The
126 /// type of write time slot depends on the result of the read time slots and the direction byte. The
127 /// direction byte determines the type of write time slot if both read time slots are 0 (a typical
128 /// case). In this case, a write-one time slot is generated if V = 1 and a write-zero time
129 /// slot if V = 0.
130 /// If the read time slots are 0 and 1, they are followed by a write-zero time slot.
131 /// If the read time slots are 1 and 0, they are followed by a write-one time slot.
132 /// If the read time slots are both 1 (error case), the subsequent write time slot is a write-one.
133 ///
134 ///
135 /// # Arguments
136 /// * `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.
137 ///
138 /// # Returns
139 /// A result containing a tuple of two booleans:
140 /// * The first boolean indicates the id bit read from the bus.
141 /// * The second boolean indicates the complement bit read from the bus.
142 ///
143 /// # Errors
144 /// This method returns an error if the triplet read operation is not implemented or if any other error occurs.
145 #[cfg(feature = "triplet-read")]
146 #[cfg_attr(docsrs, doc(cfg(feature = "triplet-read")))]
147 fn read_triplet(&mut self) -> OneWireResult<(bool, bool, bool), Self::BusError>;
148
149 /// Check if the 1-Wire bus is in overdrive mode.
150 /// # Returns
151 /// A result containing a boolean indicating whether the bus is in overdrive mode.
152 fn get_overdrive_mode(&mut self) -> bool;
153
154 /// Set the 1-Wire bus to overdrive mode.
155 /// # Arguments
156 /// * `enable` - A boolean indicating whether to enable or disable overdrive mode.
157 /// # Returns
158 /// A result indicating the success or failure of the operation.
159 fn set_overdrive_mode(&mut self, enable: bool) -> OneWireResult<(), Self::BusError>;
160}