adc

machine Module

Class ADC

---

ESP32 integrates two 12-bit SAR (Successive Approximation Register) ADCs (Analog to Digital Converters) and supports measurements on 18 channels (analog enabled pins).
The ADC driver API supports:

• ADC1 (8 channels, attached to GPIOs 32 - 39)
• ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27).

However, there’re some restrictions for the application to use ADC2:

• The application can use ADC2 only when Wi-Fi driver is not started, since the ADC is also used by the Wi-Fi driver, which has higher priority.
• Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15), so they cannot be used freely.
  For examples, for official Develop Kits:
  
  • ESP32 Core Board V2 / ESP32 DevKitC: GPIO 0 cannot be used due to external auto program circuits.
  • ESP-WROVER-KIT V3: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.

---

This class includes full support for using ESP32 **ADC** peripheral.
Functions are added to set the attenuation and to calibrate the ADC.

ESP32 ADC input voltage range depends on attenuation setting:

Attenuation	Voltage range
0 dB	1.1 V
2.5 dB	1.5 V
6 dB	2.2 V
11 dB	3.9 V

Note: Using ADC2 works, but as support for ADC2 in esp-idf is not fully functional, some error logs may br printed while using ADC2.

---

Create the adc instance object

adc = machine.ADC(pin [,unit=1])

pin argument defines the gpio which will will be used as adc input.
It can be given as integer pin number, or machine.Pin(n) object.
For ADC1 only GPIOs 32-39 can be used as ADC inputs.
For ADC2 gpios 4, 0, 2, 15, 13, 12, 14, 27, 25, 26 can be used as ADC inputs.
Be very carefull not to use the pins used by ESP32, especially the bootstrapping pins.
Use machine.ADC.HALL constant to select ESP32 Hall sensor as input.
If Hall sensor is used, gpio#36 and gpio#39 cannot be used as adc inputs at the same time.

Optional unit argument select ESP32 ADC unit for this instance. Values 1 (ADC1, default) or 2 (ADC2) can be selected.

Initially, the attenuation is set to 0 dB, and resolution to 12 bits.

>>> import machine
>>> adc=machine.ADC(34)
>>> adc
ADC(Pin(34): unit=ADC1, chan=6, width=12 bits, atten=0dB (1.1V), Vref=1100 mV)
>>> adc2=machine.ADC(25, unit=2)
>>> adc2
ADC(Pin(25): unit=ADC2, chan=8, width=12 bits, atten=0dB (1.1V), Vref=1100 mV)
>>> 

adc.deinit()

Deinitialize the adc, free the pin used.

adc.atten(value)

Set the attenuation value.

The following attenuation constants can be used for value:
ATTN_0DB - attenuation 0 dB (range: 0 - 1.1 V)
ATTN_2_5DB - attenuation 2.5 dB (range 0 - 1.5 V)
ATTN_6DB - attenuation 6 dB (range: 0 - 2.5 V)
ATTN_11DB - attenuation 11 dB (range: 0 - 3.9 V'

>>> adc.atten(adc.ATTN_11DB)
>>> adc
ADC(Pin(34): unit=ADC1, chan=6, width=12 bits, atten=11dB (3.9V), Vref=1100 mV)
>>> 

adc.width(value)

Configure ADC capture width..

The following constants can be used for value:
WIDTH_9BIT - capture width is 9Bit
WIDTH_10BIT - capture width is 10Bit
WIDTH_11BIT - capture width is 11Bit
WIDTH_12BIT - capture width is 12Bit

>>> adc.width(adc.WIDTH_10BIT)
>>> adc
ADC(Pin(34): unit=ADC1, chan=6, width=10 bits, atten=11dB (3.9V), Vref=1100 mV)
>>> 

machine.ADC.vref([vref=mv] [,] [vref_topin=pin])

Get or set ADC refference voltage and/or reference output pin.

The gain and offset factors of an ESP32 module's ADC are calculated using the reference voltage and the Gain and Offset curves provided in the lookup tables.
Nominal voltage refernce is 1100 mV, and can be adjusted to compensate for ESP32 chip differences.
The reference voltage can be set to any value in range 1000 ~ 1200 mV.
The internal ESP32 reference can be routed to gpio to be measured and the value used to set the reference voltage for the specific ESP32 chip.

To route the reference voltage to the gpio set the argument vref_topin to the gpio pin number to be used as output.
Valid gpios are only 25, 26 and 27.

Returns tuple containing the current refference voltage in mV and selected output pin.

# Get the reference voltage
>>> machine.ADC.vref()
(1100, 0)
# Route the internal reference voltage to GPIO#25
>>> machine.ADC.vref(vref_topin=25)
# You can now measure the voltage on GPIO#25 with the voltmeter

# Set the reference voltage to measured value in mV
# This value will be used to get more precise readings
>>> machine.ADC.vref(vref=1096)
(1096, 0)

adc.read()

Read the ADC value as voltage (in mV)

Calibrated read is used.
For hall sensor readings, the raw value is returned.

adc.readraw()

Read the raw ADC value as integer value in a range 0 ~ 2^width-1