# Analog to Digital Converter¶

## Overview¶

The ESP32-S2 integrates two 13-bit SAR (Successive Approximation Register) ADCs, supporting a total of 20 measurement channels (analog enabled pins).

These channels are supported:

• 10 channels: GPIO1 - GPIO10

• 10 channels: GPIO11 - GPIO20

Note

## Driver Usage¶

Note

ADC readings from a pin not connected to any signal are random.

Attenuation configuration is done per channel, see adc1_channel_t and adc2_channel_t, set as a parameter of above functions.

This API provides convenient way to configure ADC1 for reading from ULP. To do so, call function adc1_ulp_enable() and then set precision and attenuation as discussed above.

There is another specific function adc_vref_to_gpio() used to route internal reference voltage to a GPIO pin. It comes handy to calibrate ADC reading and this is discussed in section Minimizing Noise.

Note

## Application Example¶

...

The input voltage in the above example is from 0 to 1.1 V (0 dB attenuation). The input range can be extended by setting a higher attenuation, see adc_atten_t. An example of using the ADC driver including calibration (discussed below) is available at esp-idf: peripherals/adc/single_read/adc

...

if ( r == ESP_OK ) {
} else if ( r == ESP_ERR_TIMEOUT ) {
}

The reading may fail due to collision with Wi-Fi, if the return value of this API is ESP_ERR_INVALID_STATE, then the reading result is not valid. An example using the ADC2 driver to read the output of DAC is available in esp-idf: peripherals/adc/single_read/adc2

The value read in both these examples is 13 bits wide (range 0-8191).

## Minimizing Noise¶

The ESP32-S2 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1 µF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.

Graph illustrating noise mitigation using capacitor and multisampling of 64 samples.

The esp_adc_cal/include/esp_adc_cal.h API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV amongst different ESP32-S2s.

Graph illustrating effect of differing reference voltages on the ADC voltage curve.

Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of y = coeff_a * x + coeff_b and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user.

### Calibration Values¶

Calibration values are used to generate characteristic curves that account for the variation of ADC reference voltage of a particular ESP32-S2 chip. There are currently 1 source(s) of calibration values on ESP32-S2. The availability of these calibration values will depend on the type and production date of the ESP32-S2 chip/module.

• eFuse Two Point values calibrates the ADC output at two different voltages. This value is measured and burned into eFuse BLOCK0 during factory calibration on newly manufactured ESP32-S2 chips and modules. If you would like to purchase chips or modules with calibration, double check with distributor or Espressif (sales@espressif.com) directly.

You can verify if eFuse Two Point is present by running the espefuse.py tool with adc_info parameter

Replace /dev/ttyUSB0 with ESP32-S2 board’s port name.

## Application Extensions¶

Characterizing an ADC at a particular attenuation:

...

//Check type of calibration value used to characterize ADC
printf("eFuse Vref");
} else if (val_type == ESP_ADC_CAL_VAL_EFUSE_TP) {
printf("Two Point");
} else {
printf("Default");
}

...

Routing ADC reference voltage to GPIO, so it can be manually measured (for Default Vref):

...

if (status == ESP_OK) {
printf("v_ref routed to GPIO\n");
} else {
printf("failed to route v_ref\n");
}

## GPIO Lookup Macros¶

There are macros available to specify the GPIO number of a ADC channel, or vice versa. e.g.

## API Reference¶

This reference covers three components:

### Functions¶

Config ADC module arbiter. The arbiter is to improve the use efficiency of ADC2. After the control right is robbed by the high priority, the low priority controller will read the invalid ADC2 data, and the validity of the data can be judged by the flag bit in the data.

Note

Note

Default priority: Wi-Fi > RTC > Digital;

Note

In normal use, there is no need to call this interface to config arbiter.

Return

• ESP_OK Success

• ESP_ERR_NOT_SUPPORTED ADC unit not support arbiter.

Parameters

Enable digital controller to trigger the measurement.

Return

• ESP_OK Success

Disable digital controller to trigger the measurement.

