-
Notifications
You must be signed in to change notification settings - Fork 7.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added ADC API doc + simple example (#6301)
* Added ADC API doc + simple example * Added attenuation input voltage range + conf.py added tabs extension * Update requirements.txt * Update adc.rst
- Loading branch information
1 parent
b5f3d6c
commit a135169
Showing
4 changed files
with
230 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,208 @@ | ||
### | ||
ADC | ||
### | ||
|
||
About | ||
----- | ||
|
||
ADC (analog to digital converter) is a very common peripheral used to convert an analog signal such as voltage | ||
to a digital form so that it can be read and processed by a microcontroller. | ||
|
||
ADCs are very useful in control and monitoring applications since most sensors | ||
(e.g., temperature, pressure, force) produce analogue output voltages. | ||
|
||
.. note:: Each SoC or module has a different number of ADC's with a different number of channels and pins availible. Refer to datasheet of each board for more info. | ||
|
||
Arduino-ESP32 ADC API | ||
--------------------- | ||
|
||
ADC common API | ||
************** | ||
|
||
analogRead | ||
^^^^^^^^^^ | ||
|
||
This function is used to get the ADC raw value for a given pin/ADC channel. | ||
|
||
.. code-block:: arduino | ||
uint16_t analogRead(uint8_t pin); | ||
* ``pin`` GPIO pin to read analog value | ||
|
||
This function will return analog raw value. | ||
|
||
analogReadMillivolts | ||
^^^^^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to get ADC value for a given pin/ADC channel in millivolts. | ||
|
||
.. code-block:: arduino | ||
uint32_t analogReadMilliVolts(uint8_t pin); | ||
* ``pin`` GPIO pin to read analog value | ||
|
||
This function will return analog value in millivolts. | ||
|
||
analogReadResolution | ||
^^^^^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to set the resolution of ``analogRead`` return value. Default is 12 bits (range from 0 to 4096) | ||
for all chips except ESP32S3 where default is 13 bits (range from 0 to 8192). | ||
When different resolution is set, the values read will be shifted to match the given resolution. | ||
|
||
Range is 1 - 16 .The default value will be used, if this function is not used. | ||
|
||
.. note:: For the ESP32, the resolution is between 9 to12 and it will change the ADC hardware resolution. Else value will be shifted. | ||
|
||
.. code-block:: arduino | ||
void analogReadResolution(uint8_t bits); | ||
* ``bits`` sets analog read resolution | ||
|
||
analogSetClockDiv | ||
^^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to set the divider for the ADC clock. | ||
|
||
Range is 1 - 255. Default value is 1. | ||
|
||
.. code-block:: arduino | ||
void analogSetClockDiv(uint8_t clockDiv); | ||
* ``clockDiv`` sets the divider for ADC clock. | ||
|
||
analogSetAttenuation | ||
^^^^^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to set the attenuation for all channels. | ||
|
||
Input voltages can be attenuated before being input to the ADCs. | ||
There are 4 available attenuation options, the higher the attenuation is, the higher the measurable input voltage could be. | ||
|
||
The measurable input voltage differs for each chip, see table below for detailed information. | ||
|
||
.. tabs:: | ||
|
||
.. tab:: ESP32 | ||
|
||
===================== =========================================== | ||
Attenuation Measurable input voltage range | ||
===================== =========================================== | ||
``ADC_ATTEN_DB_0`` 100 mV ~ 950 mV | ||
``ADC_ATTEN_DB_2_5`` 100 mV ~ 1250 mV | ||
``ADC_ATTEN_DB_6`` 150 mV ~ 1750 mV | ||
``ADC_ATTEN_DB_11`` 150 mV ~ 2450 mV | ||
===================== =========================================== | ||
|
||
.. tab:: ESP32-S2 | ||
|
||
===================== =========================================== | ||
Attenuation Measurable input voltage range | ||
===================== =========================================== | ||
``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV | ||
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV | ||
``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV | ||
``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV | ||
===================== =========================================== | ||
|
||
.. tab:: ESP32-C3 | ||
|
||
===================== =========================================== | ||
Attenuation Measurable input voltage range | ||
===================== =========================================== | ||
``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV | ||
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV | ||
``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV | ||
``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV | ||
===================== =========================================== | ||
|
||
.. tab:: ESP32-S3 | ||
|
||
===================== =========================================== | ||
Attenuation Measurable input voltage range | ||
===================== =========================================== | ||
``ADC_ATTEN_DB_0`` 0 mV ~ 950 mV | ||
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1250 mV | ||
``ADC_ATTEN_DB_6`` 0 mV ~ 1750 mV | ||
``ADC_ATTEN_DB_11`` 0 mV ~ 3100 mV | ||
===================== =========================================== | ||
|
||
.. code-block:: arduino | ||
void analogSetAttenuation(adc_attenuation_t attenuation); | ||
* ``attenuation`` sets the attenuation. | ||
|
||
analogSetPinAttenuation | ||
^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to set the attenuation for a specific pin/ADC channel. For more information refer to `analogSetAttenuation`_. | ||
|
||
.. code-block:: arduino | ||
void analogSetPinAttenuation(uint8_t pin, adc_attenuation_t attenuation); | ||
* ``pin`` selects specific pin for attenuation settings. | ||
* ``attenuation`` sets the attenuation. | ||
|
||
adcAttachPin | ||
^^^^^^^^^^^^ | ||
|
||
This function is used to attach the pin to ADC (it will also clear any other analog mode that could be on) | ||
|
||
.. code-block:: arduino | ||
bool adcAttachPin(uint8_t pin); | ||
This function will return ``true`` if configuration is successful. Else returns ``false``. | ||
|
||
ADC API specific for ESP32 chip | ||
******************************* | ||
|
||
analogSetWidth | ||
^^^^^^^^^^^^^^ | ||
|
||
This function is used to set the hardware sample bits and read resolution. | ||
Default is 12bit (0 - 4095). | ||
Range is 9 - 12. | ||
|
||
.. code-block:: arduino | ||
void analogSetWidth(uint8_t bits); | ||
analogSetVRefPin | ||
^^^^^^^^^^^^^^^^ | ||
|
||
This function is used to set pin to use for ADC calibration if the esp is not already calibrated (pins 25, 26 or 27). | ||
|
||
.. code-block:: arduino | ||
void analogSetVRefPin(uint8_t pin); | ||
* ``pin`` GPIO pin to set VRefPin for ADC calibration | ||
|
||
hallRead | ||
^^^^^^^^ | ||
|
||
This function is used to get the ADC value of the HALL sensor conneted to pins 36(SVP) and 39(SVN). | ||
|
||
.. code-block:: arduino | ||
int hallRead(); | ||
This function will return the hall sensor value. | ||
|
||
|
||
Example Applications | ||
******************** | ||
|
||
Here is an example of how to use the ADC. | ||
|
||
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogRead/AnalogRead.ino | ||
:language: arduino | ||
|
||
Or you can run Arduino example 01.Basics -> AnalogReadSerial. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
void setup() { | ||
// initialize serial communication at 115200 bits per second: | ||
Serial.begin(115200); | ||
|
||
//set the resolution to 12 bits (0-4096) | ||
analogReadResolution(12); | ||
} | ||
|
||
void loop() { | ||
// read the analog / millivolts value for pin 2: | ||
int analogValue = analogRead(2); | ||
int analogVolts = analogReadMilliVolts(2); | ||
|
||
// print out the values you read: | ||
Serial.printf("ADC analog value = %d\n",analogValue); | ||
Serial.printf("ADC millivolts value = %d\n",analogVolts); | ||
|
||
delay(100); // delay in between reads for clear read from serial | ||
} |