mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-13 20:11:53 +01:00
Add BME680 BSEC docs (#793)
This commit is contained in:
Trevor North
GitHub
parent
acf110f84d
commit
97ae661d19
269
components/sensor/bme680_bsec.rst
Normal file
269
components/sensor/bme680_bsec.rst
Normal file
@ -0,0 +1,269 @@
|
||||
BME680 Temperature+Pressure+Humidity+Gas Sensor via BSEC
|
||||
========================================================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up BME680 temperature, humidity, pressure and gas sensors via BSEC.
|
||||
:image: bme680.jpg
|
||||
:keywords: BME680
|
||||
|
||||
The ``bme680_bsec`` sensor platform allows you to use your BME680
|
||||
(`datasheet <https://cdn-shop.adafruit.com/product-files/3660/BME680.pdf>`__,
|
||||
`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 :ref:`I²C <i2c>` is required to be set up in your configuration for this sensor to work.
|
||||
|
||||
.. figure:: images/bme680-full.jpg
|
||||
:align: center
|
||||
:width: 50.0%
|
||||
|
||||
BME680 Temperature, Pressure, Humidity & Gas Sensor.
|
||||
|
||||
.. _BSEC license agreement: https://www.bosch-sensortec.com/media/boschsensortec/downloads/bsec/2017-07-17_clickthrough_license_terms_environmentalib_sw_clean.pdf
|
||||
|
||||
.. _Adafruit: https://www.adafruit.com/product/3660
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# 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:
|
||||
------------------------
|
||||
|
||||
The configuration is made up of three parts: The central hub, individual sensors, and accuracy text sensor.
|
||||
|
||||
Hub Configuration:
|
||||
|
||||
- **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.
|
||||
|
||||
- **state_save_interval** (*Optional*, :ref:`config-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:
|
||||
|
||||
- **temperature** (*Optional*): The information for the temperature sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the temperature sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **pressure** (*Optional*): The information for the pressure sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the pressure sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **humidity** (*Optional*): The information for the humidity sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the humidity sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **gas_resistance** (*Optional*): The information for the gas sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the gas resistance sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **iaq** (*Optional*): The information for the IAQ sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the IAQ sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **iaq_accuracy** (*Optional*): The information for the numeric IAQ accuracy sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the IAQ accuracy sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
- **co2_equivalent** (*Optional*): The information for the CO2 equivalent sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the CO2 equivalent sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-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*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
Text Sensor Configuration:
|
||||
|
||||
- **iaq_accuracy** (*Optional*): The information for the IAQ accuracy sensor.
|
||||
|
||||
- **name** (**Required**, string): The name for the IAQ accuracy sensor.
|
||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||
- All other options from :ref:`TextSensor <config-text_sensor>`.
|
||||
|
||||
.. figure:: images/bme680-bsec-ui.png
|
||||
:align: center
|
||||
:width: 80.0%
|
||||
|
||||
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 :ref:`Sensor <config-sensor>` and :ref:`TextSensor <config-text_sensor>` are also available for filtering, automation and so on.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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: lp
|
||||
|
||||
# Interval at which to save BSEC state
|
||||
# ------------------------------------
|
||||
# Default: 6h
|
||||
state_save_interval: 6h
|
||||
|
||||
sensor:
|
||||
- platform: bme680_bsec
|
||||
temperature:
|
||||
# Temperature in °C
|
||||
name: "BME680 Temperature"
|
||||
filters:
|
||||
- median
|
||||
pressure:
|
||||
# Pressure in hPa
|
||||
name: "BME680 Pressure"
|
||||
filters:
|
||||
- median
|
||||
humidity:
|
||||
# Relative humidity %
|
||||
name: "BME680 Humidity"
|
||||
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.
|
||||
|
||||
.. _bsec-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
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`bme680`
|
||||
- :apiref:`bme680_bsec/bme680_bsec.h`
|
||||
- `BSEC Arduino Library <https://github.com/BoschSensortec/BSEC-Arduino-library>`__ by `Bosch Sensortec <https://www.bosch-sensortec.com/>`__
|
||||
- `Bosch Sensortec Community <https://community.bosch-sensortec.com/>`__
|
||||
- :ghedit:`Edit`
|
||||
|
After Width: | Height: | Size: 10 KiB |
BIN
components/sensor/images/bme680-bsec-ui.png
Normal file
BIN
components/sensor/images/bme680-bsec-ui.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
@ -106,6 +106,7 @@ Sensor Components
|
||||
BLE RSSI, components/sensor/ble_rssi, bluetooth.svg
|
||||
BME280, components/sensor/bme280, bme280.jpg
|
||||
BME680, components/sensor/bme680, bme680.jpg
|
||||
BME680 via BSEC, components/sensor/bme680_bsec, bme680.jpg
|
||||
BMP085, components/sensor/bmp085, bmp180.jpg
|
||||
BMP280, components/sensor/bmp280, bmp280.jpg
|
||||
CCS811, components/sensor/ccs811, ccs811.jpg
|
||||
|
||||
Loading…
Reference in New Issue
Block a user