Merge branch 'schneider/bsec' into 'master'

BSEC support

See merge request card10/firmware!380

Documentation/bluetooth/ess.rst

+.. _ESS:
+
 Environmental Sensing Service
 ========================
 
-.. warning::
-    This service will be available in version v1.17
-
 The Environmental Sensing Service (ESS) implements access to
 the BME680 environmental sensor of the card10.
 
@@ -13,12 +12,25 @@ It provides:
 - Relative humidity
 - Pressure
 
+If :ref:`bsec_api` is enabled the following additional estimates are available:
+
+ - Indoor air quality (IAQ estimate
+ - Equivalent CO2 (eCO2) estimate
+
+Please refer to :ref:`bme680` for more information about BSEC.
+
 
 If notifcations are enabled a measurement of all values is performed every 3 seconds. For each measurement a notification is sent for the characteristics which have notifications enabled.
 
 
 A measurement can also be triggered by reading from a characteristic. A measurement takes roughly 200 ms. A notifciation will be sent to all characteristics which have notifications enabled except the one which was used to trigger the measurement.
 
+.. note::
+   If :ref:`bsec_api` is enabled, reading a characteristic will not trigger a new measurement.
+
+.. note::
+    This service will be available in version v1.17.
+
 
 BLE Service
 -----------
@@ -42,6 +54,11 @@ BLE Service
   UUID: ``2A6D``
   read and notify
 
+- Indoor air quality (IAQ) characteristic:
+
+  UUID: ``422302f1-2342-2342-2342-234223422342``
+  read and notify
+
 Temperature characteristic
 ---------------------------------
 
@@ -63,3 +80,20 @@ Pressure characteristic
 - 32 bit little endian value representing the measured pressure.
 
 - Unit: 0.1 Pa (0.001 hPa)
+
+Indoor air quality (IAQ) characteristic
+---------------------------------
+
+Data format:
+
+======== =========================== ===========================
+Byte 0   Bytes 1-2                   Bytes 3-4
+-------- --------------------------- ---------------------------
+Accuracy IAQ (16-bit little endian)  eCO2 (16-bit little endian)
+======== =========================== ===========================
+
+
+Units:
+
+- Accuracy and IAQ units: See :ref:`bsec_api` API description
+- CO2 unit: [ppm]

Documentation/card10-cfg.rst

@@ -56,4 +56,10 @@ Option name        Type       Description
 ``long_press_ms``  Integer    Defines the timespan for a long key press in milliseconds.
 ------------------ ---------- -----------
 ``retrigger_ms``   Integer    Defines the timespan for repeating key presses when a key is hold in milliseconds.
+------------------ ---------- -----------
+``bsec_enable``    Boolean    Activate the Bosch :ref:`bsec_api` binary blob to compute an Indoor Air Quality indication.
+------------------ ---------- -----------
+``bsec_debug``     Boolean    Turn on debug output of the BSEC system. Prints each meaurement on the console.
+------------------ ---------- -----------
+``bsec_offset``    Integer    Temperature offset in .1 K. Example: Set to `-14` if temperature reads 1.4 "C" to high. Default: -2.2 K (appropriate for a card10 without a case, connected to USB and with BLE active in vertical orientation).
 ================== ========== ===========

Documentation/pycardium/ble_hid.rst

@@ -3,7 +3,7 @@
 The ``ble_hid`` module provides access to the BLE Human Interface Device functionality.
 
 .. note::
-    Make sure to enable the BLE HID functionality in ``card10.cfg`` and reboot your card10
+    Make sure to enable the BLE HID functionality in :ref:`card10_cfg` and reboot your card10
     if you want to use BLE HID.
 
     Also make sure that the ``adafruit_hid`` folder from the card10 release archive is placed

Documentation/pycardium/bme680.rst

@@ -4,6 +4,31 @@
 =================================
 Allows access to environmental data of card10's surroundings.
 
+If ``bsec_enable`` is set in :ref:`card10_cfg`, the proprietary Bosch BSEC
+library will be activated which offers the following extra functionality:
+
+ - Manual temperature offset compensation
+    The ``bsec_offset`` configuration allows to configure a static temperature
+    offset. Please use a reference thermometer to determine the offset of your
+    card10. If no offset is provided a default offset for a card10 which is
+    connected to USB, has BLE active and is without a case is used.
+ - A fixed measurement interval of 3 seconds
+    This helps to stabilize the temperature of the card10.
+ - An indoor air quality (IAQ)  and equivalent CO2 estimation algorithm
+    Please refer to the :ref:`bsec_api` API documentation to get more information
+    about how to interpret these estimates.
+
+.. note::
+   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.
+
+
+.. note::
+    See also the BLE :ref:`ESS`.
+
+
 **Example**:
 
 .. code-block:: python
@@ -21,6 +46,14 @@ Allows access to environmental data of card10's surroundings.
 
            time.sleep(1)
 
+You can use the return type of :py:meth:`~bme680.Bme680.get_data` to decide
+if you want to use/display the additonal fields returned if BSEC is enabled.
+
+.. code-block:: python
+
+    if isinstance(d, bme680.BSECData):
+        print("Air quality:    {:7d}".format(d.iaq))
+
 Sensor Class
 ------------
 

Documentation/pycardium/config.rst

 ``config`` - Configuration
 ==========================
 The ``config`` module provides functions to interact with card10's
-configuration file (``card10.cfg``).
+configuration file (:ref:`card10_cfg`).
 
 .. automodule:: config
    :members:

epicardium/ble/ble_main.c

@@ -263,6 +263,7 @@ static const attsCccSet_t bleCccSet[BLE_NUM_CCC_IDX] =
   {HID_INPUT_REPORT_1_CH_CCC_HDL,       ATT_CLIENT_CFG_NOTIFY,    DM_SEC_LEVEL_NONE},    /* HIDAPP_IN_KEYBOARD_CCC_HDL */
   {HID_INPUT_REPORT_2_CH_CCC_HDL,       ATT_CLIENT_CFG_NOTIFY,    DM_SEC_LEVEL_NONE},    /* HIDAPP_IN_MOUSE_CCC_HDL */
   {HID_INPUT_REPORT_3_CH_CCC_HDL,       ATT_CLIENT_CFG_NOTIFY,    DM_SEC_LEVEL_NONE},    /* HIDAPP_IN_CONSUMER_CCC_HDL */
+  {ESS_IAQ_CH_CCC_HDL,    ATT_CLIENT_CFG_NOTIFY,    DM_SEC_LEVEL_NONE},   /* BLE_ESS_IAQ_CCC_IDX */
 };
 
 /**************************************************************************************************
@@ -485,6 +486,7 @@ static void bleProcCccState(bleMsg_t *pMsg)
     case BLE_ESS_TEMP_CCC_IDX:
     case BLE_ESS_HUMI_CCC_IDX:
     case BLE_ESS_PRES_CCC_IDX:
+    case BLE_ESS_IAQ_CCC_IDX:
       bleESS_ccc_update();
     break;
   };

epicardium/ble/cccd.h

@@ -12,6 +12,7 @@ enum
   HIDAPP_IN_KEYBOARD_CCC_HDL,           /*! HID Input Report characteristic for keyboard inputs */
   HIDAPP_IN_MOUSE_CCC_HDL,              /*! HID Input Report characteristic for mouse inputs */
   HIDAPP_IN_CONSUMER_CCC_HDL,             /*! HID Input Report characteristic for consumer control inputs */
