feat: ADCv2

#814

This work was done over about 6 months by:
Ashcon Mohseninia <[email protected]>
and
Justin Beaurivage <[email protected]>
with input from the atsamd-rs community.

Begin constructing an async ADC concept for D5X

Draft up new ADC API

Test implementation of async read for ADC

Resolve rest of the adc read future

Move to type based ADC implementation

Broken read_blocking implementation

Begin implementing async reading ADC

Automatically convert pins to correct mode in with_pins

Remove explicit reference to a chip in favor of PAC

Split async and sync ADC into different implementations

Clean up ADC

Add inlines everywhere

Add wait_flags method and do some extra cleanup

Add blocking and async buffered read methods

Derive debug for Adc Error

Fix ADC read_buffer not ever starting

Fix ADC reading blocking buffer always returning BufferOverrun

Implement more ADCSettings

Add in temperature calibration parameters to calibration

Add in CPU Temperature reading

Add CPU internal sensors reading, and setting VREF for adc

Restrict internal CPU sensors to primary CPU ADC

Remove breaking comments in Cargo.toml

Allow blocking methods on async-enabled ADCs

Derive defmt::Format for error type

Remove duplicate methods

ADC: Add support for samd21 line

Remove curiosity nano reference

Make names more consistent with the rest of the crate

samd21 - Fix ADC results being multiplied by 2x

Error if ADC is configured for summation/averaging but user has selected an incorrect bit width

Improve ADC comments

Resolve clippy warnings

Add ADC Pins for D11

Improve imports and hal_cfg usage for ADC

Leave workspace Cargo.toml unchanged

Make good use of the typelevel guarantees provided by clock::v2

Remove the need for the Channel machinery

D5x - Document TH and TL parameters better

Improve D11/D21 ADC clocking

Cleanup config type aliases

Add doc comment for ADC::new (thumbv6)

Simplify some snippets, add missing doc comment, and add missing sync calls

Minimal working ADC example for feather_m0

Fix some bugs in conversion methods

Slightly improve docs

Revert workspace Cargo.toml

Add D11 ADC calibration

Update T1 BSPs

Fix misaligned flash read

Make internal calibration API safer

Fix math error in ADC bias calibration

Improve ADC reading results by powering down and up ADC

Fix fmt and clippy warns

Start fixing pygamer examples

Fix overrun errors on thumbv6 targets

Fix dividers in examples

Fix Samd21g build

First round of ADC Doc fixes

Construct ADC from ADC Builder

D5x - Correct all calibration values

D11 - Correct all calibrations and add temp cals

Cleanup and finalize ADC

Refactor the check_and_clear_flags method

Improve, standardize examples and make them more robust

Mention that async ADC is supported in repo README

Doc and formatting fixes

Fix warning when building without async feature

Supply vref in SAMD11 adc example

Fix Calibration parts_to_f32

Stabilize ADC reading after a setting change

Document TSEN enable

correct calibration floating point values

rework calibration decimal numbers

Document tsen enabling procedure for d11 too

ADC docs

Remove disused parts_to_f32()

Update docstrings for d5x temperature methods

SAMD21 - Expose bandgap voltage and rename vbat to IO

D2x - Optimize ADC temp cals

D21 - Remove raw field on read_cpu_temperature

Make ADC examples use single reads rather than buffer reads

Fix output averages being wrong

Calibration bug fixes

Fine tune sensor reading settings

Remove useless read from ADC when discarding value

D21 - Document how to NOT nuke the VREF register when enabling TSEN

Make reading CPU temperature infaillible

Make cpu sensor/temp reading actually async for the async implementation

Tidy comments in examples

clippy lints, formatting

Author: rnd-ash

README.md

@@ -109,6 +109,7 @@ use the async APIs.
 * DMAC
 * EIC (GPIO interrupts)
 * Timers
+* ADC
 
 ### Examples
 

boards/feather_m0/Cargo.toml

@@ -87,6 +87,10 @@ required-features = ["adalogger", "usb", "sdmmc"]
 [[example]]
 name = "adc"
 
+[[example]]
+name = "async_adc"
+required-features = ["async"]
+
 [[example]]
 name = "async_dmac"
 required-features = ["dma", "async"]

boards/feather_m0/examples/adc.rs

@@ -1,41 +1,53 @@
 #![no_std]
 #![no_main]
 
+use atsamd_hal::adc::AdcBuilder;
+use feather_m0 as bsp;
+
+use bsp::hal;
+use bsp::pac;
+
 #[cfg(not(feature = "use_semihosting"))]
 use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
 use panic_semihosting as _;
 
