Polishing the PWM and USB examples.

boards/pico/examples/pico_blinky.rs

@@ -1,4 +1,4 @@
-//! # Pico Blinky
+//! # Pico Blinky Example
 //!
 //! Blinks the LED on a Pico board.
 //!

boards/pico/examples/pico_countdown_blinky.rs

@@ -1,4 +1,4 @@
-//! # Pico Countdown Blinky
+//! # Pico Countdown Blinky Example
 //!
 //! Blinks the LED on a Pico board, using an RP2040 Timer in Count-down mode.
 //!

boards/pico/examples/pico_gpio_in_out.rs

@@ -1,36 +1,74 @@
-//! Toggle LED based on GPIO input
+//! # Pico GPIO In/Out Example
 //!
-//! This will control an LED on GP25 based on a button hooked up to GP15. The button should be tied
+//! Toggles the LED based on GPIO input.
-//! to ground, as the input pin is pulled high internally by this example. When the button is
+//!
-//! pressed, the LED will turn off.
+//! This will control an LED on GP25 based on a button hooked up to GP15. The
+//! button should cause the line to be grounded, as the input pin is pulled high
+//! internally by this example. When the button is pressed, the LED will turn
+//! off.
+//!
+//! 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;
-use panic_halt as _;
-use pico::{hal, Pins};
 
