Documentation/overview.rst

+.. _firmware_overview:
+
+Overview
+========
+To make the most of card10's dual-core processor, its firmware will have been
+divided into two parts: The "main" firmware running on core 0 which will have
+been called *Epicardium* and the "user-code" running on core 1.  In most cases
+this will have been *Pycardium*, our MicroPython port.
+
+.. image:: ./static/overview.svg
+
+Epicardium
+----------
+Epicardium is based on `FreeRTOS <https://www.freertos.org/>`_.  There are a
+number of tasks that will have been keeping card10 running.  These are:
+
++--------------------+-------------------------------+----------+-------------------------------------------+
+| Name               | ID Global                     | Priority | Description                               |
++====================+===============================+==========+===========================================+
+| `vPmicTask`_       | ``pmic_task_id`` (static)     | +4       | Power Management (and Reset Button)       |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vLifecycleTask`_  | ``lifecycle_task`` (static)   | +3       | Control of the payload running on core 1. |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vBleTask`_        | ``ble_task_id`` (static)      | +3       | Bluetooth Low Energy Stack                |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vSerialTask`_     | ``serial_task_id``            | +3       | Serial Output via UART/CDC-ACM/BLE        |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vApiDispatcher`_  | ``dispatcher_task_id``        | +2       | Epicardium API dispatcher                 |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vInterruptsTask`_ | ``interrupts_task`` (static)  | +2       | Interrupt dispatcher worker               |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vMAX30001Task`_   | ``max30001_task_id`` (static) | +1       | `MAX30001`_ ECG driver                    |
++--------------------+-------------------------------+----------+-------------------------------------------+
+| `vBhi160Task`_     | ``bhi160_task_id`` (static)   | +1       | `BHI160`_ sensor fusion driver            |
++--------------------+-------------------------------+----------+-------------------------------------------+
+
+.. _vPmicTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/pmic.c#L281
+.. _vLifecycleTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/lifecycle.c#L361
+.. _vBleTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/ble/ble.c#L237
+.. _vSerialTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/serial.c#L289
+.. _vApiDispatcher: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/dispatcher.c#L25
+.. _vInterruptsTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/interrupts.c#L119
+.. _vLedTask: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/personal_state.c#L58
+.. _vMAX30001Task: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/max30001.c#L378
+.. _vBhi160Task: https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/epicardium/modules/bhi.c#L419
+
+.. _MAX30001: https://www.maximintegrated.com/en/products/analog/data-converters/analog-front-end-ics/MAX30001.html
+.. _BHI160: https://www.bosch-sensortec.com/bst/products/all_products/bhi160
+
+Epicardium API
+--------------
+Epicardium exposes lots of functionality via the *Epicardium API*.  The
+technical details of this API can be found in this :ref:`overview
+<epicardium_api_overview>`.  If you are interested in adding new API calls,
+you should probably read the :ref:`epicardium_api_guide` guide.
+
+Pycardium
+---------
+
+Pycardium is our MicroPython fork.  Its purpose is to make it as easy as
+possible to interact with card10.  If you are interested in working on
+Pycardium, take a look at the :ref:`pycardium_guide` guide.
+
+.. _l0dables:
+
+l0dables
+--------
+
+Next to Pycardium, other bare-metal code can also run on core 1.  For example,
+a `Rustcardium`_ or C-cardium.  These l0dables must be compiled using our special
+linker script and should link against the api-caller library so they can
+interface with the :ref:`epicardium_api`.
+
+Note: this feature is disabled by default and has to be enabled in :ref:`card10_cfg`. A :ref:`card10_cfg` file dropped into the :ref:`usb_file_transfer` of the badge containing ``execute_elf = true`` is enough.
+
+l0dables are currently built within the source tree of the main repository. See |l0dables_blinky|_ for an example of a hello-world-like program. Within those programs, you can access the :ref:`epicardium_api` to control the hardware and behaviour of the badge.
+
+Once you have a built ELF file, you can drop it into the FAT filesystem of the flash (eg. via :ref:`usb_file_transfer`) and it will be available from the menu program of the badge.
+
+.. _Rustcardium: https://git.card10.badge.events.ccc.de/astro/rust-card10
+.. |l0dables_blinky| replace:: ``l0dables/blinky``
+.. _l0dables_blinky: https://git.card10.badge.events.ccc.de/card10/firmware/-/tree/master/l0dables
+
+Program Flow Diagram
+--------------------
+The following diagram is a rough overview of the program flow in this fimware:
+
+.. image:: ./static/firmware-flow.svg

Documentation/pycardium-guide.rst