-use cortex_m_semihosting::hprintln;
-
-use bsp::hal;
-use bsp::pac;
-use feather_m0 as bsp;
-
 use bsp::entry;
-use hal::adc::Adc;
-use hal::clock::GenericClockController;
-use hal::prelude::*;
+use bsp::Pins;
 use pac::{CorePeripherals, Peripherals};
 
+use hal::{
+    adc::{Accumulation, Adc, Prescaler, Resolution},
+    clock::GenericClockController,
+};
+
 #[entry]
 fn main() -> ! {
     let mut peripherals = Peripherals::take().unwrap();
-    let core = CorePeripherals::take().unwrap();
+    let _core = CorePeripherals::take().unwrap();
+
+    let pins = Pins::new(peripherals.port);
+
     let mut clocks = GenericClockController::with_external_32kosc(
         peripherals.gclk,
         &mut peripherals.pm,
         &mut peripherals.sysctrl,
         &mut peripherals.nvmctrl,
     );
-    let pins = bsp::Pins::new(peripherals.port);
-    let mut delay = hal::delay::Delay::new(core.SYST, &mut clocks);
-    let mut adc = Adc::adc(peripherals.adc, &mut peripherals.pm, &mut clocks);
-    let mut a0: bsp::A0 = pins.a0.into();
+    let gclk0 = clocks.gclk0();
+    let adc_clock = clocks.adc(&gclk0).unwrap();
+
+    let mut adc = AdcBuilder::new(Accumulation::single(atsamd_hal::adc::AdcResolution::_12))
+        .with_clock_cycles_per_sample(5)
+        .with_clock_divider(Prescaler::Div128)
+        .with_vref(atsamd_hal::adc::Reference::Intvcc0)
+        .enable(peripherals.adc, &mut peripherals.pm, &adc_clock)
+        .unwrap();
+    let mut adc_pin = pins.a0.into_alternate();
 
     loop {
-        let data: u16 = adc.read(&mut a0).unwrap();
-        hprintln!("{}", data).ok();
-        delay.delay_ms(1000u16);
+        let res = adc.read(&mut adc_pin);
+        #[cfg(feature = "use_semihosting")]
+        cortex_m_semihosting::hprintln!("ADC value: {}", read).unwrap();
     }
 }

boards/feather_m0/examples/async_adc.rs

@@ -0,0 +1,58 @@
+#![no_std]
+#![no_main]
+
+use atsamd_hal::adc::AdcBuilder;
+use feather_m0 as bsp;
+
+use bsp::hal;
+use bsp::pac;
+
+#[cfg(not(feature = "use_semihosting"))]
+use panic_halt as _;
+#[cfg(feature = "use_semihosting")]
+use panic_semihosting as _;
+
+use bsp::Pins;
+use pac::{CorePeripherals, Peripherals};
+
+use hal::{
+    adc::{Accumulation, Adc, Adc0, Prescaler, Resolution},
+    clock::GenericClockController,
+};
+
+atsamd_hal::bind_interrupts!(struct Irqs {
+    ADC => atsamd_hal::adc::InterruptHandler<Adc0>;
+});
+
+#[embassy_executor::main]
+async fn main(_s: embassy_executor::Spawner) -> ! {
+    let mut peripherals = Peripherals::take().unwrap();
+    let _core = CorePeripherals::take().unwrap();
+
+    let pins = Pins::new(peripherals.port);
+
+    let mut clocks = GenericClockController::with_external_32kosc(
+        peripherals.gclk,
+        &mut peripherals.pm,
+        &mut peripherals.sysctrl,
+        &mut peripherals.nvmctrl,
+    );
+    let gclk0 = clocks.gclk0();
+    let adc_clock = clocks.adc(&gclk0).unwrap();
+
+    let mut adc = AdcBuilder::new(Accumulation::single(atsamd_hal::adc::AdcResolution::_12))
+        .with_clock_cycles_per_sample(5)
+        .with_clock_divider(Prescaler::Div128)
+        .with_vref(atsamd_hal::adc::Reference::Arefa)
+        .enable(peripherals.adc, &mut peripherals.pm, &adc_clock)
+        .unwrap()
+        .into_future(Irqs);
+
+    let mut adc_pin = pins.a0.into_alternate();
+
+    loop {
+        let res = adc.read(&mut adc_pin).await;
+        #[cfg(feature = "use_semihosting")]
+        cortex_m_semihosting::hprintln!("ADC Result: {}", res).unwrap();
+    }
+}

