/
esp_adc_cal.h
140 lines (128 loc) · 5.98 KB
/
esp_adc_cal.h
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef __ESP_ADC_CAL_H__
#define __ESP_ADC_CAL_H__
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include "esp_err.h"
#include "driver/adc.h"
/**
* @brief Type of calibration value used in characterization
*/
typedef enum {
ESP_ADC_CAL_VAL_EFUSE_VREF = 0, /**< Characterization based on reference voltage stored in eFuse*/
ESP_ADC_CAL_VAL_EFUSE_TP = 1, /**< Characterization based on Two Point values stored in eFuse*/
ESP_ADC_CAL_VAL_DEFAULT_VREF = 2, /**< Characterization based on default reference voltage*/
ESP_ADC_CAL_VAL_MAX
} esp_adc_cal_value_t;
/**
* @brief Structure storing characteristics of an ADC
*
* @note Call esp_adc_cal_characterize() to initialize the structure
*/
typedef struct {
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 burned into eFuse
*
* 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)
* @note in ESP32S2, only ESP_ADC_CAL_VAL_EFUSE_TP is supported. Some old ESP32S2s do not support this, either.
* In which case you have to calibrate it manually, possibly by performing your own two-point calibration on the chip.
*
* @return
* - ESP_OK: The calibration mode is supported in eFuse
* - ESP_ERR_NOT_SUPPORTED: Error, eFuse values are not burned
* - ESP_ERR_INVALID_ARG: Error, invalid argument (ESP_ADC_CAL_VAL_DEFAULT_VREF)
*/
esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t value_type);
/**
* @brief Characterize an ADC at a particular attenuation
*
* 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
* For ESP32, Two Point values and eFuse Vref calibration can be enabled/disabled using menuconfig.
* For ESP32s2, only Two Point values calibration and only ADC_WIDTH_BIT_13 is supported. The parameter default_vref is unused.
*
*
* @param[in] adc_num ADC to characterize (ADC_UNIT_1 or ADC_UNIT_2)
* @param[in] atten Attenuation to characterize
* @param[in] bit_width Bit width configuration of ADC
* @param[in] default_vref Default ADC reference voltage in mV (Only in ESP32, used if eFuse values is not available)
* @param[out] chars Pointer to empty structure used to store ADC characteristics
*
* @return
* - ESP_ADC_CAL_VAL_EFUSE_VREF: eFuse Vref used for characterization
* - ESP_ADC_CAL_VAL_EFUSE_TP: Two Point value used for characterization (only in Linear Mode)
* - ESP_ADC_CAL_VAL_DEFAULT_VREF: Default Vref used for characterization
*/
esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
adc_atten_t atten,
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 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] chars Pointer to initialized structure containing ADC characteristics
*
* @return Voltage in mV
*/
uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars);
/**
* @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
* 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] chars Pointer to initialized ADC characteristics structure
* @param[out] voltage Pointer to store converted voltage
*
* @return
* - 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
*/
esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel, const esp_adc_cal_characteristics_t *chars, uint32_t *voltage);
#ifdef __cplusplus
}
#endif
#endif /* __ESP_ADC_CAL_H__ */