Merge branch 'docs/add_index_page_for_adc' into 'master'

docs: Add index page for ADC

See merge request espressif/esp-idf!40079

docs/en/api-reference/peripherals/adc/adc_calibration.rst

@@ -199,7 +199,7 @@ The {IDF_TARGET_NAME} ADC is sensitive to noise, leading to large discrepancies
 
 .. only:: esp32
 
-    .. figure:: ../../../_static/diagrams/adc/adc-noise-graph.jpg
+    .. figure:: ../../../../_static/diagrams/adc/adc-noise-graph.jpg
         :align: center
         :alt: ADC noise mitigation
 

docs/en/api-reference/peripherals/adc/adc_continuous.rst

@@ -3,14 +3,12 @@ Analog to Digital Converter (ADC) Continuous Mode Driver
 
 :link_to_translation:`zh_CN:[中文]`
 
-{IDF_TARGET_ADC_NUM:default="two", esp32c2="one", esp32c6="one", esp32h2="one", esp32c5="one", esp32c61="one"}
-
 Introduction
 ------------
 
 The Analog to Digital Converter is integrated on the chip and is capable of measuring analog signals from specific analog IO pads. Additionally, the Direct Memory Access (DMA) functionality is utilized to efficiently retrieve ADC conversion results.
 
-{IDF_TARGET_NAME} has {IDF_TARGET_ADC_NUM} ADC unit(s), which can be used in scenarios like:
+{IDF_TARGET_NAME} has {IDF_TARGET_SOC_ADC_PERIPH_NUM} ADC unit(s), which can be used in scenarios like:
 
 - Generate one-shot ADC conversion result
 - Generate continuous ADC conversion results

docs/en/api-reference/peripherals/adc/adc_oneshot.rst

@@ -8,7 +8,7 @@ Introduction
 
 The Analog to Digital Converter is integrated on the chip and is capable of measuring analog signals from specific analog IO pins.
 
-{IDF_TARGET_NAME} has {SOC_ADC_PERIPH_NUM} ADC unit(s), which can be used in scenario(s) like:
+{IDF_TARGET_NAME} has {IDF_TARGET_SOC_ADC_PERIPH_NUM} ADC unit(s), which can be used in scenario(s) like:
 
 .. list::
 
@@ -194,11 +194,10 @@ Thread Safety
 - :cpp:func:`adc_oneshot_new_unit`
 - :cpp:func:`adc_oneshot_config_channel`
 - :cpp:func:`adc_oneshot_read`
+- :cpp:func:`adc_oneshot_del_unit`
 
 Above functions are guaranteed to be thread-safe. Therefore, you can call them from different RTOS tasks without protection by extra locks.
 
-- :cpp:func:`adc_oneshot_del_unit` is not thread-safe. Besides, concurrently calling this function may result in failures of the above thread-safe APIs.
-
 
 .. _adc-oneshot-kconfig-options:
 
@@ -217,5 +216,4 @@ Application Examples
 API Reference
 -------------
 
-.. include-build-file:: inc/adc_types.inc
 .. include-build-file:: inc/adc_oneshot.inc

docs/en/api-reference/peripherals/adc/index.rst

@@ -0,0 +1,102 @@
+Analog to Digital Converter (ADC)
+=================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Overview
+--------
+
+This guide provides a comprehensive overview of the ADC (Analog to Digital Converter) controller on {IDF_TARGET_NAME}. 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.
+
+{IDF_TARGET_NAME} integrates {IDF_TARGET_SOC_ADC_PERIPH_NUM} 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 <{IDF_TARGET_DATASHEET_EN_URL}>`__.
+
+
+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 (2\ :sup:`12`) discrete levels, which defines the minimum detectable change in input signal.
+
+The voltage ``Vdata`` corresponding to a raw ADC result ``data`` is calculated as:
+
+.. math::
+
+    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 :doc:`adc_calibration`, 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:
+
+.. math::
+
+    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.
+
+.. only:: not esp32
+
+    For detailed input voltage ranges associated with each attenuation setting, refer to the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Electrical Characteristics > ADC Characteristics.
+
+.. only:: esp32
+
+    For detailed input voltage ranges associated with each attenuation setting, refer to the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Function Description > Analog Peripherals > Analog-to-Digital Converter (ADC).
+
+Driver Usage
+------------
+
+.. list::
+
+    - ADC unit supports **oneshot mode**. Oneshot mode is suitable for oneshot sampling: ADC samples one channel at a time.
+    :SOC_ADC_DMA_SUPPORTED: - 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:
+
+.. toctree::
+    :maxdepth: 2
+
+    adc_oneshot
+    :SOC_ADC_DMA_SUPPORTED: adc_continuous
+
+
+ADC Calibration
+----------------
+
+The ADC calibration driver corrects deviations through software to obtain more accurate output results.
+
+For more information, refer to the following guide:
+
+.. toctree::
+    :maxdepth: 2
+
+    adc_calibration
+
+API Reference
+-------------
+
+.. include-build-file:: inc/adc_channel.inc
+.. include-build-file:: inc/adc_types.inc

docs/en/api-reference/peripherals/index.rst

@@ -6,9 +6,7 @@ Peripherals API
 .. toctree::
     :maxdepth: 1
 
-    :SOC_ADC_SUPPORTED: adc_oneshot
-    :SOC_ADC_DMA_SUPPORTED: adc_continuous
-    :SOC_ADC_SUPPORTED: adc_calibration
+    :SOC_ADC_SUPPORTED: adc/index
     :SOC_ANA_CMPR_SUPPORTED: ana_cmpr
     :SOC_BITSCRAMBLER_SUPPORTED: bitscrambler
     :SOC_MIPI_CSI_SUPPORTED: camera_driver