ADC 模数转换器

API

专题

ESP32

ADC（模数转换器）是一种非常常见的外设，用于将电压等模拟信号转换为数字形式，以便微控制器可以读取和处理。

ADC 在控制和监控应用中非常有用，因为大多数传感器（例如温度、压力、力）都会产生模拟输出电压。

注意

每个 SoC 或模块都有不同数量的 ADC，具有不同数量的可用通道和引脚。有关更多信息，请参阅每个板的数据表。

Arduino-ESP32 ADC API

ADC OneShot 模式

ADC OneShot 模式 API 与 Arduino 的 analogRead 函数完全兼容。调用 analogRead 或 analogReadMilliVolts 函数时，它会返回请求的引脚上单个转换的结果。

analogRead

此函数用于获取给定 pin/ADC 通道的 ADC 原始值。

uint16_t analogRead(uint8_t pin);

pin GPIO 模拟引脚

此函数将返回模拟原始值（未校准）。

analogReadMilliVolts

此函数用于获取给定引脚/ADC 通道的 ADC 原始值，并将其转换为以毫伏为单位的校准结果。

uint32_t analogReadMilliVolts(uint8_t pin);

pin GPIO 模拟引脚

此函数将返回以毫伏为单位的模拟值（校准）。

analogReadResolution

该函数用于设置 analogRead 返回值的分辨率。除 ESP32-S3 外，所有芯片的默认值均为 12 位（范围从 0 到 4095），ESP32-S3 的默认值为 13 位（范围从 0 到 8191）。当设置不同的分辨率时，读取的值将移动以匹配给定的分辨率。

范围为 1 - 16 。如果不使用此函数，则将使用默认值。

注意

对于 ESP32，分辨率在 9 到 12 之间，它会改变 ADC 硬件分辨率。否则 value 将被移动。

void analogReadResolution(uint8_t bits);

bits 设置模拟读取分辨率

analogSetAttenuation

此功能用于设置所有通道的衰减。

输入电压在输入到 ADC 之前可以衰减。有 4 个可用的衰减选项，衰减越高，可测量的输入电压就越高。

每个芯片的可测量输入电压不同，有关详细信息，请参见下表。

.. tabs::

   .. tab:: ESP32

      =====================  ===========================================
      Attenuation            Measurable input voltage range
      =====================  ===========================================
      ``ADC_ATTEN_DB_0``     100 mV ~ 950 mV
      ``ADC_ATTEN_DB_2_5``   100 mV ~ 1250 mV
      ``ADC_ATTEN_DB_6``     150 mV ~ 1750 mV
      ``ADC_ATTEN_DB_11``    150 mV ~ 3100 mV
      =====================  ===========================================

   .. tab:: ESP32-S2

      =====================  ===========================================
      Attenuation            Measurable input voltage range
      =====================  ===========================================
      ``ADC_ATTEN_DB_0``     0 mV ~ 750 mV
      ``ADC_ATTEN_DB_2_5``   0 mV ~ 1050 mV
      ``ADC_ATTEN_DB_6``     0 mV ~ 1300 mV
      ``ADC_ATTEN_DB_11``    0 mV ~ 2500 mV
      =====================  ===========================================

   .. tab:: ESP32-C3

      =====================  ===========================================
      Attenuation            Measurable input voltage range
      =====================  ===========================================
      ``ADC_ATTEN_DB_0``     0 mV ~ 750 mV
      ``ADC_ATTEN_DB_2_5``   0 mV ~ 1050 mV
      ``ADC_ATTEN_DB_6``     0 mV ~ 1300 mV
      ``ADC_ATTEN_DB_11``    0 mV ~ 2500 mV
      =====================  ===========================================

   .. tab:: ESP32-S3

      =====================  ===========================================
      Attenuation            Measurable input voltage range
      =====================  ===========================================
      ``ADC_ATTEN_DB_0``     0 mV ~ 950 mV
      ``ADC_ATTEN_DB_2_5``   0 mV ~ 1250 mV
      ``ADC_ATTEN_DB_6``     0 mV ~ 1750 mV
      ``ADC_ATTEN_DB_11``    0 mV ~ 3100 mV
      =====================  ===========================================

void analogSetAttenuation(adc_attenuation_t attenuation);

attenuation 设置衰减。

