From c26a6f7830e530a23615472f0cc190f053c27161 Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Tue, 24 Jun 2025 14:48:32 +0800 Subject: [PATCH] docs: Add index page for ADC --- docs/conf_common.py | 9 +- .../peripherals/{ => adc}/adc_calibration.rst | 2 +- .../peripherals/{ => adc}/adc_continuous.rst | 4 +- .../peripherals/{ => adc}/adc_oneshot.rst | 6 +- .../api-reference/peripherals/adc/index.rst | 102 ++++++++++++++++++ docs/en/api-reference/peripherals/index.rst | 4 +- docs/page_redirects.txt | 4 + .../peripherals/{ => adc}/adc_calibration.rst | 2 +- .../peripherals/{ => adc}/adc_continuous.rst | 4 +- .../peripherals/{ => adc}/adc_oneshot.rst | 6 +- .../api-reference/peripherals/adc/index.rst | 102 ++++++++++++++++++ .../zh_CN/api-reference/peripherals/index.rst | 4 +- 12 files changed, 225 insertions(+), 24 deletions(-) rename docs/en/api-reference/peripherals/{ => adc}/adc_calibration.rst (99%) rename docs/en/api-reference/peripherals/{ => adc}/adc_continuous.rst (99%) rename docs/en/api-reference/peripherals/{ => adc}/adc_oneshot.rst (97%) create mode 100644 docs/en/api-reference/peripherals/adc/index.rst rename docs/zh_CN/api-reference/peripherals/{ => adc}/adc_calibration.rst (99%) rename docs/zh_CN/api-reference/peripherals/{ => adc}/adc_continuous.rst (99%) rename docs/zh_CN/api-reference/peripherals/{ => adc}/adc_oneshot.rst (96%) create mode 100644 docs/zh_CN/api-reference/peripherals/adc/index.rst diff --git a/docs/conf_common.py b/docs/conf_common.py index fffec165d3..972805f610 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -214,8 +214,13 @@ ISP_DOCS = ['api-reference/peripherals/isp.rst'] 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_calibration.rst b/docs/en/api-reference/peripherals/adc/adc_calibration.rst similarity index 99% rename from docs/en/api-reference/peripherals/adc_calibration.rst rename to docs/en/api-reference/peripherals/adc/adc_calibration.rst index 0409cbc338..cbc707dd46 100644 --- a/docs/en/api-reference/peripherals/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_continuous.rst b/docs/en/api-reference/peripherals/adc/adc_continuous.rst similarity index 99% rename from docs/en/api-reference/peripherals/adc_continuous.rst rename to docs/en/api-reference/peripherals/adc/adc_continuous.rst index 2c4d7698d4..be0e3d1935 100644 --- a/docs/en/api-reference/peripherals/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_oneshot.rst b/docs/en/api-reference/peripherals/adc/adc_oneshot.rst similarity index 97% rename from docs/en/api-reference/peripherals/adc_oneshot.rst rename to docs/en/api-reference/peripherals/adc/adc_oneshot.rst index 24fee32be5..f4039f3288 100644 --- a/docs/en/api-reference/peripherals/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 new file mode 100644 index 0000000000..c95b8d6864 --- /dev/null +++ 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 index 487e64081a..265b7d6082 100644 --- 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 index f566d25354..6e6ed04b85 100644 --- 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_calibration.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_calibration.rst similarity index 99% rename from docs/zh_CN/api-reference/peripherals/adc_calibration.rst rename to docs/zh_CN/api-reference/peripherals/adc/adc_calibration.rst index d9244158c8..384c8b7859 100644 --- a/docs/zh_CN/api-reference/peripherals/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_continuous.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_continuous.rst similarity index 99% rename from docs/zh_CN/api-reference/peripherals/adc_continuous.rst rename to docs/zh_CN/api-reference/peripherals/adc/adc_continuous.rst index 154241eb5d..4bd3b47a6a 100644 --- a/docs/zh_CN/api-reference/peripherals/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_oneshot.rst b/docs/zh_CN/api-reference/peripherals/adc/adc_oneshot.rst similarity index 96% rename from docs/zh_CN/api-reference/peripherals/adc_oneshot.rst rename to docs/zh_CN/api-reference/peripherals/adc/adc_oneshot.rst index 8365bb49e9..5460de580e 100644 --- a/docs/zh_CN/api-reference/peripherals/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 new file mode 100644 index 0000000000..2c5954d1ee --- /dev/null +++ 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 index 1ab96fe457..36806bb110 100644 --- 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