Return

• ESP_OK Success

Return

• ESP_OK Success

Parameters
• idx: Filter index.

Set adc digital controller filter configuration.

Note

For ESP32S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time.

Return

• ESP_OK Success

Parameters

Get adc digital controller filter configuration.

Note

For ESP32S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time.

Return

• ESP_OK Success

Parameters

Enable/disable adc digital controller filter. Filtering the ADC data to obtain smooth data at higher sampling rates.

Note

For ESP32S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time.

Return

• ESP_OK Success

Parameters
• idx: Filter index.

• enable: Enable/Disable filter.

Config monitor of adc digital controller.

Note

For ESP32S2, The monitor will monitor all the enabled channel data of the each ADC unit at the same time.

Return

• ESP_OK Success

Parameters

Enable/disable monitor of adc digital controller.

Note

For ESP32S2, The monitor will monitor all the enabled channel data of the each ADC unit at the same time.

Return

• ESP_OK Success

Parameters
• idx: Monitor index.

• enable: True or false enable monitor.

Return

• ESP_OK Success

Parameters

Return

• ESP_OK Success

Parameters

Return

• ESP_OK Success

Parameters

Return

Parameters

esp_err_t adc_digi_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, )

Register ADC interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

Return

• ESP_OK Success

• ESP_ERR_NOT_FOUND Can not find the interrupt that matches the flags.

• ESP_ERR_INVALID_ARG Function pointer error.

Parameters
• fn: Interrupt handler function.

• arg: Parameter for handler function

• intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

Deregister ADC interrupt handler, the handler is an ISR.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG hander error.

• ESP_FAIL ISR not be registered.

Set I2S data source.

Parameters
• src: I2S DMA data source, I2S DMA can get data from digital signals or from ADC.

Return

• ESP_OK success

Parameters

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

### Structures¶

ADC digital controller (DMA mode) conversion rules setting.

Public Members

uint8_t atten : 2

ADC sampling voltage attenuation configuration. Modification of attenuation affects the range of measurements. 0: measurement range 0 - 800mV, 1: measurement range 0 - 1100mV, 2: measurement range 0 - 1350mV, 3: measurement range 0 - 2600mV.

uint8_t reserved : 2

reserved0

uint8_t channel : 4

uint8_t val

Raw data value

ADC digital controller (DMA mode) output data format. Used to analyze the acquired ADC (DMA) data.

Note

ESP32-S2: Member channel can be used to judge the validity of the ADC data, because the role of the arbiter may get invalid ADC data.

Public Members

uint16_t data : 12

ADC real output data info. Resolution: 12 bit.

ADC real output data info. Resolution: 11 bit.

uint16_t channel : 4

ADC channel index info. For ESP32-S2: If (channel < ADC_CHANNEL_MAX), The data is valid. If (channel > ADC_CHANNEL_MAX), The data is invalid.

When the configured output format is 12bit. ADC_DIGI_FORMAT_12BIT

uint16_t unit : 1

When the configured output format is 11bit. ADC_DIGI_FORMAT_11BIT

uint16_t val

Raw data value

ADC digital controller (DMA mode) clock system setting. Calculation formula: controller_clk = (APLL or APB) / (div_num + div_a / div_b + 1).

Note

: The clocks of the DAC digital controller use the ADC digital controller clock divider.

Public Members

bool use_apll

true: use APLL clock; false: use APB clock.

uint32_t div_num

Division factor. Range: 0 ~ 255. Note: When a higher frequency clock is used (the division factor is less than 9), the ADC reading value will be slightly offset.

uint32_t div_b

Division factor. Range: 1 ~ 63.

uint32_t div_a

Division factor. Range: 0 ~ 63.

CONFIG_IDF_TARGET_ESP32.

ADC digital controller (DMA mode) configuration parameters.

Example setting: When using ADC1 channel0 to measure voltage, the sampling rate is required to be 1 kHz:

