# Analog to Digital Converter (ADC)

[中文]

## Overview

This guide provides a comprehensive overview of the ADC (Analog to Digital Converter) controller on ESP32. 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 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. The results provided by the ADC driver APIs are raw data values that represent the analog input in digital form.

By default, the bit width of these raw ADC results is 12 bits. This means the input voltage range is divided into 4096 (212) discrete levels, which defines the minimum detectable change in input signal.

The voltage `Vdata` corresponding to a raw ADC result `data` is calculated as:

\[V_{data} = \frac{data}{2^{bitwidth} - 1} \times V_{ref}\]

Where:

- `data` is the raw ADC result.

- `bitwidth` is the resolution of the ADC result (e.g., 12 bits).

- `Vref` is the ADC’s reference voltage.

By design, `Vref` is set to 1100 mV. However, due to manufacturing variations, the actual value may range between 1000 mV and 1200 mV depending on the chip.

To obtain calibrated and accurate voltage values, refer to the section Analog to Digital Converter (ADC) Calibration Driver, which explains how to use the ADC calibration driver to adjust the raw results based on the actual `Vref` value.

## ADC Attenuation

The ADC can measure analog voltages from 0 V to `Vref`. To measure higher voltages, input signals can be attenuated before being passed to the ADC.

The supported attenuation levels are:

- 0 dB (k≈100%)

- 2.5 dB (k≈75%)

- 6 dB (k≈50%)

- 12 dB (k≈25%)

Higher attenuation levels allow the ADC to measure higher input voltages. The voltage `Vdata` after applying attenuation can be calculated using:

\[V_{data} = \frac{V_{ref}}{k}\times{\frac{data}{2^{bitwidth} - 1}}\]

Where:

- `k` is the ratio value corresponding to the attenuation level.

- Other variables are as defined above.

For detailed input voltage ranges associated with each attenuation setting, refer to the datasheet > Function Description > Analog Peripherals > Analog-to-Digital Converter (ADC).

## 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:

- Analog to Digital Converter (ADC) Oneshot Mode Driver
  - Introduction
  - Functional Overview
  - Application Examples
  - API Reference
- Analog to Digital Converter (ADC) Continuous Mode Driver
  - Introduction
  - Driver Concepts
  - Functional Overview
  - Application Examples
  - API Reference

## 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
  - Introduction
  - Functional Overview
  - API Reference

## API Reference

### Header File

- components/soc/esp32/include/soc/adc_channel.h

- This header file can be included with:

  >     #include "soc/adc_channel.h"

### Macros

ADC1_GPIO36_CHANNEL

ADC1_CHANNEL_0_GPIO_NUM

ADC1_GPIO37_CHANNEL

ADC1_CHANNEL_1_GPIO_NUM

ADC1_GPIO38_CHANNEL

ADC1_CHANNEL_2_GPIO_NUM

ADC1_GPIO39_CHANNEL

ADC1_CHANNEL_3_GPIO_NUM

ADC1_GPIO32_CHANNEL

ADC1_CHANNEL_4_GPIO_NUM

ADC1_GPIO33_CHANNEL

ADC1_CHANNEL_5_GPIO_NUM

ADC1_GPIO34_CHANNEL

ADC1_CHANNEL_6_GPIO_NUM

ADC1_GPIO35_CHANNEL

ADC1_CHANNEL_7_GPIO_NUM

ADC2_GPIO4_CHANNEL

ADC2_CHANNEL_0_GPIO_NUM

ADC2_GPIO0_CHANNEL

ADC2_CHANNEL_1_GPIO_NUM

ADC2_GPIO2_CHANNEL

ADC2_CHANNEL_2_GPIO_NUM

ADC2_GPIO15_CHANNEL

ADC2_CHANNEL_3_GPIO_NUM

ADC2_GPIO13_CHANNEL

ADC2_CHANNEL_4_GPIO_NUM

ADC2_GPIO12_CHANNEL

ADC2_CHANNEL_5_GPIO_NUM

ADC2_GPIO14_CHANNEL

ADC2_CHANNEL_6_GPIO_NUM

ADC2_GPIO27_CHANNEL

ADC2_CHANNEL_7_GPIO_NUM

ADC2_GPIO25_CHANNEL

ADC2_CHANNEL_8_GPIO_NUM

ADC2_GPIO26_CHANNEL

ADC2_CHANNEL_9_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_rtc_clk_src_t adc_oneshot_clk_src_t

  Clock source type of oneshot mode which uses RTC 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.