+.. _pycardium_guide:
+
+Pycardium Module Development
+============================
+This is a step-by-step guide on augmenting Pycardium with new modules.  These
+module are either written in Python or in C:
+
+* **Python Modules**: Python modules live in ``pycardium/modules/py`` and are
+  pre-compiled and packed into Pycardium at build-time.  Python modules are
+  meant to be used for creating abstractions and helpers based on lower level
+  functionality.  The rationale is that it is easier to write pythonic modules
+  in python instead of having to wrap all that in C code.  Though care has to
+  be taken as these modules can eat quite a lot of space.
+
+* **C Modules**: C modules allow MicroPython code to interface with the rest of
+  the system or allow a much faster implementation of performance-critical
+  code. For interfacing with card10, these modules are mostly meant to make use
+  of the :ref:`Epicardium API <epicardium_api_overview>`.
+
+Python Modules
+--------------
+Adding a new Python module
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add a file in ``pycardium/modules/py``.  The name of the file dictates the name
+of the module.  Next, add you file to the list in
+``pycardium/modules/py/meson.build`` to make the build-system aware of it.
+Rebuild, and you should see your module pop up in the list shown by
+
+.. code-block:: python
+
+   help("modules")
+
+Size Consideration
+~~~~~~~~~~~~~~~~~~
+Python modules can get quite big.  If you want to know exact sizes, take a look at
+the output of
+
+.. code-block:: shell-session
+
+   ls -lh build/pycardium/*@@frozen.c@*/
+
+If your module contains some kind of big lookup-table or data-block, consider
+pushing that into external flash.  You can then read the data using standard
+Python ``open()`` and if you need to decode it, use the ``ustruct`` or ``ujson``
+module.
+
+Creating a new C module
+-----------------------
+Module Source
+~~~~~~~~~~~~~
+Create a new file in ``pycardium/modules``.  The basic structure of a C module
+looks like this:
+
+.. code-block:: c++
+
+   #include "py/obj.h"
+
+   /* Define a function in this module */
+   static mp_obj_t mp_example_hello(mp_obj_t number)
+   {
+           int num = mp_obj_get_int(number);
+           printf("Hello from example: %d\r\n", num);
+           return mp_const_none;
+   }
+   /* Create an object for this function */
+   static MP_DEFINE_CONST_FUN_OBJ_1(example_hello_obj, mp_example_hello);
+
+   /* The globals table for this module */
+   static const mp_rom_map_elem_t example_module_globals_table[] = {
+           {MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_example)},
+           {MP_ROM_QSTR(MP_QSTR_hello), MP_ROM_PTR(&example_hello_obj)},
+   };
+   static MP_DEFINE_CONST_DICT(example_module_globals, example_module_globals_table);
+
+   const mp_obj_module_t example_module = {
+           .base    = {&mp_type_module},
+           .globals = (mp_obj_dict_t*)&example_module_globals,
+   };
+
+   /* This is a special macro that will make MicroPython aware of this module */
+   /* clang-format off */
+   MP_REGISTER_MODULE(MP_QSTR_example, example_module, MODULE_EXAMPLE_ENABLED);
+
+.. note::
+
+   Please keep the ``/* clang-format off */``.  It ensures that *clang-format*
+   won't touch the following line.  This is necessary because MicroPython's
+   codegen scripts can'd deal with newlines in the ``MP_REGISTER_MODULE`` macro.
+
+Build Integration
+~~~~~~~~~~~~~~~~~
+Next, you need to add your module to ``pycardium/meson.build``. There is a list
+of module sources at the very top called ``modsrc`` where you need to add your
+file (e.g. ``modules/example.c``).
+
+QSTR Definitions
+~~~~~~~~~~~~~~~~
+If you now run ``ninja -C build/``, you will hit a few errors regarding missing
+QSTR definitions.  With the example module above, they will look similar to
+this:
+
+.. code-block:: text
+
+   ../pycardium/modules/example.c:15:46: error: 'MP_QSTR_example' undeclared here (not in a function)
+      15 |  {MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_example)},
+
+To fix these errors, you need to add all QSTRs your module needs to
+``pycardium/modules/qstrdefs.h``.  Add a section for your module where you
+define all QSTRs you need:
+
+.. code-block:: cpp
+
+   /* example */
+   Q(example)
+   Q(hello)
+
+Each ``Q(...)`` will define into a corresponding ``MP_QSTR_...``.  So
+``Q(example)`` corresponds to ``MP_QSTR_example``.
+
+Enable Module
+~~~~~~~~~~~~~
+The last step is to actually enable inclusion of your module into the firmware.
+Do this by adding a define in ``pycardium/mpconfigport.h``:
+
+.. code-block:: cpp
+
+   #define MODULE_EXAMPLE_ENABLED              (1)
+
+The name of the define is the one from the last line in the module source above.
+
+Wrapping Epicardium API
+-----------------------
+Most modules will probably make use of the :ref:`Epicardium API
+<epicardium_api_overview>`. Doing so does not require any extra work, you can
+just call the API from your module code.  You should check the input that your
+module got from MicroPython before sending data off to Epicardium.  For
+example, raise a ``ValueError`` if an integer is too big to fit into the type
+specified by the API.  You should also gracefully handle errors returned by API
+calls.  As most API calls use *errno* codes, you can just wrap them in an
+``OSError``:
+
+.. code-block:: cpp
+
+   int ret = epic_bma_get_accel(&values);
+
+   if (ret < 0) {
+          mp_raise_OSError(-ret);
+   }
+
+QSTRs
+-----
+QSTRs are so called “interned strings”. This means they are not allocated like
+normal python objects but instead live in flash and are indexed. This allow
+MicroPython to very efficiently use them as identifiers. According to them,
+comparing two QSTR is as fast as comparing integers.
+
+Unfortunately, the way these QSTRs are collected from the source files is quite
+weird.  MicroPython comes with a few python scripts (namely `makeqstrdefs.py`_
+and `makeqstrdata.py`_) that parse the C source files and search for uses of
+``MP_QSTR_*``.  These are then sorted and indexed into a header file called
+``qstrdefs.collected.h``. This is closely tied in with their Makefiles.
+
+As we use our own build system, we had to somehow wrap this generation to work
+for us as well. This is done using a few scripts in `lib/micropython`_.
+Currently, our build system does **not** parse the module sources to search for
+QSTRs.  Instead all QSTRs needed by modules need to be defined in the header
+``pycardium/modules/qstrdefs.h``.
+
+.. _makeqstrdefs.py: https://github.com/micropython/micropython/blob/master/py/makeqstrdefs.py
+.. _makeqstrdata.py: https://github.com/micropython/micropython/blob/master/py/makeqstrdata.py
+.. _lib/micropython: https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/lib/micropython
+
+Functions for MicroPython
+-------------------------
+As shown in the example above, you can create functions that can be called from
+MicroPython code.  These functions always have one of the following signatures.
+To create a MicroPython object for a function, you need the macro call shown
+after each signature.  Please place these calls directly after the function
+body as shown above.
+
+.. code-block:: cpp
+
+   /* Function with 0 arguments */
+   mp_obj_t mp_example_fun0(void);
+   static MP_DEFINE_CONST_FUN_OBJ_0(example_fun0_obj, mp_example_fun0);
+
+   /* Function with 1 argument */
+   mp_obj_t mp_example_fun1(mp_obj_t arg0_in);
+   static MP_DEFINE_CONST_FUN_OBJ_1(example_fun1_obj, mp_example_fun0);
+
+   /* Function with 2 arguments */
+   mp_obj_t mp_example_fun2(mp_obj_t arg0_in, mp_obj_t arg1_in);
+   static MP_DEFINE_CONST_FUN_OBJ_2(example_fun2_obj, mp_example_fun0);
+
+   /* Function with 3 arguments */
+   mp_obj_t mp_example_fun3(mp_obj_t arg0_in, mp_obj_t arg1_in, mp_obj_t arg2_in);
+   static MP_DEFINE_CONST_FUN_OBJ_3(example_fun3_obj, mp_example_fun0);
+
+   /* Function with 4 or more arguments */
+   mp_obj_t mp_example_fun4(size_t n_args, mp_obj_t *args);
+   static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(example_fun4_obj, 4, 4, mp_example_fun4);
+
+For functions with 4 or more arguments, you need to use the
+``MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN`` macro and instead of directly accessing
+the arguments, you get an array.  The macro gets two numbers (they are the same
+in the example above):  The minimum and maximum number of arguments.
+
+MicroPython Objects
+-------------------
+**TL;DR**: Look at |obj.h|_.  It contains most functions needed to create,
+access, and modify MicroPython objects.
+
+.. |obj.h| replace:: ``lib/micropython/micropython/py/obj.h``
+.. _obj.h: https://github.com/micropython/micropython/blob/master/py/obj.h
+
+For C modules to interface with MicroPython, you need to be able to interface
+with MicroPython objects.  The generic type of an object is ``mp_obj_t``.  As
+you can see in the example above, this is also what a function gets as
+arguments and returns back to MicroPython.  You can cast ``mp_obj_t`` to
+concrete object types if you made sure it is actually the correct type.
+
+Booleans
+~~~~~~~~
+``True`` and ``False`` are *const* objects, called ``mp_const_true`` and
+``mp_const_false`` respectively.  A usual equality check can be used:
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+   #include "py/runtime.h"
+
+   if (bool_obj == mp_const_true) {
+       /* is a boolean true */
+   } else if (bool_obj == mp_const_false) {
+       /* is a boolean false */
+   } else {
+       mp_raise_TypeError("arg 0 is not a boolean");
+   }
+
+Integers
+~~~~~~~~
+As long as your integers stay within **31**-bit limits, integers are stored very
+efficiently and can be accessed and created like this:
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+
+   /* Create a new integer which is < 2^31 */
+   mp_obj_t int_obj = MP_OBJ_NEW_SMALL_INT(0xc0ffee);
+
+   /* Check if an integer is small and if so, extract it */
+   if (mp_obj_is_small_int(int_obj)) {
+           int int_value = MP_OBJ_SMALL_INT_VALUE(int_obj);
+   }
+
+For bigger integers or if you are uncertain about the limits, use the following
+functions:
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+
+   /* Create new integer objects in various sizes and signedness */
+   mp_obj_t int0_obj = mp_obj_new_int((mp_int_t)value);
+   mp_obj_t int1_obj = mp_obj_new_int_from_uint((mp_uint_t)value);
+   mp_obj_t int2_obj = mp_obj_new_int_from_ll((long long)value);
+   mp_obj_t int3_obj = mp_obj_new_int_from_ull((unsigned long long)value);
+
+   /* Check if a value is an integer */
+   if (mp_obj_is_integer(int_obj)) {
+
+           /* Get an integer */
+           int int0 = mp_obj_get_int(int_obj);
+           int int0 = mp_obj_get_int_truncated(int_obj);
+   }
+
+   int value;
+   if (!mp_obj_get_int_maybe(int_obj, &value)) {
+      /* Not an integer! */
+   }
+
+To get really big integers you have to use
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+   #include "py/objint.h"
+
+   long long value;
+   mp_obj_int_to_bytes_impl(int_obj, 8, (byte*)&value);
+
+Strings
+~~~~~~~
+As in CPython, MicroPython also has multiple string representations:  There is
+``str``, ``bytes``, and ``bytearray`` but also the above mentions ``QSTR``\ s.
+Ideally, code should work with as many of these as possible and to ensure this,
+please use these generic functions:
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+
+   /* Create a new string object */
+   char buf[] = "Hello MicroPython!";
+   mp_obj_t str_obj = mp_obj_new_str(buf, sizeof(buf));
+
+   /* Check if an object is a string */
+   if (mp_obj_is_str(str_obj)) {
+           /* Either str or QSTR */
+   }
+   if (mp_obj_is_str_or_bytes) {
+           /* Either str, QSTR, or bytes */
+   }
+
+   /*
+    * Get a char array from a string object.
+    * CAUTION! This string is not necessarily null terminated!
+    */
+   char *str_data;
+   size_t str_len;
+   str_data = mp_obj_str_get_data(str_obj, &str_len);
+
+Lists & Tuples
+~~~~~~~~~~~~~~
+While lists and tuples can be accessed using type specific functions, you
+should refrain from doing so:  Use generic indexing functions instead, as they
+also allow types derived from lists or tuples or types with custom indexing
+implementations (i.e. duck-typing).
+
+.. code-block:: cpp
+
+   #include "py/obj.h"
+   #include "py/runtime.h"
+
+   /* Get the length of a list-like object */
+   mp_int_t len = mp_obj_get_int(mp_obj_len(list_obj));
+
+   /* Get element at a specific index */
+   mp_obj_t elem5 = mp_obj_subscr(
+           list_obj,
+           MP_OBJ_NEW_SMALL_INT(5),
+           MP_OBJ_SENTINEL
+   );
+
+To create a list or tuple:
+
+.. code-block:: cpp
+
+   mp_obj_t values[] = {
+           MP_OBJ_NEW_SMALL_INT(0xde),
+           MP_OBJ_NEW_SMALL_INT(0xad),
+           MP_OBJ_NEW_SMALL_INT(0xbe),
+           MP_OBJ_NEW_SMALL_INT(0xef),
+   };
+
+   /* Create a tuple */
+   mp_obj_t tuple = mp_obj_new_tuple(4, values);
+
+   /* Create a list */
+   mp_obj_t list = mp_obj_new_list(4, values);

