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}
158