embedded_hal_async/
i2c.rs

Help
1//! Async I2C API.
2//!
3//! This API supports 7-bit and 10-bit addresses. Traits feature an `AddressMode`
4//! marker type parameter. Two implementation of the `AddressMode` exist:
5//! `SevenBitAddress` and `TenBitAddress`.
6//!
7//! Through this marker types it is possible to implement each address mode for
8//! the traits independently in `embedded-hal` implementations and device drivers
9//! can depend only on the mode that they support.
10//!
11//! Additionally, the I2C 10-bit address mode has been developed to be fully
12//! backwards compatible with the 7-bit address mode. This allows for a
13//! software-emulated 10-bit addressing implementation if the address mode
14//! is not supported by the hardware.
15//!
16//! Since 7-bit addressing is the mode of the majority of I2C devices,
17//! `SevenBitAddress` has been set as default mode and thus can be omitted if desired.
18
19pub use embedded_hal::i2c::Operation;
20pub use embedded_hal::i2c::{
21    AddressMode, Error, ErrorKind, ErrorType, NoAcknowledgeSource, SevenBitAddress, TenBitAddress,
22};
23
24/// Async I2c.
25pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
26    /// Reads enough bytes from slave with `address` to fill `buffer`.
27    ///
28    /// # I2C Events (contract)
29    ///
30    /// ``` text
31    /// Master: ST SAD+R        MAK    MAK ...    NMAK SP
32    /// Slave:           SAK B0     B1     ... BN
33    /// ```
34    ///
35    /// Where
36    ///
37    /// - `ST` = start condition
38    /// - `SAD+R` = slave address followed by bit 1 to indicate reading
39    /// - `SAK` = slave acknowledge
40    /// - `Bi` = ith byte of data
41    /// - `MAK` = master acknowledge
42    /// - `NMAK` = master no acknowledge
43    /// - `SP` = stop condition
44    #[inline]
45    async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
46        self.transaction(address, &mut [Operation::Read(read)])
47            .await
48    }
49
50    /// Writes bytes to slave with address `address`.
51    ///
52    /// # I2C Events (contract)
53    ///
54    /// ``` text
55    /// Master: ST SAD+W     B0     B1     ... BN     SP
56    /// Slave:           SAK    SAK    SAK ...    SAK
57    /// ```
58    ///
59    /// Where
60    ///
61    /// - `ST` = start condition
62    /// - `SAD+W` = slave address followed by bit 0 to indicate writing
63    /// - `SAK` = slave acknowledge
64    /// - `Bi` = ith byte of data
65    /// - `SP` = stop condition
66    #[inline]
67    async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
68        self.transaction(address, &mut [Operation::Write(write)])
69            .await
70    }
71
72    /// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
73    /// single transaction*.
74    ///
75    /// # I2C Events (contract)
76    ///
77    /// ``` text
78    /// Master: ST SAD+W     O0     O1     ... OM     SR SAD+R        MAK    MAK ...    NMAK SP
79    /// Slave:           SAK    SAK    SAK ...    SAK          SAK I0     I1     ... IN
80    /// ```
81    ///
82    /// Where
83    ///
84    /// - `ST` = start condition
85    /// - `SAD+W` = slave address followed by bit 0 to indicate writing
86    /// - `SAK` = slave acknowledge
87    /// - `Oi` = ith outgoing byte of data
88    /// - `SR` = repeated start condition
89    /// - `SAD+R` = slave address followed by bit 1 to indicate reading
90    /// - `Ii` = ith incoming byte of data
91    /// - `MAK` = master acknowledge
92    /// - `NMAK` = master no acknowledge
93    /// - `SP` = stop condition
94    #[inline]
95    async fn write_read(
96        &mut self,
97        address: A,
98        write: &[u8],
99        read: &mut [u8],
100    ) -> Result<(), Self::Error> {
101        self.transaction(
102            address,
103            &mut [Operation::Write(write), Operation::Read(read)],
104        )
105        .await
106    }
107
108    /// Execute the provided operations on the I2C bus as a single transaction.
109    ///
110    /// Transaction contract:
111    /// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
112    /// - Data from adjacent operations of the same type are sent after each other without an SP or SR.
113    /// - Between adjacent operations of a different type an SR and SAD+R/W is sent.
114    /// - After executing the last operation an SP is sent automatically.
115    /// - If the last operation is a `Read` the master does not send an acknowledge for the last byte.
116    ///
117    /// - `ST` = start condition
118    /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
119    /// - `SR` = repeated start condition
120    /// - `SP` = stop condition
121    async fn transaction(
122        &mut self,
123        address: A,
124        operations: &mut [Operation<'_>],
125    ) -> Result<(), Self::Error>;
126}
127
128impl<A: AddressMode, T: I2c<A> + ?Sized> I2c<A> for &mut T {
129    #[inline]
130    async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
131        T::read(self, address, read).await
132    }
133
134    #[inline]
135    async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
136        T::write(self, address, write).await
137    }
138
139    #[inline]
140    async fn write_read(
141        &mut self,
142        address: A,
143        write: &[u8],
144        read: &mut [u8],
145    ) -> Result<(), Self::Error> {
146        T::write_read(self, address, write, read).await
147    }
148
149    #[inline]
150    async fn transaction(
151        &mut self,
152        address: A,
153        operations: &mut [Operation<'_>],
154    ) -> Result<(), Self::Error> {
155        T::transaction(self, address, operations).await
156    }
157}
embedded_hal_async/i2c.rs

embedded_hal_async/
i2c.rs