+---------------------+--------+--------+--------+
| sample rate         | 1 kHz  | 1 kHz  | 1 kHz  |
+---------------------+--------+--------+--------+
| conv_mode           | single |  both  |  alter |
| adc1_pattern_len    |    1   |    1   |    1   |
| dig_clk.use_apll    |    0   |    0   |    0   |
| dig_clk.div_num     |   99   |   99   |   99   |
| dig_clk.div_b       |    0   |    0   |    0   |
| dig_clk.div_a       |    0   |    0   |    0   |
| interval            |  400   |  400   |  200   |
+---------------------+--------+--------+--------+
| trigger_meas_freq | 1 kHz  | 1 kHz  | 2 kHz  |
+---------------------+--------+--------+--------+

Explanation of the relationship between conv_limit_num, dma_eof_num and the number of DMA outputs:

+---------------------+--------+--------+--------+
| conv_mode           | single |  both  |  alter |
+---------------------+--------+--------+--------+
| trigger meas times  |    1   |    1   |    1   |
+---------------------+--------+--------+--------+
| conv_limit_num      |   +1   |   +1   |   +1   |
| dma_eof_num         |   +1   |   +2   |   +1   |
| dma output (byte)   |   +2   |   +4   |   +2   |
+---------------------+--------+--------+--------+

Public Members

bool conv_limit_en

Enable the function of limiting ADC conversion times. If the number of ADC conversion trigger count is equal to the limit_num, the conversion is stopped.

uint32_t conv_limit_num

Set the upper limit of the number of ADC conversion triggers. Range: 1 ~ 255.

Pattern table length for digital controller. Range: 0 ~ 16 (0: Don’t change the pattern table setting). The pattern table that defines the conversion rules for each SAR ADC. Each table has 16 items, in which channel selection, resolution and attenuation are stored. When the conversion is started, the controller reads conversion rules from the pattern table one by one. For each controller the scan sequence has at most 16 different rules before repeating itself.

Pointer to pattern table for digital controller. The table size defined by adc1_pattern_len.

uint32_t interval

The number of interval clock cycles for the digital controller to trigger the measurement. The unit is the divided clock. Range: 40 ~ 4095. Expression: trigger_meas_freq = controller_clk / 2 / interval. Refer to adc_digi_clk_t. Note: The sampling rate of each channel is also related to the conversion mode (See adc_digi_convert_mode_t) and pattern table settings.

ADC digital controller clock divider settings. Refer to adc_digi_clk_t. Note: The clocks of the DAC digital controller use the ADC digital controller clock divider.

uint32_t dma_eof_num

DMA eof num of adc digital controller. If the number of measurements reaches dma_eof_num, then dma_in_suc_eof signal is generated in DMA. Note: The converted data in the DMA in link buffer will be multiple of two bytes.

ADC arbiter work mode and priority setting.

Note

Public Members

uint8_t rtc_pri

RTC controller priority. Range: 0 ~ 2.

uint8_t dig_pri

Digital controller priority. Range: 0 ~ 2.

uint8_t pwdet_pri

Wi-Fi controller priority. Range: 0 ~ 2.

ADC digital controller (DMA mode) filter configuration.

Note

For ESP32-S2, The filter object of the ADC is fixed.

Note

For ESP32-S2, The filter object is always all enabled channels.

Public Members

Set adc unit number for filter. For ESP32-S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time.

ADC digital controller (DMA mode) monitor configuration.

Note

For ESP32-S2, The monitor object of the ADC is fixed.

Note

For ESP32-S2, The monitor object is always all enabled channels.

Public Members

Set adc unit number for monitor. For ESP32-S2, monitor IDX0/IDX1 can only be used to monitor all enabled channels of ADC1/ADC2 unit at the same time.

uint32_t threshold

Set monitor threshold of adc digital controller.

### Macros¶

Note

ESP32S2: Only ADC2 supports (needs) an arbiter.

### Enumerations¶

Note

Values:

SAR ADC 1 and 2 alternative mode.

Note

Values:

Values:

No input attenumation, ADC can measure up to approx. 800 mV.

