Merge pull request #64 from xoviat/i2c-trait

add i2c trait

2 files changed, 171 insertions, 0 deletions

diff --git a/embassy-traits/src/i2c.rs b/embassy-traits/src/i2c.rs
new file mode 100644
index 000000000..4dc8865e3
--- /dev/null
+++ b/embassy-traits/src/i2c.rs
@@ -0,0 +1,169 @@
+//! Async I2C API
+//!
+//! This API supports 7-bit and 10-bit addresses. Traits feature an `AddressMode`
+//! marker type parameter. Two implementation of the `AddressMode` exist:
+//! `SevenBitAddress` and `TenBitAddress`.
+//!
+//! Through this marker types it is possible to implement each address mode for
+//! the traits independently in `embedded-hal` implementations and device drivers
+//! can depend only on the mode that they support.
+//!
+//! Additionally, the I2C 10-bit address mode has been developed to be fully
+//! backwards compatible with the 7-bit address mode. This allows for a
+//! software-emulated 10-bit addressing implementation if the address mode
+//! is not supported by the hardware.
+//!
+//! Since 7-bit addressing is the mode of the majority of I2C devices,
+//! `SevenBitAddress` has been set as default mode and thus can be omitted if desired.
+//!
+//! ### Device driver compatible only with 7-bit addresses
+//!
+//! For demonstration purposes the address mode parameter has been omitted in this example.
+//!
+//! ```
+//! # use embedded_hal::blocking::i2c::WriteRead;
+//! const ADDR: u8  = 0x15;
+//! # const TEMP_REGISTER: u8 = 0x1;
+//! pub struct TemperatureSensorDriver<I2C> {
+//!     i2c: I2C,
+//! }
+//!
+//! impl<I2C, E> TemperatureSensorDriver<I2C>
+//! where
+//!     I2C: WriteRead<Error = E>,
+//! {
+//!     pub fn read_temperature(&mut self) -> Result<u8, E> {
+//!         let mut temp = [0];
+//!         self.i2c
+//!             .write_read(ADDR, &[TEMP_REGISTER], &mut temp)
+//!             .await
+//!             .and(Ok(temp[0]))
+//!     }
+//! }
+//! ```
+//!
+//! ### Device driver compatible only with 10-bit addresses
+//!
+//! ```
+//! # use embedded_hal::blocking::i2c::{TenBitAddress, WriteRead};
+//! const ADDR: u16  = 0x158;
+//! # const TEMP_REGISTER: u8 = 0x1;
+//! pub struct TemperatureSensorDriver<I2C> {
+//!     i2c: I2C,
+//! }
+//!
+//! impl<I2C, E> TemperatureSensorDriver<I2C>
+//! where
+//!     I2C: WriteRead<TenBitAddress, Error = E>,
+//! {
+//!     pub fn read_temperature(&mut self) -> Result<u8, E> {
+//!         let mut temp = [0];
+//!         self.i2c
+//!             .write_read(ADDR, &[TEMP_REGISTER], &mut temp)
+//!             .await
+//!             .and(Ok(temp[0]))
+//!     }
+//! }
+//! ```
+
+use core::future::Future;
+use core::pin::Pin;
+
+mod private {
+    pub trait Sealed {}
+}
+
+/// Address mode (7-bit / 10-bit)
+///
+/// Note: This trait is sealed and should not be implemented outside of this crate.
+pub trait AddressMode: private::Sealed {}
+
+/// 7-bit address mode type
+pub type SevenBitAddress = u8;
+
+/// 10-bit address mode type
+pub type TenBitAddress = u16;
+
+impl private::Sealed for SevenBitAddress {}
+impl private::Sealed for TenBitAddress {}
+
+impl AddressMode for SevenBitAddress {}
+
+impl AddressMode for TenBitAddress {}
+
+/// Blocking read
+pub trait Read<A: AddressMode = SevenBitAddress> {
+    /// Error type
+    type Error;
+
+    type ReadFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a;
+    type WriteFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a;
+    type WriteReadFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a;
+
+    /// Reads enough bytes from slave with `address` to fill `buffer`
+    ///
+    /// # I2C Events (contract)
+    ///
+    /// ``` text
+    /// Master: ST SAD+R        MAK    MAK ...    NMAK SP
+    /// Slave:           SAK B0     B1     ... BN
+    /// ```
+    ///
+    /// Where
+    ///
+    /// - `ST` = start condition
+    /// - `SAD+R` = slave address followed by bit 1 to indicate reading
+    /// - `SAK` = slave acknowledge
+    /// - `Bi` = ith byte of data
+    /// - `MAK` = master acknowledge
+    /// - `NMAK` = master no acknowledge
+    /// - `SP` = stop condition
+    fn read<'a>(self: Pin<&'a mut Self>, address: A, buffer: &mut [u8]) -> Self::ReadFuture<'a>;
+
+    /// Sends bytes to slave with address `address`
+    ///
+    /// # I2C Events (contract)
+    ///
+    /// ``` text
+    /// Master: ST SAD+W     B0     B1     ... BN     SP
+    /// Slave:           SAK    SAK    SAK ...    SAK
+    /// ```
+    ///
+    /// Where
+    ///
+    /// - `ST` = start condition
+    /// - `SAD+W` = slave address followed by bit 0 to indicate writing
+    /// - `SAK` = slave acknowledge
+    /// - `Bi` = ith byte of data
+    /// - `SP` = stop condition
+    fn write<'a>(self: Pin<&'a mut Self>, address: A, bytes: &[u8]) -> Self::WriteFuture<'a>;
+
+    /// Sends bytes to slave with address `address` and then reads enough bytes to fill `buffer` *in a
+    /// single transaction*
+    ///
+    /// # I2C Events (contract)
+    ///
+    /// ``` text
+    /// Master: ST SAD+W     O0     O1     ... OM     SR SAD+R        MAK    MAK ...    NMAK SP
+    /// Slave:           SAK    SAK    SAK ...    SAK          SAK I0     I1     ... IN
+    /// ```
+    ///
+    /// Where
+    ///
+    /// - `ST` = start condition
+    /// - `SAD+W` = slave address followed by bit 0 to indicate writing
+    /// - `SAK` = slave acknowledge
+    /// - `Oi` = ith outgoing byte of data
+    /// - `SR` = repeated start condition
+    /// - `SAD+R` = slave address followed by bit 1 to indicate reading
+    /// - `Ii` = ith incoming byte of data
+    /// - `MAK` = master acknowledge
+    /// - `NMAK` = master no acknowledge
+    /// - `SP` = stop condition
+    fn write_read<'a>(
+        self: Pin<&'a mut Self>,
+        address: A,
+        bytes: &[u8],
+        buffer: &mut [u8],
+    ) -> Self::WriteReadFuture<'a>;
+}
diff --git a/embassy-traits/src/lib.rs b/embassy-traits/src/lib.rs
index 849bbaec3..10d44d9de 100644
--- a/embassy-traits/src/lib.rs
+++ b/embassy-traits/src/lib.rs
@@ -4,8 +4,10 @@
 #![feature(const_fn_fn_ptr_basics)]
 #![feature(const_option)]
 #![allow(incomplete_features)]
+#![feature(type_alias_impl_trait)]
 
 pub mod delay;
 pub mod flash;
 pub mod gpio;
+pub mod i2c;
 pub mod uart;