Merge #879

879: Improve ADC configuration options r=Dirbaio a=chemicstry

This smooths out a few rough edges with ADC:
- Make `Resolution::to_max_count()` pub for all ADC versions. Useful if performing conversion manually.
- `VREF` and `VREFINT` were convoluted. `VREF` is an external voltage reference used for all ADC conversions and it is exposed as a separate pin on large chips, while on smaller ones it is connected to `VDDA` internally. `VREFINT` is an internal voltage reference connected to one of the ADC channels and can be used to calculate unknown `VREF` voltage.
- Add a separate `VREF_DEFAULT_MV`, equal to 3.3V, which is the usual supply voltage and should work for most simple cases.
  - For an external voltage reference `set_vref()` can be used to set a known precise voltage.
  - If no voltage reference is present, `VREFINT` calibration can be used to calculate unknown `VREF` voltage. If I understand correctly, this is only implemented for `adc_v3` (L4?), but is not currently exposed (private). If someone is interested, this can be fixed in separate PR.

Co-authored-by: chemicstry <chemicstry@gmail.com>

embassy-stm32/src/adc/v2.rs

@@ -7,7 +7,10 @@ use crate::adc::{AdcPin, Instance};
 use crate::time::Hertz;
 use crate::Peripheral;
 
-pub const VDDA_CALIB_MV: u32 = 3000;
+/// Default VREF voltage used for sample conversion to millivolts.
+pub const VREF_DEFAULT_MV: u32 = 3300;
+/// VREF voltage used for factory calibration of VREFINTCAL register.
+pub const VREF_CALIB_MV: u32 = 3300;
 
 #[cfg(not(any(rcc_f4, rcc_f7)))]
 fn enable() {
@@ -47,7 +50,7 @@ impl Resolution {
         }
     }
 
