DIY - ESP32：ESP32 ADC 模擬數碼轉換器 API 函數（四十六）

DIY - ESP32：ESP32 ADC 模擬數碼轉換器 API 函數（四十六）：

ESP32 在 IDF 內已經有 ADC（模擬數碼轉換器 / Analog to Digital Converter）API 函數模塊，主要用於設定和讀取 ADC。

ESP32 SAR ADC 的功能概況

功能 - adc1_pad_get_io_num

原型：esp_err_t adc1_pad_get_io_num(adc1_channel_t channel, gpio_num_t *gpio_num)

參數：channel: Channel to get the gpio number

            gpio_num: output buffer to hold the gpio number

返回：ESP_OK if success

            ESP_ERR_INVALID_ARG if channal not valid

說明：Get the gpio number of a specific ADC1 channel.

範例：

功能 - adc1_config_width

原型：esp_err_t adc1_config_width(adc_bits_width_t width_bit)

參數：width_bit: Bit capture width for ADC1

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Configure ADC1 capture width, meanwhile enable output invert for ADC1. The configuration is for all channels of ADC1.

範例：

功能 - adc_set_data_width

原型：esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit)

參數：adc_unit: ADC unit index

            width_bit: Bit capture width for ADC unit.

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Configure ADC capture width.

範例：

功能 - adc1_config_channel_atten

原型：esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten)

參數：channel: ADC1 channel to configure

            atten: Attenuation level

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.

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.

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.

When VDD_A is 3.3V:

0dB attenuaton (ADC_ATTEN_DB_0) gives full-scale voltage 1.1V

2.5dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5V

6dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2V

11dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9V (see note below)

Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges:

Note：The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured bit width, this value is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.)

Note：At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.

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.

範例：

功能 - adc1_get_raw

原型：int adc1_get_raw(adc1_channel_t channel)

參數：channel: ADC1 channel to read

返回：-1: Parameter error

            Other: ADC1 channel reading.

說明：Take an ADC1 reading from a single channel.

Note：When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue.

Note：Call adc1_config_width() 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.

範例：

功能 - adc_power_on

原型：void adc_power_on()

參數：

返回：

說明：Enable ADC power.

範例：

功能 - adc_power_off

原型：void adc_power_off()

參數：

返回：

說明：Power off SAR ADC This function will force power down for ADC.

範例：

功能 - adc_gpio_init

原型：esp_err_t adc_gpio_init(adc_unit_t adc_unit, adc_channel_t channel)

參數：adc_unit: ADC unit index

            channel: ADC channel index

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Initialize ADC pad.

範例：

功能 - adc_set_data_inv

原型：esp_err_t adc_set_data_inv(adc_unit_t adc_unit, bool inv_en)

參數：adc_unit: ADC unit index

            inv_en: whether enable data invert

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Set ADC data invert.

範例：

功能 - adc_set_clk_div

原型：esp_err_t adc_set_clk_div(uint8_t clk_div)

參數：clk_div: ADC clock divider, ADC clock is divided from APB clock

返回：ESP_OK success

說明：Set ADC source clock.

範例：

功能 - adc_set_i2s_data_source

原型：esp_err_t adc_set_i2s_data_source(adc_i2s_source_t src)

參數：src: I2S DMA data source, I2S DMA can get data from digital signals or from ADC.

返回：ESP_OK success

說明：Set I2S data source.

範例：

功能 - adc_i2s_mode_init

原型：esp_err_t adc_i2s_mode_init(adc_unit_t adc_unit, adc_channel_t channel)

參數：adc_unit: ADC unit index

            channel: ADC channel index

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Initialize I2S ADC mode.

範例：

功能 - adc1_ulp_enable

原型：void adc1_ulp_enable()

參數：

返回：

說明：Configure ADC1 to be usable by the ULP.

            This function reconfigures ADC1 to be controlled by the ULP. Effect of this function can be reverted using adc1_get_raw function. Note that adc1_config_channel_atten, adc1_config_width functions need to be called to configure ADC1 channels, before ADC1 is used by the ULP.

範例：

功能 - hall_sensor_read

