diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst new file mode 100644 index 000000000..511020632 --- /dev/null +++ b/components/sensor/bme680_bsec.rst @@ -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` diff --git a/components/sensor/images/bme680-bsec-ui.png b/components/sensor/images/bme680-bsec-ui.png new file mode 100644 index 000000000..f85dea8fd Binary files /dev/null and b/components/sensor/images/bme680-bsec-ui.png differ diff --git a/index.rst b/index.rst index 3b3fe3968..27eb9c151 100644 --- a/index.rst +++ b/index.rst @@ -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