Analog to Digital Converter (ADC)

Overview

This guide provides a comprehensive overview of the ADC (Analog to Digital Converter) controller on ESP32-S31. It begins by introducing core ADC concepts such as conversion principles, raw data resolution, reference voltage, and attenuation. Then it walks through the two supported ADC driver modes — oneshot mode and continuous mode — along with ADC calibration, which helps improve accuracy.

ESP32-S31 integrates 2 ADC(s) for measuring analog signals from multiple input channels. For details about the number of measurement channels (analog-enabled pins), voltage ranges, and other ADC characteristics, please refer to the datasheet.

ADC Conversion

ADC conversion is the process of converting an input analog voltage to a digital value. On ESP32-S31, use adc_cali_chan_raw_to_voltage() to convert the results from adc_oneshot_read() and adc_continuous_read() into voltage in millivolts.

ADC Attenuation

ESP32-S31 supports only 0 dB attenuation. The single-ended input range is about -2 V to 2 V. For the corresponding analog IOs and electrical characteristics, refer to the datasheet.

Driver Usage

ADC unit supports oneshot mode. Oneshot mode is suitable for oneshot sampling: ADC samples one channel at a time.
Each ADC unit supports continuous mode. Continuous mode is designed for continuous sampling: ADC sequentially samples a group of channels or continuously samples a single channel.

See the guide below for implementation details:

ADC Calibration

The ADC calibration driver corrects deviations through software to obtain more accurate output results.

For more information, refer to the following guide:

Analog to Digital Converter (ADC) Calibration Driver

API Reference

Header File

components/soc/esp32s31/include/soc/adc_channel.h
This header file can be included with:
#include "soc/adc_channel.h"

Macros

ADC1_GPIO42_CHANNEL

ADC1_CHANNEL_0_GPIO_NUM

ADC1_GPIO43_CHANNEL

ADC1_CHANNEL_1_GPIO_NUM

ADC1_GPIO44_CHANNEL

ADC1_CHANNEL_2_GPIO_NUM

ADC1_GPIO45_CHANNEL

ADC1_CHANNEL_3_GPIO_NUM

ADC1_GPIO46_CHANNEL

ADC1_CHANNEL_4_GPIO_NUM

ADC1_GPIO47_CHANNEL

ADC1_CHANNEL_5_GPIO_NUM

ADC1_GPIO48_CHANNEL

ADC1_CHANNEL_6_GPIO_NUM

ADC1_GPIO49_CHANNEL

ADC1_CHANNEL_7_GPIO_NUM

ADC2_GPIO50_CHANNEL

ADC2_CHANNEL_0_GPIO_NUM

ADC2_GPIO51_CHANNEL

ADC2_CHANNEL_1_GPIO_NUM

ADC2_GPIO52_CHANNEL

ADC2_CHANNEL_2_GPIO_NUM

ADC2_GPIO53_CHANNEL

ADC2_CHANNEL_3_GPIO_NUM

ADC2_GPIO54_CHANNEL

ADC2_CHANNEL_4_GPIO_NUM

ADC2_GPIO55_CHANNEL

ADC2_CHANNEL_5_GPIO_NUM

ADC2_GPIO56_CHANNEL

ADC2_CHANNEL_6_GPIO_NUM

ADC2_GPIO57_CHANNEL

ADC2_CHANNEL_7_GPIO_NUM

Header File

components/esp_hal_ana_conv/include/hal/adc_types.h
This header file can be included with:
#include "hal/adc_types.h"
This header file is a part of the API provided by the esp_hal_ana_conv component. To declare that your component depends on esp_hal_ana_conv, add the following to your CMakeLists.txt:
REQUIRES esp_hal_ana_conv
or
PRIV_REQUIRES esp_hal_ana_conv

Structures

struct adc_digi_pattern_config_t

ADC digital controller pattern configuration.

Public Members

uint8_t atten: Attenuation of this ADC channel.

uint8_t channel: ADC channel.

uint8_t unit: ADC unit.

uint8_t bit_width: ADC output bit width.

Type Definitions

typedef soc_periph_adc_digi_clk_src_t adc_oneshot_clk_src_t: Clock source type of oneshot mode which uses digital controller.

typedef soc_periph_adc_digi_clk_src_t adc_continuous_clk_src_t: Clock source type of continuous mode which uses digital controller.

Enumerations

enum adc_unit_t

ADC unit.

Values:

enumerator ADC_UNIT_1: SAR ADC 1.

enumerator ADC_UNIT_2: SAR ADC 2.

enum adc_channel_t

ADC channels.

Values:

enumerator ADC_CHANNEL_0: ADC channel.

