Module embedded_hal::i2c

Expand description

Blocking 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.

Examples

`embedded-hal` implementation for an MCU

Here is an example of an embedded-hal implementation of the Write trait for both modes:

/// I2C0 hardware peripheral which supports both 7-bit and 10-bit addressing.
pub struct I2c0;

impl I2c<SevenBitAddress> for I2c0
{
    fn read(&mut self, addr: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write(&mut self, addr: u8, bytes: &[u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write_iter<B: IntoIterator<Item = u8>>(&mut self, addr: u8, bytes: B) -> Result<(), Self::Error> {
        // ...
    }
    fn write_read(&mut self, addr: u8, bytes: &[u8], buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write_iter_read<B: IntoIterator<Item = u8>>(&mut self, addr: u8, bytes: B, buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn transaction<'a>(&mut self, address: u8, operations: &mut [Operation<'a>]) -> Result<(), Self::Error> {
        // ...
    }
    fn transaction_iter<'a, O: IntoIterator<Item = Operation<'a>>>(&mut self, address: u8, operations: O) -> Result<(), Self::Error> {
        // ...
    }
}

impl I2c<TenBitAddress> for I2c0
{
    fn read(&mut self, addr: u16, buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write(&mut self, addr: u16, bytes: &[u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write_iter<B: IntoIterator<Item = u8>>(&mut self, addr: u16, bytes: B) -> Result<(), Self::Error> {
        // ...
    }
    fn write_read(&mut self, addr: u16, bytes: &[u8], buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn write_iter_read<B: IntoIterator<Item = u8>>(&mut self, addr: u16, bytes: B, buffer: &mut [u8]) -> Result<(), Self::Error> {
        // ...
    }
    fn transaction<'a>(&mut self, address: u16, operations: &mut [Operation<'a>]) -> Result<(), Self::Error> {
        // ...
    }
    fn transaction_iter<'a, O: IntoIterator<Item = Operation<'a>>>(&mut self, address: u16, operations: O) -> Result<(), Self::Error> {
        // ...
    }
}

Device driver compatible only with 7-bit addresses

For demonstration purposes the address mode parameter has been omitted in this example.

const ADDR: u8  = 0x15;
pub struct TemperatureSensorDriver<I2C> {
    i2c: I2C,
}

impl<I2C, E: Error> TemperatureSensorDriver<I2C>
where
    I2C: I2c<Error = E>,
{
    pub fn read_temperature(&mut self) -> Result<u8, E> {
        let mut temp = [0];
        self.i2c
            .write_read(ADDR, &[TEMP_REGISTER], &mut temp)
            .and(Ok(temp[0]))
    }
}

Device driver compatible only with 10-bit addresses

const ADDR: u16  = 0x158;
pub struct TemperatureSensorDriver<I2C> {
    i2c: I2C,
}

impl<I2C, E: Error> TemperatureSensorDriver<I2C>
where
    I2C: I2c<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)
            .and(Ok(temp[0]))
    }
}