+// GPIO traits
+use embedded_hal::digital::v2::{InputPin, OutputPin};
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
+use panic_halt as _;
+
+// 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 just reads the button
+/// and sets the LED appropriately.
 #[entry]
 fn main() -> ! {
+    // Grab our singleton objects
     let mut pac = pac::Peripherals::take().unwrap();
 
-    let sio = Sio::new(pac.SIO);
+    // Note - we don't do any clock set-up in this example. The RP2040 will run
-    let pins = Pins::new(
+    // at it's default clock speed.
+
+    // 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,
     );
+
+    // Our LED output
     let mut led_pin = pins.led.into_push_pull_output();
+
+    // Our button input
     let button_pin = pins.bootsel.into_pull_down_input();
 
+    // Run forever, setting the LED according to the button
     loop {
         if button_pin.is_low().unwrap() {
             led_pin.set_high().unwrap();
@@ -39,3 +77,5 @@ fn main() -> ! {
         }
     }
 }
+
+// End of file

boards/pico/examples/pico_pwm_blink.rs

@@ -1,40 +1,72 @@
-//! Blinks the LED on a Pico board
+//! # Pico PWM Blink Example
 //!
-//! This will fade in/out the LED attached to GP25, which is the pin the Pico uses for the on-board LED.
+//! Fades the LED on a Pico board using the PWM peripheral.
+//!
+//! This will fade in/out the 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;
-use embedded_hal::PwmPin;
-use embedded_time::fixed_point::FixedPoint;
-use panic_halt as _;
-use pico::{
-    hal::{
-        clocks::{init_clocks_and_plls, Clock},
-        pac,
-        pwm::*,
-        watchdog::Watchdog,
-    },
-    Pins, XOSC_CRYSTAL_FREQ,
-};
-use rp2040_hal::sio::Sio;
 
+// GPIO traits
+use embedded_hal::PwmPin;
+
+// 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 _;
+
+// 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;
 
+// The minimum PWM value (i.e. LED brightness) we want
 const LOW: u16 = 0;
+
+// The maximum PWM value (i.e. LED brightness) we want
 const HIGH: u16 = 25000;
 
+/// 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 fades 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(
+    // Configure the clocks
-        XOSC_CRYSTAL_FREQ,
+    //
+    // 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,
@@ -45,34 +77,42 @@ fn main() -> ! {
     .ok()
     .unwrap();
 
-    let sio = Sio::new(pac.SIO);
+    // The single-cycle I/O block controls our GPIO pins
-    let pins = Pins::new(
+    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,
     );
 
+    // 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());
 
     // Init PWMs
-    let mut pwm_slices = Slices::new(pac.PWM, &mut pac.RESETS);
+    let mut pwm_slices = hal::pwm::Slices::new(pac.PWM, &mut pac.RESETS);
 
     // Configure PWM4
     let pwm = &mut pwm_slices.pwm4;
     pwm.set_ph_correct();
     pwm.enable();
 
-    // Use B channel (which outputs to GPIO 25)
+    // Output channel B on PWM4 to the LED pin
     let channel = &mut pwm.channel_b;
     channel.output_to(pins.led);
 
+    // Infinite loop, fading LED up and down
     loop {
+        // Ramp brightness up
         for i in (LOW..=HIGH).skip(100) {
             delay.delay_us(8);
             channel.set_duty(i);
         }
 
+        // Ramp brightness down
         for i in (LOW..=HIGH).rev().skip(100) {
             delay.delay_us(8);
             channel.set_duty(i);
@@ -81,3 +121,5 @@ fn main() -> ! {
         delay.delay_ms(500);
     }
 }
+
+// End of file

boards/pico/examples/pico_usb_serial_interrupt.rs

@@ -1,49 +1,86 @@
-//! Creates a USB Serial device on a Pico board, with the USB driver running in the USB interrupt
+//! # Pico USB Serial (with Interrupts) Example
 //!
-//! This will create a USB Serial device echoing anything it receives converting to caps the ASCII
+//! Creates a USB Serial device on a Pico board, with the USB driver running in
-//! alphabetical caracters.
+//! the USB interrupt.
+//!
+//! This will create a USB Serial device echoing anything it receives. Incoming
+//! ASCII characters are converted to upercase, so you can tell it is working
+//! and not just local-echo!
+//!
+//! See the `Cargo.toml` file for Copyright and licence details.
+
 #![no_std]
 #![no_main]
 
-use crate::pac::interrupt;
+// The macro for our start-up function
 use cortex_m_rt::entry;
+
+// The macro for marking our interrupt functions
+use pico::hal::pac::interrupt;
+
+// 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::{
+// Pull in any important traits
-        self,
+use pico::hal::prelude::*;
-        clocks::{init_clocks_and_plls, Clock},
+
-        pac,
+// A shorter alias for the Peripheral Access Crate, which provides low-level
-        sio::Sio,
+// register access
-        usb::UsbBus,
+use pico::hal::pac;
-        watchdog::Watchdog,
+
-    },
+// A shorter alias for the Hardware Abstraction Layer, which provides
-    XOSC_CRYSTAL_FREQ,
+// higher-level drivers.
-};
+use pico::hal;
+
+// USB Device support
 use usb_device::{class_prelude::*, prelude::*};
+
+// USB Communications Class Device support
 use usbd_serial::SerialPort;
 
+/// 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;
 
-// Static data so that it can be accessed in both main and interrupt context
+/// The USB Device Driver (shared with the interrupt).
-static mut USB_DEVICE: Option<UsbDevice<UsbBus>> = None;
+static mut USB_DEVICE: Option<UsbDevice<hal::usb::UsbBus>> = None;
-static mut USB_BUS: Option<UsbBusAllocator<UsbBus>> = None;
-static mut USB_SERIAL: Option<SerialPort<UsbBus>> = None;
-static mut SAID_HELLO: bool = false;
 
-// Blinky-related imports, not needed for USB
+/// The USB Bus Driver (shared with the interrupt).
-use embedded_hal::digital::v2::OutputPin;
+static mut USB_BUS: Option<UsbBusAllocator<hal::usb::UsbBus>> = None;
-use embedded_time::rate::*;
-use pico::Pins;
 
+/// The USB Serial Device Driver (shared with the interrupt).
+static mut USB_SERIAL: Option<SerialPort<hal::usb::UsbBus>> = None;
+
+/// 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 mut watchdog = Watchdog::new(pac.WATCHDOG);
+    let core = pac::CorePeripherals::take().unwrap();
 
-    let clocks = init_clocks_and_plls(
+    // Set up the watchdog driver - needed by the clock setup code
-        XOSC_CRYSTAL_FREQ,
+    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,
@@ -54,7 +91,7 @@ fn main() -> ! {
     .ok()
     .unwrap();
 
-    let usb_bus = UsbBusAllocator::new(UsbBus::new(
+    let usb_bus = UsbBusAllocator::new(hal::usb::UsbBus::new(
         pac.USBCTRL_REGS,
         pac.USBCTRL_DPRAM,
         clocks.usb_clock,
@@ -62,6 +99,7 @@ fn main() -> ! {
         &mut pac.RESETS,
     ));
     unsafe {
+        // Note (safety): This is safe as interrupts haven't been started yet
         USB_BUS = Some(usb_bus);
     }
 
@@ -71,6 +109,7 @@ fn main() -> ! {
     }
 
     let usb_dev = UsbDeviceBuilder::new(
+        // Note (safety): This is safe as interrupts haven't been started yet
         unsafe { USB_BUS.as_ref().unwrap() },
         UsbVidPid(0x16c0, 0x27dd),
     )
@@ -80,6 +119,7 @@ fn main() -> ! {
     .device_class(2) // from: https://www.usb.org/defined-class-codes
     .build();
     unsafe {
+        // Note (safety): This is safe as interrupts haven't been started yet
         USB_DEVICE = Some(usb_dev);
     }
 
@@ -88,20 +128,28 @@ fn main() -> ! {
         pac::NVIC::unmask(hal::pac::Interrupt::USBCTRL_IRQ);
     };
 
-    // No more USB code after this point in main!
+    // No more USB code after this point in main! We can do anything we want in
-    // We can do anything we want in here since USB is handled
+    // here since USB is handled in the interrupt - let's blink an LED!
-    // in the interrupt - let's blink an LED.
+
-    let core = pac::CorePeripherals::take().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);
+    // The single-cycle I/O block controls our GPIO pins
-    let pins = Pins::new(
+    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);
@@ -110,37 +158,55 @@ fn main() -> ! {
     }
 }
 
+/// This function is called whenever the USB Hardware generates an Interrupt
+/// Request.
+///
+/// We do all our USB work under interrupt, so the main thread can continue on
+/// knowing nothing about USB.
 #[allow(non_snake_case)]
 #[interrupt]
 unsafe fn USBCTRL_IRQ() {
-    let mut buf = [0u8; 64];
+    use core::sync::atomic::{AtomicBool, Ordering};
+
+    /// Note whether we've already printed the "hello" message.
+    static SAID_HELLO: AtomicBool = AtomicBool::new(false);
+
+    // Grab the global objects. This is OK as we only access them under interrupt.
     let usb_dev = USB_DEVICE.as_mut().unwrap();
     let serial = USB_SERIAL.as_mut().unwrap();
 
-    if !SAID_HELLO {
+    // Say hello exactly once on start-up
-        SAID_HELLO = true;
+    if SAID_HELLO.load(Ordering::Relaxed) == false {
-        let _ = serial.write(b"HelloWorld!\r\n");
+        SAID_HELLO.store(true, Ordering::Relaxed);
+        let _ = serial.write(b"Hello, World!\r\n");
     }
 
+    // Poll the USB driver with all of our supported USB Classes
     if usb_dev.poll(&mut [serial]) {
-        let _ = serial.read(&mut buf).map(|count| {
+        let mut buf = [0u8; 64];
-            if count == 0 {
+        match serial.read(&mut buf) {
-                return;
+            Err(_e) => {
+                // Do nothing
             }
-
+            Ok(0) => {
-            // Echo back in upper case
+                // Do nothing
-            buf.iter_mut().take(count).for_each(|c| {
+            }
-                if let 0x61..=0x7a = *c {
+            Ok(count) => {
-                    *c &= !0x20;
+                // Convert to upper case
-                }
+                buf.iter_mut().take(count).for_each(|b| {
-            });
+                    b.make_ascii_uppercase();
-
-            let mut wr_ptr = &buf[..count];
-            while !wr_ptr.is_empty() {
-                let _ = serial.write(wr_ptr).map(|len| {
-                    wr_ptr = &wr_ptr[len..];
                 });
+
+                // Send back to the host
+                let mut wr_ptr = &buf[..count];
+                while !wr_ptr.is_empty() {
+                    let _ = serial.write(wr_ptr).map(|len| {
+                        wr_ptr = &wr_ptr[len..];
+                    });
+                }
             }
-        });
+        }
     }
 }
+
+// End of file