原型：int hall_sensor_read()

參數：

返回：The hall sensor reading.

說明：Read Hall Sensor.

Note：When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue.

Note：The Hall Sensor uses channels 0 and 3 of ADC1. Do not configure these channels for use as ADC channels.

Note：The ADC1 module must be enabled by calling adc1_config_width() before calling hall_sensor_read(). ADC1 should be configured for 12 bit readings, as the hall sensor readings are low values and do not cover the full range of the ADC.

範例：

功能 - adc2_pad_get_io_num

原型：esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num)

參數：channel: Channel to get the gpio number

            gpio_num: output buffer to hold the gpio number

返回：ESP_OK if success

            ESP_ERR_INVALID_ARG if channal not valid

說明：Get the gpio number of a specific ADC2 channel.

範例：

功能 - adc2_config_channel_atten

原型：esp_err_t adc2_config_channel_atten(adc2_channel_t channel, adc_atten_t atten)

參數：channel: ADC2 channel to configure

            atten: Attenuation level

返回：ESP_OK success

            ESP_ERR_INVALID_ARG Parameter error

說明：Configure the ADC2 channel, including setting attenuation. 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.

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.

When VDD_A is 3.3V:

0dB attenuaton (ADC_ATTEN_0db) gives full-scale voltage 1.1V

2.5dB attenuation (ADC_ATTEN_2_5db) gives full-scale voltage 1.5V

6dB attenuation (ADC_ATTEN_6db) gives full-scale voltage 2.2V

11dB attenuation (ADC_ATTEN_11db) gives full-scale voltage 3.9V (see note below)

Note：The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC2 configured bit width, this value is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.)

Note：At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.

範例：

功能 - adc2_get_raw

原型：esp_err_t adc2_get_raw(adc2_channel_t channel, adc_bits_width_t width_bit, int *raw_out)

參數：channel: ADC2 channel to read

            width_bit: Bit capture width for ADC2

            raw_out: the variable to hold the output data.

返回：ESP_OK if success

            ESP_ERR_TIMEOUT the WIFI is started, using the ADC2

說明：Take an ADC2 reading on a single channel.

Note：When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue.

Note：For a given channel, adc2_config_channel_atten() must be called before the first time this function is called. If Wi-Fi is started via esp_wifi_start(), this function will always fail with ESP_ERR_TIMEOUT.

範例：

功能 - adc2_vref_to_gpio

原型：esp_err_t adc2_vref_to_gpio(gpio_num_t gpio)

參數：gpio: GPIO number (gpios 25,26,27 supported)

返回：ESP_OK: v_ref successfully routed to selected gpio

            ESP_ERR_INVALID_ARG: Unsupported gpio

說明：Output ADC2 reference voltage to gpio 25 or 26 or 27. This function utilizes the testing mux exclusive to ADC 2 to route the reference voltage one of ADC2’s channels. Supported gpios are gpios 25, 26, and 27. This refernce voltage can be manually read from the pin and used in the esp_adc_cal component.

範例：   

2018年 12月 6日 天氣報告

氣溫：24.6度 @ 19:10

相對濕度：百分之 76%

天氣：多雲

相關網址：
※ DIY - ESP32：ESP32 ADC 模擬數碼轉換器介紹 （四十三）
※ DIY - ESP32：ESP32 ADC / DAC 模擬數碼轉換器電路 （四十四）
※ DIY - ESP32：ESP32 ADC / DAC 模擬數碼轉換器程式 （四十五）
※ DIY - ESP32：ESP32 ADC 模擬數碼轉換器 API 函數巨集及其它（四十七）
※ DIY - ESP32：ESP32 DAC 數位類比轉換器 API 函數（四十八）
※ DIY - ESP32：ESP32 DAC數位類比轉換器 API 函數巨集及其它（四十九）
※ DIY - ESP32：ESP32 ADC 類比數位轉換器測試（五十）
※ DIY - ESP32：ESP32 ADC DVM 數字電壓錶電路（五十一）
※ DIY - ESP32：ESP32 ADC DVM 數字電壓錶程式 （五十二）