+  BLE_ESS_IAQ_CCC_IDX,                    /*! Environmental sensing service, IAQ characteristic */
   BLE_NUM_CCC_IDX
 };
 

epicardium/ble/ess.c

@@ -11,6 +11,8 @@
 #include "modules/log.h"
 #include "modules/modules.h"
 
+#include "ble/ble_api.h"
+
 #include "FreeRTOS.h"
 #include "timers.h"
 
@@ -46,7 +48,19 @@ static const uint8_t UUID_char_pressure[] = {
 	UINT16_TO_BYTES(ATT_UUID_PRESSURE)
 };
 
+/* BLE UUID for IAQ */
+static const uint8_t UUID_char_IAQ[] = {
+	ATT_PROP_READ | ATT_PROP_NOTIFY,
+	UINT16_TO_BYTES(ESS_IAQ_VAL_HDL),
+	CARD10_UUID_SUFFIX, 0xf1, CARD10_UUID_PREFIX
+};
+static const uint8_t UUID_attChar_IAQ[] = {
+	CARD10_UUID_SUFFIX, 0xf1, CARD10_UUID_PREFIX
+};
+
+
 static const uint16_t UUID_char_len = sizeof(UUID_char_temperature);
+static const uint16_t UUID_char_IAQ_len = sizeof(UUID_char_IAQ);
 
 static uint8_t initTemperatureValue[] = { UINT16_TO_BYTES(0) };
 static uint16_t initTemperatureLen = sizeof(initTemperatureValue);
@@ -57,6 +71,9 @@ static uint16_t initHumidityLen = sizeof(initHumidityValue);
 static uint8_t initPressureValue[] = { UINT32_TO_BYTES(0) };
 static uint16_t initPressureLen = sizeof(initPressureValue);
 
+static uint8_t initIAQValue[] = {0x00, UINT16_TO_BYTES(0), UINT16_TO_BYTES(0)};
+static uint16_t initIAQLen = sizeof(initIAQValue);
+
 /* Temperature client characteristic configuration */
 static uint8_t essValTempChCcc[] = {UINT16_TO_BYTES(0x0000)};
 static const uint16_t essLenTempChCcc = sizeof(essValTempChCcc);
@@ -69,6 +86,10 @@ static const uint16_t essLenHumidityChCcc = sizeof(essValHumidityChCcc);
 static uint8_t essValPressureChCcc[] = {UINT16_TO_BYTES(0x0000)};
 static const uint16_t essLenPressureChCcc = sizeof(essValPressureChCcc);
 
+/* IAQ client characteristic configuration */
+static uint8_t essValIAQChCcc[] = {UINT16_TO_BYTES(0x0000)};
+static const uint16_t essLenIAQChCcc = sizeof(essValIAQChCcc);
+
 /* clang-format on */
 
 /*
@@ -171,6 +192,35 @@ static const attsAttr_t ESSSvcAttrList[] = {
 			 ATTS_PERMIT_WRITE) // How about security?
 	},
 
+	// IAQ
+	{
+		.pUuid       = attChUuid,
+		.pValue      = (uint8_t *)UUID_char_IAQ,
+		.pLen        = (uint16_t *)&UUID_char_IAQ_len,
+		.maxLen      = sizeof(UUID_char_IAQ),
+		.permissions = ATTS_PERMIT_READ,
+	},
+	{
+		.pUuid       = UUID_attChar_IAQ,
+		.pValue      = initIAQValue,
+		.pLen        = &initIAQLen,
+		.maxLen      = sizeof(initIAQValue),
+		.settings    = ATTS_SET_READ_CBACK,
+		.permissions = ATTS_PERMIT_READ | ATTS_PERMIT_READ_ENC |
+			       ATTS_PERMIT_READ_AUTH,
+	},
+	/* Characteristic CCC descriptor */
+	{
+		.pUuid    = attCliChCfgUuid,
+		.pValue   = essValIAQChCcc,
+		.pLen     = (uint16_t *)&essLenIAQChCcc,
+		.maxLen   = sizeof(essValIAQChCcc),
+		.settings = ATTS_SET_CCC,
+		.permissions =
+			(ATTS_PERMIT_READ |
+			 ATTS_PERMIT_WRITE) // How about security?
+	},
+
 };
 
 // validating that the service really has all charateristics
