diff --git a/components/driver/include/driver/adc_common.h b/components/driver/include/driver/adc_common.h index 38e4d9dd8a..6e19d00d4d 100644 --- a/components/driver/include/driver/adc_common.h +++ b/components/driver/include/driver/adc_common.h @@ -144,58 +144,48 @@ esp_err_t adc_gpio_init(adc_unit_t adc_unit, adc_channel_t channel); esp_err_t adc1_pad_get_io_num(adc1_channel_t channel, gpio_num_t *gpio_num); /** - * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux. - * - * The default ADC full-scale voltage is 1.1 V. To read higher voltages (up to the pin maximum voltage, - * usually 3.3 V) requires setting >0 dB signal attenuation for that ADC channel. - * - * When the analog voltage supply (VDDA) is 3.3 V: - * - * - 0 dB attenuation (ADC_ATTEN_DB_0) gives full-scale voltage 1.1 V - * - 2.5 dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5 V - * - 6 dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2 V - * - 11 dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9 V (see note below) - * - * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges: - * - * +----------+------------+--------------------------+ - * | SoC | attenuation| suggested range (mV) | - * +==========+============+==========================+ - * | | 0 | 100 ~ 950 | - * | +------------+--------------------------+ - * | | 2.5 | 100 ~ 1250 | - * | ESP32 +------------+--------------------------+ - * | | 6 | 150 ~ 1750 | - * | +------------+--------------------------+ - * | | 11 | 150 ~ 2450 | - * +----------+------------+--------------------------+ - * | | 0 | 100 ~ 800 | - * | +------------+--------------------------+ - * | | 2.5 | 100 ~ 1100 | - * | ESP32-S2 +------------+--------------------------+ - * | | 6 | 150 ~ 1350 | - * | +------------+--------------------------+ - * | | 11 | 150 ~ 2600 | - * +----------+------------+--------------------------+ - * - * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges. - * @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured bit width, - * this value in ESP32 is 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits. - * this value in ESP32-S2 is 8191 for 13-bits.) - * - * @note At 11 dB attenuation the maximum voltage is limited by VDDA, not the full scale voltage. - * - * @note For any given channel, this function must be called before the first time ``adc1_get_raw()`` is called for that channel. - * - * @note This function can be called multiple times to configure multiple - * ADC channels simultaneously. You may call ``adc1_get_raw()`` only after configuring a channel. - * - * @param channel ADC1 channel to configure - * @param atten Attenuation level - * - * @return - * - ESP_OK success - * - ESP_ERR_INVALID_ARG Parameter error + * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux. + * + * The default ADC voltage is for attenuation 0 dB and listed in the table below. + * By setting higher attenuation it is possible to read higher voltages. + * + * Due to ADC characteristics, most accurate results are obtained within the "suggested range" + * shown in the following table. + * + * +----------+-------------+-----------------+ + * | | attenuation | suggested range | + * | SoC | (dB) | (mV) | + * +==========+=============+=================+ + * | | 0 | 100 ~ 950 | + * | +-------------+-----------------+ + * | | 2.5 | 100 ~ 1250 | + * | ESP32 +-------------+-----------------+ + * | | 6 | 150 ~ 1750 | + * | +-------------+-----------------+ + * | | 11 | 150 ~ 2450 | + * +----------+-------------+-----------------+ + * | | 0 | 0 ~ 750 | + * | +-------------+-----------------+ + * | | 2.5 | 0 ~ 1050 | + * | ESP32-S2 +-------------+-----------------+ + * | | 6 | 0 ~ 1300 | + * | +-------------+-----------------+ + * | | 11 | 0 ~ 2500 | + * +----------+-------------+-----------------+ + * + * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges. + * + * @note For any given channel, this function must be called before the first time ``adc1_get_raw()`` is called for that channel. + * + * @note This function can be called multiple times to configure multiple + * ADC channels simultaneously. You may call ``adc1_get_raw()`` only after configuring a channel. + * + * @param channel ADC1 channel to configure + * @param atten Attenuation level + * + * @return + * - ESP_OK success + * - ESP_ERR_INVALID_ARG Parameter error */ esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten); @@ -292,26 +282,40 @@ esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num); /** * @brief Configure the ADC2 channel, including setting attenuation. * - * The default ADC full-scale voltage is 1.1 V. To read higher voltages (up to the pin maximum voltage, - * usually 3.3 V) requires setting >0 dB signal attenuation for that ADC channel. + * The default ADC voltage is for attenuation 0 dB and listed in the table below. + * By setting higher attenuation it is possible to read higher voltages. * - * When the analog voltage supply (VDDA) is 3.3 V: + * Due to ADC characteristics, most accurate results are obtained within the "suggested range" + * shown in the following table. * - * - 0 dB attenuation (ADC_ATTEN_0db) gives full-scale voltage 1.1 V - * - 2.5 dB attenuation (ADC_ATTEN_2_5db) gives full-scale voltage 1.5 V - * - 6 dB attenuation (ADC_ATTEN_6db) gives full-scale voltage 2.2 V - * - 11 dB attenuation (ADC_ATTEN_11db) gives full-scale voltage 3.9 V (see note below) + * +----------+-------------+-----------------+ + * | | attenuation | suggested range | + * | SoC | (dB) | (mV) | + * +==========+=============+=================+ + * | | 0 | 100 ~ 950 | + * | +-------------+-----------------+ + * | | 2.5 | 100 ~ 1250 | + * | ESP32 +-------------+-----------------+ + * | | 6 | 150 ~ 1750 | + * | +-------------+-----------------+ + * | | 11 | 150 ~ 2450 | + * +----------+-------------+-----------------+ + * | | 0 | 0 ~ 750 | + * | +-------------+-----------------+ + * | | 2.5 | 0 ~ 1050 | + * | ESP32-S2 +-------------+-----------------+ + * | | 6 | 0 ~ 1300 | + * | +-------------+-----------------+ + * | | 11 | 0 ~ 2500 | + * +----------+-------------+-----------------+ + * + * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges. * * @note This function also configures the input GPIO pin mux to * connect it to the ADC2 channel. It must be called before calling * ``adc2_get_raw()`` for this channel. * - * @note The full-scale voltage is the voltage corresponding to a maximum reading - * (depending on ADC2 configured bit width, - * this value for ESP32 is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits. - * this value for ESP32-S2 is: 8191 for 13-bits.) - * - * @note At 11 dB attenuation the maximum voltage is limited by VDDA, not the full scale voltage. + * @note For any given channel, this function must be called before the first time ``adc2_get_raw()`` is called for that channel. * * @param channel ADC2 channel to configure * @param atten Attenuation level