模数转换传感器

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

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

# 示例配置条目
sensor:
  - platform: adc
    pin: GPIOXX
    name: "客厅亮度"
    update_interval: 60s

配置变量

• 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 (可选, 时间): 检查传感器的时间间隔。默认为 60s。

• 传感器的所有其他选项。

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）。可以使用过滤器乘数获取旧的未校准测量值：

# 要复制旧的未校准输出，设置 raw:true 并只保留一个乘数行。
raw: true
filters:
  - multiply: 0.00026862 # 1.1/4095, 用于衰减 0db
  - multiply: 0.00036630 # 1.5/4095, 用于衰减 2.5db
  - multiply: 0.00053724 # 2.2/4095, 用于衰减 6db
  - multiply: 0.00095238 # 3.9/4095, 用于衰减 12db
  # 您现有的过滤器放在这里

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

测量 VCC

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

sensor:
  - platform: adc
    pin: VCC
    name: "VCC 电压"

在 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: "内核温度"
    unit_of_measurement: "°C"
    filters:
      - lambda: return 27 - (x - 0.706f) / 0.001721f;

多个 ADC 传感器

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

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

该电路板有一个内部分压器，可以轻松测量电池电压，方法是在 GPIO34 上使用 12dB 衰减。

- platform: adc
  name: "电池电压"
  pin: GPIO34
  accuracy_decimals: 2
  update_interval: 60s
  attenuation: 12dB
  samples: 10
  filters:
    - multiply: 2.0  # 分压器要求我们乘以 2

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

另请参阅

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