Polishing the blinky examples.

boards/pico/examples/pico_blinky.rs

@@ -1,35 +1,66 @@
-//! Blinks the LED on a Pico board
+//! # Pico Blinky
 //!
-//! This will blink an LED attached to GP25, which is the pin the Pico uses for the on-board LED.
+//! Blinks the LED on a Pico board.
+//!
+//! This will blink an LED attached to GP25, which is the pin the Pico uses for
+//! the on-board LED.
+//!
+//! 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;
+
+// GPIO traits
 use embedded_hal::digital::v2::OutputPin;
+
+// Time handling traits
 use embedded_time::rate::*;
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
 use panic_halt as _;
-use pico::{
-    hal::{
-        clocks::{init_clocks_and_plls, Clock},
-        pac,
-        sio::Sio,
-        watchdog::Watchdog,
-    },
-    Pins, XOSC_CRYSTAL_FREQ,
-};
+
+// Pull in any important traits
+use pico::hal::prelude::*;
+
+// A shorter alias for the Peripheral Access Crate, which provides low-level
+// register access
+use pico::hal::pac;
+
+// A shorter alias for the Hardware Abstraction Layer, which provides
+// higher-level drivers.
+use pico::hal;
+
+/// 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;
 
+/// 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 blinks the LED in an
+/// infinite loop.
 #[entry]
 fn main() -> ! {
+    // Grab our singleton objects
     let mut pac = pac::Peripherals::take().unwrap();
     let core = pac::CorePeripherals::take().unwrap();
 
-    let mut watchdog = Watchdog::new(pac.WATCHDOG);
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::watchdog::Watchdog::new(pac.WATCHDOG);
 
-    let clocks = init_clocks_and_plls(
-        XOSC_CRYSTAL_FREQ,
+    // Configure the clocks
+    //
+    // Our default is 12 MHz crystal input, 125 MHz system clock
+    let clocks = hal::clocks::init_clocks_and_plls(
+        pico::XOSC_CRYSTAL_FREQ,
         pac.XOSC,
         pac.CLOCKS,
         pac.PLL_SYS,
@@ -40,17 +71,25 @@ fn main() -> ! {
     .ok()
     .unwrap();
 
+    // The delay object lets us wait for specified amounts of time (in
+    // milliseconds)
     let mut delay = cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().integer());
 
-    let sio = Sio::new(pac.SIO);
-    let pins = Pins::new(
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::sio::Sio::new(pac.SIO);
+
+    // Set the pins up according to their function on this particular board
+    let pins = pico::Pins::new(
         pac.IO_BANK0,
         pac.PADS_BANK0,
         sio.gpio_bank0,
         &mut pac.RESETS,
     );
+
+    // Set the LED to be an output
     let mut led_pin = pins.led.into_push_pull_output();
 
+    // Blink the LED at 1 Hz
     loop {
         led_pin.set_high().unwrap();
         delay.delay_ms(500);
@@ -58,3 +97,5 @@ fn main() -> ! {
         delay.delay_ms(500);
     }
 }
+
+// End of file

boards/pico/examples/pico_countdown_blinky.rs

@@ -1,18 +1,37 @@
-//! Blinks the LED on a Pico board
+//! # Pico Countdown Blinky
 //!
-//! This will blink an LED attached to GP25, which is the pin the Pico uses for the on-board LED.
+//! Blinks the LED on a Pico board, using an RP2040 Timer in Count-down mode.
+//!
+//! This will blink an LED attached to GP25, which is the pin the Pico uses for
+//! the on-board LED.
+//!
+//! See the `Cargo.toml` file for Copyright and licence details.
+
 #![no_std]
 #![no_main]
 
-use cortex_m::prelude::_embedded_hal_timer_CountDown;
+// The macro for our start-up function
 use cortex_m_rt::entry;
+
+use cortex_m::prelude::*;
+
+// GPIO traits
 use embedded_hal::digital::v2::OutputPin;
+
+// Traits for converting integers to amounts of time
 use embedded_time::duration::Extensions;
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
 use panic_halt as _;
-use pico::{
-    hal::{self as hal, clocks::init_clocks_and_plls, pac, sio::Sio, watchdog::Watchdog},
-    XOSC_CRYSTAL_FREQ,
-};
+
+// A shorter alias for the Peripheral Access Crate, which provides low-level
+// register access
+use pico::hal::pac;
+
+// A shorter alias for the Hardware Abstraction Layer, which provides
+// higher-level drivers.
+use pico::hal;
 
 #[link_section = ".boot2"]
 #[used]
@@ -20,11 +39,17 @@ pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER;
 
 #[entry]
 fn main() -> ! {
+    // Grab our singleton objects
     let mut pac = pac::Peripherals::take().unwrap();
-    let mut watchdog = Watchdog::new(pac.WATCHDOG);
 
-    let _clocks = init_clocks_and_plls(
-        XOSC_CRYSTAL_FREQ,
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::watchdog::Watchdog::new(pac.WATCHDOG);
+
+    // Configure the clocks
+    //
+    // Our default is 12 MHz crystal input, 125 MHz system clock
+    let _clocks = hal::clocks::init_clocks_and_plls(
+        pico::XOSC_CRYSTAL_FREQ,
         pac.XOSC,
         pac.CLOCKS,
         pac.PLL_SYS,
@@ -35,26 +60,32 @@ fn main() -> ! {
     .ok()
     .unwrap();
 
+    // Configure the Timer peripheral in count-down mode
     let timer = hal::timer::Timer::new(pac.TIMER);
     let mut count_down = timer.count_down();
 
-    let sio = Sio::new(pac.SIO);
-    let pins = hal::gpio::Pins::new(
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::sio::Sio::new(pac.SIO);
+
+    // Set the pins up according to their function on this particular board
+    let pins = pico::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 mut led_pin = pins.led.into_push_pull_output();
+
+    // Blink the LED at 1 Hz
     loop {
+        // LED on, and wait for 500ms
         led_pin.set_high().unwrap();
-        // wait for 500ms
         count_down.start(500.milliseconds());
         let _ = nb::block!(count_down.wait());
 
+        // LED off, and wait for 500ms
         led_pin.set_low().unwrap();
-        // wait for 500ms
         count_down.start(500.milliseconds());
         let _ = nb::block!(count_down.wait());
     }

rp2040-hal/src/prelude.rs

@@ -1 +1,2 @@
 //! Prelude
+pub use crate::clocks::Clock as _rphal_clocks_Clock;