docs(bme680): Document new sensor interface

Signed-off-by: Rahix <rahix@rahix.de>

Documentation/conf.py

@@ -90,6 +90,7 @@ html_context = {
 autodoc_mock_imports = [
     "buttons",
     "interrupt",
+    "sys_bme680",
     "sys_display",
     "sys_leds",
     "sys_max30001",

Documentation/pycardium/bme680.rst

@@ -2,6 +2,7 @@
 
 ``bme680`` - Environmental Sensor
 =================================
+Allows access to environmental data of card10's surroundings.
 
 **Example**:
 
@@ -9,17 +10,28 @@
 
    import bme680, utime
 
-   bme680.init()
+   with bme680.Bme680() as environment:
+       while True:
+           d = environment.get_data()
 
-   while True:
-       temperature, humidity, pressure, resistance = bme680.get_data()
+           print("Temperature:    {:10.2f} °C".format(d.temperature))
+           print("Humidity:       {:10.2f} % r.h.".format(d.humidity))
+           print("Pressure:       {:10.2f} hPa".format(d.pressure))
+           print("Gas Resistance: {:10.2f} Ω".format(d.resistance))
 
-       print("Temperature:    {:10.2f} °C".format(temperature))
-       print("Humidity:       {:10.2f} % r.h.".format(humidity))
-       print("Pressure:       {:10.2f} hPa".format(pressure))
-       print("Gas Resistance: {:10.2f} Ω".format(resistance))
+           utime.sleep(1)
 
-       utime.sleep(1)
+Sensor Class
+------------
+
+.. autoclass:: bme680.Bme680
+   :members:
+
+Deprecated Interface
+--------------------
+The following functions should no longer be used directly.  The only exist for
+compatibility as they were the old BME680 interface in previous firmware
+versions.
 
 .. py:function:: init()
 
@@ -29,6 +41,8 @@
    :py:func:`bme680.init`.
 
    .. versionadded:: 1.4
+   .. deprecated:: 1.10
+      Use the :py:class:`bme680.Bme680` class instead.
 
 .. py:function:: get_data()
 
@@ -38,9 +52,13 @@
       ``pressure`` (hPa) and ``gas resistance`` (Ohm).
 
    .. versionadded:: 1.4
+   .. deprecated:: 1.10
+      Use the :py:class:`bme680.Bme680` class instead.
 
 .. py:function:: deinit()
 
    Deinitialize the sensor.
 
    .. versionadded:: 1.4
+   .. deprecated:: 1.10
+      Use the :py:class:`bme680.Bme680` class instead.

pycardium/modules/py/bme680.py

@@ -10,6 +10,33 @@ Bme680Data = ucollections.namedtuple(
 
 
 class Bme680:
+    """
+    BME680 4-in-1 environmental sensor.
+
+    **Example**:
+
+    .. code-block:: python
+
+        import bme680
+
+        environment = bme680.Bme680()
+        print("Current temperature: {:4.1f} °C".format(environment.temperature()))
+
+    This class can also be used as a context-manager which will automatically
+    deactivate the sensor on exit:
+
+    .. code-block:: python
+
+        import bme680
+
+        with bme680.Bme680() as environment:
+            print("H: {:4.1f}%".format(environment.humidity()))
+
+        # Sensor is off again, saving power
+
+    .. versionadded:: 1.10
+    """
+
     def __init__(self):
         sys_bme680.init()
 
@@ -20,19 +47,88 @@ class Bme680:
         self.close()
 
     def get_data(self):
+        """
+        Get all sensor data at once.
+
+        :py:meth:`~bme680.Bme680.get_data` returns a namedtuple with the
+        following fields:
+
+        - ``temperature``: Temperature in *°C*
+        - ``humidity``: Relative humidity
+        - ``pressure``: Barometric pressure in *hPa*
+        - ``gas_resistance``: Gas resistance in *Ω*
+
+        **Example**:
+
+        .. code-block:: python
+
+            import bme680
+
+            with bme680.Bme680() as environment:
+                data = environment.get_data()
+
+                print("T: {}".format(data.temperature))
+                print("H: {}".format(data.humidity))
+        """
         return Bme680Data(*sys_bme680.get_data())
 
     def close(self):
+        """
+        Stop/deinit the BME680.
+
+        If you no longer need measurements, you should call this function to
+        save power.
+        """
         sys_bme680.deinit()
 
     def temperature(self):
+        """
+        Measure current temperature in *°C*.
+
+        **Example**:
+
+        .. code-block:: python
+
+            environment = bme680.Bme680()
+            print(str(environment.temperature()))
+        """
         return self.get_data().temperature
 
     def humidity(self):
+        """
+        Measure current relative humidity.
+
+        **Example**:
+
+        .. code-block:: python
+
+            environment = bme680.Bme680()
+            print(str(environment.humidity()))
+        """
         return self.get_data().humidity
 
     def pressure(self):
+        """
+        Measure current barometric pressure in *hPa*.
+
+        **Example**:
+
+        .. code-block:: python
+
+            environment = bme680.Bme680()
+            print(str(environment.pressure()))
+        """
         return self.get_data().pressure
 
     def gas_resistance(self):
+        """
+        Measure current gas resistance in *Ω*.
+
+        **Example**:
+
+        .. code-block:: python
+
+            environment = bme680.Bme680()
+            print(str(environment.gas_resistance()))
+        """
         return self.get_data().gas_resistance