esp_adc_cal/Remove lookup table
This commit removes the lookup table mode due to inferior performance when compared to linear mode under attenuation 0, 1 and 2. However small portions of the lookup table are kept for the higher voltages of atten 3 (above ADC reading 2880). That voltage range in atten 3 has non linear characteristics making the LUT performan better than linear mode.
This commit is contained in:
Darian Leung
@@ -22,15 +22,6 @@ extern "C" {
|
||||
#include <stdint.h>
|
||||
#include "esp_err.h"
|
||||
#include "driver/adc.h"
|
||||
#include "esp_adc_cal_constants.h"
|
||||
|
||||
/**
|
||||
* @brief ADC characterization mode
|
||||
*/
|
||||
typedef enum {
|
||||
ESP_ADC_CAL_MODE_LIN = 0, /**< Characterize the ADC as a linear curve*/
|
||||
ESP_ADC_CAL_MODE_LUT= 1, /**< Characterize the ADC using a lookup table*/
|
||||
} esp_adc_cal_mode_t;
|
||||
|
||||
/**
|
||||
* @brief Type of calibration value used in characterization
|
||||
@@ -41,48 +32,27 @@ typedef enum {
|
||||
ESP_ADC_CAL_VAL_DEFAULT_VREF = 2, /**< Characterization based on default reference voltage*/
|
||||
} esp_adc_cal_value_t;
|
||||
|
||||
/**
|
||||
* @brief Structure storing Lookup Table
|
||||
*
|
||||
* A Lookup Table (LUT) of a given ADC and attenuation contains two curves
|
||||
* mapping ADC readings to a voltage in mV. Each curve contains 33 equally spaced
|
||||
* points separated by a step size of 128. The low_vref_curve represents the ADC
|
||||
* voltage curve of a module with a reference voltage of 1000mV, whilst the
|
||||
* high_vref_curve represents a reference voltage of 1200mV.
|
||||
*
|
||||
* @note Separate LUTs are provided for each ADC at each attenuation
|
||||
*/
|
||||
typedef struct {
|
||||
uint32_t low_vref_curve[33]; /**< Voltage curve at a reference voltage of 1000mV*/
|
||||
uint32_t high_vref_curve[33]; /**< Voltage curve at a reference voltage of 1200mV*/
|
||||
} esp_adc_cal_lookup_table_t;
|
||||
|
||||
/**
|
||||
* @brief Structure storing characteristics of an ADC
|
||||
*
|
||||
* @note Call esp_adc_cal_get_characteristics() to initialize the structure
|
||||
* @note Call esp_adc_cal_characterize() to initialize the structure
|
||||
*/
|
||||
typedef struct {
|
||||
esp_adc_cal_mode_t mode; /**< Characterization mode*/
|
||||
adc_unit_t adc_num; /**< ADC number*/
|
||||
union {
|
||||
struct {
|
||||
uint32_t coeff_a; /**< 1st order coefficient of linear characteristics curve*/
|
||||
uint32_t coeff_b; /**< 0th order coefficient of linear characteristics curve*/
|
||||
} linear_chars;
|
||||
struct {
|
||||
uint32_t vref; /**< Reference voltage*/
|
||||
const esp_adc_cal_lookup_table_t *table; /**< Pointer to lookup table*/
|
||||
} lut_chars;
|
||||
};
|
||||
adc_unit_t adc_num; /**< ADC number*/
|
||||
adc_atten_t atten; /**< ADC attenuation*/
|
||||
adc_bits_width_t bit_width; /**< ADC bit width */
|
||||
uint32_t coeff_a; /**< Gradient of ADC-Voltage curve*/
|
||||
uint32_t coeff_b; /**< Offset of ADC-Voltage curve*/
|
||||
uint32_t vref; /**< Vref used by lookup table*/
|
||||
const uint32_t *low_curve; /**< Pointer to low Vref curve of lookup table (NULL if unused)*/
|
||||
const uint32_t *high_curve; /**< Pointer to high Vref curve of lookup table (NULL if unused)*/
|
||||
} esp_adc_cal_characteristics_t;
|
||||
|
||||
|
||||
/**
|
||||
* @brief Checks if ADC calibration values are stored in eFuse
|
||||
* @brief Checks if ADC calibration values are burned into eFuse
|
||||
*
|
||||
* This function checks if ADC reference voltage or Two Point calibration voltages
|
||||
* have been burned to the eFuse of the current ESP32
|
||||
* This function checks if ADC reference voltage or Two Point values have been
|
||||
* burned to the eFuse of the current ESP32
|
||||
*
|
||||
* @param value_type Type of calibration value (ESP_ADC_CAL_VAL_EFUSE_VREF or ESP_ADC_CAL_VAL_EFUSE_TP)
|
||||
*
|
||||
@@ -94,24 +64,19 @@ typedef struct {
|
||||
esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t value_type);
|
||||
|
||||
/**
|
||||
* @brief Characterize an ADC at a particular attenuation under Linear or LUT Mode
|
||||
* @brief Characterize an ADC at a particular attenuation
|
||||
*
|
||||
* This function will generate the characteristics curve of one of the ADCs at a
|
||||
* particular attenuation. This characteristics curve will be stored in a
|
||||
* characteristics structure. Linear Mode will be characterize the ADC-Voltage
|
||||
* curve as a linear curve. LUT Mode will characterize the ADC-Voltage curve
|
||||
* using a lookup table. Calibration values in eFuse will be used to generate
|
||||
* the characteristics curve if available, and vref_default will be used if they
|
||||
* are not.
|
||||
* This function will characterize the ADC at a particular attenuation and generate
|
||||
* the ADC-Voltage curve in the form of [y = coeff_a * x + coeff_b].
|
||||
* Characterization can be based on Two Point values, eFuse Vref, or default Vref
|
||||
* and the calibration values will be prioritized in that order.
|
||||
*
|
||||
* @note This function will abort if there are no available options for
|
||||
* characterization (characterization modes and calibration value types
|
||||
* can be enabled and disabled in menuconfig)
|
||||
* @note Two Point values and eFuse Vref can be enabled/disabled using menuconfig.
|
||||
*
|
||||
* @param[in] adc_num ADC to characterize (ADC_UNIT_1 or ADC_UNIT_2)
|
||||
* @param[in] atten Attenuation to characterize
|
||||
* @param[in] mode Characterization mode (Linear or LUT)
|
||||
* @param[in] vref_default Default ADC reference voltage in mV (used if eFuse is not available)
|
||||
* @param[in] bit_width Bit width configuration of ADC
|
||||
* @param[in] default_vref Default ADC reference voltage in mV (used if eFuse values is not available)
|
||||
* @param[out] chars Pointer to empty structure used to store ADC characteristics
|
||||
*
|
||||
* @return
|
||||
@@ -121,66 +86,60 @@ esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t value_type);
|
||||
*/
|
||||
esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
|
||||
adc_atten_t atten,
|
||||
esp_adc_cal_mode_t mode,
|
||||
uint32_t vref_default,
|
||||
adc_bits_width_t bit_width,
|
||||
uint32_t default_vref,
|
||||
esp_adc_cal_characteristics_t *chars);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Convert an ADC reading to voltage in mV
|
||||
*
|
||||
* This function converts a an ADC reading to a voltage in mV based on the
|
||||
* ADC characteristics curve provided.
|
||||
* This function converts an ADC reading to a voltage in mV based on the ADC's
|
||||
* characteristics.
|
||||
*
|
||||
* @note Characteristics structure must be initialized before this function
|
||||
* is called (call esp_adc_cal_characterize())
|
||||
*
|
||||
* @param[in] adc_reading ADC reading
|
||||
* @param[in] bit_width Bit width of the ADC reading
|
||||
* @param[in] chars Pointer to initialized structure containing ADC characteristics curve
|
||||
* @param[in] chars Pointer to initialized structure containing ADC characteristics
|
||||
*
|
||||
* @return Voltage in mV
|
||||
*
|
||||
* @note characteristics structure must be initialized first using esp_adc_cal_characterize()
|
||||
*/
|
||||
uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, adc_bits_width_t bit_width, const esp_adc_cal_characteristics_t *chars);
|
||||
uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars);
|
||||
|
||||
/**
|
||||
* @brief Reads an ADC and returns a voltage in mV
|
||||
* @brief Reads an ADC and converts the reading to a voltage in mV
|
||||
*
|
||||
* This function reads an ADC then converts the raw reading to a voltage in mV
|
||||
* using the characteristics curve provided. The ADC that is read is also
|
||||
* based on the characteristics provided. The ADC that is read is also
|
||||
* determined by the characteristics.
|
||||
*
|
||||
* @note The Characteristics structure must be initialized before this
|
||||
* function is called (call esp_adc_cal_characterize())
|
||||
*
|
||||
* @param[in] channel ADC Channel to read
|
||||
* @param[in] bit_width Bit width of ADC reading (must be same as ADC configuration)
|
||||
* @param[in] chars Pointer to initialized ADC characteristics structure
|
||||
* @param[out] voltage Pointer to store converted voltage
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK: ADC read and converted
|
||||
* - ESP_ERR_TIMEOUT: Error, could not read ADC
|
||||
* - ESP_OK: ADC read and converted to mV
|
||||
* - ESP_ERR_TIMEOUT: Error, timed out attempting to read ADC
|
||||
* - ESP_ERR_INVALID_ARG: Error due to invalid arguments
|
||||
*
|
||||
* @note The ADC must be initialized before calling this function. The
|
||||
* bit_width parameter must be the same as the bit width used in
|
||||
* configuration
|
||||
*
|
||||
* @note Characteristics structure must be initialized using before calling
|
||||
* this function
|
||||
*/
|
||||
esp_err_t adc_to_voltage(adc_channel_t channel, adc_bits_width_t bit_width, const esp_adc_cal_characteristics_t *chars, uint32_t *voltage);
|
||||
esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel, const esp_adc_cal_characteristics_t *chars, uint32_t *voltage);
|
||||
|
||||
/* -------------------------- Deprecated API ------------------------------- */
|
||||
|
||||
/** @cond */ //Doxygen command to hide deprecated function from API Reference
|
||||
/**
|
||||
* @deprecated ADC1 characterization function. Deprecated in order to accommodate
|
||||
* new characterization functions. Use esp_adc_cal_characterize() instead
|
||||
* ADC2 and eFuse functionality. Use esp_adc_cal_characterize() instead
|
||||
*/
|
||||
void esp_adc_cal_get_characteristics(uint32_t vref, adc_atten_t atten, adc_bits_width_t bit_width, esp_adc_cal_characteristics_t *chars) __attribute__((deprecated));
|
||||
|
||||
/*
|
||||
* @deprecated This function reads ADC1 and returns the corrected voltage. This
|
||||
* has been deprecated in order to accommodate ADC2 support and new
|
||||
* ADC calibration methods. Use the new function adc_to_voltage() instead
|
||||
* has been deprecated in order to accommodate ADC2 support. Use the
|
||||
* new function esp_adc_cal_get_voltage() instead.
|
||||
*/
|
||||
uint32_t adc1_to_voltage(adc1_channel_t channel, const esp_adc_cal_characteristics_t *chars) __attribute__((deprecated));
|
||||
|
||||
|
||||
Reference in New Issue
Block a user