esp_hal/analog/adc/calibration/

curve.rs

use core::marker::PhantomData;

use crate::analog::adc::{
    AdcCalEfuse,
    AdcCalLine,
    AdcCalScheme,
    AdcHasLineCal,
    Attenuation,
    CalibrationAccess,
    Error,
};

const COEFF_MUL: i64 = 1 << 52;

/// Integer type for the error polynomial's coefficients. Despite
/// the type, this is a fixed-point number with 52 fractional bits.
type CurveCoeff = i64;

/// Polynomial coefficients for a specified attenuation.
pub struct CurveCoeffs {
    /// Attenuation.
    atten: Attenuation,
    /// Polynomial coefficients.
    coeff: &'static [CurveCoeff],
}

type CurvesCoeffs = &'static [CurveCoeffs];

/// Marker trait for ADCs that support curve fitting.
///
/// See also [`AdcCalCurve`].
pub trait AdcHasCurveCal {
    /// Coefficients for calculating the reading voltage error.
    ///
    /// A set of coefficients for each attenuation, selected for the eFuse
    /// calibration version on this chip.
    fn curves_coeffs() -> CurvesCoeffs;
}

/// Curve fitting ADC calibration scheme.
///
/// This scheme implements polynomial error correction using predefined
/// coefficient sets for each attenuation. It returns readings in mV.
///
/// This scheme also includes basic calibration ([`super::AdcCalBasic`]) and
/// line fitting ([`AdcCalLine`]).
#[derive(Clone, Copy)]
pub struct AdcCalCurve<ADCX> {
    line: AdcCalLine<ADCX>,

    /// Coefficients of the error estimation polynomial.
    ///
    /// The constant coefficient comes first; the error polynomial is
    /// `coeff[0] + coeff[1] * x + ... + coeff[n] * x^n`.
    ///
    /// This calibration works by first applying linear calibration. Then
    /// the error polynomial is applied to the output of linear calibration.
    /// The output of the polynomial is our estimate of the error; it gets
    /// subtracted from linear calibration's output to get the final reading.
    coeff: &'static [CurveCoeff],

    _phantom: PhantomData<ADCX>,
}

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

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

    fn new_cal_with_channel(atten: Attenuation, channel: u8) -> Result<Self, Error> {
        let line = AdcCalLine::<ADCX>::new_cal_with_channel(atten, channel)?;

        // Every shipped coefficient table covers all four attenuations; a miss
        // means the user requested an attenuation the chip never characterized.
        let Some(coeff) = ADCX::curves_coeffs()
            .iter()
            .find(|item| item.atten == atten)
        else {
            return Err(Error::UnsupportedAttenuation(atten));
        };

        Ok(Self {
            line,
            coeff: coeff.coeff,
            _phantom: PhantomData,
        })
    }

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

        // Truncate each polynomial term before summing to match integer division
        // in the curve-fitting reference model.
        //
        // The products need i128: the highest-order term (ESP32-S3, x^4) times its
        // coefficient does not fit an i64.
        let err = if val == 0 || self.coeff.is_empty() {
            0
        } else {
            let mut var: i128 = 1; // val^i
            let mut err: i128 = 0;

            for &coeff in self.coeff {
                err += var * i128::from(coeff) / i128::from(COEFF_MUL);
                var *= i128::from(val);
            }

            err as i32
        };

        (val as i32 - err) as u16
    }
}

