adc

[中文]

Overview

The adc peripheral describes an ESP-IDF ADC continuous or one-shot driver instance. BMGR converts adc entries in board_peripherals.yaml into periph_adc_config_t according to role, and creates a continuous or one-shot handle.

adc is commonly used for internal ADC audio input and ADC buttons. Continuous mode targets a persistent sampling data stream; one-shot mode targets on-demand reading of a single ADC channel.

Supported Operating Modes

adc differentiates operating modes by role. Continuous mode internally supports two configuration syntaxes: patterns and channel_list.

Minimal Configuration

Continuous: patterns Configuration

board_peripherals.yaml:

peripherals:
  - name: adc_audio_in
    type: adc
    role: continuous
    config:
      sample_freq_hz: 16000
      patterns:
        - unit: ADC_UNIT_1      # [TO_BE_CONFIRMED]
          channel: 0            # [TO_BE_CONFIRMED]
          atten: ADC_ATTEN_DB_12
          bit_width: ADC_BITWIDTH_DEFAULT

Continuous: Single Unit Configuration

board_peripherals.yaml:

peripherals:
  - name: adc_audio_in
    type: adc
    role: continuous
    config:
      sample_freq_hz: 16000
      unit_id: ADC_UNIT_1       # [TO_BE_CONFIRMED]
      channel_list: [0]         # [TO_BE_CONFIRMED]

oneshot

board_peripherals.yaml:

peripherals:
  - name: adc_oneshot
    type: adc
    role: oneshot
    config:
      unit_id: ADC_UNIT_1       # [TO_BE_CONFIRMED]
      channel_id: 4             # [TO_BE_CONFIRMED]

Mode Notes

Continuous mode creates an adc_continuous_handle_t. The patterns syntax can describe a complete adc_digi_pattern_config_t list; the channel_list syntax is used for one or more channels on the same ADC unit. The two syntaxes cannot be used simultaneously.

Oneshot mode creates an adc_oneshot_unit_handle_t and configures a single channel_id. ADC button devices reference a one-shot peripheral; when the internal ADC audio input needs to reuse a peripheral, it references a continuous peripheral.

The mapping of ADC channels to GPIOs depends on the target chip. The channel field in the template is marked as [TO_BE_CONFIRMED]; board configurations should verify this using the chip datasheet or the ESP-IDF ADC mapping API.

Full Field Reference

Continuous: patterns Configuration Full Fields

# ADC Peripheral Default Configuration
# This file provides commented default configurations used by the ADC peripheral parser.
# Based on periph_adc.py parsing script

