avr_hal_generic/
i2c.rs

Help
1//! I2C Implementations
2//!
3//! Check the documentation of [`I2c`] for details.
4
5use embedded_hal::i2c::SevenBitAddress;
6
7use crate::port;
8use core::marker::PhantomData;
9
10/// TWI Status Codes
11pub mod twi_status {
12    // The status codes defined in the C header are meant to be used with the
13    // masked status value: (TWSR & TW_STATUS_MASK).  In our case, svd2rust
14    // already added code to shift it to just the status value, so all status
15    // codes need to be shifted to the right as well.
16
17    /// Start condition transmitted
18    pub const TW_START: u8 = 0x08 >> 3;
19
20    /// Repeated start condition transmitted
21    pub const TW_REP_START: u8 = 0x10 >> 3;
22
23    // Master Transmitter -----------------------------------------------------
24    /// SLA+W transmitted, ACK received
25    pub const TW_MT_SLA_ACK: u8 = 0x18 >> 3;
26
27    /// SLA+W transmitted, NACK received
28    pub const TW_MT_SLA_NACK: u8 = 0x20 >> 3;
29
30    /// Data transmitted, ACK received
31    pub const TW_MT_DATA_ACK: u8 = 0x28 >> 3;
32
33    /// Data transmitted, NACK received
34    pub const TW_MT_DATA_NACK: u8 = 0x30 >> 3;
35
36    /// Arbitration lost in SLA+W or data
37    pub const TW_MT_ARB_LOST: u8 = 0x38 >> 3;
38
39    // Master Receiver --------------------------------------------------------
40    /// Arbitration lost in SLA+R or NACK
41    pub const TW_MR_ARB_LOST: u8 = 0x38 >> 3;
42
43    /// SLA+R transmitted, ACK received
44    pub const TW_MR_SLA_ACK: u8 = 0x40 >> 3;
45
46    /// SLA+R transmitted, NACK received
47    pub const TW_MR_SLA_NACK: u8 = 0x48 >> 3;
48
49    /// Data received, ACK returned
50    pub const TW_MR_DATA_ACK: u8 = 0x50 >> 3;
51
52    /// Data received, NACK returned
53    pub const TW_MR_DATA_NACK: u8 = 0x58 >> 3;
54
55    // Slave Transmitter ------------------------------------------------------
56    /// SLA+R received, ACK returned
57    pub const TW_ST_SLA_ACK: u8 = 0xA8 >> 3;
58
59    /// Arbitration lost in SLA+RW, SLA+R received, ACK returned
60    pub const TW_ST_ARB_LOST_SLA_ACK: u8 = 0xB0 >> 3;
61
62    /// Data transmitted, ACK received
63    pub const TW_ST_DATA_ACK: u8 = 0xB8 >> 3;
64
65    /// Data transmitted, NACK received
66    pub const TW_ST_DATA_NACK: u8 = 0xC0 >> 3;
67
68    /// Last data byte transmitted, ACK received
69    pub const TW_ST_LAST_DATA: u8 = 0xC8 >> 3;
70
71    // Slave Receiver ---------------------------------------------------------
72    /// SLA+W received, ACK returned
73    pub const TW_SR_SLA_ACK: u8 = 0x60 >> 3;
74
75    /// Arbitration lost in SLA+RW, SLA+W received, ACK returned
76    pub const TW_SR_ARB_LOST_SLA_ACK: u8 = 0x68 >> 3;
77
78    /// General call received, ACK returned
79    pub const TW_SR_GCALL_ACK: u8 = 0x70 >> 3;
80
81    /// Arbitration lost in SLA+RW, general call received, ACK returned
82    pub const TW_SR_ARB_LOST_GCALL_ACK: u8 = 0x78 >> 3;
83
84    /// Data received, ACK returned
85    pub const TW_SR_DATA_ACK: u8 = 0x80 >> 3;
86
87    /// Data received, NACK returned
88    pub const TW_SR_DATA_NACK: u8 = 0x88 >> 3;
89
90    /// General call data received, ACK returned
91    pub const TW_SR_GCALL_DATA_ACK: u8 = 0x90 >> 3;
92
93    /// General call data received, NACK returned
94    pub const TW_SR_GCALL_DATA_NACK: u8 = 0x98 >> 3;
95
96    /// Stop or repeated start condition received while selected
97    pub const TW_SR_STOP: u8 = 0xA0 >> 3;
98
99    // Misc -------------------------------------------------------------------
100    /// No state information available
101    pub const TW_NO_INFO: u8 = 0xF8 >> 3;
102
103    /// Illegal start or stop condition
104    pub const TW_BUS_ERROR: u8 = 0x00 >> 3;
105}
106
107/// I2C Error
108#[derive(ufmt::derive::uDebug, Debug, Clone, Copy, Eq, PartialEq)]
109#[repr(u8)]
110pub enum Error {
111    /// Lost arbitration while trying to acquire bus
112    ArbitrationLost,
113    /// No slave answered for this address or a slave replied NACK
114    AddressNack,
115    /// Slave replied NACK to sent data
116    DataNack,
117    /// A bus-error occured
118    BusError,
119    /// An unknown error occured.  The bus might be in an unknown state.
120    Unknown,
121}
122
123impl embedded_hal::i2c::Error for Error {
124    fn kind(&self) -> embedded_hal::i2c::ErrorKind {
125        match *self {
126            Error::ArbitrationLost => embedded_hal::i2c::ErrorKind::ArbitrationLoss,
127            Error::AddressNack => embedded_hal::i2c::ErrorKind::NoAcknowledge(
128                embedded_hal::i2c::NoAcknowledgeSource::Address,
129            ),
130            Error::DataNack => embedded_hal::i2c::ErrorKind::NoAcknowledge(
131                embedded_hal::i2c::NoAcknowledgeSource::Data,
132            ),
133            Error::BusError => embedded_hal::i2c::ErrorKind::Bus,
134            Error::Unknown => embedded_hal::i2c::ErrorKind::Other,
135        }
136    }
137}
138
139impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> embedded_hal::i2c::ErrorType
140    for I2c<H, I2C, SDA, SCL, CLOCK>
141{
142    type Error = Error;
143}
144
145/// I2C Transfer Direction
146#[derive(ufmt::derive::uDebug, Debug, Clone, Copy, Eq, PartialEq)]
147#[repr(u8)]
148pub enum Direction {
149    /// Write to a slave (LSB is 0)
150    Write,
151    /// Read from a slave (LSB is 1)
152    Read,
153}
154
155/// Internal trait for low-level I2C peripherals.
156///
157/// This trait defines the common interface for all I2C peripheral variants.  It is used as an
158/// intermediate abstraction ontop of which the [`I2c`] API is built.  **Prefer using the
159/// [`I2c`] API instead of this trait.**
160pub trait I2cOps<H, SDA, SCL> {
161    /// Setup the bus for operation at a certain speed.
162    ///
163    /// **Warning**: This is a low-level method and should not be called directly from user code.
164    fn raw_setup<CLOCK: crate::clock::Clock>(&mut self, speed: u32);
165
166    /// Start a bus transaction to a certain `address` in either read or write mode.
167    ///
168    /// If a previous transaction was not stopped via `raw_stop()`, this should generate a repeated
169    /// start condition.
170    ///
171    /// **Warning**: This is a low-level method and should not be called directly from user code.
172    fn raw_start(&mut self, address: u8, direction: Direction) -> Result<(), Error>;
173
174    /// Write some bytes to the bus.
175    ///
176    /// This method must only be called after a transaction in write mode was successfully started.
177    ///
178    /// **Warning**: This is a low-level method and should not be called directly from user code.
179    fn raw_write(&mut self, bytes: &[u8]) -> Result<(), Error>;
180
181    /// Read some bytes from the bus.
182    ///
183    /// This method must only be called after a transaction in read mode was successfully started.
184    ///
185    /// **Warning**: This is a low-level method and should not be called directly from user code.
186    fn raw_read(&mut self, buffer: &mut [u8]) -> Result<(), Error>;
187
188    /// Send a stop-condition and release the bus.
189    ///
190    /// This method must only be called after successfully starting a bus transaction.  This method
191    /// does not need to block until the stop condition has actually occured.
192    ///
193    /// **Warning**: This is a low-level method and should not be called directly from user code.
194    fn raw_stop(&mut self) -> Result<(), Error>;
195}
196
197/// I2C driver
198///
199/// # Example
200/// (for Arduino Uno)
201/// ```
202/// let dp = arduino_hal::Peripherals::take().unwrap();
203/// let pins = arduino_hal::pins!(dp);
204///
205/// let mut i2c = arduino_hal::I2c::new(
206///     dp.TWI,
207///     pins.a4.into_pull_up_input(),
208///     pins.a5.into_pull_up_input(),
209///     50000,
210/// );
211///
212/// // i2c implements the embedded-hal traits so it can be used with generic drivers.
213/// ```
214pub struct I2c<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> {
215    p: I2C,
216    #[allow(dead_code)]
217    sda: SDA,
218    #[allow(dead_code)]
219    scl: SCL,
220    _clock: PhantomData<CLOCK>,
221    _h: PhantomData<H>,
222}
223
224impl<H, I2C, SDAPIN, SCLPIN, CLOCK>
225    I2c<H, I2C, port::Pin<port::mode::Input, SDAPIN>, port::Pin<port::mode::Input, SCLPIN>, CLOCK>
226where
227    I2C: I2cOps<H, port::Pin<port::mode::Input, SDAPIN>, port::Pin<port::mode::Input, SCLPIN>>,
228    SDAPIN: port::PinOps,
229    SCLPIN: port::PinOps,
230    CLOCK: crate::clock::Clock,
231{
232    /// Initialize an I2C peripheral on the given pins.
233    ///
234    /// Note that the SDA and SCL pins are hardwired for each I2C peripheral and you *must* pass
235    /// the correct ones.  This is enforced at compile time.
236    ///
237    /// This method expects the internal pull-ups to be configured for both pins to comply with the
238    /// I2C specification.  If you have external pull-ups connected, use
239    /// [`I2c::with_external_pullup`] instead.
240    pub fn new(
241        p: I2C,
242        sda: port::Pin<port::mode::Input<port::mode::PullUp>, SDAPIN>,
243        scl: port::Pin<port::mode::Input<port::mode::PullUp>, SCLPIN>,
244        speed: u32,
245    ) -> Self {
246        let mut i2c = Self {
247            p,
248            sda: sda.forget_imode(),
249            scl: scl.forget_imode(),
250            _clock: PhantomData,
251            _h: PhantomData,
252        };
253        i2c.p.raw_setup::<CLOCK>(speed);
254        i2c
255    }
256
257    /// Initialize an I2C peripheral on the given pins.
258    ///
259    /// Note that the SDA and SCL pins are hardwired for each I2C peripheral and you *must* pass
260    /// the correct ones.  This is enforced at compile time.
261    ///
262    /// This method expects that external resistors pull up SDA and SCL.
263    pub fn with_external_pullup(
264        p: I2C,
265        sda: port::Pin<port::mode::Input<port::mode::Floating>, SDAPIN>,
266        scl: port::Pin<port::mode::Input<port::mode::Floating>, SCLPIN>,
267        speed: u32,
268    ) -> Self {
269        let mut i2c = Self {
270            p,
271            sda: sda.forget_imode(),
272            scl: scl.forget_imode(),
273            _clock: PhantomData,
274            _h: PhantomData,
275        };
276        i2c.p.raw_setup::<CLOCK>(speed);
277        i2c
278    }
279}
280
281impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> I2c<H, I2C, SDA, SCL, CLOCK>
282where
283    CLOCK: crate::clock::Clock,
284    crate::delay::Delay<CLOCK>: embedded_hal_v0::blocking::delay::DelayMs<u16>,
285{
286    /// Test whether a device answers on a certain address.
287    pub fn ping_device(&mut self, address: u8, direction: Direction) -> Result<bool, Error> {
288        match self.p.raw_start(address, direction) {
289            Ok(_) => {
290                self.p.raw_stop()?;
291                Ok(true)
292            }
293            Err(Error::AddressNack) => Ok(false),
294            Err(e) => Err(e),
295        }
296    }
297
298    /// Scan the bus for connected devices.  This method will output an summary in the format known
299    /// from [`i2cdetect(8)`][i2cdetect-linux] on the selected serial connection.  For example:
300    ///
301    /// ```text
302    /// -    0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
303    /// 00:       -- -- -- -- -- -- -- -- -- -- -- -- -- --
304    /// 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
305    /// 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
306    /// 30: -- -- -- -- -- -- -- -- 38 39 -- -- -- -- -- --
307    /// 40: -- -- -- -- -- -- -- -- 48 -- -- -- -- -- -- --
308    /// 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
309    /// 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
310    /// 70: -- -- -- -- -- -- -- --
311    /// ```
312    ///
313    /// [i2cdetect-linux]: https://man.archlinux.org/man/community/i2c-tools/i2cdetect.8.en
314    pub fn i2cdetect<W: ufmt::uWrite>(
315        &mut self,
316        w: &mut W,
317        direction: Direction,
318    ) -> Result<(), W::Error> {
319        use embedded_hal_v0::blocking::delay::DelayMs;
320        let mut delay = crate::delay::Delay::<CLOCK>::new();
321
322        w.write_str(
323            "\
324-    0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f\r\n\
32500:      ",
326        )?;
327
328        fn u4_to_hex(b: u8) -> char {
329            match b {
330                x if x < 0xa => (0x30 + x).into(),
331                x if x < 0x10 => (0x57 + x).into(),
332                _ => '?',
333            }
334        }
335
336        for address in 0x02..=0x77 {
337            let (ah, al) = (u4_to_hex(address >> 4), u4_to_hex(address & 0xf));
338
339            if address % 0x10 == 0 {
340                w.write_str("\r\n")?;
341                w.write_char(ah)?;
342                w.write_str("0:")?;
343            }
344
345            match self.ping_device(address, direction) {
346                Ok(true) => {
347                    w.write_char(' ')?;
348                    w.write_char(ah)?;
349                    w.write_char(al)?;
350                }
351                Ok(false) => {
352                    w.write_str(" --")?;
353                }
354                Err(e) => {
355                    w.write_str(" E")?;
356                    w.write_char(u4_to_hex(e as u8))?;
357                }
358            }
359
360            delay.delay_ms(10u16);
361        }
362
363        w.write_str("\r\n")?;
364
365        Ok(())
366    }
367}
368
369impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> embedded_hal_v0::blocking::i2c::Write
370    for I2c<H, I2C, SDA, SCL, CLOCK>
371{
372    type Error = Error;
373
374    fn write(&mut self, address: u8, bytes: &[u8]) -> Result<(), Self::Error> {
375        self.p.raw_start(address, Direction::Write)?;
376        self.p.raw_write(bytes)?;
377        self.p.raw_stop()?;
378        Ok(())
379    }
380}
381
382impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> embedded_hal_v0::blocking::i2c::Read
383    for I2c<H, I2C, SDA, SCL, CLOCK>
384{
385    type Error = Error;
386
387    fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
388        self.p.raw_start(address, Direction::Read)?;
389        self.p.raw_read(buffer)?;
390        self.p.raw_stop()?;
391        Ok(())
392    }
393}
394
395impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> embedded_hal_v0::blocking::i2c::WriteRead
396    for I2c<H, I2C, SDA, SCL, CLOCK>
397{
398    type Error = Error;
399
400    fn write_read(
401        &mut self,
402        address: u8,
403        bytes: &[u8],
404        buffer: &mut [u8],
405    ) -> Result<(), Self::Error> {
406        self.p.raw_start(address, Direction::Write)?;
407        self.p.raw_write(bytes)?;
408        self.p.raw_start(address, Direction::Read)?;
409        self.p.raw_read(buffer)?;
410        self.p.raw_stop()?;
411        Ok(())
412    }
413}
414
415impl<H, I2C: I2cOps<H, SDA, SCL>, SDA, SCL, CLOCK> embedded_hal::i2c::I2c<SevenBitAddress>
416    for I2c<H, I2C, SDA, SCL, CLOCK>
417{
418    fn transaction(
419        &mut self,
420        address: u8,
421        operations: &mut [embedded_hal::i2c::Operation<'_>],
422    ) -> Result<(), Self::Error> {
423        let mut previous_direction = Direction::Read;
424        for (idx, operation) in operations.iter_mut().enumerate() {
425            match operation {
426                embedded_hal::i2c::Operation::Read(buffer) => {
427                    if idx == 0 || previous_direction != Direction::Read {
428                        self.p.raw_start(address, Direction::Read)?;
429                    }
430                    self.p.raw_read(buffer)?;
431                    previous_direction = Direction::Read;
432                }
433                embedded_hal::i2c::Operation::Write(bytes) => {
434                    if idx == 0 || previous_direction != Direction::Write {
435                        self.p.raw_start(address, Direction::Write)?;
436                    }
437                    self.p.raw_write(bytes)?;
438                    previous_direction = Direction::Write;
439                }
440            }
441        }
442        if operations.len() > 0 {
443            self.p.raw_stop()?;
444        }
445
446        Ok(())
447    }
448}
449
450#[macro_export]
451macro_rules! impl_i2c_twi {
452    (
453        hal: $HAL:ty,
454        peripheral: $I2C:ty,
455        sda: $sdapin:ty,
456        scl: $sclpin:ty,
457    ) => {
458        impl
459            $crate::i2c::I2cOps<
460                $HAL,
461                $crate::port::Pin<$crate::port::mode::Input, $sdapin>,
462                $crate::port::Pin<$crate::port::mode::Input, $sclpin>,
463            > for $I2C
464        {
465            #[inline]
466            fn raw_setup<CLOCK: $crate::clock::Clock>(&mut self, speed: u32) {
467                // Calculate TWBR register value
468                let twbr = ((CLOCK::FREQ / speed) - 16) / 2;
469                self.twbr.write(|w| unsafe { w.bits(twbr as u8) });
470
471                // Disable prescaler
472                self.twsr.write(|w| w.twps().prescaler_1());
473            }
474
475            #[inline]
476            fn raw_start(&mut self, address: u8, direction: Direction) -> Result<(), Error> {
477                // Write start condition
478                self.twcr
479                    .write(|w| w.twen().set_bit().twint().set_bit().twsta().set_bit());
480                // wait()
481                while self.twcr.read().twint().bit_is_clear() {}
482
483                // Validate status
484                match self.twsr.read().tws().bits() {
485                    $crate::i2c::twi_status::TW_START | $crate::i2c::twi_status::TW_REP_START => (),
486                    $crate::i2c::twi_status::TW_MT_ARB_LOST
487                    | $crate::i2c::twi_status::TW_MR_ARB_LOST => {
488                        return Err($crate::i2c::Error::ArbitrationLost);
489                    }
490                    $crate::i2c::twi_status::TW_BUS_ERROR => {
491                        return Err($crate::i2c::Error::BusError);
492                    }
493                    _ => {
494                        return Err($crate::i2c::Error::Unknown);
495                    }
496                }
497
498                // Send slave address
499                let dirbit = if direction == $crate::i2c::Direction::Read {
500                    1
501                } else {
502                    0
503                };
504                let rawaddr = (address << 1) | dirbit;
505                self.twdr.write(|w| unsafe { w.bits(rawaddr) });
506                // transact()
507                self.twcr.write(|w| w.twen().set_bit().twint().set_bit());
508                while self.twcr.read().twint().bit_is_clear() {}
509
510                // Check if the slave responded
511                match self.twsr.read().tws().bits() {
512                    $crate::i2c::twi_status::TW_MT_SLA_ACK
513                    | $crate::i2c::twi_status::TW_MR_SLA_ACK => (),
514                    $crate::i2c::twi_status::TW_MT_SLA_NACK
515                    | $crate::i2c::twi_status::TW_MR_SLA_NACK => {
516                        // Stop the transaction if it did not respond
517                        self.raw_stop()?;
518                        return Err($crate::i2c::Error::AddressNack);
519                    }
520                    $crate::i2c::twi_status::TW_MT_ARB_LOST
521                    | $crate::i2c::twi_status::TW_MR_ARB_LOST => {
522                        return Err($crate::i2c::Error::ArbitrationLost);
523                    }
524                    $crate::i2c::twi_status::TW_BUS_ERROR => {
525                        return Err($crate::i2c::Error::BusError);
526                    }
527                    _ => {
528                        return Err($crate::i2c::Error::Unknown);
529                    }
530                }
531
532                Ok(())
533            }
534
535            #[inline]
536            fn raw_write(&mut self, bytes: &[u8]) -> Result<(), Error> {
537                for byte in bytes {
538                    self.twdr.write(|w| unsafe { w.bits(*byte) });
539                    // transact()
540                    self.twcr.write(|w| w.twen().set_bit().twint().set_bit());
541                    while self.twcr.read().twint().bit_is_clear() {}
542
543                    match self.twsr.read().tws().bits() {
544                        $crate::i2c::twi_status::TW_MT_DATA_ACK => (),
545                        $crate::i2c::twi_status::TW_MT_DATA_NACK => {
546                            self.raw_stop()?;
547                            return Err($crate::i2c::Error::DataNack);
548                        }
549                        $crate::i2c::twi_status::TW_MT_ARB_LOST => {
550                            return Err($crate::i2c::Error::ArbitrationLost);
551                        }
552                        $crate::i2c::twi_status::TW_BUS_ERROR => {
553                            return Err($crate::i2c::Error::BusError);
554                        }
555                        _ => {
556                            return Err($crate::i2c::Error::Unknown);
557                        }
558                    }
559                }
560                Ok(())
561            }
562
563            #[inline]
564            fn raw_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
565                let last = buffer.len() - 1;
566                for (i, byte) in buffer.iter_mut().enumerate() {
567                    if i != last {
568                        self.twcr
569                            .write(|w| w.twint().set_bit().twen().set_bit().twea().set_bit());
570                        // wait()
571                        while self.twcr.read().twint().bit_is_clear() {}
572                    } else {
573                        self.twcr.write(|w| w.twint().set_bit().twen().set_bit());
574                        // wait()
575                        while self.twcr.read().twint().bit_is_clear() {}
576                    }
577
578                    match self.twsr.read().tws().bits() {
579                        $crate::i2c::twi_status::TW_MR_DATA_ACK
580                        | $crate::i2c::twi_status::TW_MR_DATA_NACK => (),
581                        $crate::i2c::twi_status::TW_MR_ARB_LOST => {
582                            return Err($crate::i2c::Error::ArbitrationLost);
583                        }
584                        $crate::i2c::twi_status::TW_BUS_ERROR => {
585                            return Err($crate::i2c::Error::BusError);
586                        }
587                        _ => {
588                            return Err($crate::i2c::Error::Unknown);
589                        }
590                    }
591
592                    *byte = self.twdr.read().bits();
593                }
594                Ok(())
595            }
596
597            #[inline]
598            fn raw_stop(&mut self) -> Result<(), Error> {
599                self.twcr
600                    .write(|w| w.twen().set_bit().twint().set_bit().twsto().set_bit());
601                Ok(())
602            }
603        }
604    };
605}
avr_hal_generic/i2c.rs

avr_hal_generic/
i2c.rs
