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

docs/requirements.txt

@@ -3,3 +3,4 @@
 #
 # matplotlib is currently required only by the script generate_chart.py
 sphinx-copybutton==0.3.0
+sphinx-tabs==3.2.0

docs/source/api/adc.rst

@@ -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.

docs/source/conf.py

@@ -30,7 +30,8 @@ release = '2.0.2'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx_copybutton'
+    'sphinx_copybutton',
+    'sphinx_tabs.tabs'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

libraries/ESP32/examples/AnalogRead/AnalogRead.ino

@@ -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
+}