Polish I2C example.

rp2040-hal/examples/i2c.rs

@@ -1,49 +1,108 @@
-//! Sends a message using i2c
-#![no_std]
-#![no_main]
-
-use cortex_m_rt::entry;
-use embedded_hal::blocking::i2c::Write;
-use embedded_time::rate::Extensions;
-use hal::gpio::FunctionI2C;
-use hal::i2c::I2C;
-use hal::pac;
-use hal::sio::Sio;
-use panic_halt as _;
-use rp2040_hal as hal;
-
-#[link_section = ".boot2"]
-#[used]
-pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER;
-
-const SYS_HZ: u32 = 125_000_000_u32;
-
-#[entry]
-fn main() -> ! {
-    let mut pac = pac::Peripherals::take().unwrap();
-
-    let sio = Sio::new(pac.SIO);
-    let pins = hal::gpio::Pins::new(
-        pac.IO_BANK0,
-        pac.PADS_BANK0,
-        sio.gpio_bank0,
-        &mut pac.RESETS,
-    );
-
-    let sda_pin = pins.gpio18.into_mode::<FunctionI2C>();
-    let scl_pin = pins.gpio19.into_mode::<FunctionI2C>();
-
-    let mut i2c = I2C::i2c1(
-        pac.I2C1,
-        sda_pin,
-        scl_pin,
-        400.kHz(),
-        &mut pac.RESETS,
-        SYS_HZ.Hz(),
-    );
-
-    i2c.write(0x2c, &[1, 2, 3]).unwrap();
-
-    #[allow(clippy::empty_loop)]
-    loop {}
-}
+//! # I²C Example
+//!
+//! This application demonstrates how to talk to I²C devices with an RP2040.
+//!
+//! It may need to be adapted to your particular board layout and/or pin assignment.
+//!
+//! See the `Cargo.toml` file for Copyright and licence details.
+
+#![no_std]
+#![no_main]
+
+// The macro for our start-up function
+use cortex_m_rt::entry;
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
+use panic_halt as _;
+
+// The I²C trait from Embedded HAL we need
+use embedded_hal::blocking::i2c::Write;
+
+// A frequency/time related trait we need
+use embedded_time::rate::Extensions;
+
+// Alias for our HAL crate
+use rp2040_hal as hal;
+
+// A shorter alias for the Peripheral Access Crate, which provides low-level
+// register access
+use hal::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.
+#[link_section = ".boot2"]
+#[used]
+pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER;
+
+/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
+/// if your board has a different frequency
+const XTAL_FREQ_HZ: u32 = 12_000_000u32;
+
+/// Entry point to our bare-metal application.
+///
+/// The `#[entry]` macro ensures the Cortex-M start-up code calls this function
+/// as soon as all global variables are initialised.
+///
+/// The function configures the RP2040 peripherals, then performs a single I²C
+/// write to a fixed address.
+#[entry]
+fn main() -> ! {
+    let mut pac = pac::Peripherals::take().unwrap();
+
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::watchdog::Watchdog::new(pac.WATCHDOG);
+
+    // Configure the clocks
+    let clocks = hal::clocks::init_clocks_and_plls(
+        XTAL_FREQ_HZ,
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut watchdog,
+    )
+    .ok()
+    .unwrap();
+
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::sio::Sio::new(pac.SIO);
+
+    // Set the pins to their default state
+    let pins = hal::gpio::Pins::new(
+        pac.IO_BANK0,
+        pac.PADS_BANK0,
+        sio.gpio_bank0,
+        &mut pac.RESETS,
+    );
+
+    // Configure two pins as being I²C, not GPIO
+    let sda_pin = pins.gpio18.into_mode::<hal::gpio::FunctionI2C>();
+    let scl_pin = pins.gpio19.into_mode::<hal::gpio::FunctionI2C>();
+    // let not_an_scl_pin = pins.gpio20.into_mode::<hal::gpio::FunctionI2C>();
+
+    // 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
+    // peripheral isn't available on these pins!
+    let mut i2c = hal::i2c::I2C::i2c1(
+        pac.I2C1,
+        sda_pin,
+        scl_pin, // Try `not_an_scl_pin` here
+        400.kHz(),
+        &mut pac.RESETS,
+        clocks.system_clock,
+    );
+
+    // Write three bytes to the I²C device with 7-bit address 0x2C
+    i2c.write(0x2c, &[1, 2, 3]).unwrap();
+
+    // Demo finish - just loop until reset
+
+    #[allow(clippy::empty_loop)]
+    loop {
+        // Empty loop
+    }
+}
+
+// End of file