analogSetPinAttenuation

此功能用于设置特定引脚/ADC 通道的衰减。有关更多信息，请参阅 analogSetAttenuation。

void analogSetPinAttenuation(uint8_t pin, adc_attenuation_t attenuation);

pin 选择用于 Attenuation Settings 的特定 pin。
attenuation 设置衰减。

analogSetWidth

注意

该功能仅适用于 ESP32 芯片。

此函数用于设置硬件采样位和读取分辨率。默认值为 12 位（0 - 4095）。范围为 9 - 12。

void analogSetWidth(uint8_t bits);

ADC Continuous mode （连续模式）

ADC Continuous 模式是一个 API，旨在在后台对多个引脚执行模拟转换，其功能是在完成这些转换后接收回调以访问结果。

此 API 允许您指定单个周期内每个 pin 所需的转换次数，以及相应的采样率。analogContinuousRead 函数的结果是 adc_continuous_data_t 结构的数组。这些结构同时包含每个引脚的原始平均值和以毫伏为单位的平均值。

analogContinuous 模拟连续

此功能用于在所选引脚上配置 ADC continuous 外设。

bool analogContinuous(const uint8_t pins[], size_t pins_count, uint32_t conversions_per_pin, uint32_t sampling_freq_hz, void (*userFunc)(void));

pins[] 要设置的 pins 数组
pins_count 数组中的引脚数
conversions_per_pin 设置每个 ADC 周期将运行每个引脚的转换次数
sampling_freq_hz 设置 ADC 的采样频率（以 Hz 为单位）
userFunc 设置回调函数在 adc 转换完成后调用（可设置为 NULL）

如果配置成功，此函数将返回 true。如果返回 false，则发生错误，并且未配置 ADC continuous。

analogContinuousRead

此功能用于将 ADC 连续数据读取到结果缓冲区。结果缓冲区是一个 adc_continuous_data_t 数组。

typedef struct {
    uint8_t pin;           /*!<ADC pin */
    uint8_t channel;       /*!<ADC channel */
    int avg_read_raw;      /*!<ADC average raw data */
    int avg_read_mvolts;   /*!<ADC average voltage in mV */
} adc_continuous_data_t;

bool analogContinuousRead(adc_continuous_data_t ** buffer, uint32_t timeout_ms);

buffer conversion result buffer 以 adc_continuous_data_t 格式从 ADC 读取。
timeout_ms 等待数据的时间（以毫秒为单位）。

如果读取成功并且缓冲区填充了数据，则此函数将返回 true。如果返回 false，则读取失败，buffer 设置为 NULL。

analogContinuousStart

此功能用于启动 ADC 连续转换。

bool analogContinuousStart();

如果 ADC Continuous 成功启动，此函数将返回 true。如果返回 false，则表示启动 ADC Continuous 失败。

analogContinuousStop analogContinuousStop 控制器

此功能用于停止 ADC 连续转换。

bool analogContinuousStop();

如果 ADC continuous 成功停止，此函数将返回 true。如果返回 false，则表示停止 ADC continuous 失败。

analogContinuousDeinit

此函数用于取消初始化 ADC continuous peripheral。

bool analogContinuousDeinit();

如果 ADC continuous 成功取消初始化，则此函数将返回 true。如果返回 false，则表示 ADC continuous 的去初始化失败。

analogContinuousSetAtten

此功能用于设置 ADC 连续外设的衰减。有关更多信息，请参阅 analogSetAttenuation。

void analogContinuousSetAtten(adc_attenuation_t attenuation);

attenuation 设置衰减（默认值为 11 dB）。

analogContinuousSetWidth

此函数用于设置硬件分辨率位。所有芯片的默认值为 12 位（0 - 4095）。

注意

该功能仅对 ESP32 芯片有效，因为它允许在 9-12 位范围内设置分辨率。

void analogContinuousSetWidth(uint8_t bits);

bits 设置分辨率位。

Example Applications 示例应用

以下是如何在 OneShot 模式下使用 ADC 的示例，或者您可以运行 Arduino 示例 01.Basics -> AnalogReadSerial。

examples/AnalogRead/AnalogRead.ino

以下是如何在 Continuous 模式下使用 ADC 的示例。

examples/AnalogReadContinuous/AnalogReadContinuous.ino

Arduino ESP32 指南