documentation: update docs on ADC support for Espressif devices

fdcavalcanti · fdcavalcanti · commit e0fd5b55a76c · 2025-04-16T08:41:59.000-03:00
Add documentation for ADC on RISC-V and Xtensa Espressif devices.

Signed-off-by: Filipe Cavalcanti &lt;filipe.cavalcanti@espressif.com&gt;
diff --git a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst
@@ -53,6 +53,27 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+adc
+---
+
+The ``adc`` configuration enables the ADC driver and the ADC example application.
+ADC Unit 1 is registered to ``/dev/adc0`` with channels 0, 1, 2 and 3 enabled by default.
+Currently, the ADC operates in oneshot mode.
+
+More ADC channels can be enabled or disabled in ``ADC Configuration`` menu.
+
+This example shows channels 0 and 1 connected to 3.3 V and channels 2 and 3 to GND (all readings
+show in units of mV)::
+
+    nsh> adc -n 1
+    adc_main: g_adcstate.count: 1
+    adc_main: Hardware initialized. Opening the ADC device: /dev/adc0
+    Sample:
+    1: channel: 0 value: 2900
+    2: channel: 1 value: 2900
+    3: channel: 2 value: 0
+    4: channel: 3 value: 0
+
 ble
 ---
 
diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst
@@ -131,7 +131,7 @@ where:
 * ``ESPTOOL_BINDIR=./`` is the path of the externally-built 2nd stage bootloader and the partition table (if applicable): when built using the ``make bootloader``, these files are placed into ``nuttx`` folder.
 * ``ESPTOOL_BAUD`` is able to change the flash baud rate if desired.
 
-Flashing NSH Example 
+Flashing NSH Example
 --------------------
 
 This example shows how to build and flash the ``nsh`` defconfig for the ESP32-C3-DevKitC-02 board::
@@ -343,7 +343,7 @@ The following list indicates the state of peripherals' support in NuttX:
 =========== ======= ====================
 Peripheral  Support NOTES
 =========== ======= ====================
-ADC          No
+ADC          Yes    Oneshot
 AES          No
 Bluetooth    Yes
 CAN/TWAI     Yes
@@ -370,6 +370,38 @@ Watchdog     Yes     XTWDT supported
 Wi-Fi        Yes     WPA3-SAE supported
 =========== ======= ====================
 
+Analog-to-digital converter (ADC)
+---------------------------------
+
+Two ADC units are available for the ESP32-C3:
+
+* ADC1 with 5 channels.
+* ADC2 with 1 channel and internal voltage reading. **This unit is not implemented.**
+
+Those units are independent and can be used simultaneously. During bringup, GPIOs for selected channels are
+configured automatically to be used as ADC inputs.
+If available, ADC calibration is automatically applied (see
+`this page <https://docs.espressif.com/projects/esp-idf/en/v5.1/esp32c3/api-reference/peripherals/adc_calibration.html>`__ for more details).
+Otherwise, a simple conversion is applied based on the attenuation and resolution.
+
+The ADC unit is accessible using the ADC character driver, which returns data for the enabled channels.
+
+The ADC1 unit can be enabled in the menu :menuselection:`System Type --> Peripheral Support --> Analog-to-digital converter (ADC)`.
+
+Then, it can be customized in the menu :menuselection:`System Type --> ADC Configuration`, which includes operating mode, gain and channels.
+
+========== ===========
+ Channel    ADC1 GPIO
+========== ===========
+0           0
+1           1
+2           2
+3           3
+4           4
+========== ===========
+
+.. warning:: Maximum measurable voltage may saturate around 2900 mV.
+
 Secure Boot and Flash Encryption
 ================================
 
diff --git a/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst b/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst
@@ -88,6 +88,27 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+adc
+---
+
+The ``adc`` configuration enables the ADC driver and the ADC example application.
+ADC Unit 1 is registered to ``/dev/adc0`` with channels 0, 1, 2 and 3 enabled by default.
+Currently, the ADC operates in oneshot mode.
+
+More ADC channels can be enabled or disabled in ``ADC Configuration`` menu.
+
+This example shows channels 0 and 1 connected to 3.3 V and channels 2 and 3 to GND (all readings
+show in units of mV)::
+
+    nsh> adc -n 1
+    adc_main: g_adcstate.count: 1
+    adc_main: Hardware initialized. Opening the ADC device: /dev/adc0
+    Sample:
+    1: channel: 0 value: 3611
+    2: channel: 1 value: 3611
+    3: channel: 2 value: 103
+    4: channel: 3 value: 104
+
 bmp180
 ------
 
@@ -110,10 +131,10 @@ the following output is expected::
     nsh> cap
     cap_main: Hardware initialized. Opening the capture device: /dev/capture0
     cap_main: Number of samples: 0