Documentation/pycardium/bhi160.rst

+.. py:module:: bhi160
+
+``bhi160`` - Sensor Fusion
+==========================
+
+.. versionadded:: 1.4
+
+Supports the BHI160 sensor on the card10 for accelerometer, gyroscope,
+magnetometer and orientation.
+
+The coordinate system of the BHI160 sensor data looks like this:
+
+.. image:: ../static/bhi160-coordinates.png
+
+* The **accelerometer** axes are just the ones shown in the picture.
+* The **gyroscope**'s angular velocities rotate counter clockwise around
+  their respective axis.
+* The **orientation** sensor uses the following mapping:
+
+  +---------------------+----------------------+-------------------+
+  | X                   | Y                    | Z                 |
+  +=====================+======================+===================+
+  | Azimuth (0° - 360°) | Pitch (-180° - 180°) | Roll (-90° - 90°) |
+  +---------------------+----------------------+-------------------+
+
+**Example**:
+
+.. code-block:: python
+
+   import bhi160
+   import time
+
+   bhi = bhi160.BHI160Orientation()
+
+    while True:
+        samples = bhi.read()
+        if len(samples) == 0:
+            time.sleep(0.25)
+            continue
+        # print the latest sample
+        print(samples[-1])
+        time.sleep(0.25)
+
+
+Orientation
+-----------
+.. autoclass:: bhi160.BHI160Orientation
+   :members:
+   :inherited-members:
+
+Accelerometer
+-------------
+.. autoclass:: bhi160.BHI160Accelerometer
+  :members:
+  :inherited-members:
+
+Gyroscope
+---------
+.. autoclass:: bhi160.BHI160Gyroscope
+  :members:
+  :inherited-members:
+
+Magnetometer
+------------
+.. autoclass:: bhi160.BHI160Magnetometer
+  :members:
+  :inherited-members:

