From 4507b3fde6ca3cfb43464e3d30b28a8bba64dee1 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 27 Mar 2018 10:46:11 +1100 Subject: [PATCH] adc: Add doc details about configure not needed before each read --- components/driver/include/driver/adc.h | 28 +++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/components/driver/include/driver/adc.h b/components/driver/include/driver/adc.h index ccbe85014..e6c6df1a4 100644 --- a/components/driver/include/driver/adc.h +++ b/components/driver/include/driver/adc.h @@ -147,11 +147,15 @@ esp_err_t adc1_config_width(adc_bits_width_t width_bit); esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit); /** - * @brief Configure the ADC1 channel, including setting attenuation. + * @brief Set the attenuation of a particular channel on ADC1, and configure its + * associated GPIO pin mux. * - * @note This function also configures the input GPIO pin mux to - * connect it to the ADC1 channel. It must be called before calling - * adc1_get_raw() for this channel. + * @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. adc1_get_raw() can then be called for any configured + * channel. * * The default ADC full-scale voltage is 1.1V. To read higher voltages (up to the pin maximum voltage, * usually 3.3V) requires setting >0dB signal attenuation for that ADC channel. @@ -168,6 +172,15 @@ esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit); * * @note At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage. * + * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges: + * + * - 0dB attenuaton (ADC_ATTEN_DB_0) between 100 and 950mV + * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) between 100 and 1250mV + * - 6dB attenuation (ADC_ATTEN_DB_6) between 150 to 1750mV + * - 11dB attenuation (ADC_ATTEN_DB_11) between 150 to 2450mV + * + * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges. + * * @param channel ADC1 channel to configure * @param atten Attenuation level * @@ -178,13 +191,14 @@ esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit); esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten); /** - * @brief Take an ADC1 reading on a single channel + * @brief Take an ADC1 reading from a single channel. * * @note Call adc1_config_width() before the first time this * function is called. * - * @note For a given channel, adc1_config_channel_atten(channel) - * must be called before the first time this function is called. + * @note For any given channel, adc1_config_channel_atten(channel) + * must be called before the first time this function is called. Configuring + * a new channel does not prevent a previously configured channel from being read. * * @param channel ADC1 channel to read *