# -----------------------------------------------------------------------------
# CONTINUOUS MODE (role: continuous)
# -----------------------------------------------------------------------------
- name: adc_continuous
  type: adc
  role: continuous
  config:
    # Max length of the conversion results that driver can store, in bytes. Default: 1024
    max_store_buf_size: 1024

    # Conversion frame size in bytes. Should be a multiple of 'SOC_ADC_DIGI_DATA_BYTES_PER_CONV' for your target. Default: 256
    conv_frame_size: 256

    # Flush internal pool when full. Default: 1
    flush_pool: 1

    # The expected ADC sampling frequency in Hz.
    # Please check the 'soc/soc_caps.h' for the valid values
    sample_freq_hz: 20000

    # ADC DMA output format. (default: ADC_DIGI_OUTPUT_FORMAT_TYPE2)
    format: ADC_DIGI_OUTPUT_FORMAT_TYPE2
    # Valid values:
    # - ADC_DIGI_OUTPUT_FORMAT_TYPE1
    # - ADC_DIGI_OUTPUT_FORMAT_TYPE2

    # Conversion mode for DMA operation.
    # If omitted, parser auto-derives:
    # - single_unit + unit1 => ADC_CONV_SINGLE_UNIT_1
    # - single_unit + unit2 => ADC_CONV_SINGLE_UNIT_2
    # - pattern mixed unit  => ADC_CONV_BOTH_UNIT
    conv_mode: ADC_CONV_SINGLE_UNIT_1
    # Valid values:
    # - ADC_CONV_SINGLE_UNIT_1
    # - ADC_CONV_SINGLE_UNIT_2
    # - ADC_CONV_BOTH_UNIT
    # - ADC_CONV_ALTER_UNIT

    # ADC pattern configuration
    patterns:
      - unit: ADC_UNIT_1  # [TO_BE_CONFIRMED] ADC unit, optional values are ADC_UNIT_1 and ADC_UNIT_2
        channel: 4        # [TO_BE_CONFIRMED] ADC channel used by this audio input path
                          # Use adc_continuous_io_to_channel() / adc_continuous_channel_to_io() to map IO to channel.
        # ADC attenuation. Different parameters determine the input range. (default: ADC_ATTEN_DB_0)
        # Valid values:
        # - ADC_ATTEN_DB_0
        # - ADC_ATTEN_DB_2_5
        # - ADC_ATTEN_DB_6
        # - ADC_ATTEN_DB_12
        # - ADC_ATTEN_DB_11 (deprecated on some targets)
        atten: ADC_ATTEN_DB_0
        # ADC raw output bit-width.
        # Valid values:
        # - ADC_BITWIDTH_9
        # - ADC_BITWIDTH_10
        # - ADC_BITWIDTH_11
        # - ADC_BITWIDTH_12
        # - ADC_BITWIDTH_13
        # - ADC_BITWIDTH_DEFAULT
        # - SOC_ADC_DIGI_MAX_BITWIDTH
        bit_width: SOC_ADC_DIGI_MAX_BITWIDTH

      # Example of a second pattern for another ADC unit (if supported by the target)
      - unit: ADC_UNIT_2
        channel: 0
        atten: ADC_ATTEN_DB_12
        bit_width: ADC_BITWIDTH_DEFAULT

Continuous: Single Unit Configuration Full Fields

# Single Unit configuration mode, simpler mode for single unit ADC path
- name: adc_continuous
  type: adc
  role: continuous
  config:
    max_store_buf_size: 1024
    conv_frame_size: 256
    flush_pool: 1
    sample_freq_hz: 20000
    format: ADC_DIGI_OUTPUT_FORMAT_TYPE2
    conv_mode: ADC_CONV_SINGLE_UNIT_1

    # Below are the single unit configuration parameters, alternative to patterns[]
    unit_id: ADC_UNIT_1  # [TO_BE_CONFIRMED] ADC unit, optional values are ADC_UNIT_1 and ADC_UNIT_2
    channel_list: [4]    # [TO_BE_CONFIRMED] List of ADC channels used by this audio input path.
    atten: ADC_ATTEN_DB_0
    bit_width: SOC_ADC_DIGI_MAX_BITWIDTH

oneshot Full Fields