enumerator ADC_CHANNEL_1: ADC channel.

enumerator ADC_CHANNEL_2: ADC channel.

enumerator ADC_CHANNEL_3: ADC channel.

enumerator ADC_CHANNEL_4: ADC channel.

enumerator ADC_CHANNEL_5: ADC channel.

enumerator ADC_CHANNEL_6: ADC channel.

enumerator ADC_CHANNEL_7: ADC channel.

enumerator ADC_CHANNEL_8: ADC channel.

enumerator ADC_CHANNEL_9: ADC channel.

enumerator ADC_CHANNEL_10: ADC channel.

enum adc_atten_t

ADC attenuation parameter. Different parameters determine the range of the ADC.

Values:

enumerator ADC_ATTEN_DB_0: No input attenuation, ADC can measure up to approx.

enumerator ADC_ATTEN_DB_2_5: The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB.

enumerator ADC_ATTEN_DB_6: The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB.

enumerator ADC_ATTEN_DB_12: The input voltage of ADC will be attenuated extending the range of measurement by about 12 dB.

enum adc_bitwidth_t

ADC bitwidth.

Values:

enumerator ADC_BITWIDTH_DEFAULT: Default ADC output bits, max supported width will be selected.

enumerator ADC_BITWIDTH_9: ADC output width is 9Bit.

enumerator ADC_BITWIDTH_10: ADC output width is 10Bit.

enumerator ADC_BITWIDTH_11: ADC output width is 11Bit.

enumerator ADC_BITWIDTH_12: ADC output width is 12Bit.

enumerator ADC_BITWIDTH_13: ADC output width is 13Bit.

enum adc_ulp_mode_t

ADC ULP working mode.

This decides the controller that controls ADC when in low power mode. Set ADC_ULP_MODE_DISABLE for normal mode.

Values:

enumerator ADC_ULP_MODE_DISABLE: ADC ULP mode is disabled.

enumerator ADC_ULP_MODE_FSM: ADC is controlled by ULP FSM.

enumerator ADC_ULP_MODE_RISCV: ADC is controlled by ULP RISCV.

enum adc_digi_convert_mode_t

ADC digital controller (DMA mode) work mode.

Values:

enumerator ADC_CONV_SINGLE_UNIT_1: Only use ADC1 for conversion.

enumerator ADC_CONV_SINGLE_UNIT_2: Only use ADC2 for conversion.

enumerator ADC_CONV_BOTH_UNIT: Use Both ADC1 and ADC2 for conversion simultaneously.

enumerator ADC_CONV_ALTER_UNIT: Use both ADC1 and ADC2 for conversion by turn. e.g. ADC1 -> ADC2 -> ADC1 -> ADC2 .....

enum adc_digi_output_format_t

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

Values:

enumerator ADC_DIGI_OUTPUT_FORMAT_TYPE1: See adc_digi_output_data_t.type1

enumerator ADC_DIGI_OUTPUT_FORMAT_TYPE2: See adc_digi_output_data_t.type2

enum adc_digi_iir_filter_t

ADC IIR Filter ID.

Values:

enumerator ADC_DIGI_IIR_FILTER_0: Filter 0.

enumerator ADC_DIGI_IIR_FILTER_1: Filter 1.

enum adc_digi_iir_filter_coeff_t

IIR Filter Coefficient.

Values:

enumerator ADC_DIGI_IIR_FILTER_COEFF_2: The filter coefficient is 2.

enumerator ADC_DIGI_IIR_FILTER_COEFF_4: The filter coefficient is 4.

enumerator ADC_DIGI_IIR_FILTER_COEFF_8: The filter coefficient is 8.

enumerator ADC_DIGI_IIR_FILTER_COEFF_16: The filter coefficient is 16.

enumerator ADC_DIGI_IIR_FILTER_COEFF_32: The filter coefficient is 32.

enumerator ADC_DIGI_IIR_FILTER_COEFF_64: The filter coefficient is 64.

enum adc_monitor_id_t

ADC monitor (continuous mode) ID.

Values:

enumerator ADC_MONITOR_0: The monitor index 0.

enumerator ADC_MONITOR_1: The monitor index 1.

enum adc_monitor_mode_t

Monitor config/event mode type.

Values:

enumerator ADC_MONITOR_MODE_HIGH: ADC raw_result > threshold value, monitor interrupt will be generated.

enumerator ADC_MONITOR_MODE_LOW: ADC raw_result < threshold value, monitor interrupt will be generated.

Was this page helpful?

Thank you! We received your feedback.
If you have any comments, fill in Espressif Documentation Feedback Form.

We value your feedback.
Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.