The input voltage of ADC will be attenuated, extending the range of measurement to up to approx. 1100 mV.

The input voltage of ADC will be attenuated, extending the range of measurement to up to approx. 1350 mV.

The input voltage of ADC will be attenuated, extending the range of measurement to up to approx. 2600 mV.

Values:

I2S data from GPIO matrix signal

Values:

ADC digital controller (DMA mode) work mode.

Note

The conversion mode affects the sampling frequency: SINGLE_UNIT_1: When the measurement is triggered, only ADC1 is sampled once. SINGLE_UNIT_2: When the measurement is triggered, only ADC2 is sampled once. BOTH_UNIT : When the measurement is triggered, ADC1 and ADC2 are sampled at the same time. ALTER_UNIT : When the measurement is triggered, ADC1 or ADC2 samples alternately.

Values:

SAR ADC 1 and 2 alternative mode.

ADC digital controller (DMA mode) output data format option.

Values:

ADC to DMA data format, [15:12]-channel, [11: 0]-12 bits ADC data (adc_digi_output_data_t). Note: For single convert mode.

ADC digital controller (DMA mode) interrupt type options.

Values:

Note

Values:

Force shield arbiter, Select the highest priority controller to work.

Fixed priority switch controller mode.

Loop priority switch controller mode. Each controller has the same priority, and the arbiter will switch to the next controller after the measurement is completed.

ADC digital controller (DMA mode) filter index options.

Note

For ESP32-S2, The filter object of the ADC is fixed.

Values:

The filter index 0. For ESP32-S2, It can only be used to filter all enabled channels of ADC1 unit at the same time.

The filter index 1. For ESP32-S2, It can only be used to filter all enabled channels of ADC2 unit at the same time.

ADC digital controller (DMA mode) filter type options. Expression: filter_data = (k-1)/k * last_data + new_data / k.

Values:

The filter mode is first-order IIR filter. The coefficient is 2.

The filter mode is first-order IIR filter. The coefficient is 4.

The filter mode is first-order IIR filter. The coefficient is 8.

The filter mode is first-order IIR filter. The coefficient is 16.

The filter mode is first-order IIR filter. The coefficient is 64.

ADC digital controller (DMA mode) monitor index options.

Note

For ESP32-S2, The monitor object of the ADC is fixed.

Values:

The monitor index 0. For ESP32-S2, It can only be used to monitor all enabled channels of ADC1 unit at the same time.

The monitor index 1. For ESP32-S2, It can only be used to monitor all enabled channels of ADC2 unit at the same time.

Set monitor mode of adc digital controller. MONITOR_HIGH:If ADC_OUT > threshold, Generates monitor interrupt. MONITOR_LOW: If ADC_OUT < threshold, Generates monitor interrupt.

Values:

If ADC_OUT > threshold, Generates monitor interrupt.

If ADC_OUT < threshold, Generates monitor interrupt.

### Functions¶

Increment the usage counter for ADC module. ADC will stay powered on while the counter is greater than 0. Call adc_power_release when done using the ADC.

Decrement the usage counter for ADC module. ADC will stay powered on while the counter is greater than 0. Call this function when done using the ADC.

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

Get the GPIO number of a specific ADC1 channel.

Return

• ESP_OK if success

• ESP_ERR_INVALID_ARG if channel not valid

Parameters
• channel: Channel to get the GPIO number

• gpio_num: output buffer to hold the GPIO number

Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.

The default ADC voltage is for attenuation 0 dB and listed in the table below. By setting higher attenuation it is possible to read higher voltages.

Due to ADC characteristics, most accurate results are obtained within the “suggested range” shown in the following table.