boards/feather_m4/Cargo.toml

@@ -35,6 +35,7 @@ version = "0.3.1"
 [dev-dependencies]
 heapless = "0.7"
 panic-halt = "0.2"
+cortex-m-semihosting = "0.5.0"
 panic-semihosting = "0.5"
 rtic = {version = "2.1.1", features = ["thumbv7-backend"]}
 smart-leds = "0.3"
@@ -53,6 +54,9 @@ usb = ["atsamd-hal/usb", "usb-device"]
 async = ["atsamd-hal/async"]
 use_semihosting = []
 
+[[example]]
+name = "adc"
+
 [[example]]
 name = "blinky_basic"
 

boards/feather_m4/examples/adc.rs

@@ -0,0 +1,59 @@
+#![no_std]
+#![no_main]
+
+use atsamd_hal::adc::AdcBuilder;
+use feather_m4 as bsp;
+
+use bsp::hal;
+use bsp::pac;
+
+#[cfg(not(feature = "use_semihosting"))]
+use panic_halt as _;
+#[cfg(feature = "use_semihosting")]
+use panic_semihosting as _;
+
+use bsp::entry;
+use bsp::Pins;
+use pac::{CorePeripherals, Peripherals};
+
+use hal::{
+    adc::{Accumulation, Adc, Prescaler, Resolution},
+    clock::v2::{clock_system_at_reset, pclk::Pclk},
+};
+
+#[entry]
+fn main() -> ! {
+    let mut peripherals = Peripherals::take().unwrap();
+    let _core = CorePeripherals::take().unwrap();
+
+    let pins = Pins::new(peripherals.port);
+
+    let (mut buses, clocks, tokens) = clock_system_at_reset(
+        peripherals.oscctrl,
+        peripherals.osc32kctrl,
+        peripherals.gclk,
+        peripherals.mclk,
+        &mut peripherals.nvmctrl,
+    );
+
+    // Enable the ADC0 ABP clock...
+    let apb_adc0 = buses.apb.enable(tokens.apbs.adc0);
+    // ...and enable the ADC0 PCLK. Both of these are required for the
+    // ADC to run.
+    let (pclk_adc0, _gclk0) = Pclk::enable(tokens.pclks.adc0, clocks.gclk0);
+
+    let mut adc = AdcBuilder::new(Accumulation::single(atsamd_hal::adc::AdcResolution::_12))
+        .with_clock_cycles_per_sample(5)
+        // Overruns if clock divider < 32 in debug mode
+        .with_clock_divider(Prescaler::Div32)
+        .with_vref(atsamd_hal::adc::Reference::Arefa)
+        .enable(peripherals.adc0, apb_adc0, &pclk_adc0)
+        .unwrap();
+    let mut adc_pin = pins.a0.into_alternate();
+
+    loop {
+        let res = adc.read(&mut adc_pin);
+        #[cfg(feature = "use_semihosting")]
+        cortex_m_semihosting::hprintln!("ADC value: {}", res);
+    }
+}

boards/metro_m4/Cargo.toml

@@ -67,6 +67,10 @@ use_semihosting = []
 [[example]]
 name = "adc"
 
+[[example]]
+name = "async_adc"
+required-features = ["async"]
+
 [[example]]
 name = "async_dmac"
 required-features = ["dma", "async"]

boards/metro_m4/examples/adc.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![no_main]
 
+use atsamd_hal::adc::AdcBuilder;
 use metro_m4 as bsp;
 
 use bsp::hal;
@@ -11,35 +12,47 @@ use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
 use panic_semihosting as _;
 
-use cortex_m_semihosting::hprintln;
-
 use bsp::entry;
-use hal::adc::Adc;
-use hal::clock::GenericClockController;
-use hal::gpio::B;
-use hal::prelude::*;
-use pac::gclk::pchctrl::Genselect::Gclk11;
+use bsp::Pins;
 use pac::{CorePeripherals, Peripherals};
 
