docs: Add index page for ADC

0cici · 0cici · commit c26a6f7830e5 · 2025-07-02T14:10:57.000+08:00
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -214,8 +214,13 @@
 
 DSLP_STUB_DOCS = ['api-guides/deep-sleep-stub.rst']
 
-ADC_DOCS = ['api-reference/peripherals/adc_oneshot.rst', 'api-reference/peripherals/adc_calibration.rst']
-ADC_DMA_DOCS = ['api-reference/peripherals/adc_continuous.rst']
+ADC_DOCS = [
+    'api-reference/peripherals/adc/index.rst',
+    'api-reference/peripherals/adc/adc_oneshot.rst',
+    'api-reference/peripherals/adc/adc_calibration.rst',
+]
+
+ADC_DMA_DOCS = ['api-reference/peripherals/adc/adc_continuous.rst']
 
 ANA_CMPR_DOCS = ['api-reference/peripherals/ana_cmpr.rst']
 
diff --git a/docs/en/api-reference/peripherals/adc/adc_calibration.rst b/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
 
diff --git a/docs/en/api-reference/peripherals/adc/adc_continuous.rst b/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
diff --git a/docs/en/api-reference/peripherals/adc/adc_oneshot.rst b/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
diff --git a/docs/en/api-reference/peripherals/adc/index.rst b/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
diff --git a/docs/en/api-reference/peripherals/index.rst b/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
diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt
@@ -27,6 +27,10 @@ api-reference/storage/spi_flash                 api-reference/peripherals/spi_fl
 api-reference/storage/spi_flash_concurrency     api-reference/peripherals/spi_flash/spi_flash_concurrency
 api-reference/storage/spi_flash_override_driver api-reference/peripherals/spi_flash/spi_flash_override_driver
 api-reference/storage/spi_flash_optional_feature    api-reference/peripherals/spi_flash/spi_flash_optional_feature
+api-reference/peripherals/adc_oneshot     /api-reference/peripherals/adc/adc_oneshot
+api-reference/peripherals/adc_continuous     api-reference/peripherals/adc/adc_continuous
+api-reference/peripherals/adc_calibration     api-reference/peripherals/adc/adc_calibration
+api-reference/peripherals/adc     api-reference/peripherals/adc/index
 
 
 get-started/idf-monitor                         api-guides/tools/idf-monitor
diff --git a/docs/zh_CN/api-reference/peripherals/adc/adc_calibration.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_calibration.rst
@@ -199,7 +199,7 @@ ADC 校准驱动程序会提供 ADC 校准方案。对于驱动程序来说，
 
 .. only:: esp32
 
-    .. figure:: ../../../_static/diagrams/adc/adc-noise-graph.jpg
+    .. figure:: ../../../../_static/diagrams/adc/adc-noise-graph.jpg
         :align: center
         :alt: ADC 噪声抑制
 
diff --git a/docs/zh_CN/api-reference/peripherals/adc/adc_continuous.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_continuous.rst
@@ -3,14 +3,12 @@
 
 :link_to_translation:`en:[English]`
 
-{IDF_TARGET_ADC_NUM:default="两", esp32c2="一", esp32c6="一", esp32h2="一", esp32c5="一", esp32c61="一"}
-
 简介
 ------------
 
 {IDF_TARGET_NAME} 芯片集成了模数转换器 (ADC)，支持测量特定模拟 IO 管脚的模拟信号。此外，ADC 还支持直接内存访问 (DMA) 功能，高效获取 ADC 转换结果。
 
-{IDF_TARGET_NAME} 具有 {IDF_TARGET_ADC_NUM} 个 ADC 单元，可应用于以下场景：
+{IDF_TARGET_NAME} 具有 {IDF_TARGET_SOC_ADC_PERIPH_NUM} 个 ADC 单元，可应用于以下场景：
 
 - 生成单次 ADC 转换结果
 - 生成连续 ADC 转换结果
diff --git a/docs/zh_CN/api-reference/peripherals/adc/adc_oneshot.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_oneshot.rst
@@ -8,7 +8,7 @@
 
 模数转换器集成于芯片，支持测量特定模拟 IO 管脚的模拟信号。
 
-{IDF_TARGET_NAME} 有 {SOC_ADC_PERIPH_NUM} 个 ADC 单元，可以在以下场景使用：
+{IDF_TARGET_NAME} 有 {IDF_TARGET_SOC_ADC_PERIPH_NUM} 个 ADC 单元，可以在以下场景使用：
 
 .. list::
 
@@ -194,11 +194,10 @@ flash 写入/擦除、OTA 等原因都可能导致 cache 禁用，此时，默
 - :cpp:func:`adc_oneshot_new_unit`
 - :cpp:func:`adc_oneshot_config_channel`
 - :cpp:func:`adc_oneshot_read`