+----------+-------------+-----------------+
|          | attenuation | suggested range |
|    SoC   |     (dB)    |      (mV)       |
+==========+=============+=================+
|          |       0     |    100 ~  950   |
|          +-------------+-----------------+
|          |       2.5   |    100 ~ 1250   |
|   ESP32  +-------------+-----------------+
|          |       6     |    150 ~ 1750   |
|          +-------------+-----------------+
|          |      11     |    150 ~ 2450   |
+----------+-------------+-----------------+
|          |       0     |      0 ~  750   |
|          +-------------+-----------------+
|          |       2.5   |      0 ~ 1050   |
| ESP32-S2 +-------------+-----------------+
|          |       6     |      0 ~ 1300   |
|          +-------------+-----------------+
|          |      11     |      0 ~ 2500   |
+----------+-------------+-----------------+

For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.

Note

For any given channel, this function must be called before the first time adc1_get_raw() is called for that channel.

Note

This function can be called multiple times to configure multiple ADC channels simultaneously. You may call adc1_get_raw() only after configuring a channel.

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters
• channel: ADC1 channel to configure

• atten: Attenuation level

Configure ADC1 capture width, meanwhile enable output invert for ADC1. The configuration is for all channels of ADC1.

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters
• width_bit: Bit capture width for ADC1

Note

ESP32: When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue. As a workaround, call adc_power_acquire() in the app. This will result in higher power consumption (by ~1mA), but will remove the glitches on GPIO36 and GPIO39.

Note

Call adc1_config_width() before the first time this function is called.

Note

For any given channel, adc1_config_channel_atten(channel) must be called before the first time this function is called. Configuring a new channel does not prevent a previously configured channel from being read.

Return

• -1: Parameter error

Parameters

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• inv_en: whether enable data invert

Return

• ESP_OK success

Parameters
• clk_div: ADC clock divider, ADC clock is divided from APB clock

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• width_bit: Bit capture width for ADC unit.

Configure ADC1 to be usable by the ULP.

This function reconfigures ADC1 to be controlled by the ULP. Effect of this function can be reverted using adc1_get_raw() function.

Get the GPIO number of a specific ADC2 channel.

Return

• ESP_OK if success

• ESP_ERR_INVALID_ARG if channel not valid

Parameters
• channel: Channel to get the GPIO number

• gpio_num: output buffer to hold the GPIO number

Configure the ADC2 channel, including setting attenuation.

The default ADC voltage is for attenuation 0 dB and listed in the table below. By setting higher attenuation it is possible to read higher voltages.

Due to ADC characteristics, most accurate results are obtained within the “suggested range” shown in the following table.

+----------+-------------+-----------------+
|          | attenuation | suggested range |
|    SoC   |     (dB)    |      (mV)       |
+==========+=============+=================+
|          |       0     |    100 ~  950   |
|          +-------------+-----------------+
|          |       2.5   |    100 ~ 1250   |
|   ESP32  +-------------+-----------------+
|          |       6     |    150 ~ 1750   |
|          +-------------+-----------------+
|          |      11     |    150 ~ 2450   |
+----------+-------------+-----------------+
|          |       0     |      0 ~  750   |
|          +-------------+-----------------+
|          |       2.5   |      0 ~ 1050   |
| ESP32-S2 +-------------+-----------------+
|          |       6     |      0 ~ 1300   |
|          +-------------+-----------------+
|          |      11     |      0 ~ 2500   |
+----------+-------------+-----------------+

For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.

Note

This function also configures the input GPIO pin mux to connect it to the ADC2 channel. It must be called before calling adc2_get_raw() for this channel.

Note

For any given channel, this function must be called before the first time adc2_get_raw() is called for that channel.

Return

• ESP_OK success

• ESP_ERR_INVALID_ARG Parameter error

Parameters
• channel: ADC2 channel to configure

• atten: Attenuation level

Note

ESP32: When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue. As a workaround, call adc_power_acquire() in the app. This will result in higher power consumption (by ~1mA), but will remove the glitches on GPIO36 and GPIO39.

Note

ESP32: For a given channel, adc2_config_channel_atten() must be called before the first time this function is called. If Wi-Fi is started via esp_wifi_start(), this function will always fail with ESP_ERR_TIMEOUT.

Note

