From 20951be6872a9fd90aa70e81782d1dfd212ab314 Mon Sep 17 00:00:00 2001 From: caixinying-git Date: Fri, 28 Jul 2023 10:31:35 +0800 Subject: [PATCH] docs: provide CN translation for api-reference/peripherals/adc_calibration.rst --- .../peripherals/adc_calibration.rst | 76 ++++--- .../peripherals/adc_calibration.rst | 210 +++++++++++++++++- 2 files changed, 252 insertions(+), 34 deletions(-) diff --git a/docs/en/api-reference/peripherals/adc_calibration.rst b/docs/en/api-reference/peripherals/adc_calibration.rst index c058219c51..ce1d6119c1 100644 --- a/docs/en/api-reference/peripherals/adc_calibration.rst +++ b/docs/en/api-reference/peripherals/adc_calibration.rst @@ -1,11 +1,12 @@ Analog to Digital Converter (ADC) Calibration Driver ==================================================== +:link_to_translation:`zh_CN:[中文]` Introduction ------------ -Based on series of comparisons with the reference voltage, {IDF_TARGET_NAME} ADC determines each bit of the output digital result. Per design the {IDF_TARGET_NAME} ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV among different chips. This guide will introduce an ADC calibration driver to minimize this difference. +In {IDF_TARGET_NAME}, the digital-to-analog converter (ADC) compares the input analog voltage to the reference, and determines each bit of the output digital result. By design, the ADC reference voltage for {IDF_TARGET_NAME} is 1100 mV. However, the true reference voltage can range from 1000 mV to 1200 mV among different chips. This guide introduces the ADC calibration driver to minimize the effect of different reference voltages, and get more accurate output results. Functional Overview @@ -13,24 +14,25 @@ Functional Overview The following sections of this document cover the typical steps to install and use the ADC calibration driver: -- `Calibration Scheme Creation <#calibration-scheme-creation>`__ - covers how to create a calibration scheme handle and delete the calibration scheme handle. -- `Result Conversion <#result-conversion>`__ - convers how to convert ADC raw result to calibrated result. -- `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver. -- `Minimize Noise <#minimize-noise>`__ - describes a general way to minimize the noise. +.. list:: -.. only:: esp32 + - :ref:`adc-calibration-scheme-creation` - covers how to create a calibration scheme handle and delete the calibration scheme handle. + - :ref:`adc-result-conversion` - covers how to convert ADC raw result to calibrated result. + - :ref:`adc-thread-safety` - lists which APIs are guaranteed to be thread-safe by the driver. + - :ref:`Minimize Noise ` - describes a general way to minimize the noise. + :esp32: - :ref:`adc-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior. - - `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can be used to make a different effect on driver behavior. +.. _adc-calibration-scheme-creation: Calibration Scheme Creation ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ADC calibration driver provides ADC calibration scheme(s). From calibration driver's point of view, an ADC calibration scheme is created to an ADC calibration handle :cpp:type:`adc_cali_handle_t`. +The ADC calibration driver provides ADC calibration scheme(s). From the calibration driver's point of view, an ADC calibration scheme is created for an ADC calibration handle :cpp:type:`adc_cali_handle_t`. -:cpp:func:`adc_cali_check_scheme` can be used to know which calibration scheme is supported on the chip. For those users who are already aware of the supported scheme, this step can be skipped. Just call the corresponding function to create the scheme handle. +:cpp:func:`adc_cali_check_scheme` can be used to know which calibration scheme is supported on the chip. If you already know the supported schemes, this step can be skipped. Just call the corresponding function to create the scheme handle. -For those users who use their custom ADC calibration schemes, you could either modify this function :cpp:func:`adc_cali_check_scheme`, or just skip this step and call your custom creation function. +If you use your custom ADC calibration schemes, you could either modify this function :cpp:func:`adc_cali_check_scheme`, or just skip this step and call your custom creation function. .. only:: esp32 or esp32s2 or esp32c2 @@ -39,23 +41,23 @@ For those users who use their custom ADC calibration schemes, you could either m {IDF_TARGET_NAME} supports :c:macro:`ADC_CALI_SCHEME_VER_LINE_FITTING` scheme. To create this scheme, set up :cpp:type:`adc_cali_line_fitting_config_t` first. - - :cpp:member:`adc_cali_line_fitting_config_t::unit_id`, the ADC that your ADC raw results are from. - - :cpp:member:`adc_cali_line_fitting_config_t::atten`, ADC attenuation that your ADC raw results use. - - :cpp:member:`adc_cali_line_fitting_config_t::bitwidth`, the ADC raw result bitwidth. + - :cpp:member:`adc_cali_line_fitting_config_t::unit_id`, the ADC that your ADC raw results are from. + - :cpp:member:`adc_cali_line_fitting_config_t::atten`, ADC attenuation that your ADC raw results use. + - :cpp:member:`adc_cali_line_fitting_config_t::bitwidth`, bit width of ADC raw result. .. only:: esp32 - There is also a configuration :cpp:member:`adc_cali_line_fitting_config_t::default_vref`. Normally this can be simply set to 0. Line Fitting scheme doesn't rely on this value. However, if the Line Fitting scheme required eFuse bits are not burnt on your board, driver will rely on this value to do the calibration. + There is also a configuration :cpp:member:`adc_cali_line_fitting_config_t::default_vref`. Normally this can be simply set to 0. Line Fitting scheme does not rely on this value. However, if the Line Fitting scheme required eFuse bits are not burnt on your board, the driver will rely on this value to do the calibration. - You can use :cpp:func:`adc_cali_scheme_line_fitting_check_efuse` to check the eFuse bits. Normally the Line Fitting scheme eFuse value will be :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP` or :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`. This means Line Fitting scheme will use calibration parameters burnt in the eFuse to do the calibration. + You can use :cpp:func:`adc_cali_scheme_line_fitting_check_efuse` to check the eFuse bits. Normally the Line Fitting scheme eFuse value is :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP` or :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`. This means the Line Fitting scheme uses calibration parameters burnt in the eFuse to do the calibration. - When the Line Fitting scheme eFuse value is :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF`, you need to set the :cpp:member:`esp_adc_cali_line_fitting_init::default_vref`. Default vref is an estimate of the ADC reference voltage provided by the users as a parameter during calibration. + When the Line Fitting scheme eFuse value is :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF`, you need to set the :cpp:member:`esp_adc_cali_line_fitting_init::default_vref`. Default vref is an estimate of the ADC reference voltage provided as a parameter during calibration. After setting up the configuration structure, call :cpp:func:`adc_cali_create_scheme_line_fitting` to create a Line Fitting calibration scheme handle. .. only:: esp32s2 - This function may fail due to reasons such as :c:macro:`ESP_ERR_INVALID_ARG` or :c:macro:`ESP_ERR_NO_MEM`. Especially, when the function return :c:macro:`ESP_ERR_NOT_SUPPORTED`, this means the calibration scheme required eFuse bits are not burnt on your board. + This function may fail due to reasons such as :c:macro:`ESP_ERR_INVALID_ARG` or :c:macro:`ESP_ERR_NO_MEM`. Especially, when the function returns :c:macro:`ESP_ERR_NOT_SUPPORTED`, this means the calibration scheme required eFuse bits are not burnt on your board. .. code:: c @@ -72,7 +74,7 @@ For those users who use their custom ADC calibration schemes, you could either m Delete Line Fitting Scheme - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: c @@ -91,21 +93,21 @@ For those users who use their custom ADC calibration schemes, you could either m .. only:: not esp32c6 - :cpp:member:`adc_cali_curve_fitting_config_t::unit_id`, the ADC that your ADC raw results are from. - - :cpp:member:`adc_cali_curve_fitting_config_t::chan`, this member is kept here for extensibility. The calibration scheme only differs by attenuation, there's no difference among different channels. + - :cpp:member:`adc_cali_curve_fitting_config_t::chan`, this member is kept here for extensibility. The calibration scheme only differs by attenuation, there is no difference among different channels. - :cpp:member:`adc_cali_curve_fitting_config_t::atten`, ADC attenuation that your ADC raw results use. - - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`, the ADC raw result bitwidth. + - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`, bit width of ADC raw result. .. only:: esp32c6 - :cpp:member:`adc_cali_curve_fitting_config_t::unit_id`, the ADC that your ADC raw results are from. - - :cpp:member:`adc_cali_curve_fitting_config_t::chan`, the ADC channel that your ADC raw results are from. The calibration scheme not only differs by attenuation but also related to the channels. + - :cpp:member:`adc_cali_curve_fitting_config_t::chan`, the ADC channel that your ADC raw results are from. The calibration scheme not only differs by attenuation but is also related to the channels. - :cpp:member:`adc_cali_curve_fitting_config_t::atten`, ADC attenuation that your ADC raw results use. - - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`, the ADC raw result bitwidth. + - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`, bit width of ADC raw result. After setting up the configuration structure, call :cpp:func:`adc_cali_create_scheme_curve_fitting` to create a Curve Fitting calibration scheme handle. This function may fail due to reasons such as :c:macro:`ESP_ERR_INVALID_ARG` or :c:macro:`ESP_ERR_NO_MEM`. Especially, when the function return :c:macro:`ESP_ERR_NOT_SUPPORTED`, this means the calibration scheme required eFuse bits are not burnt on your board. Create Curve Fitting Scheme - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: c @@ -122,7 +124,7 @@ For those users who use their custom ADC calibration schemes, you could either m Delete Curve Fitting Scheme - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: c @@ -136,19 +138,21 @@ For those users who use their custom ADC calibration schemes, you could either m .. note:: - For users who want to use their custom calibration schemes, you could provide a creation function to create your calibration scheme handle. Check the function table `adc_cali_scheme_t` in `components/esp_adc/interface/adc_cali_interface.h` to know the ESP ADC calibration interface. + If you want to use your custom calibration schemes, you could provide a creation function to create your calibration scheme handle. Check the function table ``adc_cali_scheme_t`` in ``components/esp_adc/interface/adc_cali_interface.h`` to know the ESP ADC calibration interface. +.. _adc-result-conversion: + Result Conversion ^^^^^^^^^^^^^^^^^ -After setting up the calibration characteristics, you can call :cpp:func:`adc_cali_raw_to_voltage` to convert the ADC raw result into calibrated result. The calibrated result is in the unit of mV. This function may fail due to invalid argument. Especailly, if this function returns :c:macro:`ESP_ERR_INVALID_STATE`, this means the calibration scheme isn't created. You need to create a calibration scheme handle, use :cpp:func:`adc_cali_check_scheme` to know the supported calibration scheme. On the other hand, you could also provide a custom calibration scheme and create the handle. +After setting up the calibration characteristics, you can call :cpp:func:`adc_cali_raw_to_voltage` to convert the ADC raw result into calibrated result. The calibrated result is in the unit of mV. This function may fail due to an invalid argument. Especially, if this function returns :c:macro:`ESP_ERR_INVALID_STATE`, this means the calibration scheme is not created. You need to create a calibration scheme handle, use :cpp:func:`adc_cali_check_scheme` to know the supported calibration scheme. On the other hand, you could also provide a custom calibration scheme and create the handle. .. only:: esp32c2 .. note:: - ADC calibration is only supported under :c:macro:`ADC_ATTEN_DB_0` and :c:macro:`ADC_ATTEN_DB_11`. Under :c:macro:`ADC_ATTEN_DB_0`, input voltage higher than 950 mV is not supported. Under :c:macro:`ADC_ATTEN_DB_11`, input voltage higher than 2800 mV is not supported. + ADC calibration is only supported under :c:macro:`ADC_ATTEN_DB_0` and :c:macro:`ADC_ATTEN_DB_11`. Under :c:macro:`ADC_ATTEN_DB_0`, the attenuation of ADC is set to 0 dB, and input voltage higher than 950 mV is not supported. Under :c:macro:`ADC_ATTEN_DB_11`, the attenuation of ADC is set to 11 dB, and input voltage higher than 2800 mV is not supported. Get Voltage ~~~~~~~~~~~ @@ -159,28 +163,34 @@ Get Voltage ESP_LOGI(TAG, "ADC%d Channel[%d] Cali Voltage: %d mV", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN0, voltage[0][0]); +.. _adc-thread-safety: + Thread Safety ^^^^^^^^^^^^^ -The factory function :cpp:func:`esp_adc_cali_new_scheme` is guaranteed to be thread safe by the driver. Therefore, you can call them from different RTOS tasks without protection by extra locks. +The factory function :cpp:func:`esp_adc_cali_new_scheme` is guaranteed to be thread-safe by the driver. Therefore, you can call them from different RTOS tasks without protection by extra locks. -Other functions that take the :cpp:type:`adc_cali_handle_t` as the first positional parameter are not thread safe, you should avoid calling them from multiple tasks. +Other functions that take the :cpp:type:`adc_cali_handle_t` as the first positional parameter are not thread-safe, you should avoid calling them from multiple tasks. .. only:: esp32 + .. _adc-kconfig-options: + Kconfig Options ^^^^^^^^^^^^^^^ - - :ref:`CONFIG_ADC_CAL_EFUSE_TP_ENABLE`, disable this to decrease the code size, if you are aware of the calibration eFuse value :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP` isn't this one. - - :ref:`CONFIG_ADC_CAL_EFUSE_VREF_ENABLE`, disable this to decrease the code size, if you are aware of the calibration eFuse value :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF` isn't this one. - - :ref:`CONFIG_ADC_CAL_LUT_ENABLE`, disable this to decrease the code size, if you don't calibrate the ADC raw results under :c:macro:`ADC_ATTEN_DB_11`. + - :ref:`CONFIG_ADC_CAL_EFUSE_TP_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`. + - :ref:`CONFIG_ADC_CAL_EFUSE_VREF_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`. + - :ref:`CONFIG_ADC_CAL_LUT_ENABLE` - disable this to decrease the code size, if you do not calibrate the ADC raw results under :c:macro:`ADC_ATTEN_DB_11`. +.. _adc-minimize-noise: + Minimize Noise ^^^^^^^^^^^^^^ -The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. Depending on the usage scenario, you may need to connect a bypass capacitor (e.g. a 100 nF ceramic capacitor) to the ADC input pad in use, to minimize noise. Besides, multisampling may also be used to further mitigate the effects of noise. +The {IDF_TARGET_NAME} ADC is sensitive to noise, leading to large discrepancies in ADC readings. Depending on the usage scenario, you may need to connect a bypass capacitor (e.g., a 100 nF ceramic capacitor) to the ADC input pad in use, to minimize noise. Besides, multisampling may also be used to further mitigate the effects of noise. .. only:: esp32 diff --git a/docs/zh_CN/api-reference/peripherals/adc_calibration.rst b/docs/zh_CN/api-reference/peripherals/adc_calibration.rst index 2c86bc1d28..df7b345c39 100644 --- a/docs/zh_CN/api-reference/peripherals/adc_calibration.rst +++ b/docs/zh_CN/api-reference/peripherals/adc_calibration.rst @@ -1 +1,209 @@ -.. include:: ../../../en/api-reference/peripherals/adc_calibration.rst \ No newline at end of file +模数转换器 (ADC) 校准驱动程序 +================================= + +:link_to_translation:`en:[English]` + +简介 +---- + +在 {IDF_TARGET_NAME} 中，模数转换器 (ADC) 比较输入的模拟电压和参考电压，以确定每一位数字输出结果。{IDF_TARGET_NAME} 设计的 ADC 参考电压为 1100 mV。然而，不同芯片的真实参考电压可能会略有变化，范围在 1000 mV 到 1200 mV 之间。本文介绍了 ADC 校准驱动程序，可以降低参考电压不同带来的影响，获取更准确的输出结果。 + + +功能概述 +-------- + +下文将分节概述安装和使用 ADC 校准驱动程序的基本步骤： + +.. list:: + + - :ref:`adc-calibration-scheme-creation` - 介绍如何创建和删除校准方案句柄。 + - :ref:`adc-result-conversion` - 介绍如何将原始 ADC 结果转换为校准后的结果。 + - :ref:`adc-thread-safety` - 列出由驱动程序认证为线程安全的 API。 + - :ref:`减少噪声 ` - 介绍一种常见的降低噪声的方法。 + :esp32: - :ref:`adc-kconfig-options` - 列出了驱动程序支持的 Kconfig 选项，这些选项会对驱动程序的行为产生不同影响。 + + +.. _adc-calibration-scheme-creation: + +创建校准方案 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ADC 校准驱动程序会提供 ADC 校准方案。对于驱动程序来说，每个 ADC 校准方案对应一个 ADC 校准句柄 :cpp:type:`adc_cali_handle_t`。 + +使用 :cpp:func:`adc_cali_check_scheme` 可以查看芯片支持的校准方案。若已了解芯片支持的校准方案，可以跳过该步骤，直接调用对应函数创建校准方案句柄。 + +使用自定义 ADC 校准方案时，可以选择调整函数 :cpp:func:`adc_cali_check_scheme`，或直接跳过该步骤，调用自定义函数创建校准方案句柄。 + +.. only:: esp32 or esp32s2 or esp32c2 + + ADC 校准线性拟合方案 + ``````````````````````````````````` + + {IDF_TARGET_NAME} 支持 :c:macro:`ADC_CALI_SCHEME_VER_LINE_FITTING` 方案。要创建此方案，请先根据以下配置选项，设置 :cpp:type:`adc_cali_line_fitting_config_t`。 + + - :cpp:member:`adc_cali_line_fitting_config_t::unit_id`，表示 ADC 原始结果来自哪个 ADC 单元。 + - :cpp:member:`adc_cali_line_fitting_config_t::atten`，表示 ADC 原始结果的衰减程度。 + - :cpp:member:`adc_cali_line_fitting_config_t::bitwidth`，表示 ADC 原始结果的位宽。 + + .. only:: esp32 + + :cpp:member:`adc_cali_line_fitting_config_t::default_vref` 通常默认设置为 0，此值不影响线性拟合方案的校准过程。然而，如果线性拟合方案所需使用的 eFuse 位没有烧录到板上，则驱动程序将根据 :cpp:member:`adc_cali_line_fitting_config_t::default_vref` 进行校准。 + + 通过 :cpp:func:`adc_cali_scheme_line_fitting_check_efuse` 可以检查 eFuse 位。一般情况下，线性拟合方案的 eFuse 值为 :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP` 或 :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`。这意味着线性拟合方案在校准时，使用的是烧录在 eFuse 中的校准参数。 + + 当线性拟合方案的 eFuse 值为 :c:macro:`ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF` 时，请设置 :cpp:member:`esp_adc_cali_line_fitting_init::default_vref`。默认 vref 为 ADC 参考电压的估计值，在校准时作为参数提供。 + + 设置完上述配置结构体后，请调用 :cpp:func:`adc_cali_create_scheme_line_fitting` 创建线性拟合校准方案句柄。 + + .. only:: esp32s2 + + 由于 :c:macro:`ESP_ERR_INVALID_ARG` 或 :c:macro:`ESP_ERR_NO_MEM` 等原因，该函数调用可能失败。函数返回 :c:macro:`ESP_ERR_NOT_SUPPORTED` 时，说明你的开发板缺少烧录所需的 eFuse 位。 + + .. code:: c + + ESP_LOGI(TAG, "calibration scheme version is %s", "Line Fitting"); + adc_cali_line_fitting_config_t cali_config = { + .unit_id = unit, + .atten = atten, + .bitwidth = ADC_BITWIDTH_DEFAULT, + }; + ESP_ERROR_CHECK(adc_cali_create_scheme_line_fitting(&cali_config, &handle)); + + + ADC 校准使用完毕后，请调用 :cpp:func:`adc_cali_delete_scheme_line_fitting`，删除线性拟合校准方案句柄。 + + + 删除线性拟合校准方案句柄 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. code:: c + + ESP_LOGI(TAG, "delete %s calibration scheme", "Line Fitting"); + ESP_ERROR_CHECK(adc_cali_delete_scheme_line_fitting(handle)); + + +.. only:: esp32c3 or esp32s3 or esp32c6 + + ADC 校准曲线拟合方案 + ```````````````````````````````````` + + {IDF_TARGET_NAME} 支持 :c:macro:`ADC_CALI_SCHEME_VER_CURVE_FITTING` 方案。要创建此方案，请先根据以下配置选项，设置 :cpp:type:`adc_cali_curve_fitting_config_t`。 + + + .. only:: not esp32c6 + + - :cpp:member:`adc_cali_curve_fitting_config_t::unit_id`，表示 ADC 原始结果来自哪个 ADC 单元。 + - :cpp:member:`adc_cali_curve_fitting_config_t::chan`，此选项保留以供扩展。校准方案仅因衰减程度而异，与通道选择无关。 + - :cpp:member:`adc_cali_curve_fitting_config_t::atten`，表示 ADC 原始结果的衰减程度。 + - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`，表示 ADC 原始结果的位宽。 + + .. only:: esp32c6 + + - :cpp:member:`adc_cali_curve_fitting_config_t::unit_id`，表示 ADC 原始结果来自哪个 ADC 单元。 + - :cpp:member:`adc_cali_curve_fitting_config_t::chan`，表示获取 ADC 原始结果的 ADC 通道。校准方案不仅因衰减程度而异，还与通道选择有关。 + - :cpp:member:`adc_cali_curve_fitting_config_t::atten`，表示 ADC 原始结果的衰减程度。 + - :cpp:member:`adc_cali_curve_fitting_config_t::bitwidth`，表示 ADC 原始结果的位宽。 + + 设置完上述配置结构体后，请调用 :cpp:func:`adc_cali_create_scheme_curve_fitting` 创建曲线拟合方案句柄。 由于 :c:macro:`ESP_ERR_INVALID_ARG` 或 :c:macro:`ESP_ERR_NO_MEM` 等原因，该函数调用可能失败。函数返回 :c:macro:`ESP_ERR_NOT_SUPPORTED` 时，说明你的开发板没有烧录校准方案所需的 eFuse 位。 + + 创建曲线拟合方案句柄 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. code:: c + + ESP_LOGI(TAG, "calibration scheme version is %s", "Curve Fitting"); + adc_cali_curve_fitting_config_t cali_config = { + .unit_id = unit, + .atten = atten, + .bitwidth = ADC_BITWIDTH_DEFAULT, + }; + ESP_ERROR_CHECK(adc_cali_create_scheme_curve_fitting(&cali_config, &handle)); + + + ADC 校准使用完毕后，请调用 :cpp:func:`adc_cali_delete_scheme_curve_fitting`，删除校准方案句柄。 + + + 删除曲线拟合方案句柄 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. code:: c + + ESP_LOGI(TAG, "delete %s calibration scheme", "Curve Fitting"); + ESP_ERROR_CHECK(adc_cali_delete_scheme_curve_fitting(handle)); + + +.. only:: esp32h2 + + 目前尚不支持任何校准方案。 + +.. note:: + + 要使用自定义校准方案，可以通过提供创建函数，创建自己的校准方案句柄。请参阅 ``components/esp_adc/interface/adc_cali_interface.h`` 中的函数表 ``adc_cali_scheme_t``，了解 ESP ADC 校准接口。 + + +.. _adc-result-conversion: + +结果转换 +^^^^^^^^^^^^^^^^^ + +对驱动程序进行完上述配置和初始化工作后，可以调用 :cpp:func:`adc_cali_raw_to_voltage`，将原始 ADC 结果转换为校准结果，校准结果以 mV 为单位。该函数可能因参数无效而调用失败。如果函数返回 :c:macro:`ESP_ERR_INVALID_STATE`，说明校准方案尚未创建。因此你需要创建一个校准方案句柄，通过 :cpp:func:`adc_cali_check_scheme` 可以了解当前芯片支持的校准方案；你也可以提供自定义校准方案，创建对应的校准方案句柄。 + +.. only:: esp32c2 + + .. note:: + + ADC 校准仅在 :c:macro:`ADC_ATTEN_DB_0` 和 :c:macro:`ADC_ATTEN_DB_11` 时支持。在 :c:macro:`ADC_ATTEN_DB_0` 时，ADC 的衰减程度设置为 0 dB，仅支持低于 950 mV 的输入电压；在 :c:macro:`ADC_ATTEN_DB_11` 时，ADC 的衰减程度设置为 11 dB，仅支持低于 2800 mV 的输入电压。 + +获取电压 +~~~~~~~~~~~ + +.. code:: c + + ESP_ERROR_CHECK(adc_cali_raw_to_voltage(adc_cali_handle, adc_raw[0][0], &voltage[0][0])); + ESP_LOGI(TAG, "ADC%d Channel[%d] Cali Voltage: %d mV", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN0, voltage[0][0]); + + +.. _adc-thread-safety: + +线程安全 +^^^^^^^^^^^^^ + +驱动程序会确保工厂函数 :cpp:func:`esp_adc_cali_new_scheme` 的线程安全，使用时，可以直接从不同的 RTOS 任务中调用此类函数，无需额外锁保护。 + +其他以 :cpp:type:`adc_cali_handle_t` 作为第一个位置参数的函数均非线程安全，在没有设置互斥锁保护的任务中，应避免从多个任务中调用这类函数。 + + +.. only:: esp32 + + .. _adc-kconfig-options: + + Kconfig 选项 + ^^^^^^^^^^^^^^^ + + - :ref:`CONFIG_ADC_CAL_EFUSE_TP_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`，则可以禁用该选项，减小代码大小。 + - :ref:`CONFIG_ADC_CAL_EFUSE_VREF_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`，则可以禁用该选项，减小代码大小。 + - :ref:`CONFIG_ADC_CAL_LUT_ENABLE` - 如果校准 ADC 原始结果时，衰减没有设置成 :c:macro:`ADC_ATTEN_DB_11`，则可以禁用该选项，减小代码大小。 + + +.. _adc-minimize-noise: + +减少噪声 +^^^^^^^^^^^^^^ + +{IDF_TARGET_NAME} ADC 对噪声敏感，可能导致 ADC 读数出现较大偏差。根据不同使用场景，要减少噪声影响，你可能需要将旁路电容（如 100 nF 陶瓷电容）连接到 ADC 使用的输入管脚。此外，也可以通过多次采样，进一步减轻噪声的影响。 + +.. only:: esp32 + + .. figure:: ../../../_static/diagrams/adc/adc-noise-graph.jpg + :align: center + :alt: ADC 噪声抑制 + + 图中展示了连接电容以及 64 次采样对噪声的抑制效果。 + + +API 参考 +-------- + + +.. include-build-file:: inc/adc_cali.inc +.. include-build-file:: inc/adc_cali_scheme.inc