adc: add methods to utilize oversampling

Author: newAM

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `Rtc::calibrate_lp` to calibrate the RTC.
 - Added `Rtc::recalibration_pending`.
 - Added `Rtc::is_alarm_{a,b}_en`.
+- Added methods to utilize ADC oversampling.
 
 ## Changed
 - `Rtc.alarm_{a,b}` returns `Alarm` instead of `Option<Alarm>`.

Cargo.lock

@@ -9,9 +9,11 @@
 #![cfg_attr(feature = "stm32wl5x_cm0p", allow(dead_code))]
 #![cfg_attr(feature = "stm32wl5x_cm0p", allow(unused_imports))]
 
-use crate::Ratio;
+#[cfg(not(feature = "stm32wl5x_cm0p"))]
+pub use pac::adc::cfgr2::{OVSR_A as OversampleRatio, OVSS_A as OversampleShift};
 
 use crate::gpio;
+use crate::Ratio;
 
 use super::pac;
 use core::{ptr::read_volatile, time::Duration};
@@ -1057,7 +1059,7 @@ impl Adc {
 
     /// Returns `true` if the temperature sensor is enabled.
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn is_tsen_enabled(&mut self) -> bool {
         self.adc.ccr.read().tsen().is_enabled()
     }
@@ -1145,11 +1147,48 @@ impl Adc {
 
     /// Returns `true` if the internal voltage reference is enabled.
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn is_vref_enabled(&mut self) -> bool {
         self.adc.ccr.read().vrefen().is_enabled()
     }
 
+    /// Enable oversampling.
+    ///
+    /// # Panics
+    ///
+    /// * (debug) ADC is enabled
+    #[inline]
+    #[cfg(not(feature = "stm32wl5x_cm0p"))]
+    pub fn enable_oversampling(&mut self, ratio: OversampleRatio, shift: OversampleShift) {
+        debug_assert!(!self.is_enabled());
+        self.adc.cfgr2.modify(|_, w| {
+            w.ovse()
+                .enabled()
+                .ovsr()
+                .variant(ratio)
+                .ovss()
+                .variant(shift)
+        })
+    }
+
+    /// Disables oversampling.
+    ///
+    /// # Panics
+    ///
+    /// * (debug) ADC is enabled
+    #[inline]
+    pub fn disable_oversampling(&mut self) {
+        debug_assert!(!self.is_enabled());
+        self.adc.cfgr2.modify(|_, w| w.ovse().disabled())
+    }
+
+    /// Returns `true` if oversampling is enabled.
+    #[inline]
+    #[must_use]
+    pub fn is_oversampling_enabled(&mut self) -> bool {
+        self.adc.cfgr2.read().ovse().is_enabled()
+    }
+
     /// Read the internal voltage reference.
     ///
     /// # Panics
@@ -1304,7 +1343,7 @@ impl Adc {
 
     /// Returns `true` if V<sub>BAT</sub> is enabled.
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn is_vbat_enabled(&self) -> bool {
         self.adc.ccr.read().vbaten().is_enabled()
     }
@@ -1381,14 +1420,14 @@ impl Adc {
     /// assert_eq!(adc.is_enabled(), false);
     /// ```
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn is_enabled(&self) -> bool {
         self.adc.cr.read().aden().bit_is_set()
     }
 
     /// Returns `true` if an ADC disable command is in-progress.
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn disable_in_progress(&self) -> bool {
         self.adc.cr.read().addis().bit_is_set()
     }
@@ -1414,7 +1453,7 @@ impl Adc {
     /// assert_eq!(adc.is_disabled(), true);
     /// ```
     #[inline]
-    #[must_use = "no reason to call this function if you are not using the result"]
+    #[must_use]
     pub fn is_disabled(&self) -> bool {
         let cr = self.adc.cr.read();
         cr.aden().bit_is_clear() && cr.addis().bit_is_clear()

hal/src/adc.rs

@@ -5,7 +5,7 @@ use core::sync::atomic::{compiler_fence, Ordering::SeqCst};
 use defmt::unwrap;
 use defmt_rtt as _; // global logger
 use nucleo_wl55jc_bsp::hal::{
-    adc::{self, Adc, Clk},
+    adc::{self, Adc, Clk, OversampleRatio, OversampleShift},
     cortex_m::{self, delay::Delay},
     pac::{self, DWT},
     rcc,
@@ -21,12 +21,14 @@ const CYC_PER_US: u32 = FREQ / 1000 / 1000;
 // WARNING will wrap-around eventually, use this for relative timing only
 defmt::timestamp!("{=u32:us}", DWT::cycle_count() / CYC_PER_US);
 
-fn validate_vbat(sample: u16) {
+fn validate_vbat(sample: u16, oversample: i16) {
     const EXPECTED: i16 = 4096 / 3;
-    let delta: i16 = unwrap!(i16::try_from(sample).ok()) - EXPECTED;
+    let expected: i16 = EXPECTED * oversample;
+    let delta: i16 = unwrap!(i16::try_from(sample).ok()) - expected;
 
     defmt::info!("VBAT={} Δ {}", sample, delta);
-    defmt::assert!(delta < 20);
+    let tolerance: i16 = 20 * oversample;
+    defmt::assert!(delta < tolerance);
 }
 
 #[defmt_test::tests]
@@ -250,7 +252,22 @@ mod tests {
         ta.adc.set_max_sample_time();
         let sample: u16 = ta.adc.vbat();
 
-        validate_vbat(sample);
+        validate_vbat(sample, 1);
+    }
+
+    #[test]
+    fn vbat_oversample(ta: &mut TestArgs) {
+        ta.adc.disable();
+        ta.adc
+            .enable_oversampling(OversampleRatio::MUL2, OversampleShift::NOSHIFT);
+        ta.adc.enable();
+        let sample: u16 = ta.adc.vbat();
+        validate_vbat(sample / 2, 2);
+
+        ta.adc.disable();
+        defmt::assert!(ta.adc.is_oversampling_enabled());
+        ta.adc.disable_oversampling();
+        defmt::assert!(!ta.adc.is_oversampling_enabled());
     }
 
     #[test]
@@ -312,8 +329,8 @@ mod tests {
         // instead of &mut self
         let vbat1: u16 = ta.adc.data();
         let vbat2: u16 = ta.adc.data();
-        validate_vbat(vbat1);
-        validate_vbat(vbat2);
+        validate_vbat(vbat1, 1);
+        validate_vbat(vbat2, 1);
         defmt::assert_eq!(vbat1, vbat2);
     }