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

scd4x 传感器平台允许您在 ESPHome 中使用 Sensirion SCD4X CO₂ (数据手册) 传感器。需要在配置中设置 I²C 总线才能使此传感器工作。

# 示例配置条目
sensor:
  - platform: scd4x
    co2:
      name: "车间 CO2"
    temperature:
      name: "车间温度"
    humidity:
      name: "车间湿度"

WARNING

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

配置变量

co2 (可选): CO₂ 传感器的信息。
- 传感器的所有选项。
temperature (可选): 温度传感器的信息。
- 传感器的所有选项。
humidity (可选): 湿度传感器的信息。
- 传感器的所有选项。
temperature_offset (可选, 浮点数): 温度偏移可能取决于多种因素，如 SCD4x 测量模式、附近组件的自热、环境温度和气流。此变量允许通过设置温度偏移来补偿这些影响。默认为 4°C。
automatic_self_calibration (可选, 布尔值): 是否启用自动校准 (ASC)。默认为 true。
ambient_pressure_compensation (可选, 整数): 根据给定的环境压力（mBar）启用测量 CO₂ 值的补偿。
altitude_compensation (可选, 整数): 启用因当前海拔高度（米）引起的偏差补偿。注意：如果设置了 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 毫秒。仅测量湿度和温度。CO2 报告为 0 ppm。此模式仅在 scd41 上可用，适用于需要低功耗的场景。
ambient_pressure_compensation_source (可选, ID): 设置用于环境压力补偿的外部压力传感器 ID。压力传感器必须以 hPa 为单位报告压力。校正在更新 co2 传感器状态之前应用。
address (可选, 整数): 手动指定传感器的 I²C 地址。默认为 0x62。
update_interval (可选, 时间): 检查传感器的时间间隔。默认为 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 设置静态环境压力值。也可以使用 lambda 通过 set_ambient_pressure_compensation(<mBar>) 动态更改，或者将 ambient_pressure_compensation_source 指向本地压力传感器。

使用本地传感器的示例

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

sensor:
  - platform: bme280
    pressure:
      name: "环境压力"
      id: bme_pressure

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

使用远程传感器的示例

此示例创建一个可以从 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 水平"