+- :cpp:func:`adc_oneshot_del_unit`
 
 上述函数均为线程安全，使用时，可以直接从不同的 RTOS 任务中调用以上函数，无需额外锁保护。
 
-- :cpp:func:`adc_oneshot_del_unit` 非线程安全。此外，与上文中线程安全的函数一起调用该函数时，可能导致线程安全函数的调用出错。
-
 
 .. _adc-oneshot-kconfig-options:
 
@@ -217,5 +216,4 @@ Kconfig 选项
 API 参考
 -------------
 
-.. include-build-file:: inc/adc_types.inc
 .. include-build-file:: inc/adc_oneshot.inc
diff --git a/docs/zh_CN/api-reference/peripherals/adc/index.rst b/docs/zh_CN/api-reference/peripherals/adc/index.rst
@@ -0,0 +1,102 @@
+模数转换器 (ADC)
+==================
+
+:link_to_translation:`en:[English]`
+
+概述
+----
+
+本指南介绍了 {IDF_TARGET_NAME} 的模数转换器 (ADC)。首先介绍 ADC 核心概念，如 ADC 转换、原始数据分辨率、参考电压和衰减配置，随后详细讲解两种支持的驱动模式：单次转换模式和连续转换模式，以及用于提升精度的 ADC 校准功能。
+
+{IDF_TARGET_NAME} 集成了 {IDF_TARGET_SOC_ADC_PERIPH_NUM} 个 ADC，用于测量多路输入通道的模拟信号。具体测量通道数（支持模拟功能的引脚）、电压范围和 ADC 特性，请参阅 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
+
+ADC 转换
+----------
+
+ADC 转换是将输入的模拟电压转换为数字值的过程。ADC 驱动 API 提供的原始转换结果是以数字形式反映模拟输入信号。
+
+默认情况下，ADC 原始转换结果的位宽为 12 位，这意味着输入电压范围被划分为 4096 (2\ :sup:`12`) 个离散电平，由此定义了输入信号的最小可检测变化量。
+
+根据原始值 ``data`` 计算对应电压值 ``Vdata`` 的公式如下：
+
+.. math::
+
+    V_{data} = \frac{data}{2^{bitwidth} - 1} \times V_{ref}
+
+其中：
+
+- ``data`` 是 ADC 原始数据
+- ``bitwidth`` 是 ADC 原始数据的分辨率（如 12 位）
+- ``Vref`` 是 ADC 参考电压
+
+
+设计上，``Vref`` 出厂设定为 1100 mV，但由于制造差异，实际值可能在 1000 mV 到 1200 mV 之间波动。
+
+请参阅 :doc:`adc_calibration` 了解如何利用 ADC 校准驱动以得到校准后的准确电压值。
+
+
+ADC 衰减
+----------
+
+ADC 可以测量 0 V 到 ``Vref`` 范围内的模拟电压。如需测量更高电压，可以在输入 ADC 之前对输入电压进行衰减。
+
+支持的衰减等级包括：
+
+- 0 dB (k≈100%)
+- 2.5 dB (k≈75%)
+- 6 dB (k≈50%)
+- 12 dB (k≈25%)
+
+衰减等级越高，ADC 可测量的输入电压范围越大。应用衰减后的电压 ``Vdata`` 计算公式为：
+
+.. math::
+
+    V_{data} = \frac{V_{ref}}{k}\times{\frac{data}{2^{bitwidth} - 1}}
+
+其中：
+
+- ``k``：衰减参数对应的比例值
+- 其他变量定义同上
+
+.. only:: not esp32
+
+    各衰减配置对应的可测量输入电压范围，请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__ > 电气特性 > ADC 特性。
+
+.. only:: esp32
+
+    各衰减配置对应的可测量输入电压范围，请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__ > 模拟外设 > 模/数转换器 (ADC)。
+
+驱动使用
+------------
+
+.. list::
+
+    - 每个 ADC 单元支持 **单次转换模式**。该模式适用于单次采样：ADC 一次对一个通道进行采样。
+    :SOC_ADC_DMA_SUPPORTED: - 每个 ADC 单元支持 **连续转换模式**。该模式适用于连续采样：ADC 依次对一组通道进行采样，或者连续对单个通道进行采样。
+
+详见以下指南：
+
+.. toctree::
+    :maxdepth: 2
+
+    adc_oneshot
+    :SOC_ADC_DMA_SUPPORTED: adc_continuous
+
+
+ADC 校准功能
+-----------------
+
+ADC 校准驱动通过软件方式，修正偏差，获取更准确的输出结果。
+
+详见以下指南：
+
+.. toctree::
+    :maxdepth: 2
+
+    adc_calibration
+
+API 参考
+-------------
+
+.. include-build-file:: inc/adc_channel.inc
+.. include-build-file:: inc/adc_types.inc
diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst
@@ -6,9 +6,7 @@
 .. 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_CLK_TREE_SUPPORTED: clk_tree