@@ -180,13 +230,13 @@ WSF_CT_ASSERT(
 
 static TimerHandle_t poll_timer;
 static StaticTimer_t poll_timer_buffer;
-static void bleESS_update(struct bme680_sensor_data *data);
+static void update_from_bme680(struct bme680_sensor_data *data);
 
 static void workpoll(void *data)
 {
 	struct bme680_sensor_data sensor_data;
 	if (epic_bme680_read_sensors(&sensor_data) == 0) {
-		bleESS_update(&sensor_data);
+		update_from_bme680(&sensor_data);
 	}
 }
 
@@ -254,6 +304,20 @@ static void setAttrFromBME680(struct bme680_sensor_data *data)
 	);
 }
 
+static void setAttrFromBSEC(struct bsec_sensor_data *data)
+{
+	setAttrFromBME680((struct bme680_sensor_data *)data);
+
+	uint16_t iaq            = data->indoor_air_quality;
+	uint8_t accuracy        = data->accuracy;
+	uint16_t co2_equivalent = data->co2_equivalent;
+	uint8_t IAQValue[]      = { accuracy,
+                               UINT16_TO_BYTES(iaq),
+                               UINT16_TO_BYTES(co2_equivalent) };
+
+	AttsSetAttr(ESS_IAQ_VAL_HDL, sizeof(IAQValue), IAQValue);
+}
+
 /*
  * BLE ESS read callback.
  *
@@ -301,6 +365,8 @@ static uint8_t readESSCB(
 		);
 		APP_TRACE_INFO1("ble-ess: read pressure: %u\n", pressure);
 		return ATT_SUCCESS;
+	case ESS_IAQ_VAL_HDL:
+		return ATT_SUCCESS;
 	default:
 		APP_TRACE_INFO0("ble-card10: read no handler found\n");
 		return ATT_ERR_HANDLE;
@@ -316,7 +382,7 @@ static attsGroup_t svcESSGroup = {
 	.endHandle   = ESS_END_HDL,
 };
 
-static void bleESS_update(struct bme680_sensor_data *data)
+static void update_from_bme680(struct bme680_sensor_data *data)
 {
 	setAttrFromBME680(data);
 
@@ -327,6 +393,18 @@ static void bleESS_update(struct bme680_sensor_data *data)
 	sendNotification(connId, ESS_PRESSURE_VAL_HDL, BLE_ESS_PRES_CCC_IDX);
 }
 
+void bleESS_update_from_bsec_data(struct bsec_sensor_data *data)
+{
+	setAttrFromBSEC(data);
+
+	/* Send notifications (if enabled) for all characteristics. */
+	dmConnId_t connId = AppConnIsOpen();
+	sendNotification(connId, ESS_TEMPERATURE_VAL_HDL, BLE_ESS_TEMP_CCC_IDX);
+	sendNotification(connId, ESS_HUMIDITY_VAL_HDL, BLE_ESS_HUMI_CCC_IDX);
+	sendNotification(connId, ESS_PRESSURE_VAL_HDL, BLE_ESS_PRES_CCC_IDX);
+	sendNotification(connId, ESS_IAQ_VAL_HDL, BLE_ESS_IAQ_CCC_IDX);
+}
+
 /*
  * This registers and starts the ESS service.
  */