+use hal::{
+    adc::{Accumulation, Adc, Prescaler, Resolution},
+    clock::v2::{clock_system_at_reset, pclk::Pclk},
+};
+
 #[entry]
 fn main() -> ! {
     let mut peripherals = Peripherals::take().unwrap();
-    let core = CorePeripherals::take().unwrap();
-    let mut clocks = GenericClockController::with_external_32kosc(
+    let _core = CorePeripherals::take().unwrap();
+
+    let pins = Pins::new(peripherals.port);
+
+    let (mut buses, clocks, tokens) = clock_system_at_reset(
+        peripherals.oscctrl,
+        peripherals.osc32kctrl,
         peripherals.gclk,
-        &mut peripherals.mclk,
-        &mut peripherals.osc32kctrl,
-        &mut peripherals.oscctrl,
+        peripherals.mclk,
         &mut peripherals.nvmctrl,
     );
-    let pins = bsp::Pins::new(peripherals.port);
-    let mut delay = hal::delay::Delay::new(core.SYST, &mut clocks);
-    let mut adc0 = Adc::adc0(peripherals.adc0, &mut peripherals.mclk, &mut clocks, Gclk11);
-    let mut a0 = pins.a0.into_alternate::<B>();
+
+    // Enable the ADC0 ABP clock...
+    let apb_adc0 = buses.apb.enable(tokens.apbs.adc0);
+    // ...and enable the ADC0 PCLK. Both of these are required for the
+    // ADC to run.
+    let (pclk_adc0, _gclk0) = Pclk::enable(tokens.pclks.adc0, clocks.gclk0);
+
+    let mut adc = AdcBuilder::new(Accumulation::single(atsamd_hal::adc::AdcResolution::_12))
+        .with_clock_cycles_per_sample(5)
+        .with_clock_divider(Prescaler::Div32)
+        .with_vref(atsamd_hal::adc::Reference::Arefa)
+        .enable(peripherals.adc0, apb_adc0, &pclk_adc0)
+        .unwrap();
+    let mut adc_pin = pins.a0.into_alternate();
 
     loop {
-        let data: u16 = adc0.read(&mut a0).unwrap();
-        hprintln!("{}", data).ok();
-        delay.delay_ms(1000u16);
+        let res = adc.read(&mut adc_pin);
+        #[cfg(feature = "use_semihosting")]
+        cortex_m_semihosting::hprintln!("ADC Result: {}", res).unwrap();
     }
 }

boards/metro_m4/examples/async_adc.rs

@@ -0,0 +1,63 @@
+#![no_std]
+#![no_main]
+
+use atsamd_hal::adc::AdcBuilder;
+use metro_m4 as bsp;
+
+use bsp::hal;
+use bsp::pac;
+
+#[cfg(not(feature = "use_semihosting"))]
+use panic_halt as _;
+#[cfg(feature = "use_semihosting")]
+use panic_semihosting as _;
+
+use bsp::Pins;
+use pac::{CorePeripherals, Peripherals};
+
+use hal::{
+    adc::{Accumulation, Adc, Adc0, Prescaler, Resolution},
+    clock::v2::{clock_system_at_reset, pclk::Pclk},
+};
+
+atsamd_hal::bind_multiple_interrupts!(struct Irqs {
+    ADC0: [ADC0_RESRDY, ADC0_OTHER] => atsamd_hal::adc::InterruptHandler<Adc0>;
+});
+
+#[embassy_executor::main]
+async fn main(_s: embassy_executor::Spawner) -> ! {
+    let mut peripherals = Peripherals::take().unwrap();
+    let _core = CorePeripherals::take().unwrap();
+
+    let pins = Pins::new(peripherals.port);
+
+    let (mut buses, clocks, tokens) = clock_system_at_reset(
+        peripherals.oscctrl,
+        peripherals.osc32kctrl,
+        peripherals.gclk,
+        peripherals.mclk,
+        &mut peripherals.nvmctrl,
+    );
+
+    // Enable the ADC0 ABP clock...
+    let apb_adc0 = buses.apb.enable(tokens.apbs.adc0);
+    // ...and enable the ADC0 PCLK. Both of these are required for the
+    // ADC to run.
+    let (pclk_adc0, _gclk0) = Pclk::enable(tokens.pclks.adc0, clocks.gclk0);
+
+    let mut adc = AdcBuilder::new(Accumulation::single(atsamd_hal::adc::AdcResolution::_12))
+        .with_clock_cycles_per_sample(5)
+        .with_clock_divider(Prescaler::Div32)
+        .with_vref(atsamd_hal::adc::Reference::Arefa)
+        .enable(peripherals.adc0, apb_adc0, &pclk_adc0)
+        .unwrap()
+        .into_future(Irqs);
+
+    let mut adc_pin = pins.a0.into_alternate();
+
+    loop {
+        let res = adc.read(&mut adc_pin).await;
+        #[cfg(feature = "use_semihosting")]
+        cortex_m_semihosting::hprintln!("ADC Result: {}", res).unwrap();
+    }
+}