Documentation/pycardium/ble_hid.rst

+``ble_hid`` - BLE HID
+=====================
+The ``ble_hid`` module provides access to the BLE Human Interface Device functionality.
+
+.. note::
+    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
+    on the file system of your card10.
+
+
+.. warning::
+    At least Ubuntu Linux will keep auto connecting to BLE HID devices once they are
+    paired to the host computer. If you want to connect your card10 to a phone again,
+    you might have to temporarily turn off Bluetooth on your computer.
+
+An example application can be found in the preload directory (named ``HID Demo``). It provides
+examples how to use the card10 as keyboard, mouse or volume control.
+
+Please refer to the Adafruit CircuitPython HID library for examples how to use the HID service.
+The card10 implements the same HID descriptors as the Adafruit CircuitPython BLE library and
+should be compatible with all uses of the Adafruit CircuitPython HID library.
+
+**Example emulating a keyboard**:
+
+Adapted from https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/master/CPB_Keybutton_BLE/cpb_keybutton_ble.py
+
+A more complete version of this example can be found in the HID Demo app on your card10.
+
+.. code-block:: python
+
+    import ble_hid
+    from adafruit_hid.keyboard import Keyboard
+    from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
+    from adafruit_hid.keycode import Keycode
+
+    k = Keyboard(ble_hid.devices)
+    kl = KeyboardLayoutUS(k)
+
+    k.send(Keycode.BACKSPACE)
+
+    # use keyboard_layout for words
+    kl.write("Demo with a long text to show how fast a card10 can type!")
+
+    # add shift modifier
+    k.send(Keycode.SHIFT, Keycode.F19)
+
+
+**Example emulating a mouse**:
+
+.. code-block:: python
+
+    import ble_hid
+    import bhi160
+    import buttons
+    from adafruit_hid.mouse import Mouse
+
+    m = Mouse(ble_hid.devices)
+
+    def send_report(samples):
+        if len(samples) > 0:
+            x = -int(samples[0].z)
+            y = -int(samples[0].y)
+            m.move(x, y)
+
+    sensor = bhi160.BHI160Orientation(sample_rate=10, callback=send_report)
+
+    b_old = buttons.read()
+    while True:
+        b_new = buttons.read()
+        if not b_old == b_new:
+            print(b_new)
+            b_old = b_new
+            if b_new == buttons.TOP_RIGHT:
+                m.click(Mouse.MIDDLE_BUTTON)
+            elif b_new == buttons.BOTTOM_RIGHT:
+                m.click(Mouse.RIGHT_BUTTON)
+            elif b_new == buttons.BOTTOM_LEFT:
+                m.click(Mouse.LEFT_BUTTON)
+
+.. note::
+    Make sure to catch ``OSError`` exceptions in real applications. The exception will be thrown if
+    there is connection to the host (or if it is lost) and you want to send an event.
+
+
+.. automodule:: ble_hid
+   :members:

