模数转换传感器

模数转换（adc）传感器允许您使用设备内置的 ADC 在特定引脚上测量电压。

• ESP8266：只能使用引脚 A0 (GPIO17)。
• ESP32：可用引脚因型号而异，请参阅 ESP32 引脚和硬件详情。
• RP2040：可使用 GPIO26 至 GPIO29。
• nRF52840：可使用 AIN0 至 AIN7、VDD、VDDHDIV5。

# Example configuration entry
sensor:
  - platform: adc
    pin: GPIOXX
    name: "Living Room Brightness"
    update_interval: 60s

配置变量

• pin (必选, Pin): 要测量电压的引脚。 或者在 ESP8266 或 Raspberry Pi Pico 上，也可以设置为 VCC，请参阅 测量 VCC。

• attenuation (可选): 仅适用于 ESP32。指定要使用的 ADC 衰减值。请参阅 ESP32 衰减。默认为 0db。

• raw (可选): 允许读取未经任何转换或校准的原始 ADC 输出。请参阅 自 2021.11 起 ESP32-ADC 行为不同。默认为 false。

• samples (可选): 每次传感器更新时进行的 ADC 读数次数。在 ESP32 上，如果 attenuation 设置为 auto，则忽略此值。默认为 1。

• sampling_mode (可选): 当采集多个样本时要使用的采样方法。

  • avg 所有样本的平均值（默认）
  • min 所有样本中的最小值
  • max 所有样本中的最大值

• update_interval (可选, Time): 检查传感器的时间间隔。默认为 60s。

• 来自 Sensor 的所有其他选项。

NOTE

此组件打印芯片引脚所看到的电压。在 ESP8266 上，这始终是 0.0V 到 1.0V 某些开发板（如 Wemos D1 mini）包含外部分压电路，用于将 3.3V 输入信号降至芯片内部的 1.0V。如果您的板子有此电路，请添加一个乘法过滤器以 获得正确的值：

sensor:
  - platform: adc
    # ...
    filters:
      - multiply: 3.3

ESP32 衰减

在 ESP32 上，默认情况下 ADC 测量的电压上限约为 1.1V，因为 ADC 的感知范围（衰减）默认设置为 0db。 测量更高电压需要将 attenuation 设置为以下值之一：0db、2.5db、6db、12db。 更多信息请参阅制造商网站。

为简化操作，我们提供了 attenuation: auto 设置，用于在量程之间自动/无缝切换。我们的实现 结合了所有可用量程，以在不牺牲特定衰减的情况下实现最佳分辨率。

NOTE

在我们的测试中，可用 ADC 范围为 ~0.075V 至 ~3.12V（使用 attenuation: auto 设置），超出该范围的值会饱和到任一端。 尽管测量值经过校准，但由于内部电压参考的差异，量程限制在不同芯片之间会有所变化。

ESP32 引脚和硬件详情

型号	ADC1	ADC2
ESP32	GPIO32 - GPIO39	GPIO0, GPIO2, GPIO4, GPIO12 - GPIO15, GPIO25 - GPIO27
ESP32-C2	GPIO0 - GPIO4	GPIO5
ESP32-C3	GPIO0 - GPIO4	GPIO5
ESP32-C5	GPIO1 - GPIO6	无 ADC2
ESP32-C6	GPIO0 - GPIO6	无 ADC2
ESP32-C61	GPIO1, GPIO3 - GPIO5	无 ADC2
ESP32-H2	GPIO1 - GPIO5	无 ADC2
ESP32-S2	GPIO1 - GPIO10	GPIO11 - GPIO20
ESP32-S3	GPIO1 - GPIO10	GPIO11 - GPIO20
ESP32-P4	GPIO16 - GPIO23	GPIO49 - GPIO54

不同的 ESP32 型号使用不同的 ADC 校准方法：

• 原版 ESP32（非变体）& ESP32-S2：使用线性拟合校准
• ESP32-C3、ESP32-C5、ESP32-C6、ESP32-C61、ESP32-H2、ESP32-S3 & ESP32-P4：使用曲线拟合校准

代码会自动处理这些差异，但在调试 ADC 读数或需要了解校准过程时，了解这一点很有用。

WARNING

在 ESP32-C5 上，GPIO2 是启动期间使用的引导引脚。虽然它可以用作 ADC 输入，但请避免连接可能干扰启动过程的电路。

