I2c rename, small docs clean up (#2320)

* cleanup prelude docs

* fixups and i2c rename

* changelog and migration

* fixup docs and examples

* fix lint

esp-hal/CHANGELOG.md

@@ -67,6 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - I2c `transaction` is now also available as a inherent function, lift size limit on `write`,`read` and `write_read` (#2262)
 - SPI transactions are now cancelled if the transfer object (or async Future) is dropped. (#2216)
 - The DMA channel types have been removed from peripherals (#2261)
+- `I2C` driver renamed to `I2c` (#2320)
 
 ### Fixed
 

esp-hal/MIGRATING-0.20.md

@@ -339,3 +339,7 @@ A non-exhausitve list demonstrating this change:
 -SpiDma<'static, esp_hal::peripherals::SPI2, DmaChannel0, HalfDuplexMode, Blocking>
 +SpiDma<'static, esp_hal::peripherals::SPI2, HalfDuplexMode, Blocking>
 ```
+
+## `I2C` driver renamed to `I2c`
+
+To firstly match the naming in `embedded-hal`, but also because types should be `UpperCamelCase`.

esp-hal/src/clock/mod.rs

@@ -20,15 +20,11 @@
 //! The `CPU clock` is responsible for defining the speed at which the central
 //! processing unit (CPU) operates. This driver provides predefined options for
 //! different CPU clock speeds, such as
-//!
-//!   * 80 MHz
-//!   * 96 MHz
-//!   * 120 MHz
-//!   * 160 MHz
-//!   * 240 MHz
-//!
-//! and others, depending on the microcontroller model.
-//!
+#![cfg_attr(not(esp32h2), doc = "* 80MHz")]
+#![cfg_attr(esp32h2, doc = "* 96MHz")]
+#![cfg_attr(esp32c2, doc = "* 120MHz")]
+#![cfg_attr(not(any(esp32c2, esp32h2)), doc = "* 160MHz")]
+#![cfg_attr(xtensa, doc = "* 240MHz")]
 //! ### Frozen Clock Frequencies
 //!
 //! Once the clock configuration is applied, the clock frequencies become
@@ -40,13 +36,7 @@
 //!
 //! ### Initialize With Different Clock Frequencies
 //! ```rust, no_run
-//! # #![no_std]
-//! # use esp_hal::prelude::*;
-//! # #[panic_handler]
-//! # fn panic(_ : &core::panic::PanicInfo) -> ! {
-//! #     loop {}
-//! # }
-//! # fn main() {
+#![doc = crate::before_snippet!()]
 //! // Initialize with the highest possible frequency for this chip
 //! let peripherals = esp_hal::init({
 //!     let mut config = esp_hal::Config::default();

esp-hal/src/gpio/mod.rs

@@ -49,13 +49,13 @@
 //! 
 //! ### Blink an LED
 //!
-//! See the [Commonly Used Setup] section of the crate documentation.
+//! See the [Blinky] section of the crate documentation.
 //!
 //! ### Inverting a signal using `AnyPin`
 //! See the [Inverting TX and RX Pins] example of the UART documentation.
 //!
 //! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
-//! [Commonly Used Setup]: ../index.html#commonly-used-setup
+//! [Blinky]: ../index.html#blinky
 //! [Inverting TX and RX Pins]: ../uart/index.html#inverting-tx-and-rx-pins
 
 use portable_atomic::{AtomicPtr, Ordering};

esp-hal/src/i2c.rs

@@ -31,13 +31,13 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::i2c::I2C;
+//! # use esp_hal::i2c::I2c;
 //! # use esp_hal::gpio::Io;
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //!
 //! // Create a new peripheral object with the described wiring
 //! // and standard I2C clock speed.
-//! let mut i2c = I2C::new(
+//! let mut i2c = I2c::new(
 //!     peripherals.I2C0,
 //!     io.pins.gpio1,
 //!     io.pins.gpio2,
@@ -106,7 +106,7 @@ pub enum Error {
 
 #[derive(PartialEq)]
 // This enum is used to keep track of the last/next operation that was/will be
-// performed in an embedded-hal(-async) I2C::transaction. It is used to
+// performed in an embedded-hal(-async) I2c::transaction. It is used to
 // determine whether a START condition should be issued at the start of the
 // current operation and whether a read needs an ack or a nack for the final
 // byte.
@@ -228,15 +228,15 @@ impl From<Ack> for u32 {
     }
 }
 
-/// I2C peripheral container (I2C)
-pub struct I2C<'d, T, DM: crate::Mode> {
+/// I2C driver
+pub struct I2c<'d, T, DM: crate::Mode> {
     peripheral: PeripheralRef<'d, T>,
     phantom: PhantomData<DM>,
     frequency: HertzU32,
     timeout: Option<u32>,
 }
 
-impl<T> I2C<'_, T, crate::Blocking>
+impl<T> I2c<'_, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -420,7 +420,7 @@ where
     }
 }
 
-impl<T> embedded_hal_02::blocking::i2c::Read for I2C<'_, T, crate::Blocking>
+impl<T> embedded_hal_02::blocking::i2c::Read for I2c<'_, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -431,7 +431,7 @@ where
     }
 }
 
