esp-hal 1.2.0

Bare-metal HAL for Espressif devices
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

use core::marker::PhantomData;

use super::AdcHasLineCal;
use crate::analog::adc::{
    AdcCalBasic,
    AdcCalEfuse,
    AdcCalScheme,
    AdcCalSource,
    AdcConfig,
    Attenuation,
    CalibrationAccess,
};

/// Gain is stored as a `u32`, but is really a fixed-point number.
const GAIN_SCALE: u32 = 1 << 16;

/// Line fitting ADC calibration scheme
///
/// This scheme implements gain correction based on reference points, and
/// returns readings in mV.
///
/// A reference point is a pair of a reference voltage and the corresponding
/// mean raw digital ADC value. Such values are usually stored in efuse bit
/// fields for each supported attenuation.
///
/// Also it can be measured in runtime by connecting ADC to reference voltage
/// internally but this method is not so good because actual reference voltage
/// may vary in range 1.0..=1.2 V. Currently this method is used as a fallback
/// (with 1.1 V by default) when calibration data is missing.
///
/// This scheme also includes basic calibration ([`AdcCalBasic`]).
#[derive(Clone, Copy)]
pub struct AdcCalLine<ADCX> {
    basic: AdcCalBasic<ADCX>,

    /// ADC gain.
    ///
    /// After being de-biased by the basic calibration, the reading is
    /// multiplied by this value. Despite the type, it is a fixed-point
    /// number with 16 fractional bits.
    gain: u32,

    _phantom: PhantomData<ADCX>,
}

impl<ADCX> crate::private::Sealed for AdcCalLine<ADCX> {}

impl<ADCX> AdcCalScheme<ADCX> for AdcCalLine<ADCX>
where
    ADCX: AdcCalEfuse + AdcHasLineCal + CalibrationAccess,
{
    fn new_cal(atten: Attenuation) -> Self {
        Self::new_cal_with_channel(atten, 0)
    }

    fn new_cal_with_channel(atten: Attenuation, channel: u8) -> Self {
        let basic = AdcCalBasic::<ADCX>::new_cal_with_channel(atten, channel);

        // Try get the reference point (Dout, Vin) from efuse
        // Dout means mean raw ADC value when specified Vin applied to input.
        let (code, mv) = ADCX::cal_code(atten)
            .map(|code| (code, ADCX::cal_mv(atten)))
            .unwrap_or_else(|| {
                // As a fallback try to calibrate using reference voltage source.
                // This method is not too good because actual reference voltage may varies
                // in range 1000..=1200 mV and this value currently cannot be read from efuse.
                (
                    AdcConfig::<ADCX>::adc_calibrate(atten, AdcCalSource::Ref),
                    1100, // use 1100 mV as a middle of typical reference voltage range
                )
            });

        // Estimate the (assumed) linear relationship between the measured raw value and
        // the voltage with the previously done measurement when the chip was
        // manufactured.
        //
        // Note that the constant term is zero because the basic calibration takes care
        // of it already.
        let gain = mv as u32 * GAIN_SCALE / code as u32;

        Self {
            basic,
            gain,
            _phantom: PhantomData,
        }
    }

    fn adc_cal(&self) -> u16 {
        self.basic.adc_cal()
    }

    fn adc_val(&self, val: u16) -> u16 {
        let val = self.basic.adc_val(val);

        (val as u32 * self.gain / GAIN_SCALE) as u16
    }
}