ESP32-S2: ADC2 support hardware arbiter. The arbiter is to improve the use efficiency of ADC2. After the control right is robbed by the high priority, the low priority controller will read the invalid ADC2 data. Default priority: Wi-Fi > RTC > Digital;

Return

• ESP_OK if success

• ESP_ERR_TIMEOUT ADC2 is being used by other controller and the request timed out.

• ESP_ERR_INVALID_STATE The controller status is invalid. Please try again.

Parameters

• width_bit: Bit capture width for ADC2

• raw_out: the variable to hold the output data.

This function routes the internal reference voltage of ADCn to one of ADC2’s channels. This reference voltage can then be manually measured for calibration purposes.

Note

ESP32 only supports output of ADC2’s internal reference voltage.

Return

• ESP_OK: v_ref successfully routed to selected GPIO

• ESP_ERR_INVALID_ARG: Unsupported GPIO

Parameters

• [in] gpio: GPIO number (Only ADC2’s channels IO are supported)

This function routes the internal reference voltage of ADCn to one of ADC2’s channels. This reference voltage can then be manually measured for calibration purposes.

Return

• ESP_OK: v_ref successfully routed to selected GPIO

• ESP_ERR_INVALID_ARG: Unsupported GPIO

Parameters
• [in] gpio: GPIO number (ADC2’s channels are supported)

Return

• ESP_OK Success

Return

• ESP_OK Success

Setting the digital controller.

Return

• ESP_ERR_INVALID_STATE Driver state is invalid.

• ESP_ERR_INVALID_ARG If the combination of arguments is invalid.

• ESP_OK On success

Parameters

### Macros¶

Note

This definitions are only for being back-compatible

The default (max) bit width of the ADC of current version. You can also get the maximum bitwidth by SOC_ADC_MAX_BITWIDTH defined in soc_caps.h.

### Enumerations¶

Values:

Values:

ADC2 channel 0 is GPIO4 (ESP32), GPIO11 (ESP32-S2)

ADC2 channel 1 is GPIO0 (ESP32), GPIO12 (ESP32-S2)

ADC2 channel 2 is GPIO2 (ESP32), GPIO13 (ESP32-S2)

ADC2 channel 3 is GPIO15 (ESP32), GPIO14 (ESP32-S2)

ADC2 channel 4 is GPIO13 (ESP32), GPIO15 (ESP32-S2)

ADC2 channel 5 is GPIO12 (ESP32), GPIO16 (ESP32-S2)

ADC2 channel 6 is GPIO14 (ESP32), GPIO17 (ESP32-S2)

ADC2 channel 7 is GPIO27 (ESP32), GPIO18 (ESP32-S2)

ADC2 channel 8 is GPIO25 (ESP32), GPIO19 (ESP32-S2)

ADC2 channel 9 is GPIO26 (ESP32), GPIO20 (ESP32-S2)

Values:

### Functions¶

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

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)

Parameters

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.

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

Parameters

• [in] atten: Attenuation to characterize

• [in] bit_width: Bit width configuration of ADC

• [in] default_vref: Default ADC reference voltage in mV (Only in ESP32, used if eFuse values is not available)

• [out] chars: Pointer to empty structure used to store ADC characteristics

Note

Characteristics structure must be initialized before this function is called (call esp_adc_cal_characterize())

Return

Voltage in mV

Parameters

• [in] chars: Pointer to initialized structure containing ADC characteristics

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())

Return

• ESP_ERR_INVALID_ARG: Error due to invalid arguments

Parameters

• [in] chars: Pointer to initialized ADC characteristics structure

• [out] voltage: Pointer to store converted voltage

### Structures¶

Structure storing characteristics of an ADC.

Note

Call esp_adc_cal_characterize() to initialize the structure

Public Members

uint32_t coeff_a

uint32_t coeff_b

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)

### Enumerations¶

Type of calibration value used in characterization.

Values:

Characterization based on reference voltage stored in eFuse

Characterization based on Two Point values stored in eFuse

Characterization based on default reference voltage