-impl<T> embedded_hal_02::blocking::i2c::Write for I2C<'_, T, crate::Blocking>
+impl<T> embedded_hal_02::blocking::i2c::Write for I2c<'_, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -442,7 +442,7 @@ where
     }
 }
 
-impl<T> embedded_hal_02::blocking::i2c::WriteRead for I2C<'_, T, crate::Blocking>
+impl<T> embedded_hal_02::blocking::i2c::WriteRead for I2c<'_, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -458,11 +458,11 @@ where
     }
 }
 
-impl<T, DM: crate::Mode> embedded_hal::i2c::ErrorType for I2C<'_, T, DM> {
+impl<T, DM: crate::Mode> embedded_hal::i2c::ErrorType for I2c<'_, T, DM> {
     type Error = Error;
 }
 
-impl<T> embedded_hal::i2c::I2c for I2C<'_, T, crate::Blocking>
+impl<T> embedded_hal::i2c::I2c for I2c<'_, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -475,7 +475,7 @@ where
     }
 }
 
-impl<'d, T, DM: crate::Mode> I2C<'d, T, DM>
+impl<'d, T, DM: crate::Mode> I2c<'d, T, DM>
 where
     T: Instance,
 {
@@ -494,7 +494,7 @@ where
         PeripheralClockControl::reset(T::peripheral());
         PeripheralClockControl::enable(T::peripheral());
 
-        let i2c = I2C {
+        let i2c = I2c {
             peripheral: i2c,
             phantom: PhantomData,
             frequency,
@@ -548,7 +548,7 @@ where
     }
 }
 
-impl<'d, T> I2C<'d, T, crate::Blocking>
+impl<'d, T> I2c<'d, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -581,9 +581,9 @@ where
     }
 }
 
-impl<'d, T> crate::private::Sealed for I2C<'d, T, crate::Blocking> where T: Instance {}
+impl<'d, T> crate::private::Sealed for I2c<'d, T, crate::Blocking> where T: Instance {}
 
-impl<'d, T> InterruptConfigurable for I2C<'d, T, crate::Blocking>
+impl<'d, T> InterruptConfigurable for I2c<'d, T, crate::Blocking>
 where
     T: Instance,
 {
@@ -592,7 +592,7 @@ where
     }
 }
 
-impl<'d, T> I2C<'d, T, crate::Async>
+impl<'d, T> I2c<'d, T, crate::Async>
 where
     T: Instance,
 {
@@ -779,7 +779,7 @@ mod asynch {
         }
     }
 