自 2021.11 起 ESP32-ADC 行为不同

自 2021.11 起，ADC 输出可以非常精确地读取电压，因为已纳入了制造商校准。在此之前，每块 ESP32 都会读取不同的电压，且大多不准确/非线性。鼓励手动校准设置的用户检查其安装以确保输出正确。 对于不需要精确电压读数的用户，“raw”输出选项可以在制造商校准之前获取原始 ADC 值（ESP32 为 0-4095）。可以通过过滤乘数来获得旧的未校准测量值：

# To replicate old uncalibrated output, set raw:true and keep only one of the multiplier lines.
raw: true
filters:
  - multiply: 0.00026862 # 1.1/4095, for attenuation 0db
  - multiply: 0.00036630 # 1.5/4095, for attenuation 2.5db
  - multiply: 0.00053724 # 2.2/4095, for attenuation 6db
  - multiply: 0.00095238 # 3.9/4095, for attenuation 12db
  # your existing filters would go here

请注意，我们不推荐此方法，因为它在不同芯片之间会有所不同，且较新的 ESP32 模块有不同的量程（即 0-8191）；最好使用新的校准电压并相应更新任何现有过滤器。

测量 VCC

以下配置块在受支持的硬件平台上添加了反映 VCC 的传感器。 请参阅以下各部分了解实际测量的电压。

sensor:
  - platform: adc
    pin: VCC
    name: "VCC Voltage"

在 ESP8266 上

在 ESP8266 上，您甚至可以测量芯片获得的电压。这在您希望在使用电池时电压过低时关闭芯片的情况下很有用。

要测量 VCC 电压，将 pin: 设置为 VCC，并确保 A0 引脚上没有连接任何东西。

NOTE

为避免混淆：它测量的是芯片处的电压，而不是板子的 VCC 引脚处的电压。通常应该在 3.3V 左右。

在 Raspberry Pi Pico 上

在 Raspberry Pi Pico 和 Pico W 上，将 pin: 设置为 VCC 允许您通过 ADC3（GPIO29）测量 VSYS 电压。

读数将反映以下情况之一：

• 通过 VSYS 引脚供电时的直接电源电压
• 通过 USB 供电时的 USB 电压（VBUS）减去二极管压降

我们的实验表明，Pico 的二极管压降约为 ~0.1V，Pico W 约为 ~0.25V；您可以使用传感器过滤器来调整最终值。

NOTE

在 Raspberry Pi Pico W 上，用于 VSYS 的 ADC GPIO29 引脚与 WiFi 芯片共用，因此尝试显式使用它可能会使 WiFi 连接挂起。 建议在这种情况下使用 VCC 作为 ADC 引脚。

RP2040 内部核心温度

RP2040 有一个内部温度传感器，可用于测量核心温度。此传感器在 GPIO 引脚上不可用，但在内部 ADC 上可用。 以下代码展示了如何访问温度并将其作为传感器公开。过滤器值取自 RP2040 数据手册，用于计算电压到摄氏度的转换。

sensor:
  - platform: adc
    pin: TEMPERATURE
    name: "Core Temperature"
    unit_of_measurement: "°C"
    filters:
      - lambda: return 27 - (x - 0.706f) / 0.001721f;

多个 ADC 传感器

您可以使用的 ADC 传感器数量受设备支持数量的限制。ESP8266 只有一个 ADC，一次只能处理一个传感器。例如，在 ESP8266 上，您可以测量模拟引脚（ESP8266 上的 A0）或 VCC（见上文）的值，但不能同时测量两者。同时使用两者将导致传感器值不正确。

在 Firebeetle ESP32-E 上测量电池电压

此板具有内部分压电路，使用 12dB 衰减在 GPIO34 上可以轻松测量电池电压。

- platform: adc
  name: "Battery voltage"
  pin: GPIO34
  accuracy_decimals: 2
  update_interval: 60s
  attenuation: 12dB
  samples: 10
  filters:
    - multiply: 2.0  # The voltage divider requires us to multiply by 2

这适用于 SKU:DFR0654。更多信息请参阅：制造商网站。

参见

• 传感器过滤器
• ADS1115 4 通道 16 位 A/D 转换器
• MAX6675 K 型热电偶温度传感器
• API 参考：adc_sensor.h