SCD4X CO₂、温度与相对湿度传感器

scd4x 传感器平台允许您在 ESPHome 中使用 Sensirion SCD4X CO₂（数据手册）传感器。要在您的配置中使该传感器正常工作，必须先设置好 I²C 总线。

# 示例配置条目
sensor:
  - platform: scd4x
    co2:
      name: "Workshop CO2"
    temperature:
      name: "Workshop Temperature"
    humidity:
      name: "Workshop Humidity"

WARNING

传感器上的白色膜片不得移除或篡改，以确保正常运行。

配置变量

• co2 (可选): CO₂ 传感器的信息。

  • Sensor 的所有选项。

• temperature (可选): 温度传感器的信息。

  • Sensor 的所有选项。

• humidity (可选): 湿度传感器的信息。

  • Sensor 的所有选项。

• temperature_offset (可选, float): 温度偏移可能受多种因素影响，例如 SCD4x 的测量模式、附近元件的自热、环境温度和气流。该变量通过设置温度偏移来对这些效应进行补偿。默认为 4°C。

• automatic_self_calibration (可选, boolean): 是否启用自动自校准（ASC）。默认为 true。

• ambient_pressure_compensation (可选, int): 基于给定的环境气压（单位为 mBar）启用对测量 CO₂ 值的补偿。

• altitude_compensation (可选, int): 启用对由于当前海拔（单位为米）引起的偏差的补偿。注意：如果设置了 ambient_pressure_compensation，则设置 altitude_compensation 将被忽略。

• measurement_mode (可选): 设置 scd4x 的测量模式。

  • periodic ：传感器每 5 秒进行一次新的测量。这是默认模式。

  • low_power_periodic ：传感器每 30 秒进行一次新的测量。请确保 update_interval 至少为 30 秒。

  • single_shot ：在每个更新间隔开始时启动一次测量，一次测量需要 5 秒。该模式仅在 scd41 上可用，适合需要低功耗的场合。 自动自校准针对每 5 分钟进行一次的单次测量进行了优化。 为降低噪声水平，可以连续执行多次单次测量，并使用传感器过滤器对输出值进行平均。

  • single_shot_rht_only ：在每个更新间隔开始时启动一次测量，一次测量需要 50 ms。仅测量湿度和温度。CO2 报告为 0 ppm。该模式仅在 scd41 上可用，适合需要低功耗的场合。

• ambient_pressure_compensation_source (可选, ID): 设置用于环境气压补偿的外部压力传感器 ID。压力传感器必须以 hPa 为单位报告压力。修正在更新 co2 传感器状态之前应用。

• address (可选, int): 手动指定传感器的 I²C 地址。默认为 0x62。

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

动作

scd4x.perform_forced_calibration 动作

该动作将传感器手动校准到提供的 ppm 值。 在进行强制重新校准之前，请在 CO2 浓度均匀且恒定的环境中，以最终用于正常传感器运行的运行模式（周期测量、低功耗周期测量或单次测量）运行 SCD4x 超过 3 分钟。 截至 2025 年 3 月，全球月度平均 CO₂ 浓度为 426 ppm。

on_...:
  then:
    - scd4x.perform_forced_calibration:
        # 全球月度平均 CO₂
        # https://gml.noaa.gov/ccgg/trends/global.html
        value: 426
        id: my_scd41

value 也可以是模板，例如用于定义 Home Assistant 校准动作：

api:
  actions:
    - action: calibrate_co2_value
      variables:
        co2_ppm: int
      then:
        - scd4x.perform_forced_calibration:
            value: !lambda 'return co2_ppm;'
            id: my_scd41

scd4x.factory_reset 动作

该动作触发传感器的出厂重置。校准设置将恢复为出厂设置。

on_...:
  then:
    - scd4x.factory_reset: my_scd41

气压补偿

可以通过 ambient_pressure_compensation 或 altitude_compensation 设置静态的环境气压值。也可以通过 lambdas 使用 set_ambient_pressure_compensation(<mBar>) 动态更改，或者将 ambient_pressure_compensation_source 指向本地压力传感器。

使用本地传感器的示例

注意：请记住，您的压力传感器需要以 mBar 为单位输出。

sensor:
  - platform: bme280
    pressure:
      name: "Ambient Pressure"
      id: bme_pressure

  - platform: scd4x
    measurement_mode: low_power_periodic
    ambient_pressure_compensation_source: bme_pressure
    temperature_offset: 0
    co2:
      name: "CO2 level"

使用远程传感器的示例

此示例创建一个可从 Home Assistant 调用的服务 set_ambient_pressure：

api:
  actions:
    - action: set_ambient_pressure
      variables:
        pressure_mbar: int
      then:
        - lambda: "id(my_scd41)->set_ambient_pressure_compensation(pressure_mbar);"

sensor:
  - platform: scd4x
    id: my_scd41
    measurement_mode: low_power_periodic
    temperature_offset: 0
    co2:
      name: "CO2 level"

参见

• 传感器过滤器
• 绝对湿度
• SCD30 CO₂、温度与相对湿度传感器
• API 参考：scd4x.h