-    impl<T> I2C<'_, T, crate::Async>
+    impl<T> I2c<'_, T, crate::Async>
     where
         T: Instance,
     {
@@ -1170,7 +1170,7 @@ mod asynch {
         }
     }
 
-    impl<'d, T> embedded_hal_async::i2c::I2c for I2C<'d, T, crate::Async>
+    impl<'d, T> embedded_hal_async::i2c::I2c for I2c<'d, T, crate::Async>
     where
         T: Instance,
     {

esp-hal/src/lib.rs

@@ -52,7 +52,7 @@
 //! cargo generate -a esp-rs/esp-template
 //! ```
 //!
-//! ## Commonly Used Setup
+//! ## Blinky
 //!
 //! Some minimal code to blink an LED looks like this:
 //!

esp-hal/src/prelude.rs

@@ -6,36 +6,46 @@
 //! things, particularly traits, which are used in almost every single Rust
 //! program.
 
-pub use fugit::{ExtU64 as _fugit_ExtU64, RateExtU32 as _fugit_RateExtU32};
-pub use nb;
+pub use imp::*;
 
-#[cfg(dac)]
-pub use crate::analog::dac::Instance as _esp_hal_analog_dac_Instance;
-#[cfg(any(dport, pcr, system))]
-pub use crate::clock::Clock as _esp_hal_clock_Clock;
-#[cfg(gpio)]
-pub use crate::gpio::{
-    InputPin as _esp_hal_gpio_InputPin,
-    OutputPin as _esp_hal_gpio_OutputPin,
-    Pin as _esp_hal_gpio_Pin,
-};
-#[cfg(any(i2c0, i2c1))]
-pub use crate::i2c::Instance as _esp_hal_i2c_Instance;
-#[cfg(ledc)]
-pub use crate::ledc::{
-    channel::{
-        ChannelHW as _esp_hal_ledc_channel_ChannelHW,
-        ChannelIFace as _esp_hal_ledc_channel_ChannelIFace,
-    },
-    timer::{TimerHW as _esp_hal_ledc_timer_TimerHW, TimerIFace as _esp_hal_ledc_timer_TimerIFace},
-};
-#[cfg(any(timg0, timg1))]
-pub use crate::timer::timg::{
-    Instance as _esp_hal_timer_timg_Instance,
-    TimerGroupInstance as _esp_hal_timer_timg_TimerGroupInstance,
-};
-#[cfg(any(systimer, timg0, timg1))]
-pub use crate::timer::Timer as _esp_hal_timer_Timer;
-#[cfg(any(uart0, uart1, uart2))]
-pub use crate::uart::Instance as _esp_hal_uart_Instance;
-pub use crate::{clock::CpuClock, entry, macros::*, InterruptConfigurable};
+#[doc(hidden)]
+mod imp {
+    #[doc(hidden)]
+    pub use fugit::{ExtU64 as _, RateExtU32 as _};
+    #[doc(hidden)]
+    pub use nb;
+
+    #[cfg(dac)]
+    pub use crate::analog::dac::Instance as _esp_hal_analog_dac_Instance;
+    #[cfg(any(dport, pcr, system))]
+    pub use crate::clock::Clock as _esp_hal_clock_Clock;
+    #[cfg(gpio)]
+    pub use crate::gpio::{
+        InputPin as _esp_hal_gpio_InputPin,
+        OutputPin as _esp_hal_gpio_OutputPin,
+        Pin as _esp_hal_gpio_Pin,
+    };
+    #[cfg(any(i2c0, i2c1))]
+    pub use crate::i2c::Instance as _esp_hal_i2c_Instance;
+    #[cfg(ledc)]
+    pub use crate::ledc::{
+        channel::{
+            ChannelHW as _esp_hal_ledc_channel_ChannelHW,
+            ChannelIFace as _esp_hal_ledc_channel_ChannelIFace,
+        },
+        timer::{
+            TimerHW as _esp_hal_ledc_timer_TimerHW,
+            TimerIFace as _esp_hal_ledc_timer_TimerIFace,
+        },
+    };
+    #[cfg(any(timg0, timg1))]
+    pub use crate::timer::timg::{
+        Instance as _esp_hal_timer_timg_Instance,
+        TimerGroupInstance as _esp_hal_timer_timg_TimerGroupInstance,
+    };
+    #[cfg(any(systimer, timg0, timg1))]
+    pub use crate::timer::Timer as _esp_hal_timer_Timer;
+    #[cfg(any(uart0, uart1, uart2))]
+    pub use crate::uart::Instance as _esp_hal_uart_Instance;
+    pub use crate::{clock::CpuClock, entry, macros::*, InterruptConfigurable};
+}

esp-hal/src/rtc_cntl/mod.rs

@@ -26,7 +26,6 @@
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::rtc_cntl::Rtc;
 //! # use esp_hal::rtc_cntl::Rwdt;
-//! # use crate::esp_hal::prelude::_fugit_ExtU64;
 //! # use crate::esp_hal::InterruptConfigurable;
 //! static RWDT: Mutex<RefCell<Option<Rwdt>>> = Mutex::new(RefCell::new(None));
 //! let mut delay = Delay::new();

esp-hal/src/soc/esp32/cpu_control.rs

@@ -12,7 +12,6 @@
 //! # use esp_hal::cpu_control::{CpuControl, Stack};
 //! # use core::{cell::RefCell, ptr::addr_of_mut};
 //! # use critical_section::Mutex;
-//! # use esp_hal::prelude::*;
 //! static mut APP_CORE_STACK: Stack<8192> = Stack::new();
 //!
 //! # let delay = Delay::new();
@@ -36,7 +35,6 @@
 //! // Where `cpu1_task()` may be defined as:
 //! # use esp_hal::delay::Delay;
 //! # use core::cell::RefCell;
-//! # use esp_hal::prelude::*;
 //! fn cpu1_task(
 //!     delay: &Delay,
 //!     counter: &critical_section::Mutex<RefCell<i32>>,

esp-wifi/src/lib.rs

@@ -96,7 +96,7 @@
 
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 #![no_std]
-#![cfg_attr(target_arch = "xtensa", feature(asm_experimental_arch))]
+#![cfg_attr(xtensa, feature(asm_experimental_arch))]
 #![cfg_attr(feature = "sys-logs", feature(c_variadic))]
 #![allow(rustdoc::bare_urls)]
 // allow until num-derive doesn't generate this warning anymore (unknown_lints because Xtensa

examples/src/bin/embassy_i2c.rs

@@ -19,7 +19,7 @@
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
-use esp_hal::{gpio::Io, i2c::I2C, prelude::*, timer::timg::TimerGroup};
+use esp_hal::{gpio::Io, i2c::I2c, prelude::*, timer::timg::TimerGroup};
 use lis3dh_async::{Lis3dh, Range, SlaveAddr};
 
 #[esp_hal_embassy::main]
@@ -31,7 +31,7 @@ async fn main(_spawner: Spawner) {
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 
-    let i2c0 = I2C::new_async(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 400.kHz());
+    let i2c0 = I2c::new_async(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 400.kHz());
 
     let mut lis3dh = Lis3dh::new_i2c(i2c0, SlaveAddr::Alternate).await.unwrap();
     lis3dh.set_range(Range::G8).await.unwrap();

examples/src/bin/embassy_i2c_bmp180_calibration_data.rs

@@ -20,7 +20,7 @@
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
-use esp_hal::{gpio::Io, i2c::I2C, prelude::*, timer::timg::TimerGroup};
+use esp_hal::{gpio::Io, i2c::I2c, prelude::*, timer::timg::TimerGroup};
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
@@ -31,7 +31,7 @@ async fn main(_spawner: Spawner) {
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 
-    let mut i2c = I2C::new_async(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 400.kHz());
+    let mut i2c = I2c::new_async(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 400.kHz());
 
     loop {
         let mut data = [0u8; 22];

examples/src/bin/i2c_bmp180_calibration_data.rs

@@ -12,7 +12,7 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{gpio::Io, i2c::I2C, prelude::*};
+use esp_hal::{gpio::Io, i2c::I2c, prelude::*};
 use esp_println::println;
 
 #[entry]
@@ -23,7 +23,7 @@ fn main() -> ! {
 
     // Create a new peripheral object with the described wiring and standard
     // I2C clock speed:
-    let mut i2c = I2C::new(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 100.kHz());
+    let mut i2c = I2c::new(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 100.kHz());
 
     loop {
         let mut data = [0u8; 22];

examples/src/bin/i2c_display.rs

@@ -22,7 +22,7 @@ use embedded_graphics::{
     text::{Alignment, Text},
 };
 use esp_backtrace as _;
-use esp_hal::{delay::Delay, gpio::Io, i2c::I2C, prelude::*};
+use esp_hal::{delay::Delay, gpio::Io, i2c::I2c, prelude::*};
 use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 
 #[entry]
@@ -34,7 +34,7 @@ fn main() -> ! {
 
     // Create a new peripheral object with the described wiring
     // and standard I2C clock speed
-    let i2c = I2C::new(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 100.kHz());
+    let i2c = I2c::new(peripherals.I2C0, io.pins.gpio4, io.pins.gpio5, 100.kHz());
 
     // Initialize display
     let interface = I2CDisplayInterface::new(i2c);

examples/src/bin/lcd_cam_ov2640.rs

@@ -30,7 +30,7 @@ use esp_hal::{
     dma_rx_stream_buffer,
     gpio::Io,
     i2c,
-    i2c::I2C,
+    i2c::I2c,
     lcd_cam::{
         cam::{Camera, RxEightBits},
         LcdCam,
@@ -80,7 +80,7 @@ fn main() -> ! {
 
     delay.delay_millis(500u32);
 
-    let i2c = I2C::new(peripherals.I2C0, cam_siod, cam_sioc, 100u32.kHz());
+    let i2c = I2c::new(peripherals.I2C0, cam_siod, cam_sioc, 100u32.kHz());
 
     let mut sccb = Sccb::new(i2c);
 
@@ -165,14 +165,14 @@ fn main() -> ! {
 pub const OV2640_ADDRESS: u8 = 0x30;
 
 pub struct Sccb<'d, T> {
-    i2c: I2C<'d, T, Blocking>,
+    i2c: I2c<'d, T, Blocking>,
 }
 
 impl<'d, T> Sccb<'d, T>
 where
     T: i2c::Instance,
 {
-    pub fn new(i2c: I2C<'d, T, Blocking>) -> Self {
+    pub fn new(i2c: I2c<'d, T, Blocking>) -> Self {
         Self { i2c }
     }
 

hil-test/tests/i2c.rs

@@ -7,7 +7,7 @@
 
 use esp_hal::{
     gpio::Io,
-    i2c::{Operation, I2C},
+    i2c::{I2c, Operation},
     peripherals::I2C0,
     prelude::*,
     Blocking,
@@ -15,7 +15,7 @@ use esp_hal::{
 use hil_test as _;
 
 struct Context {
-    i2c: I2C<'static, I2C0, Blocking>,
+    i2c: I2c<'static, I2C0, Blocking>,
 }
 #[cfg(test)]
 #[embedded_test::tests]
@@ -31,7 +31,7 @@ mod tests {
 
         // Create a new peripheral object with the described wiring and standard
         // I2C clock speed:
-        let i2c = I2C::new(peripherals.I2C0, sda, scl, 100.kHz());
+        let i2c = I2c::new(peripherals.I2C0, sda, scl, 100.kHz());
 
         Context { i2c }
     }