macro_rules! coeff_tables {
    ($($(#[$($meta:meta)*])* $name:ident [ $($att:ident => [ $($val:literal,)* ],)* ];)*) => {
        $(
            $(#[$($meta)*])*
            const $name: CurvesCoeffs = &[
                $(CurveCoeffs {
                    atten: Attenuation::$att,
                    coeff: &[
                        $(($val as f64 * COEFF_MUL as f64) as CurveCoeff,)*
                    ],
                },)*
            ];
        )*
    };
}

#[cfg(adc_curve_calibration)]
mod impls {
    use super::*;

    impl AdcHasCurveCal for crate::peripherals::ADC1<'_> {
        fn curves_coeffs() -> CurvesCoeffs {
            #[cfg(esp32c6)]
            if crate::efuse::rtc_calib_version() == 2 {
                return CURVES_COEFFS1_V2;
            }

            CURVES_COEFFS1
        }
    }

    #[cfg(adc_adc2)]
    impl AdcHasCurveCal for crate::peripherals::ADC2<'_> {
        fn curves_coeffs() -> CurvesCoeffs {
            CURVES_COEFFS2
        }
    }

    coeff_tables! {
        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32c3/curve_fitting_coefficients.c>
        #[cfg(esp32c3)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.225966470500043,
                -0.0007265418501948,
                0.0000109410402681,
            ],
            _2p5dB => [
                0.4229623392600516,
                -0.0000731527490903,
                0.0000088166562521,
            ],
            _6dB => [
                -1.017859239236435,
                -0.0097159265299153,
                0.0000149794028038,
            ],
            _11dB => [
                -1.4912262772850453,
                -0.0228549975564099,
                0.0000356391935717,
                -0.0000000179964582,
                0.0000000000042046,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/c602e55/components/esp_adc/esp32c5/curve_fitting_coefficients.c>
        #[cfg(esp32c5)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.2941017829027464,
                0.0007368674918527,
                0.0,
            ],
            _2p5dB => [
                -0.3224276125615327,
                0.0005325658467636,
                0.0,
            ],
            _6dB => [
                -0.3307554632960901,
                0.000409244304226,
                0.0,
            ],
            _11dB => [
                1.463642578413965,
                -0.003349642363147,
                0.0000011676836451,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/027613140/components/esp_adc/esp32c6/curve_fitting_coefficients.c#L29-L35>
        #[cfg(esp32c6)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.487166399931449,
                0.0006436483033201,
                0.0000030410131806,
            ],
            _2p5dB => [
                -0.8665498165817785,
                0.0015239070452946,
                0.0000013818878844,
            ],
            _6dB => [
                -1.2277821756674387,
                0.0022275554717885,
                0.0000005924302667,
            ],
            _11dB => [
                -0.3801417550380255,
                -0.0006020352420772,
                0.0000012442478488,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/1e76669a8b940f5dc25adc35065cb53de3c71423/components/esp_adc/esp32c61/curve_fitting_coefficients.c>
        #[cfg(esp32c61)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.8668885650149671,
                0.0015630376830615,
            ],
            _2p5dB => [
                -1.090569589734153,
                0.0013859487941542,
            ],
            _6dB => [
                -1.4231790752153335,
                0.00122016745867,
            ],
            _11dB => [
                -1.3204544579940347,
                -0.0011762579610906,
                0.0000007639928529,
            ],
        ];

        /// Error curve coefficients for calibration version 2 derived from <https://github.com/espressif/esp-idf/blob/027613140/components/esp_adc/esp32c6/curve_fitting_coefficients.c#L36-L42>
        ///
        /// Version 2 does not apply a second-step polynomial at 0 dB and 2.5 dB.
        #[cfg(esp32c6)]
        CURVES_COEFFS1_V2 [
            _0dB => [],
            _2p5dB => [],
            _6dB => [
                -1.2217864764388775,
                -0.0001954123107752,
                0.0000006409679727,
            ],
            _11dB => [
                -0.3915910437042445,
                -0.0031536470857564,
                0.0000012493873014,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/465b159cd8771ffab6be70c7675ecf6705b62649/components/esp_adc/esp32h2/curve_fitting_coefficients.c>
        #[cfg(esp32h2)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.5081991760658888,
                0.0000007858995319,
                0,
            ],
            _2p5dB => [
                -0.8359230818901277,
                0.0000009025419089,
                0,
            ],
            _6dB => [
                -1.165668771581976,
                0.0000008294679249,
                0,
            ],
            _11dB => [
                -0.3637329628677273,
                -0.0000196072597389,
                0.0000007871689227,
            ],
        ];

        /// Error curve coefficients for ADC1, derived from <https://github.com/espressif/esp-idf/blob/08e0d30a74a/components/esp_adc/esp32p4/curve_fitting_coefficients.c>
        #[cfg(esp32p4)]
        CURVES_COEFFS1 [
            _0dB => [
                -0.7170501832480995,
                0.0010598497992115,
            ],
            _2p5dB => [
                -0.9960085535084866,
                0.0015840076608145,
            ],
            _6dB => [
                -1.4711053224678996,
                0.00001594266424857,
            ],
            _11dB => [
                -2.8811493455181565,
                0.0010082311568625,
            ],
        ];

        /// Error curve coefficients for ADC2, derived from <https://github.com/espressif/esp-idf/blob/08e0d30a74a/components/esp_adc/esp32p4/curve_fitting_coefficients.c>
        #[cfg(esp32p4)]
        CURVES_COEFFS2 [
            _0dB => [
                -0.4900967548489932,
                0.0005037402667913,
            ],
            _2p5dB => [
                -0.7296214814536025,
                0.0011021577596635,
            ],
            _6dB => [
                -1.0991620450220592,
                0.0011623930881896,
            ],
            _11dB => [
                -2.442140102462673,
                0.0009458501263393,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c>
        #[cfg(esp32s3)]
        CURVES_COEFFS1 [
            _0dB => [
                -2.7856531419538344,
                -0.0050871540569528,
                0.0000097982495890,
            ],
            _2p5dB => [
                -2.9831022915028695,
                -0.0049393185868806,
                0.0000101379430548,
            ],
            _6dB => [
                -2.3285545746296417,
                -0.0147640181047414,
                0.0000208385525314,
            ],
            _11dB => [
                -0.644403418269478,
                -0.0644334888647536,
                0.0001297891447611,
                -0.0000000707697180,
                0.0000000000135150,
            ],
        ];

        /// Error curve coefficients derived from <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c>
        #[cfg(esp32s3)]
        CURVES_COEFFS2 [
            _0dB => [
                -2.5668651654328927,
                0.0001353548869615,
                0.0000036615265189,
            ],
            _2p5dB => [
                -2.3690184690298404,
                -0.0066319894226185,
                0.0000118964995959,
            ],
            _6dB => [
                -0.9452499397020617,
                -0.0200996773954387,
                0.0000259011467956,
            ],
            _11dB => [
                1.2247719764336924,
                -0.0755717904943462,
                0.0001478791187119,
                -0.0000000796725280,
                0.0000000000150380,
            ],
        ];
    }
}