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.
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"
id: 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"
- platform: template
name: "BME680 IAQ Classification"
icon: "mdi:checkbox-marked-circle-outline"
lambda: |-
if ( int(id(iaq).state) <= 50) {
return {"Excellent"};
}
else if (int(id(iaq).state) >= 51 && int(id(iaq).state) <= 100) {
return {"Good"};
}
else if (int(id(iaq).state) >= 101 && int(id(iaq).state) <= 150) {
return {"Lightly polluted"};
}
else if (int(id(iaq).state) >= 151 && int(id(iaq).state) <= 200) {
return {"Moderately polluted"};
}
else if (int(id(iaq).state) >= 201 && int(id(iaq).state) <= 250) {
return {"Heavily polluted"};
}
else if (int(id(iaq).state) >= 251 && int(id(iaq).state) <= 350) {
return {"Severely polluted"};
}
else if (int(id(iaq).state) >= 351) {
return {"Extremely polluted"};
}
else {
return {"error"};
}
Configuration variables:
address (Optional, int): Manually specify the I^2C address of the sensor. Defaults to
0x76. Another address can be0x77.temperature_offset (Optional, float): Temperature offset if device is in enclosure and reads too high. This value is subtracted from the reading (e.g. if the sensor reads 5°C higher than expected, set this to
5) and also corrects the relative humidity readings. Defaults to0.iaq_mode (Optional, string): IAQ calculation mode. Default is
staticfor static applications (e.g. fixed indoor devices). Can bemobilefor mobile applications (e.g. carry-on devices).sample_rate (Optional, string): Sample rate. Default is
lpfor low power consumption, sampling every 3 seconds. Can beulpfor 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 doesn’t 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
lpfor low power consumption, sampling every 3 seconds orulpfor 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
lpfor low power consumption, sampling every 3 seconds orulpfor 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
lpfor low power consumption, sampling every 3 seconds orulpfor ultra low power, sampling every 5 minutes.All other options from Sensor.
gas_resistance (Optional): The information for the gas sensor.
iaq (Optional): The information for the IAQ sensor.
iaq_accuracy (Optional): The information for the numeric IAQ accuracy sensor.
co2_equivalent (Optional): The information for the CO2 equivalent sensor.
breath_voc_equivalent (Optional): The information for the Breath VOC equivalent humidity 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.
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
# For example if it reads 5C too high, set this to 5
# This also corrects the relative humidity readings
# 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.