Improve documentation of the i2c peripheral driver & improve i2c example

rp2040-hal/examples/i2c.rs

@@ -21,8 +21,11 @@ use fugit::RateExtU32;
 use rp2040_hal as hal;
 
 // A shorter alias for the Peripheral Access Crate, which provides low-level
-// register access
-use hal::pac;
+// register access and a gpio related types.
+use hal::{
+    gpio::{FunctionI2C, Pin, PullUp},
+    pac,
+};
 
 /// The linker will place this boot block at the start of our program image. We
 /// need this to help the ROM bootloader get our code up and running.
@@ -75,9 +78,9 @@ fn main() -> ! {
     );
 
     // Configure two pins as being I²C, not GPIO
-    let sda_pin = pins.gpio18.into_function::<hal::gpio::FunctionI2C>();
-    let scl_pin = pins.gpio19.into_function::<hal::gpio::FunctionI2C>();
-    // let not_an_scl_pin = pins.gpio20.into_function::<hal::gpio::FunctionI2C>();
+    let sda_pin: Pin<_, FunctionI2C, PullUp> = pins.gpio18.reconfigure();
+    let scl_pin: Pin<_, FunctionI2C, PullUp> = pins.gpio19.reconfigure();
+    // let not_an_scl_pin: Pin<_, FunctionI2C, PullUp> = pins.gpio20.reconfigure();
 
     // Create the I²C drive, using the two pre-configured pins. This will fail
     // at compile time if the pins are in the wrong mode, or if this I²C

rp2040-hal/src/i2c.rs

@@ -53,9 +53,7 @@ use crate::{
     typelevel::Sealed,
 };
 
-/// Controller implementaion
-pub mod controller;
-/// Peripheral implementation
+mod controller;
 pub mod peripheral;
 
 /// Pac I2C device

rp2040-hal/src/i2c/peripheral.rs

@@ -1,3 +1,26 @@
+//! # I2C Peripheral (slave) implementation
+//!
+//! The RP2040 I2C block can behave as a peripheral node on an I2C bus.
+//!
+//! In order to handle peripheral transactions this driver exposes an iterator streaming I2C event
+//! that the usercode must handle to properly handle the I2C communitation. See [`I2CEvent`] for a
+//! list of events to handle.
+//!
+//! Although [`Start`](I2CEvent::Start), [`Restart`](I2CEvent::Restart) and [`Stop`](I2CEvent::Stop)
+//! events may not require any action on the device, [`TransferRead`](I2CEvent::TransferRead) and
+//! [`TransferWrite`](I2CEvent::TransferWrite) require some action:
+//!
+//! - [`TransferRead`](I2CEvent::TransferRead): A controller is attempting to read from this peripheral.  
+//!   The I2C block holds the SCL line low (clock stretching) until data is pushed to the transmission
+//!   FIFO by the user application using [`write`](I2CPeripheralEventIterator::write).  
+//!   Data remaining in the FIFO when the bus constroller stops the transfer are ignored & the fifo
+//!   is flushed.
+//! - [`TransferWrite`](I2CEvent::TransferWrite): A controller is sending data to this peripheral.  
+//!   The I2C block holds the SCL line (clock stretching) until there is room for more data in the
+//!   Rx FIFO using [`read`](I2CPeripheralEventIterator::read).  
+//!   Data are automatically acknowledged by the I2C block and it is not possible to NACK incoming
+//!   data comming to the rp2040.
+
 use core::{marker::PhantomData, ops::Deref};
 
 use super::{Peripheral, ValidPinScl, ValidPinSda, I2C};