BME680 Temperature+Pressure+Humidity+Gas Sensor via BSEC

Component/Hub

The bme680_bsec sensor platform allows you to use your BME680 (datasheet, Adafruit) temperature, pressure and humidity and gas sensors with ESPHome via the Bosch Sensortec Environmental Cluster (BSEC) software library. The use of Bosch’s proprietary algorithms provides additional Indoor Air Quality (IAQ), CO2 equivalent and Breath Volatile Organic Compounds (VOC) equivalent measurements.

Note

The Bosch BSEC library is only available for use after accepting its software license agreement. By enabling this component, you are explicitly agreeing to the terms of the BSEC license agreement. You must not distribute any compiled firmware binaries that include this component.

The I²C is required to be set up in your configuration for this sensor to work.

../../_images/bme680-full.jpg

BME680 Temperature, Pressure, Humidity & Gas Sensor.

# Minimal example configuration with common sensors
i2c:

bme680_bsec:

sensor:
  - platform: bme680_bsec
    temperature:
      name: "BME680 Temperature"
    pressure:
      name: "BME680 Pressure"
    humidity:
      name: "BME680 Humidity"
    iaq:
      name: "BME680 IAQ"
    co2_equivalent:
      name: "BME680 CO2 Equivalent"
    breath_voc_equivalent:
      name: "BME680 Breath VOC Equivalent"

text_sensor:
  - platform: bme680_bsec
    iaq_accuracy:
      name: "BME680 IAQ Accuracy"

Configuration variables:

  • address (Optional, int): Manually specify the I^2C address of the sensor. Defaults to 0x76. Another address can be 0x77.

  • temperature_offset (Optional, float): Temperature offset if device is in enclosure and reads too high. Defaults to 0.

  • iaq_mode (Optional, string): IAQ calculation mode. Default is static for static applications (e.g. fixed indoor devices). Can be mobile for mobile applications (e.g. carry-on devices).

  • sample_rate (Optional, string): Sample rate. Default is lp for low power consumption, sampling every 3 seconds. Can be ulp for ultra low power, sampling every 5 minutes. This controls the sampling rate for gas-dependant sensors and will govern the interval at which the sensor heater is operated. By default this rate will also be used for temperature, pressure and humidity sensors but these can be overridden on a per-sensor level if required.

  • state_save_interval (Optional, Time): The minimum interval at which to save calibrated BSEC algorithm state to flash so that calibration does have to start from zero on device restart. Defaults to 6h.

Sensor

Configuration variables:

  • temperature (Optional): The information for the temperature sensor.

    • name (Required, string): The name for the temperature sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • sample_rate (Optional, string): Optional sample rate override for this sensor. Can be lp for low power consumption, sampling every 3 seconds or ulp for ultra low power, sampling every 5 minutes.

    • All other options from Sensor.

  • pressure (Optional): The information for the pressure sensor.

    • name (Required, string): The name for the pressure sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • sample_rate (Optional, string): Optional sample rate override for this sensor. Can be lp for low power consumption, sampling every 3 seconds or ulp for ultra low power, sampling every 5 minutes.

    • All other options from Sensor.

  • humidity (Optional): The information for the humidity sensor.

    • name (Required, string): The name for the humidity sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • sample_rate (Optional, string): Optional sample rate override for this sensor. Can be lp for low power consumption, sampling every 3 seconds or ulp for ultra low power, sampling every 5 minutes.

    • All other options from Sensor.

  • gas_resistance (Optional): The information for the gas sensor.

    • name (Required, string): The name for the gas resistance sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • iaq (Optional): The information for the IAQ sensor.

    • name (Required, string): The name for the IAQ sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • iaq_accuracy (Optional): The information for the numeric IAQ accuracy sensor.

    • name (Required, string): The name for the IAQ accuracy sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • co2_equivalent (Optional): The information for the CO2 equivalent sensor.

    • name (Required, string): The name for the CO2 equivalent sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • breath_voc_equivalent (Optional): The information for the Breath VOC equivalent humidity sensor.

    • name (Required, string): The name for the Breath VOC equivalent sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