-    pwm duty cycle: 50 % 
-    pwm frequence: 50 Hz 
-    pwm duty cycle: 50 % 
-    pwm frequence: 50 Hz 
+    pwm duty cycle: 50 %
+    pwm frequence: 50 Hz
+    pwm duty cycle: 50 %
+    pwm frequence: 50 Hz
 
 coremark
 --------
diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst b/Documentation/platforms/risc-v/esp32c6/index.rst
@@ -331,7 +331,7 @@ The following list indicates the state of peripherals' support in NuttX:
 ==============  ======= ====================
 Peripheral      Support NOTES
 ==============  ======= ====================
-ADC              No     Supports internal temperature sensor
+ADC              Yes     Oneshot and internal temperature sensor
 AES              No
 Bluetooth        No
 CAN/TWAI         Yes
@@ -363,6 +363,34 @@ Wi-Fi            Yes
 XTS              No
 ==============  ======= ====================
 
+Analog-to-digital converter (ADC)
+---------------------------------
+
+One ADC unit is available for the ESP32-C6, with 7 channels.
+
+During bringup, GPIOs for selected channels are configured automatically to be used as ADC inputs.
+If available, ADC calibration is automatically applied (see
+`this page <https://docs.espressif.com/projects/esp-idf/en/v5.1/esp32c6/api-reference/peripherals/adc_calibration.html>`__ for more details).
+Otherwise, a simple conversion is applied based on the attenuation and resolution.
+
+The ADC unit is accessible using the ADC character driver, which returns data for the enabled channels.
+
+The ADC unit can be enabled in the menu :menuselection:`System Type --> Peripheral Support --> Analog-to-digital converter (ADC)`.
+
+Then, it can be customized in the menu :menuselection:`System Type --> ADC Configuration`, which includes operating mode, gain and channels.
+
+========== ===========
+ Channel    ADC1 GPIO
+========== ===========
+0           0
+1           1
+2           2
+3           3
+4           4
+5           5
+6           6
+========== ===========
+
 _`Managing esptool on virtual environment`
 ==========================================
 
diff --git a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/index.rst b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/index.rst
@@ -6,7 +6,7 @@ ESP32-H2-DevKitM-1 is an entry-level development board based on Bluetooth® Low
 IEEE 802.15.4 combo module ESP32-H2-MINI-1 or ESP32-H2-MINI-1U. You can find the board schematic
 `here <https://espressif-docs.readthedocs-hosted.com/projects/esp-dev-kits/en/latest/_static/esp32-h2-devkitm-1/esp32-h2-devkitm-1_v1.2_schematics_20230306.pdf>`_.
 
-Most of the I/O pins on the ESP32-H2-MINI-1/1U module are broken out to the pin headers on 
+Most of the I/O pins on the ESP32-H2-MINI-1/1U module are broken out to the pin headers on
 both sides of this board for easy interfacing. Developers can either connect peripherals with
 jumper wires or mount ESP32-H2-DevKitM-1 on a breadboard.
 
@@ -87,6 +87,27 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+adc
+---
+
+The ``adc`` configuration enables the ADC driver and the ADC example application.
+ADC Unit 1 is registered to ``/dev/adc0`` with channels 0, 1, 2 and 3 enabled by default.
+Currently, the ADC operates in oneshot mode.
+
+More ADC channels can be enabled or disabled in ``ADC Configuration`` menu.
+
+This example shows channels 0 and 1 connected to 3.3 V and channels 2 and 3 to GND (all readings
+show in units of mV)::
+
+    nsh> adc -n 1
+    adc_main: g_adcstate.count: 1
+    adc_main: Hardware initialized. Opening the ADC device: /dev/adc0
+    Sample:
+    1: channel: 0 value: 3713
+    2: channel: 1 value: 3714
+    3: channel: 2 value: 1
+    4: channel: 3 value: 0
+
 bmp180
 ------
 
diff --git a/Documentation/platforms/risc-v/esp32h2/index.rst b/Documentation/platforms/risc-v/esp32h2/index.rst
@@ -332,7 +332,7 @@ The following list indicates the state of peripherals' support in NuttX:
 ==============  ======= ====================
 Peripheral      Support NOTES
 ==============  ======= ====================
-ADC              No     Supports internal temperature sensor
+ADC              Yes     Oneshot and internal temperature sensor
 AES              No
 Bluetooth        No
 CAN/TWAI         Yes
@@ -363,6 +363,32 @@ Wifi             No
 XTS              No
 ==============  ======= ====================
 
