From 0c5505c4dea697fa633d4dc3fa9e872ab03b108a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Procha=CC=81zka?=
<90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Fri, 18 Feb 2022 13:21:27 +0100
Subject: [PATCH 1/4] Added ADC API doc + simple example
---
docs/source/api/adc.rst | 165 ++++++++++++++++++
.../ESP32/examples/AnalogRead/AnalogRead.ino | 19 ++
2 files changed, 184 insertions(+)
create mode 100644 docs/source/api/adc.rst
create mode 100644 libraries/ESP32/examples/AnalogRead/AnalogRead.ino
diff --git a/docs/source/api/adc.rst b/docs/source/api/adc.rst
new file mode 100644
index 00000000000..f2c3ec4b594
--- /dev/null
+++ b/docs/source/api/adc.rst
@@ -0,0 +1,165 @@
+###
+ADC
+###
+
+About
+-----
+
+ADC (analog to digital converter) is a very common peripheral used to convert an analogue 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 sensor, pressure sensor, force sensor) produce analogue output voltages.
+
+.. note:: Each board have ADC different number of ADC 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 ADC value for pin.
+
+.. code-block:: arduino
+
+ uint16_t analogRead(uint8_t pin);
+
+* ``pin`` GPIO pin to read analog value
+
+This function will return analog value.
+
+analogReadMillivolts
+^^^^^^^^^^^^^^^^^^^^
+
+This function is used to get ADC value for pin 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 ESP32 resolution between 9 and 12 will change 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.
+
+Default is 11db.
+
+.. code-block:: arduino
+
+ void analogSetAttenuation(adc_attenuation_t attenuation);
+
+* ``attenuation`` sets the attenuation.
+
+ * can be set to ADC_0db, ADC_2_5db, ADC_6db or ADC_11db.
+
+analogSetPinAttenuation
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is used to set the attenuation for a specific pin.
+
+Default is 11db.
+
+.. code-block:: arduino
+
+ void analogSetPinAttenuation(uint8_t pin, adc_attenuation_t attenuation);
+
+* ``pin`` selects specific pin for attenuation settings.
+* ``attenuation`` sets the attenuation.
+
+ * can be set to ADC_0db, ADC_2_5db, ADC_6db or ADC_11db.
+
+adcAttachPin
+^^^^^^^^^^^^
+
+This function is used to attach 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 ADC value of HALL sensor conneted to pins 36(SVP) and 39(SVN).
+
+.. code-block:: arduino
+
+ int hallRead();
+
+This function will return hall sensors 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.
\ No newline at end of file
diff --git a/libraries/ESP32/examples/AnalogRead/AnalogRead.ino b/libraries/ESP32/examples/AnalogRead/AnalogRead.ino
new file mode 100644
index 00000000000..c238517d380
--- /dev/null
+++ b/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
+}
From 08a187c6249976ae47ae2c42fa39d386d970b735 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Procha=CC=81zka?=
<90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Mon, 21 Feb 2022 12:00:00 +0100
Subject: [PATCH 2/4] Added attenuation input voltage range + conf.py added
tabs extension
---
docs/source/api/adc.rst | 59 +++++++++++++++++++++++++++++++++++------
docs/source/conf.py | 3 ++-
2 files changed, 53 insertions(+), 9 deletions(-)
diff --git a/docs/source/api/adc.rst b/docs/source/api/adc.rst
index f2c3ec4b594..075641e92db 100644
--- a/docs/source/api/adc.rst
+++ b/docs/source/api/adc.rst
@@ -80,22 +80,67 @@ analogSetAttenuation
This function is used to set the attenuation for all channels.
-Default is 11db.
+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.
-
- * can be set to ADC_0db, ADC_2_5db, ADC_6db or ADC_11db.
analogSetPinAttenuation
^^^^^^^^^^^^^^^^^^^^^^^
-This function is used to set the attenuation for a specific pin.
-
-Default is 11db.
+This function is used to set the attenuation for a specific pin. For more information refer to `analogSetAttenuation`_.
.. code-block:: arduino
@@ -103,8 +148,6 @@ Default is 11db.
* ``pin`` selects specific pin for attenuation settings.
* ``attenuation`` sets the attenuation.
-
- * can be set to ADC_0db, ADC_2_5db, ADC_6db or ADC_11db.
adcAttachPin
^^^^^^^^^^^^
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 36d9fbf4286..7fd7e721150 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -30,7 +30,8 @@
# 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.
From 8508d7c3caa48499059fc76573ae906642774f67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Procha=CC=81zka?=
<90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Mon, 21 Feb 2022 12:11:01 +0100
Subject: [PATCH 3/4] Update requirements.txt
---
docs/requirements.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0e4fb8ab59c..9e40946ec2b 100644
--- a/docs/requirements.txt
+++ b/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
\ No newline at end of file
From 6a16116cfef256ddd021904442f1176331126419 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Procha=CC=81zka?=
<90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Tue, 22 Feb 2022 09:30:56 +0100
Subject: [PATCH 4/4] Update adc.rst
---
docs/source/api/adc.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/docs/source/api/adc.rst b/docs/source/api/adc.rst
index 075641e92db..1947fdcf990 100644
--- a/docs/source/api/adc.rst
+++ b/docs/source/api/adc.rst
@@ -5,13 +5,13 @@ ADC
About
-----
-ADC (analog to digital converter) is a very common peripheral used to convert an analogue signal such as voltage
+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 sensor, pressure sensor, force sensor) produce analogue output voltages.
+(e.g., temperature, pressure, force) produce analogue output voltages.
-.. note:: Each board have ADC different number of ADC channels and pins availible. Refer to datasheet of each board for more info.
+.. 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
---------------------
@@ -22,7 +22,7 @@ ADC common API
analogRead
^^^^^^^^^^
-This function is used to get ADC value for pin.
+This function is used to get the ADC raw value for a given pin/ADC channel.
.. code-block:: arduino
@@ -30,12 +30,12 @@ This function is used to get ADC value for pin.
* ``pin`` GPIO pin to read analog value
-This function will return analog value.
+This function will return analog raw value.
analogReadMillivolts
^^^^^^^^^^^^^^^^^^^^
-This function is used to get ADC value for pin in millivolts.
+This function is used to get ADC value for a given pin/ADC channel in millivolts.
.. code-block:: arduino
@@ -48,13 +48,13 @@ 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)
+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 ESP32 resolution between 9 and 12 will change ADC hardware resolution. Else value will be shifted.
+.. 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
@@ -140,7 +140,7 @@ The measurable input voltage differs for each chip, see table below for detailed
analogSetPinAttenuation
^^^^^^^^^^^^^^^^^^^^^^^
-This function is used to set the attenuation for a specific pin. For more information refer to `analogSetAttenuation`_.
+This function is used to set the attenuation for a specific pin/ADC channel. For more information refer to `analogSetAttenuation`_.
.. code-block:: arduino
@@ -152,7 +152,7 @@ This function is used to set the attenuation for a specific pin. For more inform
adcAttachPin
^^^^^^^^^^^^
-This function is used to attach pin to ADC (it will also clear any other analog mode that could be on)
+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
@@ -188,13 +188,13 @@ This function is used to set pin to use for ADC calibration if the esp is not al
hallRead
^^^^^^^^
-This function is used to get ADC value of HALL sensor conneted to pins 36(SVP) and 39(SVN).
+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 hall sensors value.
+This function will return the hall sensor value.
Example Applications