From 35687ce319a149a44b0a725a59381084d5c16bd4 Mon Sep 17 00:00:00 2001
From: schneider <schneider@blinkenlichts.net>
Date: Thu, 24 Dec 2020 19:33:11 +0100
Subject: [PATCH] feat(bsec): Improve documentation
---
Documentation/bluetooth/ess.rst | 2 ++
Documentation/pycardium/ble_hid.rst | 2 +-
Documentation/pycardium/bme680.rst | 25 +++++++++++++++++++++++++
Documentation/pycardium/config.rst | 2 +-
epicardium/epicardium.h | 4 ++--
epicardium/modules/bsec.c | 4 +---
pycardium/modules/py/bme680.py | 22 ++++++++++++++--------
pycardium/modules/py/config.py | 6 +++---
8 files changed, 49 insertions(+), 18 deletions(-)
diff --git a/Documentation/bluetooth/ess.rst b/Documentation/bluetooth/ess.rst
index 6a84a6ab..3d9378b1 100644
--- a/Documentation/bluetooth/ess.rst
+++ b/Documentation/bluetooth/ess.rst
@@ -1,3 +1,5 @@
+.. _ESS:
+
Environmental Sensing Service
========================
diff --git a/Documentation/pycardium/ble_hid.rst b/Documentation/pycardium/ble_hid.rst
index 98f86b97..0985d0a2 100644
--- a/Documentation/pycardium/ble_hid.rst
+++ b/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
diff --git a/Documentation/pycardium/bme680.rst b/Documentation/pycardium/bme680.rst
index 9bdef024..05dac8cc 100644
--- a/Documentation/pycardium/bme680.rst
+++ b/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
diff --git a/Documentation/pycardium/config.rst b/Documentation/pycardium/config.rst
index 926098eb..d4ac67bc 100644
--- a/Documentation/pycardium/config.rst
+++ b/Documentation/pycardium/config.rst
@@ -1,7 +1,7 @@
``config`` - Configuration
==========================
The ``config`` module provides functions to interact with card10's
-configuration file (``card10.cfg``).
+configuration file (:ref:`card10_cfg`).
.. automodule:: config
:members:
diff --git a/epicardium/epicardium.h b/epicardium/epicardium.h
index 2912e1b8..2cfc527a 100644
--- a/epicardium/epicardium.h
+++ b/epicardium/epicardium.h
@@ -929,7 +929,7 @@ API(API_BME680_GET_DATA, int epic_bme680_read_sensors(
* equivalents using the gas sensor of the BME680.
*
* As it is a proprietary binary blob, it has to be enabled using
- * the ``bsec_enabled`` configuration option (see :ref:`card10_cfg`).
+ * the ``bsec_enable`` configuration option (see :ref:`card10_cfg`).
*/
/**
@@ -1017,7 +1017,7 @@ struct bsec_sensor_data {
* 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_enabled`` configuration option (see :ref:`card10_cfg`).
+ * 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.
diff --git a/epicardium/modules/bsec.c b/epicardium/modules/bsec.c
index e4ef7e78..27eb6c63 100644
--- a/epicardium/modules/bsec.c
+++ b/epicardium/modules/bsec.c
@@ -380,9 +380,7 @@ int bsec_activate(void)
float sample_rate = BSEC_SAMPLE_RATE_LP;
#endif
- bool bsec_enabled =
- config_get_boolean_with_default("bsec_enable", false);
- if (!bsec_enabled) {
+ if (!config_get_boolean_with_default("bsec_enable", false)) {
return -1;
}
diff --git a/pycardium/modules/py/bme680.py b/pycardium/modules/py/bme680.py
index b50b0562..93945474 100644
--- a/pycardium/modules/py/bme680.py
+++ b/pycardium/modules/py/bme680.py
@@ -71,8 +71,8 @@ class Bme680:
- ``pressure``: Barometric pressure in *hPa*
- ``gas_resistance``: Gas resistance in *Ω*
- If the Bosch BSEC libary is active the following extra fields will
- be returned:
+ If the Bosch BSEC library is enabled in :ref:`card10_cfg`, the
+ following additional fields will be returned:
- ``iaq``: Indoor air quality indication
- ``iaq_accuracy``: Accuracy of indoor air quality
@@ -159,9 +159,9 @@ class Bme680:
def iaq(self):
"""
- Retrieve indoor air quality as defined by the Bosch BSEC libaray.
+ Retrieve indoor air quality as defined by the Bosch BSEC library.
- BSEC needs to be enable in ``card10.cfg``. Otherwise this method
+ BSEC needs to be enable in :ref:`card10_cfg`. Otherwise this method
will raise an ``OSError`` exception.
**Example**:
@@ -170,14 +170,16 @@ class Bme680:
environment = bme680.Bme680()
print(str(environment.iaq()))
+
+ .. versionadded:: 1.17
"""
return BSECData(*sys_bme680.bsec_get_data()).iaq
def iaq_accuracy(self):
"""
- Retrieve indoor air quality accuracy as defined by the Bosch BSEC libaray.
+ Retrieve indoor air quality accuracy as defined by the Bosch BSEC library.
- BSEC needs to be enable in ``card10.cfg``. Otherwise this method
+ BSEC needs to be enable in :ref:`card10_cfg`. Otherwise this method
will raise an ``OSError`` exception.
**Example**:
@@ -186,15 +188,17 @@ class Bme680:
environment = bme680.Bme680()
print(str(environment.iaq_accuracy()))
+
+ .. versionadded:: 1.17
"""
return BSECData(*sys_bme680.bsec_get_data()).iaq_accuracy
def eco2(self):
"""
- Retrieve equivalant CO2 as defined by the Bosch BSEC libaray.
+ Retrieve equivalant CO2 as defined by the Bosch BSEC library.
- BSEC needs to be enable in ``card10.cfg``. Otherwise this method
+ BSEC needs to be enable in :ref:`card10_cfg`. Otherwise this method
will raise an ``OSError`` exception.
**Example**:
@@ -203,6 +207,8 @@ class Bme680:
environment = bme680.Bme680()
print(str(environment.eco2()))
+
+ .. versionadded:: 1.17
"""
return BSECData(*sys_bme680.bsec_get_data()).eco2
diff --git a/pycardium/modules/py/config.py b/pycardium/modules/py/config.py
index 7fae24c9..9f9927a5 100644
--- a/pycardium/modules/py/config.py
+++ b/pycardium/modules/py/config.py
@@ -3,7 +3,7 @@ import sys_config
def set_string(key, value):
"""
- Write a string to the configuration file ``card10.cfg``.
+ Write a string to the configuration file :ref:`card10_cfg`.
Both ``key`` and ``value`` must be strings or must be
convertible to a string using the :py:func:`str()` function.
@@ -14,7 +14,7 @@ def set_string(key, value):
Neither is allowed to contain the sub-string ``"execute_elf"``.
The key/value pair is immediately written to the configuration
- file (``card10.cfg``). After the file is written, configuration
+ file (:ref:`card10_cfg`). After the file is written, configuration
is read again and the new value is available via :py:func:`config.get_string`.
:param str key: Name of the configuration option.
@@ -31,7 +31,7 @@ def set_string(key, value):
def get_string(key):
"""
- Read a string from the configuration file ``card10.cfg``.
+ Read a string from the configuration file :ref:`card10_cfg`.
``key`` must be a string or must be convertible to a string using
the :py:func:`str()` function.
--
GitLab