@@ -341,11 +419,16 @@ void bleESS_init(void)
  */
 void bleESS_ccc_update(void)
 {
+	if (bsec_active()) {
+		return;
+	}
+
 	dmConnId_t connId = AppConnIsOpen();
 	if (connId != DM_CONN_ID_NONE &&
 	    (AttsCccEnabled(connId, BLE_ESS_TEMP_CCC_IDX) ||
 	     AttsCccEnabled(connId, BLE_ESS_HUMI_CCC_IDX) ||
-	     AttsCccEnabled(connId, BLE_ESS_PRES_CCC_IDX))) {
+	     AttsCccEnabled(connId, BLE_ESS_PRES_CCC_IDX) ||
+	     AttsCccEnabled(connId, BLE_ESS_IAQ_CCC_IDX))) {
 		LOG_INFO("ess", "enable periodic measurement");
 		periodic(3000);
 	} else {

epicardium/ble/ess.h

@@ -22,6 +22,10 @@ enum {
 	ESS_PRESSURE_CH_HDL,
 	ESS_PRESSURE_VAL_HDL,
 	ESS_PRES_CH_CCC_HDL,                  /*!< Pressure CCCD */
+	/*!< \brief IAQ/CO2 characteristic */
+	ESS_IAQ_CH_HDL,
+	ESS_IAQ_VAL_HDL,
+	ESS_IAQ_CH_CCC_HDL,                   /*!< IAQ CCCD */
 
 
 	/*!< \brief Maximum handle. */
@@ -29,3 +33,4 @@ enum {
 };
 
 void bleESS_ccc_update(void);
+void bleESS_update_from_bsec_data(struct bsec_sensor_data *data);

epicardium/epicardium.h

@@ -128,6 +128,7 @@ typedef _Bool bool;
 #define API_BME680_INIT            0xD0
 #define API_BME680_DEINIT          0xD1
 #define API_BME680_GET_DATA        0xD2
+#define API_BSEC_GET_DATA          0xD3
 
 #define API_BHI160_ENABLE          0xe0
 #define API_BHI160_DISABLE         0xe1
@@ -918,6 +919,135 @@ API(API_BME680_GET_DATA, int epic_bme680_read_sensors(
 	struct bme680_sensor_data *data
 ));
 
+/**
+ * .. _bsec_api:
+ *
+ * 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.
+ *
+ * As it is a proprietary binary blob, it has to be enabled using
+ * the ``bsec_enable`` configuration option (see :ref:`card10_cfg`).
+ */
+
+/**
+ * BSEC Sensor Data
+ */
+struct bsec_sensor_data {
+	/** Compensated temperature in degree celsius */
+	float temperature;
+	/** Compensated humidity in % relative humidity */
+	float humidity;
+	/** Pressure in hPa */
+	float pressure;
+	/** Gas resistance in Ohms */
+	float gas_resistance;
+	/** Timestamp in of the measurement in UNIX time (seconds since
+	 * 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.
+	 *
+	 * 1: Low accuracy:
+	 *    The sensor has not yet been calibrated. BSEC needs to collect
+	 *    more data to calibrate the sensor. This can take multiple
+	 *    hours.
+	 *
+	 *    BSEC documentation: To reach high accuracy(3) please expose
+	 *    sensor once to good air (e.g. outdoor air) and bad air (e.g.
+	 *    box with exhaled breath) for auto-trimming
+	 *
+	 * 2: Medium accuracy: auto-trimming ongoing
+	 *    BSEC has detected that it needs to recalibrate the sensor.
+	 *    This is an automatic process and usally finishes after tens
+	 *    of minutes. Can happen every now and then.
+	 *
+	 * 3: High accuracy:
+	 *    The sensor has warmed up and is calibrated.
+	 *
+	 * From BSEC documentation:
+	 * IAQ accuracy indicator will notify the user when they should
+	 * initiate a calibration process. Calibration is performed automatically
+	 * in the background if the sensor is exposed to clean and polluted air
+	 * for approximately 30 minutes each.
+	 *
+	 * See also:
+	 * https://community.bosch-sensortec.com/t5/MEMS-sensors-forum/BME680-IAQ-accuracy-definition/m-p/5931/highlight/true#M10
+	 */
+	uint8_t accuracy;
+	/** Indoor Air Quality with range 0 to 500
+	 *
+	 * Statement from the Bosch BSEC library:
+	 *
+	 * Indoor-air-quality (IAQ) gives an indication of the relative change
+	 * in ambient TVOCs detected by BME680.
+	 *
+	 * The IAQ scale ranges from 0 (clean air) to 500 (heavily polluted air).
+	 * During operation, algorithms automatically calibrate and adapt
+	 * themselves to the typical environments where the sensor is operated
+	 * (e.g., home, workplace, inside a car, etc.).This automatic background
+	 * calibration ensures that users experience consistent IAQ performance.
+	 * The calibration process considers the recent measurement history (typ.
+	 * up to four days) to ensure that IAQ=25 corresponds to typical good air
+	 * and IAQ=250 indicates typical polluted air.
+	 *
+	 * Please also consult the BME680 datsheet (pages 9 and 21) as well:
+	 * https://git.card10.badge.events.ccc.de/card10/hardware/-/blob/master/datasheets/bosch/BST-BME680-DS001.pdf
+	 *
+	 */
+	int32_t indoor_air_quality;
+	/** Unscaled IAQ value.
+	 *
+	 * See this post for details:
+	 * https://community.bosch-sensortec.com/t5/MEMS-sensors-forum/BME680-strange-IAQ-and-CO2-values/m-p/9667/highlight/true#M1505
+	 */
+	int32_t static_indoor_air_quality;
+	/** Estimation of equivalant CO2 content in the air in ppm. */
+	float co2_equivalent;
+	/** Estimation of equivalant breath VOC content in the air in ppm. */
+	float breath_voc_equivalent;
+};
+
+/**
+ *
+ * Get the current BME680 data filtered by Bosch BSEC library
+ *
+ * As it is a proprietary binary blob, it has to be enabled using
+ * the ``bsec_enable`` configuration option (see :ref:`card10_cfg`).
+ *
+ * The sample rate is currently fixed to one sample every 3 seconds.
+ * Querying the sensor more often will return cached data.
+ *
+ * After the libary has been activated it starts to calibrate the
+ * sensor. This can take multiple hours.
+ * After a reset/power on it takes about 5 minutes to stabilize
+ * the sensor if it was calibrated before.
+ *
+ * The BSEC library regularly recalibrates the sensor during operation.
+ * The ``accuracy`` field of the return data indicates the calibration
+ * status of the sensor. Please take it into consideration when
+ * using / displaying the IAQ.
+ *
+ * Please refer to the description of :c:type:`bsec_sensor_data` for more
+ * information about how to interpret its content.
+ *
+ * .. versionadded:: 1.x
+ *
+ * :param data: Where to store the environmental data.
+ * :return: 0 on success or ``-Exxx`` on error.  The following
+ *     errors might occur:
+ *
+ *     - ``-EFAULT``:  On NULL-pointer.
+ *     - ``-EINVAL``:  No data available from the sensor.
+ *     - ``-ENODEV``:  BSEC libray is not running.
+ */
+API(API_BSEC_GET_DATA, int epic_bsec_read_sensors(
+	struct bsec_sensor_data *data
+));
 /**
  * MAX86150
  * ======

epicardium/main.c

@@ -113,6 +113,7 @@ int main(void)
 		    NULL) != pdPASS) {
 		panic("Failed to create %s task!", "MAX30001");
 	}
+
 	/* MAX86150 */
 	if (xTaskCreate(
 		    vMAX86150Task,
@@ -123,6 +124,23 @@ int main(void)
 		    NULL) != pdPASS) {
 		panic("Failed to create %s task!", "MAX86150");
 	}
+
+	/* BSEC */
+	if (bsec_activate() == 0) {
+		if (xTaskCreate(
+			    vBSECTask,
+			    (const char *)"BSEC",
+			    configMINIMAL_STACK_SIZE * 4,
+			    NULL,
+			    tskIDLE_PRIORITY + 1,
+			    NULL) != pdPASS) {
+			LOG_CRIT(
+				"startup", "Failed to create %s task!", "BSEC"
+			);
+			abort();
+		}
+	}
+
 	/* API */
 	if (xTaskCreate(
 		    vApiDispatcher,

epicardium/meson.build

@@ -103,7 +103,7 @@ elf = executable(
   ble_sources,
   version_hdr,
   version_screen,
-  dependencies: [libcard10, max32665_startup_core0, maxusb, libff13, ble, bhy1, libcrypto],
+  dependencies: [libcard10, max32665_startup_core0, maxusb, libff13, ble, bhy1, libcrypto, bsec],
   link_with: [api_dispatcher_lib, freertos],
   link_whole: [max32665_startup_core0_lib, board_card10_lib, newlib_heap_lib],
   include_directories: [freertos_includes],

epicardium/modules/bme680.c

@@ -67,6 +67,13 @@ int epic_bme680_init()
 {
 	int8_t result = BME680_OK;
 
+	if (bsec_active()) {
+		/* If the proprietary Bosch BSEC libary is in use
+		 * we redirect calls to that. It always runs
+		 * in the background
+		 */
+		return 0;
+	}
 	if (initialized) {
 		return 0;
 	}
@@ -133,6 +140,10 @@ int epic_bme680_deinit()
 	 * penalty.
 	 */
 
+	if (bsec_active()) {
+		return 0;
+	}
+
 #if 0
 	if (!initialized) {
 		return 0;
@@ -152,11 +163,19 @@ int epic_bme680_read_sensors(struct bme680_sensor_data *data)
 {
 	int8_t result = BME680_OK;
 
+	if (bsec_active()) {
+		return bsec_read_bme680(data);
+	}
+
 	if (!initialized) {
 		LOG_ERR("bme680", "bme680 sensor not initialized");
 		return -EINVAL;
 	}
 
+	if (data == NULL) {
+		return -EFAULT;
+	}
+
 	uint16_t profile_dur = 0;
 	bme680_get_profile_dur(&profile_dur, &bme);
 

epicardium/modules/bsec.c

+/* Adapted from  bsec_iot_example.c and bsec_iot_ulp_plus_example.c */
+
+#include "card10.h"
+#include "bosch.h"
+#include "bsec_integration.h"
+
+#include "ble/ess.h"
+
+#include "epicardium.h"
+#include "modules.h"
+#include "config.h"
+#include "modules/log.h"
+
+#include "FreeRTOS.h"
+#include "task.h"
+
+#include "max32665.h"
+#include "gcr_regs.h"
+
+#include <string.h>
+#include <stdio.h>
+
+TaskHandle_t bsec_task_id;
+static int64_t last_bme680_timestamp;
+static bool bsec_task_active;
+static bool debug;
+static struct bsec_sensor_data last_bsec_data;
+#define ULP 0
+
+// From generic_18v_3s_4d/bsec_serialized_configurations_iaq.c
+static const uint8_t bsec_config_generic_18v_3s_4d[454] = {
+	0,   8,   4,   1,   61,  0,   0,   0,   0,   0,   0,   0,   174, 1,
+	0,   0,   48,  0,   1,   0,   0,   192, 168, 71,  64,  49,  119, 76,
+	0,   0,   225, 68,  137, 65,  0,   191, 205, 204, 204, 190, 0,   0,
+	64,  191, 225, 122, 148, 190, 0,   0,   0,   0,   216, 85,  0,   100,
+	0,   0,   0,   0,   0,   0,   0,   0,   28,  0,   2,   0,   0,   244,
+	1,   225, 0,   25,  0,   0,   128, 64,  0,   0,   32,  65,  144, 1,
+	0,   0,   112, 65,  0,   0,   0,   63,  16,  0,   3,   0,   10,  215,
+	163, 60,  10,  215, 35,  59,  10,  215, 35,  59,  9,   0,   5,   0,
+	0,   0,   0,   0,   1,   88,  0,   9,   0,   7,   240, 150, 61,  0,
+	0,   0,   0,   0,   0,   0,   0,   28,  124, 225, 61,  52,  128, 215,
+	63,  0,   0,   160, 64,  0,   0,   0,   0,   0,   0,   0,   0,   205,
+	204, 12,  62,  103, 213, 39,  62,  230, 63,  76,  192, 0,   0,   0,
+	0,   0,   0,   0,   0,   145, 237, 60,  191, 251, 58,  64,  63,  177,
+	80,  131, 64,  0,   0,   0,   0,   0,   0,   0,   0,   93,  254, 227,
+	62,  54,  60,  133, 191, 0,   0,   64,  64,  12,  0,   10,  0,   0,
+	0,   0,   0,   0,   0,   0,   0,   229, 0,   254, 0,   2,   1,   5,
+	48,  117, 100, 0,   44,  1,   112, 23,  151, 7,   132, 3,   197, 0,
+	92,  4,   144, 1,   64,  1,   64,  1,   144, 1,   48,  117, 48,  117,
+	48,  117, 48,  117, 100, 0,   100, 0,   100, 0,   48,  117, 48,  117,
+	48,  117, 100, 0,   100, 0,   48,  117, 48,  117, 100, 0,   100, 0,
+	100, 0,   100, 0,   48,  117, 48,  117, 48,  117, 100, 0,   100, 0,
+	100, 0,   48,  117, 48,  117, 100, 0,   100, 0,   44,  1,   44,  1,
+	44,  1,   44,  1,   44,  1,   44,  1,   44,  1,   44,  1,   44,  1,
+	44,  1,   44,  1,   44,  1,   44,  1,   44,  1,   8,   7,   8,   7,
+	8,   7,   8,   7,   8,   7,   8,   7,   8,   7,   8,   7,   8,   7,
+	8,   7,   8,   7,   8,   7,   8,   7,   8,   7,   112, 23,  112, 23,
+	112, 23,  112, 23,  112, 23,  112, 23,  112, 23,  112, 23,  112, 23,
+	112, 23,  112, 23,  112, 23,  112, 23,  112, 23,  255, 255, 255, 255,
+	255, 255, 255, 255, 220, 5,   220, 5,   220, 5,   255, 255, 255, 255,
+	255, 255, 220, 5,   220, 5,   255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 44,  1,   0,   0,
+	0,   0,   83,  141, 0,   0
+};
+
+/*!
+ * @brief           Capture the system time in microseconds
+ *
+ * @return          system_current_time    current system timestamp in microseconds
+ */
+static int64_t get_timestamp_us()
+{
+	int64_t tick = xTaskGetTickCount();
+	return tick * 1000;
+}
+
+/*!
+ * @brief           Handling of the ready outputs
+ *
+ * @param[in]       timestamp       time in nanoseconds
+ * @param[in]       iaq             IAQ signal
+ * @param[in]       iaq_accuracy    accuracy of IAQ signal
+ * @param[in]       temperature     temperature signal
+ * @param[in]       humidity        humidity signal
+ * @param[in]       pressure        pressure signal
+ * @param[in]       raw_temperature raw temperature signal
+ * @param[in]       raw_humidity    raw humidity signal
+ * @param[in]       gas             raw gas sensor signal
+ * @param[in]       bsec_status     value returned by the bsec_do_steps() call
+ *
+ * @return          none
+ */
+static void output_ready(
+	int64_t timestamp,
+	float iaq,
+	uint8_t iaq_accuracy,
+	float temperature,
+	float humidity,
+	float pressure,
+	float raw_temperature,
+	float raw_humidity,
+	float gas,
+	bsec_library_return_t bsec_status,
+	float static_iaq,
+	float co2_equivalent,
+	float breath_voc_equivalent
+) {
+	last_bsec_data.temperature               = temperature;
+	last_bsec_data.humidity                  = humidity;
+	last_bsec_data.pressure                  = pressure / 100.;
+	last_bsec_data.gas_resistance            = gas;
+	last_bsec_data.timestamp                 = timestamp;
+	last_bsec_data.accuracy                  = iaq_accuracy;
+	last_bsec_data.indoor_air_quality        = iaq;
+	last_bsec_data.static_indoor_air_quality = static_iaq;
+	last_bsec_data.co2_equivalent            = co2_equivalent;
+	last_bsec_data.breath_voc_equivalent     = breath_voc_equivalent;
+
+	__sync_synchronize();
+
+	last_bme680_timestamp = timestamp;
+
+	bleESS_update_from_bsec_data(&last_bsec_data);
+
+	if (debug) {
+		LOG_INFO(
+			"bsec",
+			"time[ms]: %u, IAQ: %u, IAQ ACC[0-3]: %u, T[.1C]: %u, Hum[.1%%]: %u, P[Pa]: %u, Raw T[.1C]: %u, Raw Hum[.1%%]: %u, Gas[Ohm]: %u, Static IAQ: %u, CO2[ppm]: %u, Breath VOC[ppb]: %u",
+			(unsigned int)(timestamp / 1e6),
+			(unsigned int)(iaq),
+			(unsigned int)(iaq_accuracy),
+			(unsigned int)(temperature * 10),
+			(unsigned int)(humidity * 10),
+			(unsigned int)(pressure),
+			(unsigned int)(raw_temperature * 10),
+			(unsigned int)(raw_humidity * 10),
+			(unsigned int)(gas),
+			(unsigned int)(static_iaq),
+			(unsigned int)(co2_equivalent),
+			(unsigned int)(breath_voc_equivalent * 1e3)
+		);
+	}
+}
+
+int epic_bsec_read_sensors(struct bsec_sensor_data *data)
+{
+	if (data == NULL) {
+		return -EFAULT;
+	}
+	if (!bsec_task_active) {
+		return -ENODEV;
+	}
+
+	/* TODO: could also return -EINVAL */
+	while (last_bme680_timestamp == 0)
+		vTaskDelay(pdMS_TO_TICKS(10));
+
+	*data = last_bsec_data;
+	return 0;
+}
+
+static uint32_t bsec_load(char *path, uint8_t *buffer, uint32_t n_buffer)
+{
+	uint32_t len = 0;
+	int fd, res;
+
+	LOG_DEBUG("bsec", "load %s %lu", path, n_buffer);
+
+	if ((fd = epic_file_open(path, "r")) < 0) {
+		LOG_DEBUG("bsec", "Open failed");
+		return 0;
+	}
+
+	uint32_t header;
+	if ((res = epic_file_read(fd, &header, sizeof(header))) !=
+	    sizeof(header)) {
+		LOG_WARN("bsec", "Header failed");
+		goto done;
+	}
+
+	if (header > n_buffer) {
+		LOG_WARN("bsec", "Too large");
+		goto done;
+	}
+
+	if (epic_file_read(fd, buffer, header) != (int)header) {
+		LOG_WARN("bsec", "Read failed");
+		goto done;
+	}
+
+	len = header;
+
+	LOG_DEBUG("bsec", "Success");
+done:
+	epic_file_close(fd);
+	return len;
+}
+/*!
+ * @brief           Load previous library state from non-volatile memory
+ *
+ * @param[in,out]   state_buffer    buffer to hold the loaded state string
+ * @param[in]       n_buffer        size of the allocated state buffer
+ *
+ * @return          number of bytes copied to state_buffer
+ */
+static uint32_t state_load(uint8_t *state_buffer, uint32_t n_buffer)
+{
+	return bsec_load("bsec_iaq.state", state_buffer, n_buffer);
+}
+
+/*!
+ * @brief           Save library state to non-volatile memory
+ *
+ * @param[in]       state_buffer    buffer holding the state to be stored
+ * @param[in]       length          length of the state string to be stored
+ *
+ * @return          none
+ */
+static void state_save(const uint8_t *state_buffer, uint32_t length)
+{
+	int fd, res;
+
+	LOG_DEBUG("bsec", "state_save %d", (int)length);
+
+	if ((fd = epic_file_open("bsec_iaq.state", "w")) < 0) {
+		LOG_WARN("bsec", "Open failed");
+		return;
+	}
+
+	uint32_t header = length;
+	if ((res = epic_file_write(fd, &header, sizeof(header))) !=
+	    sizeof(header)) {
+		LOG_WARN("bsec", "Header failed");
+		goto done;
+	}
+
+	if (epic_file_write(fd, state_buffer, header) != (int)header) {
+		LOG_WARN("bsec", "Write failed");
+		goto done;
+	}
+
+	LOG_DEBUG("bsec", "stack high: %lu", uxTaskGetStackHighWaterMark(NULL));
+done:
+	epic_file_close(fd);
+}
+/*!
+ * @brief           Delete the library state from non-volatile memory
+ *
+ * @return          none
+ */
+static void state_delete(void)
+{
+	LOG_DEBUG("bsec", "state_delete");
+
+	epic_file_unlink("bsec_iaq.state");
+}
+
+static int8_t
+i2c_write(uint8_t addr, uint8_t reg, uint8_t *p_buf, uint16_t size)
+{
+	int8_t ret;
+	hwlock_acquire(HWLOCK_I2C);
+	ret = card10_bosch_i2c_write(addr, reg, p_buf, size);
+	hwlock_release(HWLOCK_I2C);
+	return ret;
+}
+
+static int8_t i2c_read(uint8_t addr, uint8_t reg, uint8_t *p_buf, uint16_t size)
+{
+	int8_t ret;
+	hwlock_acquire(HWLOCK_I2C);
+	ret = card10_bosch_i2c_read(addr, reg, p_buf, size);
+	hwlock_release(HWLOCK_I2C);
+	return ret;
+}
+
+static void delay(uint32_t msec)
+{
+	if (xTaskGetSchedulerState() == taskSCHEDULER_NOT_STARTED) {
+		/* We need to fall back to hardware waits if not running
+		 * in a task context */
+		card10_bosch_delay(msec);
+	} else {
+		vTaskDelay(pdMS_TO_TICKS(msec));
+	}
+}
+
+/*!
+ * @brief           Load library config from non-volatile memory
+ *
+ * @param[in,out]   config_buffer    buffer to hold the loaded state string
+ * @param[in]       n_buffer        size of the allocated state buffer
+ *
+ * @return          number of bytes copied to config_buffer
+ */
+static uint32_t config_load(uint8_t *config_buffer, uint32_t n_buffer)
+{
+	uint32_t len = bsec_load("bsec_iaq.config", config_buffer, n_buffer);
+
+	if (len == 0) {
+		LOG_INFO("bsec", "Using default bsec_config_generic_18v_3s_4d");
+		len = sizeof(bsec_config_generic_18v_3s_4d);
+		memcpy(config_buffer, bsec_config_generic_18v_3s_4d, len);
+	}
+
+	return len;
+}
+
+#if ULP
+void ulp_plus_trigger_iaq()
+{
+	/* We call bsec_update_subscription() in order to instruct BSEC to perform an extra measurement at the next
+     * possible time slot
+     */
+
+	bsec_sensor_configuration_t requested_virtual_sensors[1];
+	uint8_t n_requested_virtual_sensors = 1;
+	bsec_sensor_configuration_t
+		required_sensor_settings[BSEC_MAX_PHYSICAL_SENSOR];
+	uint8_t n_required_sensor_settings = BSEC_MAX_PHYSICAL_SENSOR;
+	bsec_library_return_t status       = BSEC_OK;
+
+	/* To trigger a ULP plus, we request the IAQ virtual sensor with a specific sample rate code */
+	requested_virtual_sensors[0].sensor_id = BSEC_OUTPUT_IAQ;
+	requested_virtual_sensors[0].sample_rate =
+		BSEC_SAMPLE_RATE_ULP_MEASUREMENT_ON_DEMAND;
+
+	/* Call bsec_update_subscription() to enable/disable the requested virtual sensors */
+	status = bsec_update_subscription(
+		requested_virtual_sensors,
+		n_requested_virtual_sensors,
+		required_sensor_settings,
+		&n_required_sensor_settings
+	);
+
+	/* The status code would tell is if the request was accepted. It will be rejected if the sensor is not already in
+     * ULP mode, or if the time difference between requests is too short, for example. */
+}
+#endif
+
+bool bsec_active(void)
+{
+	return bsec_task_active;
+}
+
+int bsec_read_bme680(struct bme680_sensor_data *data)
+{
+	if (!bsec_task_active) {
+		return BME680_E_COM_FAIL;
+	}
+
+	if (data == NULL) {
+		return -EFAULT;
+	}
+
+	while (last_bme680_timestamp == 0)
+		vTaskDelay(pdMS_TO_TICKS(10));
+
+	data->temperature    = last_bsec_data.temperature;
+	data->humidity       = last_bsec_data.humidity;
+	data->pressure       = last_bsec_data.pressure;
+	data->gas_resistance = last_bsec_data.gas_resistance;
+
+	return BME680_OK;
+}
+
+/**
+ * Checks config and activates the BSEC libary if requested.
+ *
+ * Initializes the BSEC library before starting the task to
+ * reduce the stack size needed for the task by at least 250 bytes
+ */
+int bsec_activate(void)
+{
+	return_values_init ret;
+#if ULP
+	float sample_rate = BSEC_SAMPLE_RATE_ULP;
+#else
+	float sample_rate = BSEC_SAMPLE_RATE_LP;
+#endif
+
+	if (!config_get_boolean_with_default("bsec_enable", false)) {
+		return -1;
+	}
+
+	debug = config_get_boolean_with_default("bsec_debug", false);
+
+	float temperature_offset =
+		config_get_integer_with_default("bsec_offset", -22) / 10.;
+	if (temperature_offset != 0.0) {
+		LOG_INFO(
+			"besec",
+			"BSEC Temp offset %d/10 K",
+			(int)(temperature_offset * 10)
+		);
+	}
+
+	/* Puts AT LEAST 2 * #BSEC_MAX_PROPERTY_BLOB_SIZE = 2 * 454 = 908 bytes onto the stack */
+	ret = bsec_iot_init(
+		sample_rate,
+		-temperature_offset,
+		i2c_write,
+		i2c_read,
+		delay,
+		state_load,
+		config_load
+	);
+
+	if (ret.bsec_status == BSEC_E_CONFIG_VERSIONMISMATCH) {
+		/* BSEC version changed and old state is not compatible anymore */
+		/* If the config is also not valid anymore, the user will have
+		 * to fix that. */
+		state_delete();
+		ret = bsec_iot_init(
+			sample_rate,
+			-temperature_offset,
+			i2c_write,
+			i2c_read,
+			delay,
+			state_load,
+			config_load
+		);
+	}
+
+	if (ret.bme680_status) {
+		LOG_WARN("bsec", "bme680 init failed: %d", ret.bme680_status);
+		/* Could not initialize BME680 */
+		return -1;
+	} else if (ret.bsec_status) {
+		LOG_WARN("bsec", "bsec init failed: %d", ret.bsec_status);
+		/* Could not initialize BSEC library */
+		return -1;
+	}
+	return 0;
+}
+
+void vBSECTask(void *pvParameters)
+{
+	bsec_task_active = true;
+	bsec_task_id     = xTaskGetCurrentTaskHandle();
+
+#if ULP
+	/* State is saved every 100 samples, which means every 100 * 300 secs = 500 minutes  */
+	const int stat_save_interval = 100;
+#else
+	/* State is saved every 10.000 samples, which means every 10.000 * 3 secs = 500 minutes  */
+	const int stat_save_interval = 10000;
+#endif
+
+	/* Call to endless loop function which reads and processes data based on sensor settings */
+	/* Puts AT LEAST 2 * BSEC_MAX_STATE_BLOB_SIZE + 8 * sizeof(bsec_input_t) =
+	 * 2 * 139 + 8 * 20 = 438 bytes onto the stack */
+	bsec_iot_loop(
+		delay,
+		get_timestamp_us,
+		output_ready,
+		state_save,
+		stat_save_interval
+	);
+}

epicardium/modules/meson.build

 module_sources = files(
   'bhi.c',
+  'bsec.c',
   'bme680.c',
   'buttons.c',
   'config.c',

epicardium/modules/modules.h

@@ -136,6 +136,12 @@ void max30001_mutex_init(void);
 /* ---------- GPIO --------------------------------------------------------- */
 extern gpio_cfg_t gpio_configs[];
 
+/* ---------- BSEC / BME680 ------------------------------------------------ */
+int bsec_activate(void);
+void vBSECTask(void *pvParameters);
+bool bsec_active(void);
+struct bme680_sensor_data;
+int bsec_read_bme680(struct bme680_sensor_data *data);
 
 /* ---------- Sleep -------------------------------------------------------- */
 void sleep_deepsleep(void);

lib/meson.build

@@ -2,6 +2,7 @@ subdir('./sdk/')
 
 subdir('./vendor/Bosch/BHy1/')
 subdir('./vendor/Bosch/BME680/')
+subdir('./vendor/Bosch/BSEC/')
 subdir('./vendor/Bosch/BMA400/')
 subdir('./vendor/Maxim/MAX77650/')
 subdir('./vendor/Maxim/MAX86150/')