From ed27dc9949c8a2faaad29443a83769e214720ea8 Mon Sep 17 00:00:00 2001
From: "Jonathan Pallant (42 Technology)" <jonathan.pallant@42technology.com>
Date: Mon, 27 Sep 2021 14:42:19 +0100
Subject: [PATCH] Update ADC example.

---
 rp2040-hal/examples/adc.rs | 88 +++++++++++++++++++++++++++-----------
 1 file changed, 64 insertions(+), 24 deletions(-)

diff --git a/rp2040-hal/examples/adc.rs b/rp2040-hal/examples/adc.rs
index 7fb720a..e98accc 100644
--- a/rp2040-hal/examples/adc.rs
+++ b/rp2040-hal/examples/adc.rs
@@ -1,40 +1,66 @@
-//! Read ADC samples from the temperature sensor and pin and
-//! output them to the UART on pins 1 and 2 at 9600 baud
+//! # ADC Example
+//!
+//! This application demonstrates how to read ADC samples from the temperature
+//! sensor and pin and output them to the UART on pins 1 and 2 at 9600 baud.
+//!
+//! 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 core::fmt::Write;
-use cortex_m::prelude::_embedded_hal_adc_OneShot;
+// The macro for our start-up function
 use cortex_m_rt::entry;
-use hal::adc::Adc;
-use hal::clocks::init_clocks_and_plls;
-use hal::gpio::{self, Pins};
-use hal::pac;
-use hal::sio::Sio;
-use hal::uart::UartPeripheral;
-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;
 
+// An ADC trait we need
+use embedded_hal::adc::OneShot;
+
+// A debug/string formatting trait we need
+use core::fmt::Write;
+
+// 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 pico board is 12Mhz
-// Adjust if your board has a different frequency
+/// 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;
+
+/// Run RP2040 at 125 MHz
 const SYS_FREQ_HZ: u32 = hal::pll::common_configs::PLL_SYS_125MHZ.vco_freq.0;
 
+/// 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 prints the temperature
+/// 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);
-    let sio = Sio::new(pac.SIO);
 
-    // External high-speed crystal on the pico board is 12Mhz
+    // 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
+    let clocks = hal::clocks::init_clocks_and_plls(
         XTAL_FREQ_HZ,
         pac.XOSC,
         pac.CLOCKS,
@@ -46,16 +72,23 @@ 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, SYS_FREQ_HZ);
 
-    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 to their default state
+    let pins = hal::gpio::Pins::new(
         pac.IO_BANK0,
         pac.PADS_BANK0,
         sio.gpio_bank0,
         &mut pac.RESETS,
     );
 
-    let mut uart = UartPeripheral::<_, _>::enable(
+    // Create a UART driver
+    let mut uart = hal::uart::UartPeripheral::<_, _>::enable(
         pac.UART0,
         &mut pac.RESETS,
         hal::uart::common_configs::_9600_8_N_1,
@@ -64,14 +97,19 @@ fn main() -> ! {
     .unwrap();
 
     // UART TX (characters sent from pico) on pin 1 (GPIO0) and RX (on pin 2 (GPIO1)
-    let _tx_pin = pins.gpio0.into_mode::<gpio::FunctionUart>();
-    let _rx_pin = pins.gpio1.into_mode::<gpio::FunctionUart>();
+    let _tx_pin = pins.gpio0.into_mode::<hal::gpio::FunctionUart>();
+    let _rx_pin = pins.gpio1.into_mode::<hal::gpio::FunctionUart>();
+
+    // Write to the UART
     uart.write_full_blocking(b"ADC example\r\n");
-    // Enable adc
-    let mut adc = Adc::new(pac.ADC, &mut pac.RESETS);
+
+    // Enable ADC
+    let mut adc = hal::adc::Adc::new(pac.ADC, &mut pac.RESETS);
+
     // Enable the temperature sense channel
     let mut temperature_sensor = adc.enable_temp_sensor();
-    // Configure one of the pins as an ADC input as well.
+
+    // Configure GPIO26 as an ADC input
     let mut adc_pin_0 = pins.gpio26.into_floating_input();
     loop {
         // Read the raw ADC counts from the temperature sensor channel.
@@ -86,3 +124,5 @@ fn main() -> ! {
         delay.delay_ms(1000);
     }
 }
+
+// End of file