OVMS3-idf/docs/api-reference/peripherals/adc.rst
Darian Leung 88b05f9391 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-29 18:43:14 +08:00

102 lines
No EOL
3.2 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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).
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.
It is also possible to read the internal hall effect sensor via ADC1.
Application Example
-------------------
A full example using the ADC driver and the esp_adc_cal is available in esp-idf: :example:`peripherals/adc`
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);
int val = adc1_get_raw(ADC1_CHANNEL_0);
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
-------------
.. include:: /_build/inc/adc.inc
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 drivers 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
-------------
.. include:: /_build/inc/esp_adc_cal.inc