-    fn to_max_count(&self) -> u32 {
+    pub fn to_max_count(&self) -> u32 {
         match self {
             Resolution::TwelveBit => (1 << 12) - 1,
             Resolution::TenBit => (1 << 10) - 1,
@@ -57,9 +60,9 @@ impl Resolution {
     }
 }
 
-pub struct Vref;
+pub struct VrefInt;
-impl<T: Instance> AdcPin<T> for Vref {}
+impl<T: Instance> AdcPin<T> for VrefInt {}
-impl<T: Instance> super::sealed::AdcPin<T> for Vref {
+impl<T: Instance> super::sealed::AdcPin<T> for VrefInt {
     fn channel(&self) -> u8 {
         17
     }
@@ -150,7 +153,7 @@ impl Prescaler {
 
 pub struct Adc<'d, T: Instance> {
     sample_time: SampleTime,
-    calibrated_vdda: u32,
+    vref_mv: u32,
     resolution: Resolution,
     phantom: PhantomData<&'d mut T>,
 }
@@ -180,7 +183,7 @@ where
         Self {
             sample_time: Default::default(),
             resolution: Resolution::default(),
-            calibrated_vdda: VDDA_CALIB_MV,
+            vref_mv: VREF_DEFAULT_MV,
             phantom: PhantomData,
         }
     }
@@ -193,9 +196,16 @@ where
         self.resolution = resolution;
     }
 
+    /// Set VREF value in millivolts. This value is used for [to_millivolts()] sample conversion.
+    ///
+    /// Use this if you have a known precise VREF (VDDA) pin reference voltage.
+    pub fn set_vref_mv(&mut self, vref_mv: u32) {
+        self.vref_mv = vref_mv;
+    }
+
     /// Convert a measurement to millivolts
     pub fn to_millivolts(&self, sample: u16) -> u16 {
-        ((u32::from(sample) * self.calibrated_vdda) / self.resolution.to_max_count()) as u16
+        ((u32::from(sample) * self.vref_mv) / self.resolution.to_max_count()) as u16
     }
 
     /// Perform a single conversion.

embassy-stm32/src/adc/v3.rs

@@ -6,7 +6,10 @@ use embedded_hal_02::blocking::delay::DelayUs;
 use crate::adc::{AdcPin, Instance};
 use crate::Peripheral;
 
-pub const VDDA_CALIB_MV: u32 = 3000;
+/// Default VREF voltage used for sample conversion to millivolts.
+pub const VREF_DEFAULT_MV: u32 = 3300;
+/// VREF voltage used for factory calibration of VREFINTCAL register.
+pub const VREF_CALIB_MV: u32 = 3000;
 
 /// Sadly we cannot use `RccPeripheral::enable` since devices are quite inconsistent ADC clock
 /// configuration.
@@ -44,7 +47,7 @@ impl Resolution {
         }
     }
 
-    fn to_max_count(&self) -> u32 {
+    pub fn to_max_count(&self) -> u32 {
         match self {
             Resolution::TwelveBit => (1 << 12) - 1,
             Resolution::TenBit => (1 << 10) - 1,
@@ -54,9 +57,9 @@ impl Resolution {
     }
 }
 
-pub struct Vref;
+pub struct VrefInt;
-impl<T: Instance> AdcPin<T> for Vref {}
+impl<T: Instance> AdcPin<T> for VrefInt {}
-impl<T: Instance> super::sealed::AdcPin<T> for Vref {
+impl<T: Instance> super::sealed::AdcPin<T> for VrefInt {
     fn channel(&self) -> u8 {
         #[cfg(not(stm32g0))]
         let val = 0;
@@ -202,7 +205,7 @@ pub use sample_time::SampleTime;
 
 pub struct Adc<'d, T: Instance> {
     sample_time: SampleTime,
-    calibrated_vdda: u32,
+    vref_mv: u32,
     resolution: Resolution,
     phantom: PhantomData<&'d mut T>,
 }
@@ -241,12 +244,12 @@ impl<'d, T: Instance> Adc<'d, T> {
         Self {
             sample_time: Default::default(),
             resolution: Resolution::default(),
-            calibrated_vdda: VDDA_CALIB_MV,
+            vref_mv: VREF_DEFAULT_MV,
             phantom: PhantomData,
         }
     }
 
-    pub fn enable_vref(&self, delay: &mut impl DelayUs<u32>) -> Vref {
+    pub fn enable_vrefint(&self, delay: &mut impl DelayUs<u32>) -> VrefInt {
         unsafe {
             T::common_regs().ccr().modify(|reg| {
                 reg.set_vrefen(true);
@@ -259,7 +262,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         //cortex_m::asm::delay(20_000_000);
         delay.delay_us(15);
 
-        Vref {}
+        VrefInt {}
     }
 
     pub fn enable_temperature(&self) -> Temperature {
@@ -282,16 +285,16 @@ impl<'d, T: Instance> Adc<'d, T> {
         Vbat {}
     }
 
-    /// Calculates the system VDDA by sampling the internal VREF channel and comparing
+    /// Calculates the system VDDA by sampling the internal VREFINT channel and comparing
     /// the result with the value stored at the factory. If the chip's VDDA is not stable, run
     /// this before each ADC conversion.
     #[cfg(not(stm32g0))] // TODO is this supposed to be public?
     #[allow(unused)] // TODO is this supposed to be public?
-    fn calibrate(&mut self, vref: &mut Vref) {
+    fn calibrate(&mut self, vrefint: &mut VrefInt) {
         #[cfg(stm32l5)]
-        let vref_cal: u32 = todo!();
+        let vrefint_cal: u32 = todo!();
         #[cfg(not(stm32l5))]
-        let vref_cal = unsafe { crate::pac::VREFINTCAL.data().read().value() };
+        let vrefint_cal = unsafe { crate::pac::VREFINTCAL.data().read().value() };
         let old_sample_time = self.sample_time;
 
         // "Table 24. Embedded internal voltage reference" states that the sample time needs to be
@@ -300,11 +303,11 @@ impl<'d, T: Instance> Adc<'d, T> {
         self.sample_time = SampleTime::Cycles640_5;
 
         // This can't actually fail, it's just in a result to satisfy hal trait
-        let vref_samp = self.read(vref);
+        let vrefint_samp = self.read(vrefint);
 
         self.sample_time = old_sample_time;
 
-        self.calibrated_vdda = (VDDA_CALIB_MV * u32::from(vref_cal)) / u32::from(vref_samp);
+        self.vref_mv = (VREF_CALIB_MV * u32::from(vrefint_cal)) / u32::from(vrefint_samp);
     }
 
     pub fn set_sample_time(&mut self, sample_time: SampleTime) {
@@ -315,9 +318,16 @@ impl<'d, T: Instance> Adc<'d, T> {
         self.resolution = resolution;
     }
 
+    /// Set VREF value in millivolts. This value is used for [to_millivolts()] sample conversion.
+    ///
+    /// Use this if you have a known precise VREF (VDDA) pin reference voltage.
+    pub fn set_vref_mv(&mut self, vref_mv: u32) {
+        self.vref_mv = vref_mv;
+    }
+
     /// Convert a measurement to millivolts
     pub fn to_millivolts(&self, sample: u16) -> u16 {
-        ((u32::from(sample) * self.calibrated_vdda) / self.resolution.to_max_count()) as u16
+        ((u32::from(sample) * self.vref_mv) / self.resolution.to_max_count()) as u16
     }
 
     /*

embassy-stm32/src/adc/v4.rs

@@ -9,6 +9,11 @@ use super::{AdcPin, Instance};
 use crate::time::Hertz;
 use crate::{pac, Peripheral};
 
+/// Default VREF voltage used for sample conversion to millivolts.
+pub const VREF_DEFAULT_MV: u32 = 3300;
+/// VREF voltage used for factory calibration of VREFINTCAL register.
+pub const VREF_CALIB_MV: u32 = 3300;
+
 pub enum Resolution {
     SixteenBit,
     FourteenBit,
@@ -53,10 +58,10 @@ mod sealed {
     }
 }
 
-// NOTE: Vref/Temperature/Vbat are only available on ADC3 on H7, this currently cannot be modeled with stm32-data, so these are available from the software on all ADCs
+// NOTE: Vrefint/Temperature/Vbat are only available on ADC3 on H7, this currently cannot be modeled with stm32-data, so these are available from the software on all ADCs
-pub struct Vref;
+pub struct VrefInt;
-impl<T: Instance> InternalChannel<T> for Vref {}
+impl<T: Instance> InternalChannel<T> for VrefInt {}
-impl<T: Instance> sealed::InternalChannel<T> for Vref {
+impl<T: Instance> sealed::InternalChannel<T> for VrefInt {
     fn channel(&self) -> u8 {
         19
     }
@@ -317,6 +322,7 @@ impl Prescaler {
 
 pub struct Adc<'d, T: Instance> {
     sample_time: SampleTime,
+    vref_mv: u32,
     resolution: Resolution,
     phantom: PhantomData<&'d mut T>,
 }
@@ -354,6 +360,7 @@ impl<'d, T: Instance + crate::rcc::RccPeripheral> Adc<'d, T> {
 
         let mut s = Self {
             sample_time: Default::default(),
+            vref_mv: VREF_DEFAULT_MV,
             resolution: Resolution::default(),
             phantom: PhantomData,
         };
@@ -422,14 +429,14 @@ impl<'d, T: Instance + crate::rcc::RccPeripheral> Adc<'d, T> {
         }
     }
 
-    pub fn enable_vref(&self) -> Vref {
+    pub fn enable_vrefint(&self) -> VrefInt {
         unsafe {
             T::common_regs().ccr().modify(|reg| {
                 reg.set_vrefen(true);
             });
         }
 
-        Vref {}
+        VrefInt {}
     }
 
     pub fn enable_temperature(&self) -> Temperature {
@@ -460,9 +467,16 @@ impl<'d, T: Instance + crate::rcc::RccPeripheral> Adc<'d, T> {
         self.resolution = resolution;
     }
 
+    /// Set VREF value in millivolts. This value is used for [to_millivolts()] sample conversion.
+    ///
+    /// Use this if you have a known precise VREF (VDDA) pin reference voltage.
+    pub fn set_vref_mv(&mut self, vref_mv: u32) {
+        self.vref_mv = vref_mv;
+    }
+
     /// Convert a measurement to millivolts
     pub fn to_millivolts(&self, sample: u16) -> u16 {
-        ((u32::from(sample) * 3300) / self.resolution.to_max_count()) as u16
+        ((u32::from(sample) * self.vref_mv) / self.resolution.to_max_count()) as u16
     }
 
     /// Perform a single conversion.

examples/stm32h7/src/bin/adc.rs

@@ -28,11 +28,11 @@ async fn main(_spawner: Spawner, mut p: Peripherals) {
 
     adc.set_sample_time(SampleTime::Cycles32_5);
 
-    let mut vref_channel = adc.enable_vref();
+    let mut vrefint_channel = adc.enable_vrefint();
 
     loop {
-        let vref = adc.read_internal(&mut vref_channel);
+        let vrefint = adc.read_internal(&mut vrefint_channel);
-        info!("vref: {}", vref);
+        info!("vrefint: {}", vrefint);
         let measured = adc.read(&mut p.PC0);
         info!("measured: {}", measured);
         Timer::after(Duration::from_millis(500)).await;