1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_ADC_CAL_H__ 16 #define __ESP_ADC_CAL_H__ 17 18 #include <stdint.h> 19 #include "esp_err.h" 20 #include "driver/adc.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @brief Type of calibration value used in characterization 28 */ 29 typedef enum { 30 ESP_ADC_CAL_VAL_EFUSE_VREF = 0, /**< Characterization based on reference voltage stored in eFuse*/ 31 ESP_ADC_CAL_VAL_EFUSE_TP = 1, /**< Characterization based on Two Point values stored in eFuse*/ 32 ESP_ADC_CAL_VAL_DEFAULT_VREF = 2, /**< Characterization based on default reference voltage*/ 33 ESP_ADC_CAL_VAL_MAX, 34 ESP_ADC_CAL_VAL_NOT_SUPPORTED = ESP_ADC_CAL_VAL_MAX, 35 } esp_adc_cal_value_t; 36 37 /** 38 * @brief Structure storing characteristics of an ADC 39 * 40 * @note Call esp_adc_cal_characterize() to initialize the structure 41 */ 42 typedef struct { 43 adc_unit_t adc_num; /**< ADC number*/ 44 adc_atten_t atten; /**< ADC attenuation*/ 45 adc_bits_width_t bit_width; /**< ADC bit width */ 46 uint32_t coeff_a; /**< Gradient of ADC-Voltage curve*/ 47 uint32_t coeff_b; /**< Offset of ADC-Voltage curve*/ 48 uint32_t vref; /**< Vref used by lookup table*/ 49 const uint32_t *low_curve; /**< Pointer to low Vref curve of lookup table (NULL if unused)*/ 50 const uint32_t *high_curve; /**< Pointer to high Vref curve of lookup table (NULL if unused)*/ 51 } esp_adc_cal_characteristics_t; 52 53 /** 54 * @brief Checks if ADC calibration values are burned into eFuse 55 * 56 * This function checks if ADC reference voltage or Two Point values have been 57 * burned to the eFuse of the current ESP32 58 * 59 * @param value_type Type of calibration value (ESP_ADC_CAL_VAL_EFUSE_VREF or ESP_ADC_CAL_VAL_EFUSE_TP) 60 * @note in ESP32S2, only ESP_ADC_CAL_VAL_EFUSE_TP is supported. Some old ESP32S2s do not support this, either. 61 * In which case you have to calibrate it manually, possibly by performing your own two-point calibration on the chip. 62 * 63 * @return 64 * - ESP_OK: The calibration mode is supported in eFuse 65 * - ESP_ERR_NOT_SUPPORTED: Error, eFuse values are not burned 66 * - ESP_ERR_INVALID_ARG: Error, invalid argument (ESP_ADC_CAL_VAL_DEFAULT_VREF) 67 */ 68 esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t value_type); 69 70 /** 71 * @brief Characterize an ADC at a particular attenuation 72 * 73 * This function will characterize the ADC at a particular attenuation and generate 74 * the ADC-Voltage curve in the form of [y = coeff_a * x + coeff_b]. 75 * Characterization can be based on Two Point values, eFuse Vref, or default Vref 76 * and the calibration values will be prioritized in that order. 77 * 78 * @note 79 * For ESP32, Two Point values and eFuse Vref calibration can be enabled/disabled using menuconfig. 80 * For ESP32s2, only Two Point values calibration and only ADC_WIDTH_BIT_13 is supported. The parameter default_vref is unused. 81 * 82 * 83 * @param[in] adc_num ADC to characterize (ADC_UNIT_1 or ADC_UNIT_2) 84 * @param[in] atten Attenuation to characterize 85 * @param[in] bit_width Bit width configuration of ADC 86 * @param[in] default_vref Default ADC reference voltage in mV (Only in ESP32, used if eFuse values is not available) 87 * @param[out] chars Pointer to empty structure used to store ADC characteristics 88 * 89 * @return 90 * - ESP_ADC_CAL_VAL_EFUSE_VREF: eFuse Vref used for characterization 91 * - ESP_ADC_CAL_VAL_EFUSE_TP: Two Point value used for characterization (only in Linear Mode) 92 * - ESP_ADC_CAL_VAL_DEFAULT_VREF: Default Vref used for characterization 93 */ 94 esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num, 95 adc_atten_t atten, 96 adc_bits_width_t bit_width, 97 uint32_t default_vref, 98 esp_adc_cal_characteristics_t *chars); 99 100 /** 101 * @brief Convert an ADC reading to voltage in mV 102 * 103 * This function converts an ADC reading to a voltage in mV based on the ADC's 104 * characteristics. 105 * 106 * @note Characteristics structure must be initialized before this function 107 * is called (call esp_adc_cal_characterize()) 108 * 109 * @param[in] adc_reading ADC reading 110 * @param[in] chars Pointer to initialized structure containing ADC characteristics 111 * 112 * @return Voltage in mV 113 */ 114 uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars); 115 116 /** 117 * @brief Reads an ADC and converts the reading to a voltage in mV 118 * 119 * This function reads an ADC then converts the raw reading to a voltage in mV 120 * based on the characteristics provided. The ADC that is read is also 121 * determined by the characteristics. 122 * 123 * @note The Characteristics structure must be initialized before this 124 * function is called (call esp_adc_cal_characterize()) 125 * 126 * @param[in] channel ADC Channel to read 127 * @param[in] chars Pointer to initialized ADC characteristics structure 128 * @param[out] voltage Pointer to store converted voltage 129 * 130 * @return 131 * - ESP_OK: ADC read and converted to mV 132 * - ESP_ERR_TIMEOUT: Error, timed out attempting to read ADC 133 * - ESP_ERR_INVALID_ARG: Error due to invalid arguments 134 */ 135 esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel, const esp_adc_cal_characteristics_t *chars, uint32_t *voltage); 136 137 #ifdef __cplusplus 138 } 139 #endif 140 141 #endif /* __ESP_ADC_CAL_H__ */ 142