Skip to content

Commit

Permalink
Merge branch 'docs/add_Chinese_translation_for_api-reference/peripher…
Browse files Browse the repository at this point in the history 
…als/adc_calibration.rst' into 'master'

docs: provide CN translation for api-reference/peripherals/adc_calibration.rst

Closes DOC-5858

See merge request espressif/esp-idf!25032
  • Loading branch information
@caixinying-git
caixinying-git committed Sep 5, 2023
2 parents 32ad8f1 + 20951be commit 8a4df2d
Show file tree
Hide file tree
Showing 2 changed files with 252 additions and 34 deletions.
76 changes: 43 additions & 33 deletions docs/en/api-reference/peripherals/adc_calibration.rst
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,38 @@
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
-------------------

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 <adc-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

Expand All @@ -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
Expand All @@ -72,7 +74,7 @@ For those users who use their custom ADC calibration schemes, you could either m


Delete Line Fitting Scheme
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: c
Expand All @@ -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
Expand All @@ -122,7 +124,7 @@ For those users who use their custom ADC calibration schemes, you could either m


Delete Curve Fitting Scheme
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: c
Expand All @@ -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
~~~~~~~~~~~
Expand All @@ -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

Expand Down
Loading

0 comments on commit 8a4df2d

Please sign in to comment.