Merge branch 'schneider/bsec-doc' into 'master'

change(bsec): Update documentation

See merge request !444

Documentation/pycardium/bme680.rst

@@ -19,14 +19,28 @@ library will be activated which offers the following extra functionality:
     about how to interpret these estimates.
 
 .. note::
+   Please keep in mind that the BME680 can not directly measure CO2. It measures
+   Volatile Organic Compounds (VOCs). The BSEC library uses this measurement
+   to compute an Indoor Air Quality (IAQ) indication. It also assumes that all VOCs
+   in the air are from human breath and computes an equivalent CO2 (eCO2)
+   value from this. Please be aware of these facts when judging the accuracy
+   of the IAQ and eCO2 values. Some more information can be found in the
+   :ref:`bsec_api` API documentation.
+
+.. warning::
    For the BSEC library to properly work the card10 should be kept running
    for at least 10 hours at least once. This is needed as the BSEC library
    periodically writes calibration information about the sensor to the
    card10's file system.
 
+   Please make sure to observe the IAQ accuracy field. It will tell you if the
+   IAQ and eCO2 measurements are deemed "accurate" by the BSEC library. Your
+   application should either inform the user about the current accuracy (e.g.
+   by color coding) or simply not show any values if the accuracy is below 2.
+
 
 .. note::
-    See also the BLE :ref:`ESS`.
+   See also the BLE :ref:`ESS`.
 
 
 **Example**:

epicardium/epicardium.h

@@ -925,12 +925,20 @@ API(API_BME680_GET_DATA, int epic_bme680_read_sensors(
  *
  * BSEC
  * ----
- * The Bosch BSEC libary allows to compute an indoor air
- * qualtiy (IAQ) metric as well as CO2 and VOC content
- * equivalents using the gas sensor of the BME680.
+ * The Bosch Sensortec Environmental Cluster (BSEC) library
+ * allows to estimate an indoor air qualtiy (IAQ) metric as
+ * well as CO2 and VOC content equivalents using the gas sensor
+ * of the BME680.
  *
  * As it is a proprietary binary blob, it has to be enabled using
  * the ``bsec_enable`` configuration option (see :ref:`card10_cfg`).
+ *
+ * Please also have a look at the BME680 datasheet and some of
+ * the BSEC documentation:
+ *
+ * https://git.card10.badge.events.ccc.de/card10/hardware/-/blob/master/datasheets/bosch/BST-BME680-DS001.pdf
+ *
+ * https://git.card10.badge.events.ccc.de/card10/firmware/-/blob/master/lib/vendor/Bosch/BSEC/integration_guide/BST-BME680-Integration-Guide-AN008-48.pdf
  */
 
 /**
@@ -949,6 +957,7 @@ struct bsec_sensor_data {
 	 * 1970-01-01 00:00:00 UTC)*/
 	uint32_t timestamp;
 	/** Accuracy of IAQ, CO2 equivalent and breath VOC equivalent:
+	 *
 	 * 0: Stabilization / run-in ongoing:
 	 *    This means that the sensor still needs to warm up. Takes about
 	 *    5 min after activation of BSEC / reboot.