Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
OVMS3-idf/docs/api-reference/peripherals/adc.rst

112 lines
3.6 KiB
ReStructuredText
Raw Normal View History

docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
Analog to Digital Converter
===========================
Overview
--------
ESP32 integrates two 12-bit SAR ("Successive Approximation Register") ADCs (Analog to Digital Converters) and supports measurements on 18 channels (analog enabled pins). Some of these pins can be used to build a programmable gain amplifier which is used for the measurement of small
analog signals.
The ADC driver API currently only supports ADC1 (9 channels, attached to GPIOs 32-39).
esp_adc_cal: Added ADC calibration component Added component containg API that is able to correct raw ADC readings into a voltage in mV. Also provided a helper function that combines the process of getting the raw ADC1 reading then converting it to a voltage in mV. In doing so, the adc1_get_voltage() function of the ADC driver has been deprecated. Instead there is now adc1_get_raw to obtain the raw ADC1 reading, and adc1_to_voltage() that gets the raw reading and converts all in one function. Functions using the deprecated adc1_get_voltage() have also been updated to use adc1_get_raw(). Conversion is based on ADC characteristics. The characteristics are based on the ADC's v_ref, herefore the appropriate structure and functions have been provided to obtain the ADC characteristics. The existing ADC driver has also been modified by adding a function to route the internal ADC reference voltage to a GPIO allowing users to measure it manually. Relevant documentation has also been updated
2017-08-07 13:33:01 +00:00
Taking an ADC reading involves configuring the ADC with the desired precision and attentuation settings, and then calling adc1_get_raw() to read the channel.
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
It is also possible to read the internal hall effect sensor via ADC1.
Application Example
-------------------
esp_adc_cal: Added ADC calibration component Added component containg API that is able to correct raw ADC readings into a voltage in mV. Also provided a helper function that combines the process of getting the raw ADC1 reading then converting it to a voltage in mV. In doing so, the adc1_get_voltage() function of the ADC driver has been deprecated. Instead there is now adc1_get_raw to obtain the raw ADC1 reading, and adc1_to_voltage() that gets the raw reading and converts all in one function. Functions using the deprecated adc1_get_voltage() have also been updated to use adc1_get_raw(). Conversion is based on ADC characteristics. The characteristics are based on the ADC's v_ref, herefore the appropriate structure and functions have been provided to obtain the ADC characteristics. The existing ADC driver has also been modified by adding a function to route the internal ADC reference voltage to a GPIO allowing users to measure it manually. Relevant documentation has also been updated
2017-08-07 13:33:01 +00:00
A full example using the ADC driver and the esp_adc_cal is available in esp-idf: :example:`peripherals/adc`
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
Reading voltage on ADC1 channel 0 (GPIO 36)::
#include <driver/adc.h>
...
adc1_config_width(ADC_WIDTH_12Bit);
adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_0db);
esp_adc_cal: Added ADC calibration component Added component containg API that is able to correct raw ADC readings into a voltage in mV. Also provided a helper function that combines the process of getting the raw ADC1 reading then converting it to a voltage in mV. In doing so, the adc1_get_voltage() function of the ADC driver has been deprecated. Instead there is now adc1_get_raw to obtain the raw ADC1 reading, and adc1_to_voltage() that gets the raw reading and converts all in one function. Functions using the deprecated adc1_get_voltage() have also been updated to use adc1_get_raw(). Conversion is based on ADC characteristics. The characteristics are based on the ADC's v_ref, herefore the appropriate structure and functions have been provided to obtain the ADC characteristics. The existing ADC driver has also been modified by adding a function to route the internal ADC reference voltage to a GPIO allowing users to measure it manually. Relevant documentation has also been updated
2017-08-07 13:33:01 +00:00
int val = adc1_get_raw(ADC1_CHANNEL_0);
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
Reading the internal hall effect sensor::
#include <driver/adc.h>
...
adc1_config_width(ADC_WIDTH_12Bit);
int val = hall_sensor_read();
The value read in both these examples is 12 bits wide (range 0-4095).
API Reference
-------------
docs: Generate Doxygen directives for API documentation This is to resolve issue reported in https://github.com/espressif/esp-idf/issues/130.
2017-05-02 08:36:01 +00:00
.. include:: /_build/inc/adc.inc
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
feat(global): add macros for GPIO->channel lookup including: macros for dac, adc, touch, rtc_gpio, uart and clk_out. TW#13970
2017-08-29 07:52:04 +00:00
GPIO Lookup Macros
^^^^^^^^^^^^^^^^^^
Some useful macros can be used to specified 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).
.. include:: /_build/inc/adc_channel.inc
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
2017-02-16 02:59:50 +00:00
esp_adc_cal: Added ADC calibration component Added component containg API that is able to correct raw ADC readings into a voltage in mV. Also provided a helper function that combines the process of getting the raw ADC1 reading then converting it to a voltage in mV. In doing so, the adc1_get_voltage() function of the ADC driver has been deprecated. Instead there is now adc1_get_raw to obtain the raw ADC1 reading, and adc1_to_voltage() that gets the raw reading and converts all in one function. Functions using the deprecated adc1_get_voltage() have also been updated to use adc1_get_raw(). Conversion is based on ADC characteristics. The characteristics are based on the ADC's v_ref, herefore the appropriate structure and functions have been provided to obtain the ADC characteristics. The existing ADC driver has also been modified by adding a function to route the internal ADC reference voltage to a GPIO allowing users to measure it manually. Relevant documentation has also been updated
2017-08-07 13:33:01 +00:00
ADC Calibration
===============
Overview
--------
The esp_adc_cal API provides functions to correct for differences in measured voltages caused by non-ideal ADC reference voltages in ESP32s. The ideal ADC reference voltage is 1100mV however the reference voltage of different ESP32s can range from 1000mV to 1200mV.
Correcting the measured voltage using the esp_adc_cal API involves referencing a lookup table of voltages. The voltage obtained from the lookup table is the scaled and shifted by a gain and offset factor that is based on the ADC's reference voltage.
The reference voltage of the ADCs can be routed to certain GPIOs and measured manually using the ADC driver’s adc2_vref_to_gpio() function.
Application Example
-------------------
Reading the ADC and obtaining a result in mV::
#include <driver/adc.h>
#include <esp_adc_cal.h>
...
#define V_REF 1100 //ADC reference voltage
//Config ADC and characteristics
adc1_config_width(ADC_WIDTH_12Bit);
adc1_config_channel_atten(ADC1_CHANNEL_6, ADC_ATTEN_11db);
//Calculate ADC characteristics i.e. gain and offset factors
esp_adc_cal_characteristics_t characteristics;
esp_adc_cal_get_characteristics(V_REF, ADC_ATTEN_11db, ADC_WIDTH_12Bit, &characteristics);
//Read ADC and obtain result in mV
uint32_t voltage = adc1_to_voltage(ADC1_CHANNEL_6, &characteristics);
printf("%d mV\n",voltage);
Routing ADC reference voltage to GPIO::
#include <driver/adc.h>
#include <driver/gpio.h>
#include <esp_err.h>
...
esp_err_t status = adc2_vref_to_gpio(GPIO_NUM_25);
if (status == ESP_OK){
printf("v_ref routed to GPIO\n");
}else{
printf("failed to route v_ref\n");
}
API Reference
-------------
feat(global): add macros for GPIO->channel lookup including: macros for dac, adc, touch, rtc_gpio, uart and clk_out. TW#13970
2017-08-29 07:52:04 +00:00
.. include:: /_build/inc/esp_adc_cal.inc
Reference in a new issue Copy permalink