Polish the watchdog example.

rp2040-hal/examples/watchdog.rs

@@ -1,37 +1,64 @@
-//! How to use the watchdog peripheral to reset the system in case something takes too long
+//! # Watchdog Example
+//!
+//! This application demonstrates how to use the RP2040 Watchdog.
+//!
+//! 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]
 
-use cortex_m::prelude::{_embedded_hal_watchdog_Watchdog, _embedded_hal_watchdog_WatchdogEnable};
+// The macro for our start-up function
 use cortex_m_rt::entry;
-use embedded_hal::digital::v2::OutputPin;
-use embedded_time::duration::units::*;
-use embedded_time::fixed_point::FixedPoint;
-use hal::clocks::{init_clocks_and_plls, Clock};
-use hal::gpio::Pins;
-use hal::pac;
-use hal::sio::Sio;
-use hal::watchdog::Watchdog;
+
+// 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;
+
+// Traits we need
+use embedded_hal::digital::v2::OutputPin;
+use embedded_hal::watchdog::{Watchdog, WatchdogEnable};
+use embedded_time::fixed_point::FixedPoint;
+use embedded_time::duration::Extensions;
+use rp2040_hal::clocks::Clock;
+
+/// 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 pico board is 12Mhz
-// Adjust for your board if this isn't the same
-const EXTERNAL_XTAL_FREQ_HZ: u32 = 12_000_000;
+/// 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 cp = pac::CorePeripherals::take().unwrap();
-    let mut watchdog = Watchdog::new(pac.WATCHDOG);
-    let sio = Sio::new(pac.SIO);
+    let core = pac::CorePeripherals::take().unwrap();
 
-    let clocks = init_clocks_and_plls(
-        EXTERNAL_XTAL_FREQ_HZ,
+    // 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,
@@ -42,16 +69,19 @@ fn main() -> ! {
     .ok()
     .unwrap();
 
-    let pins = Pins::new(
+    let mut delay = cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().integer());
+
+    // 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,
     );
 
-    // We need to accurately delay to give feedback that the watchdog is working correctly
-    let mut delay = cortex_m::delay::Delay::new(cp.SYST, clocks.system_clock.freq().integer());
-
     // Configure an LED so we can show the current state of the watchdog
     let mut led_pin = pins.gpio25.into_push_pull_output();
 
@@ -60,7 +90,7 @@ fn main() -> ! {
     delay.delay_ms(2000);
 
     // Set to watchdog to reset if it's not reloaded within 1.05 seconds, and start it
-    watchdog.start(1_050_000.microseconds());
+    watchdog.start(1_050_000u32.microseconds());
 
     // Blink once a second for 5 seconds, refreshing the watchdog timer once a second to avoid a reset
     for _ in 1..=5 {