+Analog-to-digital converter (ADC)
+---------------------------------
+
+One ADC unit is available for the ESP32-H2, with 5 channels.
+
+During bringup, GPIOs for selected channels are configured automatically to be used as ADC inputs.
+If available, ADC calibration is automatically applied (see
+`this page <https://docs.espressif.com/projects/esp-idf/en/v5.1/esp32h2/api-reference/peripherals/adc_calibration.html>`__ for more details).
+Otherwise, a simple conversion is applied based on the attenuation and resolution.
+
+The ADC unit is accessible using the ADC character driver, which returns data for the enabled channels.
+
+The ADC unit can be enabled in the menu :menuselection:`System Type --> Peripheral Support --> Analog-to-digital converter (ADC)`.
+
+Then, it can be customized in the menu :menuselection:`System Type --> ADC Configuration`, which includes operating mode, gain and channels.
+
+========== ===========
+ Channel    ADC1 GPIO
+========== ===========
+0           1
+1           2
+2           3
+3           4
+4           5
+========== ===========
+
 _`Managing esptool on virtual environment`
 ==========================================
 
diff --git a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
@@ -163,6 +163,27 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+adc
+---
+
+The ``adc`` configuration enables the ADC driver and the ADC example application.
+ADC Unit 1 is registered to ``/dev/adc0`` with channels 0, 3 and 4 enabled by default.
+Currently, the ADC operates in oneshot mode.
+
+More ADC channels can be enabled or disabled in ``ADC Configuration`` menu.
+
+This example shows channels 0 and 4 connected to GND and channel 3 to 3.3 V (all readings
+show in units of mV)::
+
+    nsh> adc -n 1
+    adc_main: g_adcstate.count: 1
+    adc_main: Hardware initialized. Opening the ADC device: /dev/adc0
+    Sample:
+    1: channel: 0 value: 142
+    2: channel: 3 value: 3441
+    3: channel: 4 value: 142
+
+
 audio
 -----
 
diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst
@@ -389,7 +389,7 @@ The following list indicates the state of peripherals' support in NuttX:
 ========== ======= =====
 Peripheral Support NOTES
 ========== ======= =====
-ADC          No
+ADC          Yes    Oneshot
 AES          Yes
 Bluetooth    Yes
 Camera       No
@@ -688,6 +688,43 @@ audio subsystem and develop specific usages of the I2S peripheral.
 
 Please check for usage examples using the :doc:`ESP32 DevKitC </platforms/xtensa/esp32/boards/esp32-devkitc/index>`.
 
+Analog-to-digital converter (ADC)
+=================================
+
+Two ADC units are available for the ESP32:
+
+* ADC1 with 8 channels
+* ADC2 with 10 channels
+
+Those units are independent and can be used simultaneously. During bringup, GPIOs for selected channels are
+configured automatically to be used as ADC inputs.
+If available, ADC calibration is automatically applied (see
+`this page <https://docs.espressif.com/projects/esp-idf/en/v5.1/esp32/api-reference/peripherals/adc_calibration.html>`__ for more details).
+Otherwise, a simple conversion is applied based on the attenuation and resolution.
+
+Each ADC unit is accessible using the ADC character driver, which returns data for the enabled channels.
+
+The ADC unit can be enabled in the menu :menuselection:`System Type --> ESP32 Peripheral Selection --> Analog-to-digital converter (ADC)`.
+
+Then, it can be customized in the menu :menuselection:`System Type --> ADC Configuration`, which includes operating mode, gain and channels.
+
+========== =========== ===========
+ Channel    ADC1 GPIO   ADC2 GPIO
+========== =========== ===========
+0           36          4
+1           37          0
+2           38          2
+3           39          15
+4           32          13
+5           33          12
+6           34          14
+7           35          27
+8                       25
+9                       26
+========== =========== ===========
+
+.. warning:: ADC2 channels 1, 2 and 3 are used as strapping pins and can present undefined behavior.
+
 Using QEMU
 ==========
 
diff --git a/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst b/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst
@@ -98,6 +98,27 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+adc
+---
+
+The ``adc`` configuration enables the ADC driver and the ADC example application.
+ADC Unit 1 is registered to ``/dev/adc0`` with channels 0, 1, 2 and 3 enabled by default.
+Currently, the ADC operates in oneshot mode.
+
+More ADC channels can be enabled or disabled in ``ADC Configuration`` menu.
+
+This example shows channels 0 and 1 connected to 3.3 V and channels 2 and 3 to GND (all readings
+show in units of mV)::
+
+    nsh> adc -n 1
+    adc_main: g_adcstate.count: 1
+    adc_main: Hardware initialized. Opening the ADC device: /dev/adc0
+    Sample:
+    1: channel: 0 value: 3061
+    2: channel: 1 value: 3061
+    3: channel: 2 value: 106
+    4: channel: 3 value: 99
+
 audio
 -----
 
diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst
diff --git a/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst b/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst
