mirror of
https://github.com/espressif/esp-idf.git
synced 2025-07-30 10:47:19 +02:00
Merge branch 'feature/update_adc_programming_guide_on_c3_v4.3' into 'release/v4.3'
adc: add adc programming guide on c3 (4.3) See merge request espressif/esp-idf!13281
This commit is contained in:
Michael (XIAO Xufeng)
@ -135,7 +135,7 @@ typedef enum {
|
||||
* @brief Digital ADC DMA configuration
|
||||
*/
|
||||
typedef struct adc_digi_init_config_s {
|
||||
uint32_t max_store_buf_size; ///< Max length of the converted data that driver can store before they are processed. When this length is reached, driver will dump out all the old data and start to store them again.
|
||||
uint32_t max_store_buf_size; ///< Max length of the converted data that driver can store before they are processed.
|
||||
uint32_t conv_num_each_intr; ///< Bytes of data that can be converted in 1 interrupt.
|
||||
uint32_t adc1_chan_mask; ///< Channel list of ADC1 to be initialized.
|
||||
uint32_t adc2_chan_mask; ///< Channel list of ADC2 to be initialized.
|
||||
|
||||
@ -8,33 +8,86 @@ Analog to Digital Converter
|
||||
Overview
|
||||
--------
|
||||
|
||||
{IDF_TARGET_ADC_DATA_WIDTH:default="12", esp32s2="13"}
|
||||
{IDF_TARGET_ADC_TOTAL_CHAN:default="20", esp32="18", esp32s2="20", esp32c3="6"}
|
||||
|
||||
The {IDF_TARGET_NAME} integrates two {IDF_TARGET_ADC_DATA_WIDTH}-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs, supporting a total of {IDF_TARGET_ADC_TOTAL_CHAN} measurement channels (analog enabled pins).
|
||||
|
||||
These channels are supported:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs, supporting a total of 18 measurement channels (analog enabled pins).
|
||||
|
||||
The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application:
|
||||
|
||||
1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started.
|
||||
2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits:
|
||||
|
||||
- :ref:`ESP32 DevKitC <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
|
||||
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.
|
||||
ADC1:
|
||||
- 8 channels: GPIO32 - GPIO39
|
||||
ADC2:
|
||||
- 10 channels: GPIO0, GPIO2, GPIO4, GPIO12 - GPIO15, GOIO25 - GPIO27
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
The {IDF_TARGET_NAME} integrates two 13-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs, supporting a total of 20 measurement channels (analog enabled pins).
|
||||
ADC1:
|
||||
- 10 channels: GPIO1 - GPIO10
|
||||
ADC2:
|
||||
- 10 channels: GPIO11 - GPIO20
|
||||
|
||||
The ADC driver API supports ADC1 (10 channels, attached to GPIOs 1 - 10), and ADC2 (10 channels, attached to GPIOs 11 - 20). However, the usage of ADC2 has some restrictions for the application:
|
||||
.. only:: esp32c3
|
||||
|
||||
1. Different from ADC1, the hardware arbiter function is added to ADC2, so when using the API of ADC2 to obtain the sampling voltage, you need to check whether the reading is successful.
|
||||
ADC1:
|
||||
- 5 channels: GPIO0 - GPIO4
|
||||
ADC2:
|
||||
- 1 channels: GPIO5
|
||||
|
||||
Configuration and Reading ADC
|
||||
-----------------------------
|
||||
|
||||
Each ADC unit supports two work modes, ADC-RTC or ADC-DMA mode. ADC-RTC is controlled by the RTC controller and is suitable for low-frequency sampling operations. ADC-DMA is controlled by a digital controller and is suitable for high-frequency continuous sampling actions.
|
||||
.. _adc_limitations:
|
||||
|
||||
ADC-RTC mode
|
||||
^^^^^^^^^^^^
|
||||
ADC Limitations
|
||||
---------------
|
||||
|
||||
.. note::
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits:
|
||||
- :ref:`ESP32 DevKitC <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
|
||||
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.
|
||||
- Since the ADC2 module is also used by the Wi-Fi, only one of them could get the preemption when using together, which means the :cpp:func:`adc2_get_raw` may get blocked until Wi-Fi stops, and vice versa.
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
- Since the ADC2 module is also used by the Wi-Fi, reading operation of :cpp:func:`adc2_get_raw` may fail between :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_wifi_stop()`. Use the return code to see whether the reading is successful.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
- A specific ADC module can only work under one operating mode at any one time, either Continuous Read Mode or Single Read Mode.
|
||||
- ADC1 and ADC2 can not work under Singel Read Mode simultaneously. One of them will get blocked until another one finishes.
|
||||
- For continuous (DMA) read mode, the ADC sampling frequency (the ``sample_freq_hz`` member of :cpp:type:`adc_digi_config_t`) should be within ``SOC_ADC_SAMPLE_FREQ_THRES_LOW`` and ``SOC_ADC_SAMPLE_FREQ_THRES_HIGH``.
|
||||
|
||||
Driver Usage
|
||||
------------
|
||||
|
||||
Each ADC unit supports two work modes, ADC single read mode and ADC continuous (DMA) mode. ADC single read mode is suitable for low-frequency sampling operations. ADC continuous (DMA) read mode is suitable for high-frequency continuous sampling actions.
|
||||
|
||||
.. note::
|
||||
|
||||
ADC readings from a pin not connected to any signal are random.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
ADC Continuous (DMA) Read mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Please use the ADC continuous read mode driver as the following steps:
|
||||
|
||||
- Initialize the ADC driver by calling the function :cpp:func:`adc_digi_initialize`.
|
||||
- Initialize the ADC controller by calling the function :cpp:func:`adc_digi_controller_config`.
|
||||
- Start the ADC continuous reading by calling the function :cpp:func:`adc_digi_start`.
|
||||
- After starting the ADC, you can get the ADC reading result by calling the function :cpp:func:`adc_digi_read_bytes`. Before stopping the ADC (by calling :cpp:func:`adc_digi_stop`), the driver will keep converting the analog data to digital data.
|
||||
- Stop the ADC reading by calling the function :cpp:func:`adc_digi_stop`.
|
||||
- Deinitialize the ADC driver by calling the function :cpp:func:`adc_digi_deinitialize`.
|
||||
|
||||
.. note:: See :ref:`adc_limitations` for the limitation of using ADC continuous (DMA) read mode.
|
||||
|
||||
ADC Single Read mode
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ADC should be configured before reading is taken.
|
||||
|
||||
@ -45,8 +98,6 @@ Attenuation configuration is done per channel, see :cpp:type:`adc1_channel_t` an
|
||||
|
||||
Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` and :cpp:func:`adc2_get_raw`. Reading width of ADC2 should be set as a parameter of :cpp:func:`adc2_get_raw` instead of in the configuration functions.
|
||||
|
||||
.. note:: Since the ADC2 is shared with the WIFI module, which has higher priority, reading operation of :cpp:func:`adc2_get_raw` will fail between :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_wifi_stop()`. Use the return code to see whether the reading is successful.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor.
|
||||
@ -55,17 +106,19 @@ Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw`
|
||||
|
||||
This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above.
|
||||
|
||||
There is another specific function :cpp:func:`adc_vref_to_gpio` used to route internal reference voltage to a GPIO pin. It comes handy to calibrate ADC reading and this is discussed in section :ref:`adc-api-adc-calibration`.
|
||||
.. only:: esp32 or esp32s2
|
||||
|
||||
.. todo::
|
||||
There is another specific function :cpp:func:`adc_vref_to_gpio` used to route internal reference voltage to a GPIO pin. It comes handy to calibrate ADC reading and this is discussed in section :ref:`adc-api-adc-calibration`.
|
||||
|
||||
1. Add `ADC-DMA mode` configuration after ADC-DMA driver done.
|
||||
2. Add table for ADC-DMA clock system.
|
||||
.. note:: See :ref:`adc_limitations` for the limitation of using ADC single read mode.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
.. only:: esp32 or esp32s2
|
||||
|
||||
Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
@ -75,10 +128,10 @@ Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
|
||||
adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_DB_0);
|
||||
int val = adc1_get_raw(ADC1_CHANNEL_0);
|
||||
|
||||
The input voltage in the above example is from 0 to 1.1 V (0 dB attenuation). The input range can be extended by setting a higher attenuation, see :cpp:type:`adc_atten_t`.
|
||||
An example of using the ADC driver including calibration (discussed below) is available at esp-idf: :example:`peripherals/adc`
|
||||
The input voltage in the above example is from 0 to 1.1 V (0 dB attenuation). The input range can be extended by setting a higher attenuation, see :cpp:type:`adc_atten_t`.
|
||||
An example of using the ADC driver including calibration (discussed below) is available at esp-idf: :example:`peripherals/adc/single_read/adc`
|
||||
|
||||
Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
|
||||
Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
@ -94,10 +147,10 @@ Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
|
||||
printf("ADC2 used by Wi-Fi.\n");
|
||||
}
|
||||
|
||||
The reading may fail due to collision with Wi-Fi, should check it.
|
||||
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc`
|
||||
The reading may fail due to collision with Wi-Fi, if the return value of this API is ``ESP_ERR_INVALID_STATE``, then the reading result is not valid.
|
||||
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc/single_read/adc2`
|
||||
|
||||
.. only:: esp32
|
||||
.. only:: esp32
|
||||
|
||||
Reading the internal hall effect sensor::
|
||||
|
||||
@ -109,46 +162,48 @@ An example using the ADC2 driver to read the output of DAC is available in esp-i
|
||||
int val = hall_sensor_read();
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
.. only:: esp32
|
||||
|
||||
The value read in both these examples is 12 bits wide (range 0-4095).
|
||||
|
||||
.. only:: esp32s2
|
||||
.. only:: esp32s2
|
||||
|
||||
The value read in both these examples is 13 bits wide (range 0-8191).
|
||||
|
||||
.. _adc-api-adc-calibration:
|
||||
.. _adc-api-adc-calibration:
|
||||
|
||||
Minimizing Noise
|
||||
----------------
|
||||
Minimizing Noise
|
||||
----------------
|
||||
|
||||
The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1 µF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
|
||||
.. figure:: ../../../_static/adc-noise-graph.jpg
|
||||
.. figure:: ../../../_static/adc-noise-graph.jpg
|
||||
:align: center
|
||||
:alt: ADC noise mitigation
|
||||
|
||||
Graph illustrating noise mitigation using capacitor and multisampling of 64 samples.
|
||||
|
||||
ADC Calibration
|
||||
---------------
|
||||
ADC Calibration
|
||||
---------------
|
||||
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV amongst different {IDF_TARGET_NAME}s.
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV amongst different {IDF_TARGET_NAME}s.
|
||||
|
||||
.. figure:: ../../../_static/adc-vref-graph.jpg
|
||||
.. figure:: ../../../_static/adc-vref-graph.jpg
|
||||
:align: center
|
||||
:alt: ADC reference voltage comparison
|
||||
|
||||
Graph illustrating effect of differing reference voltages on the ADC voltage curve.
|
||||
|
||||
Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of ``y = coeff_a * x + coeff_b`` and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user.
|
||||
Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of ``y = coeff_a * x + coeff_b`` and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user.
|
||||
|
||||
Calibration Values
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
Calibration Values
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Calibration values are used to generate characteristic curves that account for the variation of ADC reference voltage of a particular {IDF_TARGET_NAME} chip. There are currently three sources of calibration values on ESP32, and one source on ESP32-S2. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
|
||||
{IDF_TARGET_ADC_CALI_SOURCE: default="3", esp32="3", esp32s2="1"}
|
||||
|
||||
.. only:: esp32
|
||||
Calibration values are used to generate characteristic curves that account for the variation of ADC reference voltage of a particular {IDF_TARGET_NAME} chip. There are currently {IDF_TARGET_ADC_CALI_SOURCE} source(s) of calibration values on {IDF_TARGET_NAME}. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
* **Two Point** values represent each of the ADCs’ readings at 150 mV and 850 mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
|
||||
|
||||
@ -164,7 +219,7 @@ Calibration values are used to generate characteristic curves that account for t
|
||||
|
||||
ESP32 Chip Surface Marking
|
||||
|
||||
If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
|
||||
If you would like to purchase chips or modules with calibration, double check with distributor or Espressif (sales@espressif.com) directly.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
@ -191,9 +246,9 @@ Calibration values are used to generate characteristic curves that account for t
|
||||
ADC2 Low reading (150 mV): 389
|
||||
ADC2 High reading (850 mV): 3206
|
||||
|
||||
.. only:: esp32s2
|
||||
.. only:: esp32s2
|
||||
|
||||
* **eFuse Two Point** values calibrates the ADC output at two different voltages. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration on newly manufactured ESP32-S2 chips and modules. If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
|
||||
* **eFuse Two Point** values calibrates the ADC output at two different voltages. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration on newly manufactured ESP32-S2 chips and modules. If you would like to purchase chips or modules with calibration, double check with distributor or Espressif (sales@espressif.com) directly.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
@ -203,12 +258,18 @@ Calibration values are used to generate characteristic curves that account for t
|
||||
|
||||
Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
|
||||
|
||||
Application Example
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
.. only:: esp32c3
|
||||
|
||||
For a full example see esp-idf: :example:`peripherals/adc`
|
||||
The code example for using ADC single read mode and ADC continuous (DMA) read mode can be found in the :example:`peripherals/adc/esp32c3` directory of ESP-IDF examples.
|
||||
|
||||
Characterizing an ADC at a particular attenuation::
|
||||
.. only:: esp32 or esp32s2
|
||||
|
||||
Application Extensions
|
||||
----------------------
|
||||
|
||||
For a full example see esp-idf: :example:`peripherals/adc/single_read`
|
||||
|
||||
Characterizing an ADC at a particular attenuation::
|
||||
|
||||
#include "driver/adc.h"
|
||||
#include "esp_adc_cal.h"
|
||||
@ -227,7 +288,7 @@ Characterizing an ADC at a particular attenuation::
|
||||
printf("Default");
|
||||
}
|
||||
|
||||
Reading an ADC then converting the reading to a voltage::
|
||||
Reading an ADC then converting the reading to a voltage::
|
||||
|
||||
#include "driver/adc.h"
|
||||
#include "esp_adc_cal.h"
|
||||
@ -236,7 +297,7 @@ Reading an ADC then converting the reading to a voltage::
|
||||
uint32_t reading = adc1_get_raw(ADC1_CHANNEL_5);
|
||||
uint32_t voltage = esp_adc_cal_raw_to_voltage(reading, adc_chars);
|
||||
|
||||
Routing ADC reference voltage to GPIO, so it can be manually measured (for **Default Vref**)::
|
||||
Routing ADC reference voltage to GPIO, so it can be manually measured (for **Default Vref**)::
|
||||
|
||||
#include "driver/adc.h"
|
||||
|
||||
@ -255,8 +316,8 @@ GPIO Lookup Macros
|
||||
There are macros available to specify the GPIO number of a ADC channel, or vice versa.
|
||||
e.g.
|
||||
|
||||
1. ``ADC1_CHANNEL_0_GPIO_NUM`` is the GPIO number of ADC1 channel 0 (36);
|
||||
2. ``ADC1_GPIO32_CHANNEL`` is the ADC1 channel number of GPIO 32 (ADC1 channel 4).
|
||||
1. ``ADC1_CHANNEL_0_GPIO_NUM`` is the GPIO number of ADC1 channel 0.
|
||||
2. ``ADC1_GPIOn_CHANNEL`` is the ADC1 channel number of GPIO n.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Reference in New Issue
Block a user