From ff6b85bdb1a875ddc78fdf7f49ce5dd15b4e51f4 Mon Sep 17 00:00:00 2001 From: caixinying-git Date: Tue, 22 Aug 2023 15:26:01 +0800 Subject: [PATCH] docs: provide CN translation for api-reference/peripherals/adc_oneshot.rst --- .../api-reference/peripherals/adc_oneshot.rst | 121 +++++---- .../api-reference/peripherals/adc_oneshot.rst | 241 +++++++++++++++++- 2 files changed, 313 insertions(+), 49 deletions(-) diff --git a/docs/en/api-reference/peripherals/adc_oneshot.rst b/docs/en/api-reference/peripherals/adc_oneshot.rst index b75e9ee451..74c08471e0 100644 --- a/docs/en/api-reference/peripherals/adc_oneshot.rst +++ b/docs/en/api-reference/peripherals/adc_oneshot.rst @@ -1,12 +1,14 @@ Analog to Digital Converter (ADC) Oneshot Mode Driver ===================================================== +:link_to_translation:`zh_CN:[中文]` + {IDF_TARGET_ADC_NUM:default="two", esp32c2="one", esp32c6="one", esp32h2="one"} Introduction ------------ -The Analog to Digital Converter is an on-chip sensor which is able to measure analog signals from dedicated analog IO pads. +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 {IDF_TARGET_ADC_NUM} ADC unit(s), which can be used in scenario(s) like: @@ -16,7 +18,7 @@ The Analog to Digital Converter is an on-chip sensor which is able to measure an - Generate continuous ADC conversion results -This guide will introduce ADC oneshot mode conversion. +This guide introduces ADC oneshot mode conversion. Functional Overview @@ -24,39 +26,39 @@ Functional Overview The following sections of this document cover the typical steps to install and operate an ADC: -- `Resource Allocation <#resource-allocation>`__ - covers which parameters should be set up to get an ADC handle and how to recycle the resources when ADC finishes working. -- `Unit Configuration <#unit-configuration>`__ - covers the parameters that should be set up to configure the ADC unit, so as to get ADC conversion raw result. -- `Read Conversion Result <#read-conversion-result>`__ - covers how to get ADC conversion raw result. -- `Hardware Limitations <#hardware-limitations>`__ - describes the ADC related hardware limitations. -- `Power Management <#power-management>`__ - covers power management related. -- `IRAM Safe <#iram-safe>`__ - describes tips on how to read ADC conversion raw result when cache is disabled. -- `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver. -- `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can be used to make a different effect on driver behavior. +- :ref:`adc-oneshot-resource-allocation` - covers which parameters should be set up to get an ADC handle and how to recycle the resources when ADC finishes working. +- :ref:`adc-oneshot-unit-configuration` - covers the parameters that should be set up to configure the ADC unit, so as to get ADC conversion raw result. +- :ref:`adc-oneshot-read-conversion-result` - covers how to get ADC conversion raw result. +- :ref:`hardware_limitations_adc_oneshot` - describes the ADC-related hardware limitations. +- :ref:`adc-oneshot-power-management` - covers power management-related information. +- :ref:`adc-oneshot-iram-safe` - describes tips on how to read ADC conversion raw results when the cache is disabled. +- :ref:`adc-oneshot-thread-safety` - lists which APIs are guaranteed to be thread-safe by the driver. +- :ref:`adc-oneshot-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior. +.. _adc-oneshot-resource-allocation: Resource Allocation ^^^^^^^^^^^^^^^^^^^ -The ADC oneshot mode driver is implemented based on {IDF_TARGET_NAME} SAR ADC module. Different ESP chips might have different number of independent ADCs. From oneshot mode driver's point of view, an ADC instance is represented by :cpp:type:`adc_oneshot_unit_handle_t`. +The ADC oneshot mode driver is implemented based on {IDF_TARGET_NAME} SAR ADC module. Different ESP chips might have different numbers of independent ADCs. From the oneshot mode driver's point of view, an ADC instance is represented by :cpp:type:`adc_oneshot_unit_handle_t`. To install an ADC instance, set up the required initial configuration structure :cpp:type:`adc_oneshot_unit_init_cfg_t`: -- :cpp:member:`adc_oneshot_unit_init_cfg_t::unit_id` selects the ADC. Please refer to the `datasheet <{IDF_TARGET_TRM_EN_URL}>`__ to know dedicated analog IOs for this ADC. -- :cpp:member:`adc_oneshot_unit_init_cfg_t::clk_src` selects the source clock of the ADC. If it's set to 0, driver will fallback to use a default clock source, see :cpp:type:`adc_oneshot_clk_src_t` to know the details. -- :cpp:member:`adc_oneshot_unit_init_cfg_t::ulp_mode` sets if the ADC will be working under ULP mode. +- :cpp:member:`adc_oneshot_unit_init_cfg_t::unit_id` selects the ADC. Please refer to the `datasheet <{IDF_TARGET_TRM_EN_URL}>`__ to know dedicated analog IOs for this ADC. +- :cpp:member:`adc_oneshot_unit_init_cfg_t::clk_src` selects the source clock of the ADC. If set to 0, the driver will fall back to using a default clock source, see :cpp:type:`adc_oneshot_clk_src_t` to know the details. +- :cpp:member:`adc_oneshot_unit_init_cfg_t::ulp_mode` sets if the ADC will be working under ULP mode. .. todo:: - Add ULP ADC related docs here. + Add ULP ADC-related docs here. -After setting up the initial configurations for the ADC, call :cpp:func:`adc_oneshot_new_unit` with the prepared :cpp:type:`adc_oneshot_unit_init_cfg_t`. This function will return an ADC unit handle, if the allocation is successful. +After setting up the initial configurations for the ADC, call :cpp:func:`adc_oneshot_new_unit` with the prepared :cpp:type:`adc_oneshot_unit_init_cfg_t`. This function will return an ADC unit handle if the allocation is successful. -This function may fail due to various errors such as invalid argumemts, insufficient memory, etc. Specifically, when the to-be-allocated ADC instance is registered already, this function will return :c:macro:`ESP_ERR_NOT_FOUND` error. Number of available ADC(s) is recorded by :c:macro:`SOC_ADC_PERIPH_NUM`. +This function may fail due to various errors such as invalid arguments, insufficient memory, etc. Specifically, when the to-be-allocated ADC instance is registered already, this function will return :c:macro:`ESP_ERR_NOT_FOUND` error. Number of available ADC(s) is recorded by :c:macro:`SOC_ADC_PERIPH_NUM`. -If a previously created ADC instance is no loger required, you should recycle the ADC instance by calling :cpp:func:`adc_oneshot_del_unit`, related hardware and software resources will be recycled as well. +If a previously created ADC instance is no longer required, you should recycle the ADC instance by calling :cpp:func:`adc_oneshot_del_unit`, related hardware and software resources will be recycled as well. - -Create an ADC Unit Handle under Normal Oneshot Mode +Create an ADC Unit Handle Under Normal Oneshot Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: c @@ -77,21 +79,23 @@ Recycle the ADC Unit ESP_ERROR_CHECK(adc_oneshot_del_unit(adc1_handle)); +.. _adc-oneshot-unit-configuration: + Unit Configuration ^^^^^^^^^^^^^^^^^^ After an ADC instance is created, set up the :cpp:type:`adc_oneshot_chan_cfg_t` to configure ADC IOs to measure analog signal: -- :cpp:member:`adc_oneshot_chan_cfg_t::atten`, ADC attenuation. Refer to the On-Chip Sensor chapter in `TRM <{IDF_TARGET_TRM_EN_URL}>`__. -- :cpp:member:`adc_oneshot_chan_cfg_t::bitwidth`, the bitwidth of the raw conversion result. +- :cpp:member:`adc_oneshot_chan_cfg_t::atten`, ADC attenuation. Refer to `TRM <{IDF_TARGET_TRM_EN_URL}>`__ > ``On-Chip Sensor and Analog Signal Processing``. +- :cpp:member:`adc_oneshot_chan_cfg_t::bitwidth`, the bitwidth of the raw conversion result. .. note:: - For the IO corresponding ADC channel number. Check `datasheet <{IDF_TARGET_TRM_EN_URL}>`__ to know the ADC IOs. - On the other hand, :cpp:func:`adc_continuous_io_to_channel` and :cpp:func:`adc_continuous_channel_to_io` can be used to know the ADC channels and ADC IOs. + For the IO corresponding ADC channel number, check `datasheet <{IDF_TARGET_TRM_EN_URL}>`__ to know the ADC IOs. -To make these settings take effect, call :cpp:func:`adc_oneshot_config_channel` with above configuration structure. You should specify an ADC channel to be configured as well. -This function (:cpp:func:`adc_oneshot_config_channel`) can be called multiple times to configure different ADC channels. The Driver will save each of these channel configurations internally. + Additionally, :cpp:func:`adc_continuous_io_to_channel` and :cpp:func:`adc_continuous_channel_to_io` can be used to know the ADC channels and ADC IOs. + +To make these settings take effect, call :cpp:func:`adc_oneshot_config_channel` with the above configuration structure. You should specify an ADC channel to be configured as well. Function :cpp:func:`adc_oneshot_config_channel` can be called multiple times to configure different ADC channels. The Driver will save each of these channel configurations internally. Configure Two ADC Channels @@ -107,16 +111,18 @@ Configure Two ADC Channels ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN1, &config)); +.. _adc-oneshot-read-conversion-result: + Read Conversion Result ^^^^^^^^^^^^^^^^^^^^^^ After above configurations, the ADC is ready to measure the analog signal(s) from the configured ADC channel(s). Call :cpp:func:`adc_oneshot_read` to get the conversion raw result of an ADC channel. -- :cpp:func:`adc_oneshot_read` is safe to use. ADC(s) are shared by some other drivers / peripherals, see `Hardware Limitations <#hardware-limitations>`__. This function uses mutexes to avoid concurrent hardware usage. Therefore, this function should not be used in an ISR context. This function may fail when the ADC is in use by other drivers / peripherals, and return :c:macro:`ESP_ERR_TIMEOUT`. Under this condition, the ADC raw result is invalid. +- :cpp:func:`adc_oneshot_read` is safe to use. ADC(s) are shared by some other drivers/peripherals, see :ref:`hardware_limitations_adc_oneshot`. This function uses mutexes to avoid concurrent hardware usage. Therefore, this function should not be used in an ISR context. This function may fail when the ADC is in use by other drivers/peripherals, and return :c:macro:`ESP_ERR_TIMEOUT`. Under this condition, the ADC raw result is invalid. -These two functions will both fail due to invalid arguments. +This function will fail due to invalid arguments. -The ADC conversion results read from these two functions are raw data. To calculate the voltage based on the ADC raw results, this formula can be used: +The ADC conversion results read from this function are raw data. To calculate the voltage based on the ADC raw results, this formula can be used: .. parsed-literal:: @@ -124,14 +130,21 @@ The ADC conversion results read from these two functions are raw data. To calcul where: -====== ============================================================= -Vout Digital output result, standing for the voltage. -Dout ADC raw digital reading result. -Vmax Maximum measurable input analog voltage, this is related to the ADC attenuation, please refer to the On-Chip Sensor chapter in `TRM <{IDF_TARGET_TRM_EN_URL}>`__. -Dmax Maximum of the output ADC raw digital reading result, which is 2^bitwidth, where bitwidth is the :cpp:member::`adc_oneshot_chan_cfg_t:bitwidth` configured before. -====== ============================================================= +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :align: center -To do further calbration to convert the ADC raw result to voltage in mV, please refer to calibration doc :doc:`adc_calibration`. + * - Vout + - Digital output result, standing for the voltage. + * - Dout + - ADC raw digital reading result. + * - Vmax + - Maximum measurable input analog voltage, this is related to the ADC attenuation, please refer to `TRM <{IDF_TARGET_TRM_EN_URL}>`__ > ``On-Chip Sensor and Analog Signal Processing``. + * - Dmax + - Maximum of the output ADC raw digital reading result, which is 2^bitwidth, where bitwidth is the :cpp:member::`adc_oneshot_chan_cfg_t:bitwidth` configured before. + +To do further calibration to convert the ADC raw result to voltage in mV, please refer to calibration doc :doc:`adc_calibration`. Read Raw Result @@ -145,12 +158,13 @@ Read Raw Result ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN1, &adc_raw[0][1])); ESP_LOGI(TAG, "ADC%d Channel[%d] Raw Data: %d", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN1, adc_raw[0][1]); + .. _hardware_limitations_adc_oneshot: Hardware Limitations ^^^^^^^^^^^^^^^^^^^^ -- Random Number Generator uses ADC as a input source. When ADC :cpp:func:`adc_oneshot_read` works, the random number generated from RNG will be less random. +- Random Number Generator (RNG) uses ADC as an input source. When ADC :cpp:func:`adc_oneshot_read` works, the random number generated from RNG will be less random. .. only:: SOC_ADC_DMA_SUPPORTED @@ -158,43 +172,54 @@ Hardware Limitations .. only:: esp32 or esp32s2 or esp32s3 - - ADC2 is also used by the Wi-Fi. :cpp:func:`adc_oneshot_read` has provided the protection between Wi-Fi driver and ADC oneshot mode driver. + - ADC2 is also used by Wi-Fi. :cpp:func:`adc_oneshot_read` has provided protection between the Wi-Fi driver and ADC oneshot mode driver. .. only:: esp32c3 - - ADC2 oneshot mode is no longer supported, due to hardware limitation. The results are not stable. This issue can be found in `ESP32C3 Errata `_. For compatibility, you can enable :ref:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3` to force use ADC2. + - ADC2 oneshot mode is no longer supported, due to hardware limitations. The results are not stable. This issue can be found in `ESP32-C3 Series SoC Errata `_. For compatibility, you can enable :ref:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3` to force use ADC2. .. only:: esp32 - - ESP32 DevKitC: GPIO 0 cannot be used due to external auto program circuits. + - ESP32-DevKitC: GPIO0 cannot be used in oneshot mode, because the DevKit has used it for auto-flash. - - ESP-WROVER-KIT: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. + - ESP-WROVER-KIT: GPIO 0, 2, 4, and 15 cannot be used due to external connections for different purposes. + .. _adc-oneshot-power-management: + +.. only:: not esp32 + + .. _adc-oneshot-power-management: Power Management ^^^^^^^^^^^^^^^^ -When power management is enabled (i.e. :ref:`CONFIG_PM_ENABLE` is on), the system clock frequency may be adjusted when the system is in an idle state. However, the ADC oneshot mode driver works in a polling routine, the :cpp:func:`adc_oneshot_read` will poll the CPU until the function returns. During this period of time, the task in which ADC oneshot mode driver resides won't be blocked. Therefore the clock frequency is stable when reading. +When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the system clock frequency may be adjusted when the system is in an idle state. However, the ADC oneshot mode driver works in a polling routine, the :cpp:func:`adc_oneshot_read` will poll the CPU until the function returns. During this period of time, the task in which ADC oneshot mode driver resides will not be blocked. Therefore the clock frequency is stable when reading. +.. _adc-oneshot-iram-safe: + IRAM Safe ^^^^^^^^^ -By default, all the ADC oneshot mode driver APIs are not supposed to be run when the Cache is disabled (Cache may be disabled due to many reasons, such as Flash writing/erasing, OTA, etc.). If these APIs executes when the Cache is disabled, you will probably see errors like Illegal Instruction or Load/Store Prohibited. +By default, all the ADC oneshot mode driver APIs are not supposed to be run when the Cache is disabled. Cache may be disabled due to many reasons, such as Flash writing/erasing, OTA, etc. If these APIs execute when the Cache is disabled, you will probably see errors like ``Illegal Instruction`` or ``Load/Store Prohibited``. +.. _adc-oneshot-thread-safety: + Thread Safety ^^^^^^^^^^^^^ -- :cpp:func:`adc_oneshot_new_unit` -- :cpp:func:`adc_oneshot_config_channel` -- :cpp:func:`adc_oneshot_read` +- :cpp:func:`adc_oneshot_new_unit` +- :cpp:func:`adc_oneshot_config_channel` +- :cpp:func:`adc_oneshot_read` -Above functions are guaranteed to be thread safe. Therefore, you can call them from different RTOS tasks without protection by extra locks. +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 above thread-safe APIs. +- :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: + Kconfig Options ^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/peripherals/adc_oneshot.rst b/docs/zh_CN/api-reference/peripherals/adc_oneshot.rst index d8d198e1eb..6822ee8ce2 100644 --- a/docs/zh_CN/api-reference/peripherals/adc_oneshot.rst +++ b/docs/zh_CN/api-reference/peripherals/adc_oneshot.rst @@ -1 +1,240 @@ -.. include:: ../../../en/api-reference/peripherals/adc_oneshot.rst \ No newline at end of file +模数转换器 (ADC) 单次转换模式驱动 +=================================== + +:link_to_translation:`en:[English]` + +{IDF_TARGET_ADC_NUM:default="两", esp32c2="一", esp32c6="一", esp32h2="一"} + +简介 +---- + +模数转换器集成于芯片，支持测量特定模拟 IO 管脚的模拟信号。 + +{IDF_TARGET_NAME} 有 {IDF_TARGET_ADC_NUM} 个 ADC 单元，可以在以下场景使用： + +- 生成 ADC 单次转换结果 + +.. only:: SOC_ADC_DMA_SUPPORTED + + - 生成连续 ADC 转换结果 + +本指南介绍了 ADC 单次转换模式。 + + +功能概述 +-------- + +下文将分节概述安装和运行 ADC 的基本步骤： + +- :ref:`adc-oneshot-resource-allocation` - 介绍获取 ADC 句柄所需设置的参数，以及如何在 ADC 完成工作后回收资源。 +- :ref:`adc-oneshot-unit-configuration` - 介绍配置 ADC 单元所需设置的参数，用于获取 ADC 转换的原始结果。 +- :ref:`adc-oneshot-read-conversion-result` - 介绍如何获取 ADC 转换的原始结果。 +- :ref:`hardware_limitations_adc_oneshot` - 介绍与 ADC 相关的硬件限制。 +- :ref:`adc-oneshot-power-management` - 介绍电源管理的相关内容。 +- :ref:`adc-oneshot-iram-safe` - 介绍在禁用 cache 时，如何读取 ADC 转换的原始结果。 +- :ref:`adc-oneshot-thread-safety` - 介绍由驱动程序认证为线程安全的 API。 +- :ref:`adc-oneshot-kconfig-options` - 介绍支持的 Kconfig 选项，不同选项对驱动程序的操作会产生不同影响。 + +.. _adc-oneshot-resource-allocation: + +资源分配 +^^^^^^^^ + +ADC 单次转换模式驱动基于 {IDF_TARGET_NAME} SAR ADC 模块实现，不同的 ESP 芯片可能拥有不同数量的独立 ADC。对于单次转换模式驱动而言，ADC 实例以 :cpp:type:`adc_oneshot_unit_handle_t` 表示。 + +请设置所需的初始配置结构体 :cpp:type:`adc_oneshot_unit_init_cfg_t` 安装 ADC 实例，具体如下： + +- :cpp:member:`adc_oneshot_unit_init_cfg_t::unit_id` 选择 ADC。请参阅 `技术规格书 <{IDF_TARGET_TRM_CN_URL}>`__，了解对应 ADC 的专用模拟 IO 管脚。 +- :cpp:member:`adc_oneshot_unit_init_cfg_t::clk_src` 选择 ADC 的时钟源。设置为 0 时，驱动程序将使用默认时钟源，详情请参阅 :cpp:type:`adc_oneshot_clk_src_t`。 +- :cpp:member:`adc_oneshot_unit_init_cfg_t::ulp_mode` 设置是否支持 ADC 在 ULP 模式下工作。 + +.. todo:: + + Add ULP ADC-related docs here. + +完成 ADC 初始配置后，使用已设置的初始配置结构体 :cpp:type:`adc_oneshot_unit_init_cfg_t` 调用 :cpp:func:`adc_oneshot_new_unit`。如果分配成功，该函数将返回 ADC 单元实例句柄。 + +该函数可能因参数无效、内存不足等原因返回错误代码。比如，当要分配的 ADC 实例已经注册时，该函数会返回 :c:macro:`ESP_ERR_NOT_FOUND` 错误。可用 ADC 数量可通过 :c:macro:`SOC_ADC_PERIPH_NUM` 查看。 + +如果不再需要先前创建的 ADC 单元实例，请调用 :cpp:func:`adc_oneshot_del_unit` 回收该实例，相关的硬件和软件资源也会回收。 + +在普通单次转换模式下创建 ADC 单元实例句柄 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: c + + adc_oneshot_unit_handle_t adc1_handle; + adc_oneshot_unit_init_cfg_t init_config1 = { + .unit_id = ADC_UNIT_1, + .ulp_mode = ADC_ULP_MODE_DISABLE, + }; + ESP_ERROR_CHECK(adc_oneshot_new_unit(&init_config1, &adc1_handle)); + + +回收 ADC 单元实例 +~~~~~~~~~~~~~~~~~~~~ + +.. code:: c + + ESP_ERROR_CHECK(adc_oneshot_del_unit(adc1_handle)); + + +.. _adc-oneshot-unit-configuration: + +配置 ADC 单元实例 +^^^^^^^^^^^^^^^^^^^^^^ + +创建 ADC 单元实例后，请设置 :cpp:type:`adc_oneshot_chan_cfg_t` 配置 ADC IO 以测量模拟信号，具体如下： + +- :cpp:member:`adc_oneshot_chan_cfg_t::atten`，ADC 衰减。请参阅 `技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`__ > ``片上传感器与模拟信号处理``。 +- :cpp:member:`adc_oneshot_chan_cfg_t::bitwidth`，原始转换结果的位宽。 + +.. note:: + + ADC IO 及其对应的 ADC 通道编号，请参阅 `技术规格书 <{IDF_TARGET_TRM_CN_URL}>`__。 + + + 此外，可以使用 :cpp:func:`adc_continuous_io_to_channel` 和 :cpp:func:`adc_continuous_channel_to_io` 了解 ADC 通道和 ADC IO。 + +为使以上设置生效，请使用上述配置结构体调用 :cpp:func:`adc_oneshot_config_channel`，并指定要配置的 ADC 通道。函数 :cpp:func:`adc_oneshot_config_channel` 支持多次调用，以配置不同的 ADC 通道。驱动程序将在内部保存每个通道的配置。 + + +配置两个 ADC 通道 +~~~~~~~~~~~~~~~~~ + +.. code:: c + + adc_oneshot_chan_cfg_t config = { + .bitwidth = ADC_BITWIDTH_DEFAULT, + .atten = ADC_ATTEN_DB_11, + }; + ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN0, &config)); + ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN1, &config)); + + +.. _adc-oneshot-read-conversion-result: + +读取转换结果 +^^^^^^^^^^^^^^^^^^^^^^ + +完成上述配置后，ADC 即可测量来自配置好的 ADC 通道的模拟信号。调用 :cpp:func:`adc_oneshot_read` 可以获取 ADC 通道的原始转换结果。 + +- :cpp:func:`adc_oneshot_read` 可安全使用。ADC 由其他驱动程序/外设共享，请参阅 :ref:`hardware_limitations_adc_oneshot`。函数 :cpp:func:`adc_oneshot_read` 使用互斥锁，避免与其他函数同时使用硬件，因此该函数不应在 ISR 上下文中使用。当 ADC 由其他驱动程序/外设占用时，该函数可能出错，并返回 :c:macro:`ESP_ERR_TIMEOUT` 错误。此时，ADC 原始结果无效。 + +该函数可能因参数无效而调用失败。 + +通过该函数获取的 ADC 转换结果为原始数据。可以使用以下公式，根据 ADC 原始结果计算电压： + +.. parsed-literal:: + + Vout = Dout * Vmax / Dmax (1) + +其中： + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :align: center + + * - Vout + - 数字输出结果，代表电压。 + * - Dout + - ADC 原始数字读取结果。 + * - Vmax + - 可测量的最大模拟输入电压，与 ADC 衰减相关，请参考 `技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`__ > ``片上传感器与模拟信号处理``。 + * - Dmax + - 输出 ADC 原始数字读取结果的最大值，即 2^位宽，位宽即之前配置的 :cpp:member:`adc_digi_pattern_config_t::bit_width`。 + +若需进一步校准，将 ADC 原始结果转换为以 mV 为单位的电压数据，请参考校准文档 :doc:`adc_calibration`。 + + +读取原始结果 +~~~~~~~~~~~~~~~ + +.. code:: c + + ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN0, &adc_raw[0][0])); + ESP_LOGI(TAG, "ADC%d Channel[%d] Raw Data: %d", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN0, adc_raw[0][0]); + + ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN1, &adc_raw[0][1])); + ESP_LOGI(TAG, "ADC%d Channel[%d] Raw Data: %d", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN1, adc_raw[0][1]); + + +.. _hardware_limitations_adc_oneshot: + +硬件限制 +^^^^^^^^^^^^^^^^^^^^ + +- 随机数生成器 (RNG) 以 ADC 为输入源。使用 ADC 单次转换模式驱动从 RNG 生成随机数时，随机性会减弱。 + +.. only:: SOC_ADC_DMA_SUPPORTED + + - 一个 ADC 单元每次只能在一种操作模式下运行，可以是连续模式或单次模式。:cpp:func:`adc_oneshot_start` 提供了保护措施。 + +.. only:: esp32 or esp32s2 or esp32s3 + + - Wi-Fi 也使用 ADC2，:cpp:func:`adc_oneshot_read` 提供了 Wi-Fi 驱动与 ADC 单次转换模式驱动间的保护。 + +.. only:: esp32c3 + + - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 单次转换的结果可能不稳定，具体可参考 `ESP32-C3 系列芯片勘误表 `__。出于兼容性考虑，可以启用 :ref:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3`，强制使用 ADC2。 + +.. only:: esp32 + + - ESP32-DevKitC：GPIO0 已用于自动烧录功能，不能用于 ADC 单次转换模式。 + + - ESP-WROVER-KIT：GPIO0、GPIO2、GPIO4 和 GPIO15 已有其他用途，不能用于 ADC 单次转换模式。 + + .. _adc-oneshot-power-management: + +.. only:: not esp32 + + .. _adc-oneshot-power-management: + +电源管理 +^^^^^^^^ + +启用电源管理，即启用 :ref:`CONFIG_PM_ENABLE` 时，系统在空闲状态下可能会调整系统时钟频率。然而，ADC 单次转换模式驱动以轮询例程运行，:cpp:func:`adc_oneshot_read` 会不断检查 CPU 是否完成读取，直到函数返回。在此期间，ADC 单次转换模式驱动程序所在的任务不会受阻塞。因此，在读取时时钟频率保持稳定。 + + +.. _adc-oneshot-iram-safe: + +IRAM 安全 +^^^^^^^^^ + +flash 写入/擦除、OTA 等原因都可能导致 cache 禁用，此时，默认不应运行任何 ADC 单次转换模式驱动 API。如果在禁用 cache 时执行了 ADC 单次转换模式驱动 API，可能会出现类似 ``Illegal Instruction`` 或 ``Load/Store Prohibited`` 的错误。 + + +.. _adc-oneshot-thread-safety: + +线程安全 +^^^^^^^^ + +- :cpp:func:`adc_oneshot_new_unit` +- :cpp:func:`adc_oneshot_config_channel` +- :cpp:func:`adc_oneshot_read` + +上述函数均为线程安全，使用时，可以直接从不同的 RTOS 任务中调用以上函数，无需额外锁保护。 + +- :cpp:func:`adc_oneshot_del_unit` 非线程安全。此外，与上文中线程安全的函数一起调用该函数时，可能导致线程安全函数的调用出错。 + + +.. _adc-oneshot-kconfig-options: + +Kconfig 选项 +^^^^^^^^^^^^ + +- :ref:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` 决定了放置 ADC 快速读取函数的位置，即 IRAM 或 flash 中，详情请参阅 :ref:`adc-oneshot-iram-safe`。 + + +应用示例 +-------------------- + +* ADC 单次转换模式示例：:example:`peripherals/adc/oneshot_read`。 + + +API 参考 +------------- + +.. include-build-file:: inc/adc_types.inc +.. include-build-file:: inc/adc_oneshot.inc