From 193972bb9fa6ae962e49c24be681a65a01a0cd7f Mon Sep 17 00:00:00 2001
From: "Jonathan Pallant (42 Technology)" <jonathan.pallant@42technology.com>
Date: Mon, 27 Sep 2021 17:30:18 +0100
Subject: [PATCH] Polish GPIO example.

---
 rp2040-hal/examples/gpio_in_out.rs | 80 +++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 13 deletions(-)

diff --git a/rp2040-hal/examples/gpio_in_out.rs b/rp2040-hal/examples/gpio_in_out.rs
index b25e9cb..0b592d9 100644
--- a/rp2040-hal/examples/gpio_in_out.rs
+++ b/rp2040-hal/examples/gpio_in_out.rs
@@ -1,41 +1,95 @@
-//! Toggle LED based on GPIO input
+//! # GPIO 'Blinky' Example
 //!
-//! This will control an LED on GP25 based on a button hooked up to GP15. The button should be tied
-//! to ground, as the input pin is pulled high internally by this example. When the button is
-//! pressed, the LED will turn off.
+//! This application demonstrates how to control a GPIO pin on the 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;
-use embedded_hal::digital::v2::{InputPin, OutputPin};
-use hal::pac;
-use hal::sio::Sio;
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
 use panic_halt as _;
+
+// 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 traits we need
+use embedded_hal::digital::v2::InputPin;
+use embedded_hal::digital::v2::OutputPin;
+
+/// 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 toggles a GPIO pin in
+/// an infinite loop. If there is an LED connected to that pin, it will blink.
 #[entry]
 fn main() -> ! {
+    // Grab our singleton objects
     let mut pac = pac::Peripherals::take().unwrap();
 
-    let sio = Sio::new(pac.SIO);
+    // 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,
     );
-    let mut led_pin = pins.gpio25.into_push_pull_output();
-    let button_pin = pins.gpio23.into_pull_down_input();
 
+    // Configure GPIO 25 as an output
+    let mut out_pin = pins.gpio25.into_push_pull_output();
+
+    // Configure GPIO 23 as an input
+    let in_pin = pins.gpio23.into_pull_down_input();
+
+    // Output is the opposite of the input
     loop {
-        if button_pin.is_low().unwrap() {
-            led_pin.set_high().unwrap();
+        if in_pin.is_low().unwrap() {
+            out_pin.set_high().unwrap();
         } else {
-            led_pin.set_low().unwrap();
+            out_pin.set_low().unwrap();
         }
     }
 }
+
+// End of file