Text Sensor

Accuracy can be reported in text format.

Configuration variables:

  • iaq_accuracy (Optional): The information for the IAQ accuracy sensor. Shows: Stabilizing, Uncertain, Calibrating, Calibrated.

    • name (Required, string): The name for the IAQ accuracy sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from TextSensor.

../../_images/bme680-bsec-ui.png

Advanced configuration

The following configuration shows all the available sensors and optional settings for the component. It also includes an example of filtering to guard against outliers, limit the number of updates sent to home assistant and reduce storage requirements in other systems such as influxdb used to store historical data.

For each sensor all other options from Sensor and TextSensor are also available for filtering, automation and so on.

bme680_bsec:
    # i2c address
    # -----------
    # Common values are:
    # - 0x76
    # - 0x77
    # Default: 0x76
    address: 0x76

    # Temperature offset
    # ------------------
    # Useful if device is in enclosure and reads too high
    # Default: 0
    temperature_offset: 0

    # IAQ calculation mode
    # --------------------
    # Available options:
    # - static (for fixed position devices)
    # - mobile (for on person or other moveable devices)
    # Default: static
    iaq_mode: static

    # Sample rate
    # -----------
    # Available options:
    # - lp (low power - samples every 3 seconds)
    # - ulp (ultra low power - samples every 5 minutes)
    # Default: lp
    sample_rate: ulp

    # Interval at which to save BSEC state
    # ------------------------------------
    # Default: 6h
    state_save_interval: 6h

sensor:
  - platform: bme680_bsec
    temperature:
      # Temperature in °C
      name: "BME680 Temperature"
      sample_rate: lp
      filters:
        - median
    pressure:
      # Pressure in hPa
      name: "BME680 Pressure"
      sample_rate: lp
      filters:
        - median
    humidity:
      # Relative humidity %
      name: "BME680 Humidity"
      sample_rate: lp
      filters:
        - median
    gas_resistance:
      # Gas resistance in Ω
      name: "BME680 Gas Resistance"
      filters:
        - median
    iaq:
      # Indoor air quality value
      name: "BME680 IAQ"
      filters:
        - median
    iaq_accuracy:
      # IAQ accuracy as a numeric value of 0, 1, 2, 3
      name: "BME680 Numeric IAQ Accuracy"
    co2_equivalent:
      # CO2 equivalent estimate in ppm
      name: "BME680 CO2 Equivalent"
      filters:
        - median
    breath_voc_equivalent:
      # Volatile organic compounds equivalent estimate in ppm
      name: "BME680 Breath VOC Equivalent"
      filters:
        - median

text_sensor:
  - platform: bme680_bsec
    iaq_accuracy:
      # IAQ accuracy as a text value of Stabilizing, Uncertain, Calibrating, Calibrated
      name: "BME680 IAQ Accuracy"

Indoor Air Quality (IAQ) Measurement

Indoor Air Quality measurements are expressed in the IAQ index scale with 25IAQ corresponding to typical good air and 250IAQ indicating typical polluted air after calibration.

IAQ Accuracy and Calibration

The BSEC algorithm automatically gathers data in order to calibrate the IAQ measurements. The IAQ Accuracy sensor will give one of the following values:

  • Stabilizing: The device has just started, and the sensor is stabilizing (this typically lasts 5 minutes)

  • Uncertain: The background history of BSEC is uncertain. This typically means the gas sensor data was too stable for BSEC to clearly define its reference.

  • Calibrating: BSEC found new calibration data and is currently calibrating.

  • Calibrated: BSEC calibrated successfully.

Every state_save_interval, or as soon thereafter as full calibration is reached, the current algorithm state is saved to flash so that the process does not have to start from zero on device restart.

See Also