embedded_onewire/
traits_async.rs

1#![allow(async_fn_in_trait)]
2use crate::{OneWireResult, OneWireStatus};
3
4/// Trait for 1-Wire communication.
5/// This trait defines the basic operations required for 1-Wire communication, such as resetting the bus,
6/// writing and reading bytes, and writing and reading bits.
7pub trait OneWireAsync {
8    /// The status type returned by the reset operation.
9    /// This type must implement the [OneWireStatus] trait.
10    type Status: OneWireStatus;
11    /// The error type returned by the operations of this trait.
12    /// This type is used to indicate errors in the underlying hardware or communication.
13    type BusError;
14
15    /// Resets the 1-Wire bus and returns the status of the bus.
16    ///
17    /// # Returns
18    /// A result containing the status of the bus after the reset operation.
19    ///
20    /// # Errors
21    /// This method returns an error if the reset operation fails.
22    async fn reset(&mut self) -> OneWireResult<Self::Status, Self::BusError>;
23
24    /// Addresses devices on the 1-Wire bus.
25    /// The first [`OneWireAsync::read_byte`], [`OneWireAsync::read_bit`], [`OneWireAsync::write_byte`], [`OneWireAsync::write_bit`] operation should be preceded by this method to address devices on the bus.
26    /// Note: A [`OneWireAsync::read_byte`] or [`OneWireAsync::read_bit`] call will return garbage data if this method is called without specifying a ROM address on a bus with multiple devices.
27    /// # Arguments
28    /// * `rom` - The ROM address of the device to address. Pass [`None`] to skip ROM addressing and address all devices on the bus.
29    ///
30    /// # Returns
31    /// A result indicating the success or failure of the operation.
32    /// If the device is successfully addressed, the method returns `Ok(())`.
33    async fn address(&mut self, rom: Option<u64>) -> OneWireResult<(), Self::BusError> {
34        let od = self.get_overdrive_mode();
35        let cmd = if rom.is_some() {
36            if od {
37                crate::consts::ONEWIRE_MATCH_ROM_CMD_OD
38            } else {
39                crate::consts::ONEWIRE_MATCH_ROM_CMD
40            }
41        } else if od {
42            crate::consts::ONEWIRE_SKIP_ROM_CMD_OD
43        } else {
44            crate::consts::ONEWIRE_SKIP_ROM_CMD
45        };
46        self.reset().await?; // Reset the bus before addressing
47        self.write_byte(cmd).await?; // Send the match ROM command
48        if let Some(rom) = rom {
49            for &b in rom.to_le_bytes().iter() {
50                self.write_byte(b).await?; // Write each byte of the ROM address
51            }
52        }
53        Ok(())
54    }
55
56    /// Writes a byte to the device addressed using [`OneWireAsync::address`] on the 1-Wire bus.
57    /// Multiple bytes can be written in succession after addressing the device.
58    ///
59    /// # Arguments
60    /// * `byte` - The byte to write to the bus.
61    ///
62    /// # Errors
63    /// This method returns an error if the write operation fails.
64    async fn write_byte(&mut self, byte: u8) -> OneWireResult<(), Self::BusError>;
65
66    /// Reads a byte from the device addressed using [`OneWireAsync::address`] on the 1-Wire bus.
67    /// Multiple bytes can be read in succession after addressing the device.
68    ///
69    /// # Note
70    /// If there are more than one devices on the bus and [`OneWireAsync::address`] was not called
71    /// with a specific ROM address, the read operation will return garbage data.
72    ///
73    /// # Returns
74    /// Byte read from the bus.
75    ///
76    /// # Errors
77    /// This method returns an error if the read operation fails.
78    async fn read_byte(&mut self) -> OneWireResult<u8, Self::BusError>;
79
80    /// Write a single bit to the device addressed using [`OneWireAsync::address`] on the 1-Wire bus.
81    /// Multiple bits can be written in succession after addressing the device.
82    /// # Arguments
83    ///
84    /// * `bit` - The byte to write.
85    ///
86    /// # Errors
87    /// This method returns an error if the read operation fails.
88    async fn write_bit(&mut self, bit: bool) -> OneWireResult<(), Self::BusError>;
89
90    /// Reads a single bit from the device addressed using [`OneWireAsync::address`] on the 1-Wire bus.
91    /// Multiple bits can be read in succession after addressing the device.
92    ///
93    /// # Note
94    /// If there are more than one devices on the bus and [`OneWireAsync::address`] was not called
95    /// with a specific ROM address, the read operation will return garbage data.
96    ///
97    /// # Returns
98    /// The bit read from the bus.
99    /// # Errors
100    /// This method returns an error if the read operation fails.
101    async fn read_bit(&mut self) -> OneWireResult<bool, Self::BusError>;
102
103    /// # Note: Not intended for public API use.
104    /// ## 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.
105    /// ## This method is internally used by the [search algorithm](https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html).
106    ///
107    /// Generates three time slots: two read time slots and one write time slot at the 1-Wire line. The
108    /// type of write time slot depends on the result of the read time slots and the direction byte. The
109    /// direction byte determines the type of write time slot if both read time slots are 0 (a typical
110    /// case). In this case, a write-one time slot is generated if V = 1 and a write-zero time
111    /// slot if V = 0.
112    /// If the read time slots are 0 and 1, they are followed by a write-zero time slot.
113    /// If the read time slots are 1 and 0, they are followed by a write-one time slot.
114    /// If the read time slots are both 1 (error case), the subsequent write time slot is a write-one.
115    ///
116    ///
117    /// # Arguments
118    /// * `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.
119    ///
120    /// # Returns
121    /// A result containing a tuple of two booleans:
122    /// * The first boolean indicates the id bit read from the bus.
123    /// * The second boolean indicates the complement bit read from the bus.
124    ///
125    /// # Errors
126    /// This method returns an error if the triplet read operation is not implemented or if any other error occurs.
127    #[cfg(feature = "triplet-read")]
128    #[cfg_attr(docsrs, doc(cfg(feature = "triplet-read")))]
129    async fn read_triplet(&mut self) -> OneWireResult<(bool, bool, bool), Self::BusError>;
130
131    /// Check if the 1-Wire bus is in overdrive mode.
132    /// # Returns
133    /// A result containing a boolean indicating whether the bus is in overdrive mode.
134    fn get_overdrive_mode(&mut self) -> bool;
135
136    /// Set the 1-Wire bus to overdrive mode.
137    /// # Arguments
138    /// * `enable` - A boolean indicating whether to enable or disable overdrive mode.
139    /// # Returns
140    /// A result indicating the success or failure of the operation.
141    async fn set_overdrive_mode(&mut self, enable: bool) -> OneWireResult<(), Self::BusError>;
142}
embedded_onewire/traits_async.rs

embedded_onewire/
traits_async.rs