# -----------------------------------------------------------------------------
# ONE-SHOT MODE (role: oneshot)
# -----------------------------------------------------------------------------
- name: adc_oneshot
  type: adc
  role: oneshot
  config:
    # ADC unit, optional values are ADC_UNIT_1 and ADC_UNIT_2, should be less than 'SOC_ADC_PERIPH_NUM'
    # please check the 'SOC_ADC_PERIPH_NUM' in 'soc/soc_caps.h' for the valid values
    unit_id: ADC_UNIT_1  # [TO_BE_CONFIRMED] ADC unit ID

    # ADC attenuation. Different parameters determine the range of the ADC. (default: ADC_ATTEN_DB_0)
    atten: ADC_ATTEN_DB_0
    # Valid values:
    # - ADC_ATTEN_DB_0
    # - ADC_ATTEN_DB_2_5
    # - ADC_ATTEN_DB_6
    # - ADC_ATTEN_DB_12
    # - ADC_ATTEN_DB_11 (deprecated)

    # ADC raw output bitwidth. (default: ADC_BITWIDTH_DEFAULT)
    bit_width: ADC_BITWIDTH_DEFAULT
    # Valid values:
    # - ADC_BITWIDTH_9
    # - ADC_BITWIDTH_10
    # - ADC_BITWIDTH_11
    # - ADC_BITWIDTH_12
    # - ADC_BITWIDTH_13
    # - ADC_BITWIDTH_DEFAULT (Default ADC output bits, max supported width will be selected)

    # ADC channel to be used.
    # Use adc_oneshot_io_to_channel() and adc_oneshot_channel_to_io() to get the corresponding relationship between ADC channels and ADC IO.
    channel_id: 4                      # [TO_BE_CONFIRMED] ADC channel ID

    # Clock source for ADC module.
    # Please refer to soc/clk_tree_defs.h, see 'soc_periph_adc_digi_clk_src_t' for valid values
    clk_src: ADC_RTC_CLK_SRC_DEFAULT

    # ULP mode selection. (default: ADC_ULP_MODE_DISABLE)
    ulp_mode: ADC_ULP_MODE_DISABLE
    # Valid values:
    # - ADC_ULP_MODE_DISABLE
    # - ADC_ULP_MODE_FSM
    # - ADC_ULP_MODE_RISCV
    # - ADC_ULP_MODE_LP_CORE

Applicable Devices

device type

Usage

Description

audio_codec

Internal ADC audio input reuses an ADC peripheral with role: continuous

audio_codec also supports a device-local adc_local_cfg; this path does not require declaring a reusable ADC peripheral

button

sub_type: adc_single or sub_type: adc_multi references an ADC peripheral with role: oneshot

Voltage ranges, button count, and event configuration are written in the button device

Reference Code

  • esp_board_manager/peripherals/periph_adc/periph_adc.c

  • esp_board_manager/peripherals/periph_adc/periph_adc.h

  • esp_board_manager/examples/record_to_sdcard/main/record_to_sdcard.c

  • esp_board_manager/examples/record_and_play/main/record_and_play.c

Board Examples

  • esp_board_manager/boards/esp32_c3_lyra/board_peripherals.yaml: Internal ADC audio input using a continuous peripheral.

  • esp_board_manager/boards/esp32_s3_korvo2l/board_peripherals.yaml: ADC button using a one-shot peripheral.

  • esp_board_manager/boards/esp32_s3_korvo2_v3/board_peripherals.yaml: ADC button using a one-shot peripheral.

  • esp_board_manager/boards/lyrat_mini_v1_1/board_peripherals.yaml: ADC button using a one-shot peripheral.

Notes

  • Common YAML field rules: see YAML Conventions and Syntax.

  • Continuous mode must configure either patterns or channel_list, but not both simultaneously.

  • If pattern_num is explicitly configured, it must equal the number of valid entries in patterns or channel_list.

  • conv_mode must match the ADC unit combination. Use ADC_CONV_SINGLE_UNIT_1 for a single ADC_UNIT_1, ADC_CONV_SINGLE_UNIT_2 for a single ADC_UNIT_2; mixed units cannot use single-unit conversion mode.

  • The mapping of ADC channels to GPIOs depends on the target chip. After modifying ADC peripheral configuration, re-run idf.py bmgr -b <board>.

Debugging Tips

API Reference

Use esp_board_manager_get_periph_handle() to obtain the ADC peripheral handle. The handle type is periph_adc_handle_t:

typedef union {
    adc_continuous_handle_t    continuous;  /*!< Continuous-mode handle */
    adc_oneshot_unit_handle_t  oneshot;     /*!< One-shot unit handle */
} periph_adc_handle_t;

continuous is valid in continuous sampling mode, and oneshot is valid in one-shot sampling mode; the two are mutually exclusive, determined by the role field configured in board_peripherals.yaml.

The relevant declarations are in esp_board_manager/peripherals/periph_adc/periph_adc.h.

Underlying ESP-IDF driver documentation: ADC One-Shot Conversion Mode, ADC Continuous Conversion Mode.

Was this page helpful?