Documentation/pycardium/bme680.rst

+.. py:module:: bme680
+
+``bme680`` - Environmental Sensor
+=================================
+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::
+   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`.
+
+
+**Example**:
+
+.. code-block:: python
+
+   import bme680, time
+
+   with bme680.Bme680() as environment:
+       while True:
+           d = environment.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))
+
+           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
+------------
+
+.. 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()
+
+   Initialize the sensor.
+
+   Before being able to read data from the sensor, you have to call
+   :py:func:`bme680.init`.
+
+   .. versionadded:: 1.4
+   .. deprecated:: 1.10
+      Use the :py:class:`bme680.Bme680` class instead.
+
+.. py:function:: get_data()
+
+   Perform a single measurement of environmental data.
+
+   :return: Tuple containing ``temperature`` (°C), ``humidity`` (% r.h.),
+      ``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.

Documentation/pycardium/buttons.rst

+.. py:module:: buttons
+
+``buttons`` - Push Buttons
+==========================
+The :py:mod:`buttons` module allows you to use card10's push buttons as input
+in your scripts.
+
+**Example**:
+
+.. code-block:: python
+
+   import buttons
+
+   print("Press bottom left or right button:")
+
+   while True:
+      pressed = buttons.read(
+          buttons.BOTTOM_LEFT | buttons.BOTTOM_RIGHT
+      )
+
+      if pressed != 0:
+         break
+
+   if pressed & buttons.BOTTOM_LEFT != 0:
+      print("Left button pressed!")
+
+   if pressed & buttons.BOTTOM_RIGHT != 0:
+      print("Right button pressed!")
+
+.. py:function:: read(mask)
+
+   Read button status.
+
+   :param int mask: Mask of buttons to check.  Create the mask by ORing
+      :py:data:`buttons.BOTTOM_LEFT`, :py:data:`buttons.BOTTOM_RIGHT`,
+      :py:data:`buttons.TOP_RIGHT`, and :py:data:`buttons.TOP_LEFT` (=
+      :py:data:`buttons.RESET`).
+   :returns: An integer with the bits for pressed buttons set.  Use the same
+      costants as for the mask to check which buttons were pressed.
+
+.. py:data:: BOTTOM_LEFT
+
+   Bottom left button.
+
+.. py:data:: BOTTOM_RIGHT
+
+   Bottom right button.
+
+.. py:data:: TOP_RIGHT
+
+   Top right button.
+
+.. py:data:: TOP_LEFT
+
+   Top left button (Reset button).
+
+.. py:data:: RESET
+
+   Top left button (Reset button).

Documentation/pycardium/color.rst

+``color`` - Colors
+==================
+
+Color Class
+-----------
+
+.. automodule:: color
+   :members:
+
+Constants
+---------
+The color module also contains a few constanst for commonly used colors:
+
+Camp Colors
+~~~~~~~~~~~
+.. py:data:: CHAOSBLUE
+
+   .. color-example:: #0076BA
+
+.. py:data:: CHAOSBLUE_DARK
+
+   .. color-example:: #005383
+
+.. py:data:: COMMYELLOW
+
+   .. color-example:: #FFC600
+
+.. py:data:: COMMYELLOW_DARK
+
+   .. color-example:: #D39A00
+
+.. py:data:: CAMPGREEN
+
+   .. color-example:: #99BA00
+
+.. py:data:: CAMPGREEN_DARK
+
+   .. color-example:: #6F8700
+
+
+General
+~~~~~~~
+.. py:data:: BLACK
+
+   .. color-example:: #000
+
+.. py:data:: WHITE
+
+   .. color-example:: #fff
+
+.. py:data:: RED
+
+   .. color-example:: #f00
+
+.. py:data:: GREEN
+
+   .. color-example:: #0f0
+
+.. py:data:: YELLOW
+
+   .. color-example:: #ff0
+
+.. py:data:: BLUE
+
+   .. color-example:: #00f
+
+.. py:data:: MAGENTA
+
+   .. color-example:: #f0f
+
+.. py:data:: CYAN
+
+   .. color-example:: #0ff
+
+
+.. py:module:: htmlcolor
+
+``htmlcolor`` - Color Constants
+===============================
+The ``htmlcolor`` module contains even more color constants.  Note
+that loading the ``htmlcolor`` module will require ~12K of RAM.
+
+.. py:data:: ALICEBLUE
+
+   .. color-example:: aliceblue
+
+.. py:data:: ANTIQUEWHITE
+
+   .. color-example:: antiquewhite
+
+.. py:data:: AQUA
+
+   .. color-example:: aqua
+
+.. py:data:: AQUAMARINE
+
+   .. color-example:: aquamarine
+
+.. py:data:: AZURE
+
+   .. color-example:: azure
+
+.. py:data:: BEIGE
+
+   .. color-example:: beige
+
+.. py:data:: BISQUE
+
+   .. color-example:: bisque
+
+.. py:data:: BLACK
+
+   .. color-example:: black
+
+.. py:data:: BLANCHEDALMOND
+
+   .. color-example:: blanchedalmond
+
+.. py:data:: BLUE
+
+   .. color-example:: blue
+
+.. py:data:: BLUEVIOLET
+
+   .. color-example:: blueviolet
+
+.. py:data:: BROWN
+
+   .. color-example:: brown
+
+.. py:data:: BURLYWOOD
+
+   .. color-example:: burlywood
+
+.. py:data:: CADETBLUE
+
+   .. color-example:: cadetblue
+
+.. py:data:: CHARTREUSE
+
+   .. color-example:: chartreuse
+
+.. py:data:: CHOCOLATE
+
+   .. color-example:: chocolate
+
+.. py:data:: CORAL
+
+   .. color-example:: coral
+
+.. py:data:: CORNFLOWERBLUE
+
+   .. color-example:: cornflowerblue
+
+.. py:data:: CORNSILK
+
+   .. color-example:: cornsilk
+
+.. py:data:: CRIMSON
+
+   .. color-example:: crimson
+
+.. py:data:: CYAN
+
+   .. color-example:: cyan
+
+.. py:data:: DARKBLUE
+
+   .. color-example:: darkblue
+
+.. py:data:: DARKCYAN
+
+   .. color-example:: darkcyan
+
+.. py:data:: DARKGOLDENROD
+
+   .. color-example:: darkgoldenrod
+
+.. py:data:: DARKGRAY
+
+   .. color-example:: darkgray
+
+.. py:data:: DARKGREEN
+
+   .. color-example:: darkgreen
+
+.. py:data:: DARKKHAKI
+
+   .. color-example:: darkkhaki
+
+.. py:data:: DARKMAGENTA
+
+   .. color-example:: darkmagenta
+
+.. py:data:: DARKOLIVEGREEN
+
+   .. color-example:: darkolivegreen
+
+.. py:data:: DARKORANGE
+
+   .. color-example:: darkorange
+
+.. py:data:: DARKORCHID
+
+   .. color-example:: darkorchid
+
+.. py:data:: DARKRED
+
+   .. color-example:: darkred
+
+.. py:data:: DARKSALMON
+
+   .. color-example:: darksalmon
+
+.. py:data:: DARKSEAGREEN
+
+   .. color-example:: darkseagreen
+
+.. py:data:: DARKSLATEBLUE
+
+   .. color-example:: darkslateblue
+
+.. py:data:: DARKSLATEGRAY
+
+   .. color-example:: darkslategray
+
+.. py:data:: DARKTURQUOISE
+
+   .. color-example:: darkturquoise
+
+.. py:data:: DARKVIOLET
+
+   .. color-example:: darkviolet
+
+.. py:data:: DEEPPINK
+
+   .. color-example:: deeppink
+
+.. py:data:: DEEPSKYBLUE
+
+   .. color-example:: deepskyblue
+
+.. py:data:: DIMGRAY
+
+   .. color-example:: dimgray
+
+.. py:data:: DODGERBLUE
+
+   .. color-example:: dodgerblue
+
+.. py:data:: FIREBRICK
+
+   .. color-example:: firebrick
+
+.. py:data:: FLORALWHITE
+
+   .. color-example:: floralwhite
+
+.. py:data:: FORESTGREEN
+
+   .. color-example:: forestgreen
+
+.. py:data:: FUCHSIA
+
+   .. color-example:: fuchsia
+
+.. py:data:: GAINSBORO
+
+   .. color-example:: gainsboro
+
+.. py:data:: GHOSTWHITE
+
+   .. color-example:: ghostwhite
+
+.. py:data:: GOLD
+
+   .. color-example:: gold
+
+.. py:data:: GOLDENROD
+
+   .. color-example:: goldenrod
+
+.. py:data:: GRAY
+
+   .. color-example:: gray
+
+.. py:data:: GREEN
+
+   .. color-example:: green
+
+.. py:data:: GREENYELLOW
+
+   .. color-example:: greenyellow
+
+.. py:data:: HONEYDEW
+
+   .. color-example:: honeydew
+
+.. py:data:: HOTPINK
+
+   .. color-example:: hotpink
+
+.. py:data:: INDIANRED
+
+   .. color-example:: indianred
+
+.. py:data:: INDIGO
+
+   .. color-example:: indigo
+
+.. py:data:: IVORY
+
+   .. color-example:: ivory
+
+.. py:data:: KHAKI
+
+   .. color-example:: khaki
+
+.. py:data:: LAVENDER
+
+   .. color-example:: lavender
+
+.. py:data:: LAVENDERBLUSH
+
+   .. color-example:: lavenderblush
+
+.. py:data:: LAWNGREEN
+
+   .. color-example:: lawngreen
+
+.. py:data:: LEMONCHIFFON
+
+   .. color-example:: lemonchiffon
+
+.. py:data:: LIGHTBLUE
+
+   .. color-example:: lightblue
+
+.. py:data:: LIGHTCORAL
+
+   .. color-example:: lightcoral
+
+.. py:data:: LIGHTCYAN
+
+   .. color-example:: lightcyan
+
+.. py:data:: LIGHTGOLDENRODYELLOW
+
+   .. color-example:: lightgoldenrodyellow
+
+.. py:data:: LIGHTGRAY
+
+   .. color-example:: lightgray
+
+.. py:data:: LIGHTGREEN
+
+   .. color-example:: lightgreen
+
+.. py:data:: LIGHTPINK
+
+   .. color-example:: lightpink
+
+.. py:data:: LIGHTSALMON
+
+   .. color-example:: lightsalmon
+
+.. py:data:: LIGHTSEAGREEN
+
+   .. color-example:: lightseagreen
+
+.. py:data:: LIGHTSKYBLUE
+
+   .. color-example:: lightskyblue
+
+.. py:data:: LIGHTSLATEGRAY
+
+   .. color-example:: lightslategray
+
+.. py:data:: LIGHTSTEELBLUE
+
+   .. color-example:: lightsteelblue
+
+.. py:data:: LIGHTYELLOW
+
+   .. color-example:: lightyellow
+
+.. py:data:: LIME
+
+   .. color-example:: lime
+
+.. py:data:: LIMEGREEN
+
+   .. color-example:: limegreen
+
+.. py:data:: LINEN
+
+   .. color-example:: linen
+
+.. py:data:: MAGENTA
+
+   .. color-example:: magenta
+
+.. py:data:: MAROON
+
+   .. color-example:: maroon
+
+.. py:data:: MEDIUMAQUAMARINE
+
+   .. color-example:: mediumaquamarine
+
+.. py:data:: MEDIUMBLUE
+
+   .. color-example:: mediumblue
+
+.. py:data:: MEDIUMORCHID
+
+   .. color-example:: mediumorchid
+
+.. py:data:: MEDIUMPURPLE
+
+   .. color-example:: mediumpurple
+
+.. py:data:: MEDIUMSEAGREEN
+
+   .. color-example:: mediumseagreen
+
+.. py:data:: MEDIUMSLATEBLUE
+
+   .. color-example:: mediumslateblue
+
+.. py:data:: MEDIUMSPRINGGREEN
+
+   .. color-example:: mediumspringgreen
+
+.. py:data:: MEDIUMTURQUOISE
+
+   .. color-example:: mediumturquoise
+
+.. py:data:: MEDIUMVIOLETRED
+
+   .. color-example:: mediumvioletred
+
+.. py:data:: MIDNIGHTBLUE
+
+   .. color-example:: midnightblue
+
+.. py:data:: MINTCREAM
+
+   .. color-example:: mintcream
+
+.. py:data:: MISTYROSE
+
+   .. color-example:: mistyrose
+
+.. py:data:: MOCCASIN
+
+   .. color-example:: moccasin
+
+.. py:data:: NAVAJOWHITE
+
+   .. color-example:: navajowhite
+
+.. py:data:: NAVY
+
+   .. color-example:: navy
+
+.. py:data:: OLDLACE
+
+   .. color-example:: oldlace
+
+.. py:data:: OLIVE
+
+   .. color-example:: olive
+
+.. py:data:: OLIVEDRAB
+
+   .. color-example:: olivedrab
+
+.. py:data:: ORANGE
+
+   .. color-example:: orange
+
+.. py:data:: ORANGERED
+
+   .. color-example:: orangered
+
+.. py:data:: ORCHID
+
+   .. color-example:: orchid
+
+.. py:data:: PALEGOLDENROD
+
+   .. color-example:: palegoldenrod
+
+.. py:data:: PALEGREEN
+
+   .. color-example:: palegreen
+
+.. py:data:: PALETURQUOISE
+
+   .. color-example:: paleturquoise
+
+.. py:data:: PALEVIOLETRED
+
+   .. color-example:: palevioletred
+
+.. py:data:: PAPAYAWHIP
+
+   .. color-example:: papayawhip
+
+.. py:data:: PEACHPUFF
+
+   .. color-example:: peachpuff
+
+.. py:data:: PERU
+
+   .. color-example:: peru
+
+.. py:data:: PINK
+
+   .. color-example:: pink
+
+.. py:data:: PLUM
+
+   .. color-example:: plum
+
+.. py:data:: POWDERBLUE
+
+   .. color-example:: powderblue
+
+.. py:data:: PURPLE
+
+   .. color-example:: purple
+
+.. py:data:: RED
+
+   .. color-example:: red
+
+.. py:data:: ROSYBROWN
+
+   .. color-example:: rosybrown
+
+.. py:data:: ROYALBLUE
+
+   .. color-example:: royalblue
+
+.. py:data:: SADDLEBROWN
+
+   .. color-example:: saddlebrown
+
+.. py:data:: SALMON
+
+   .. color-example:: salmon
+
+.. py:data:: SANDYBROWN
+
+   .. color-example:: sandybrown
+
+.. py:data:: SEAGREEN
+
+   .. color-example:: seagreen
+
+.. py:data:: SEASHELL
+
+   .. color-example:: seashell
+
+.. py:data:: SIENNA
+
+   .. color-example:: sienna
+
+.. py:data:: SILVER
+
+   .. color-example:: silver
+
+.. py:data:: SKYBLUE
+
+   .. color-example:: skyblue
+
+.. py:data:: SLATEBLUE
+
+   .. color-example:: slateblue
+
+.. py:data:: SLATEGRAY
+
+   .. color-example:: slategray
+
+.. py:data:: SNOW
+
+   .. color-example:: snow
+
+.. py:data:: SPRINGGREEN
+
+   .. color-example:: springgreen
+
+.. py:data:: STEELBLUE
+
+   .. color-example:: steelblue
+
+.. py:data:: TAN
+
+   .. color-example:: tan
+
+.. py:data:: TEAL
+
+   .. color-example:: teal
+
+.. py:data:: THISTLE
+
+   .. color-example:: thistle
+
+.. py:data:: TOMATO
+
+   .. color-example:: tomato
+
+.. py:data:: TURQUOISE
+
+   .. color-example:: turquoise
+
+.. py:data:: VIOLET
+
+   .. color-example:: violet
+
+.. py:data:: WHEAT
+
+   .. color-example:: wheat
+
+.. py:data:: WHITE
+
+   .. color-example:: white
+
+.. py:data:: WHITESMOKE
+
+   .. color-example:: whitesmoke
+
+.. py:data:: YELLOW
+
+   .. color-example:: yellow
+
+.. py:data:: YELLOWGREEN
+
+   .. color-example:: yellowgreen

Documentation/pycardium/max30001.rst

+``max30001`` - MAX30001
+=======================
+
+.. automodule:: max30001
+   :members: