Documentation/hawkmoth/VERSION

-0.4
+0.7.0

Documentation/hawkmoth/__init__.py

@@ -52,7 +52,10 @@ class CAutoDocDirective(Directive):
         env = self.state.document.settings.env
 
         for (severity, filename, lineno, msg) in errors:
-            toprint = '{}:{}: {}'.format(filename, lineno, msg)
+            if filename:
+                toprint = '{}:{}: {}'.format(filename, lineno, msg)
+            else:
+                toprint = '{}'.format(msg)
 
             if severity.value <= env.app.verbosity:
                 self.logger.log(self._log_lvl[severity], toprint,
@@ -109,7 +112,7 @@ class CAutoDocDirective(Directive):
         return node.children
 
 def setup(app):
-    app.require_sphinx('1.8')
+    app.require_sphinx('3.0')
     app.add_config_value('cautodoc_root', app.confdir, 'env')
     app.add_config_value('cautodoc_compat', None, 'env')
     app.add_config_value('cautodoc_clang', None, 'env')

Documentation/hawkmoth/__main__.py

@@ -39,7 +39,10 @@ def main():
         print(doc)
 
     for (severity, filename, lineno, msg) in errors:
-        print('{}: {}:{}: {}'.format(severity.name,
-                                     filename, lineno, msg), file=sys.stderr)
+        if filename:
+            print('{}: {}:{}: {}'.format(severity.name,
+                                         filename, lineno, msg), file=sys.stderr)
+        else:
+            print('{}: {}'.format(severity.name, msg), file=sys.stderr)
 
 main()

Documentation/hawkmoth/parser.py

 # Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
-# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
+# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 """
 Documentation comment extractor
@@ -34,7 +34,7 @@ Otherwise, documentation comments are passed through verbatim.
 """
 
 import enum
-import itertools
+import re
 import sys
 
 from clang.cindex import CursorKind, TypeKind
@@ -75,18 +75,22 @@ def comment_extract(tu):
             current_comment = token
             continue
 
+        # Store off the token's cursor for a slight performance improvement
+        # instead of accessing the `cursor` property multiple times.
+        token_cursor = token.cursor
+
         # cursors that are 1) never documented themselves, and 2) allowed
         # between comment and the actual cursor being documented
-        if (token.cursor.kind == CursorKind.INVALID_FILE or
-            token.cursor.kind == CursorKind.TYPE_REF or
-            token.cursor.kind == CursorKind.PREPROCESSING_DIRECTIVE or
-            token.cursor.kind == CursorKind.MACRO_INSTANTIATION):
+        if (token_cursor.kind == CursorKind.INVALID_FILE or
+            token_cursor.kind == CursorKind.TYPE_REF or
+            token_cursor.kind == CursorKind.PREPROCESSING_DIRECTIVE or
+            token_cursor.kind == CursorKind.MACRO_INSTANTIATION):
             continue
 
-        if cursor is not None and token.cursor == cursor:
+        if cursor is not None and token_cursor == cursor:
             continue
 
-        cursor = token.cursor
+        cursor = token_cursor
 
         # Note: current_comment may be None
         if current_comment != None and docstr.is_doc(current_comment.spelling):
@@ -125,16 +129,18 @@ def _get_macro_args(cursor):
     if cursor.kind != CursorKind.MACRO_DEFINITION:
         return None
 
+    tokens = cursor.get_tokens()
+
     # Use the first two tokens to make sure this starts with 'IDENTIFIER('
-    x = [token for token in itertools.islice(cursor.get_tokens(), 2)]
-    if (len(x) != 2 or x[0].spelling != cursor.spelling or
-        x[1].spelling != '(' or x[0].extent.end != x[1].extent.start):
+    one = next(tokens)
+    two = next(tokens, None)
+    if two is None or one.extent.end != two.extent.start or two.spelling != '(':
         return None
 
     # Naïve parsing of macro arguments
     # FIXME: This doesn't handle GCC named vararg extension FOO(vararg...)
     args = []
-    for token in itertools.islice(cursor.get_tokens(), 2, None):
+    for token in tokens:
         if token.spelling == ')':
             return args
         elif token.spelling == ',':
@@ -161,8 +167,26 @@ def _recursive_parse(comments, cursor, nest, compat):
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, args=args, compat=compat)
 
-    elif cursor.kind == CursorKind.VAR_DECL:
-        fmt = docstr.Type.VAR
+    elif cursor.kind in [CursorKind.VAR_DECL, CursorKind.FIELD_DECL]:
+        if cursor.kind == CursorKind.VAR_DECL:
+            fmt = docstr.Type.VAR
+        else:
+            fmt = docstr.Type.MEMBER
+
+        # If this is an array, the dimensions should be applied to the name, not
+        # the type.
+        dims = ttype.rsplit(' ', 1)[-1]
+        if dims.startswith('[') and dims.endswith(']'):
+            ttype = ttype.rsplit(' ', 1)[0]
+            name = name + dims
+
+        # If this is a function pointer, or an array of function pointers, the
+        # name should be within the parenthesis as in (*name) or (*name[N]).
+        fptr_type = re.sub(r'\((\*+)(\[[^]]*\])?\)', r'(\1{}\2)'.format(name),
+                           ttype, count=1)
+        if fptr_type != ttype:
+            name = fptr_type
+            ttype = ''
 
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, ttype=ttype, compat=compat)
@@ -188,9 +212,15 @@ def _recursive_parse(comments, cursor, nest, compat):
 
         # FIXME: Handle anonymous enumerators.
 
-        fmt = docstr.Type.TYPE
+        fmts = {CursorKind.STRUCT_DECL: docstr.Type.STRUCT,
+                CursorKind.UNION_DECL: docstr.Type.UNION,
+                CursorKind.ENUM_DECL: docstr.Type.ENUM}
+
+        fmt = fmts[cursor.kind]
+
+        # name may be empty for typedefs
         result = _result(comment, cursor=cursor, fmt=fmt,
-                         nest=nest, name=ttype, compat=compat)
+                         nest=nest, name=name if name else ttype, compat=compat)
 
         nest += 1
         for c in cursor.get_children():
@@ -205,12 +235,6 @@ def _recursive_parse(comments, cursor, nest, compat):
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, compat=compat)
 
-    elif cursor.kind == CursorKind.FIELD_DECL:
-        fmt = docstr.Type.MEMBER
-
-        return _result(comment, cursor=cursor, fmt=fmt,
-                       nest=nest, name=name, ttype=ttype, compat=compat)
-
     elif cursor.kind == CursorKind.FUNCTION_DECL:
         # FIXME: check args against comment
         # FIXME: children may contain extra stuff if the return type is a
@@ -261,7 +285,8 @@ def clang_diagnostics(errors, diagnostics):
            4: ErrorLevel.ERROR}
 
     for diag in diagnostics:
-        errors.extend([(sev[diag.severity], diag.location.file.name,
+        filename = diag.location.file.name if diag.location.file else None
+        errors.extend([(sev[diag.severity], filename,
                         diag.location.line, diag.spelling)])
 
 # return a list of (comment, metadata) tuples

Documentation/hawkmoth/util/docstr.py

-# Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
-# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
+# Copyright (c) 2016-2020 Jani Nikula <jani@nikula.org>
+# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 """
 Documentation strings manipulation library
@@ -17,6 +17,9 @@ class Type(Enum):
     TEXT = auto()
     VAR = auto()
     TYPE = auto()
+    STRUCT = auto()
+    UNION = auto()
+    ENUM = auto()
     ENUM_VAL = auto()
     MEMBER = auto()
     MACRO = auto()
@@ -31,10 +34,13 @@ _doc_fmt = {
     Type.TEXT:       (0, '\n{text}\n'),
     Type.VAR:        (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
     Type.TYPE:       (1, '\n.. c:type:: {name}\n\n{text}\n'),
-    Type.ENUM_VAL:   (1, '\n.. c:macro:: {name}\n\n{text}\n'),
+    Type.STRUCT:     (1, '\n.. c:struct:: {name}\n\n{text}\n'),
+    Type.UNION:      (1, '\n.. c:union:: {name}\n\n{text}\n'),
+    Type.ENUM:       (1, '\n.. c:enum:: {name}\n\n{text}\n'),
+    Type.ENUM_VAL:   (1, '\n.. c:enumerator:: {name}\n\n{text}\n'),
     Type.MEMBER:     (1, '\n.. c:member:: {ttype} {name}\n\n{text}\n'),
     Type.MACRO:      (1, '\n.. c:macro:: {name}\n\n{text}\n'),
-    Type.MACRO_FUNC: (1, '\n.. c:function:: {name}({args})\n\n{text}\n'),
+    Type.MACRO_FUNC: (1, '\n.. c:macro:: {name}({args})\n\n{text}\n'),
     Type.FUNC:       (1, '\n.. c:function:: {ttype} {name}({args})\n\n{text}\n')
 }
 

Documentation/hawkmoth/util/readthedocs.py

+# Copyright (c) 2021, Jani Nikula <jani@nikula.org>
+# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
+"""
+Read the Docs Helpers
+=====================
+
+Helpers for setting up and using Hawkmoth on Read the Docs.
+"""
+
+import os
+import subprocess
+
+def clang_setup(force=False):
+    """Try to find and configure libclang location on RTD."""
+    if 'READTHEDOCS' in os.environ or force:
+        try:
+            result = subprocess.run(['llvm-config', '--libdir'],
+                                    check=True, capture_output=True, encoding='utf-8')
+            libdir = result.stdout.strip()
+
+            # For some reason there is no plain libclang.so symlink on RTD.
+            from clang.cindex import Config
+            Config.set_library_file(os.path.join(libdir, 'libclang.so.1'))
+        except Exception as e:
+            print(e)

Documentation/how-to-build.rst

+.. _how_to_build:
+
 How To Build
 ============
 If you just want to write MicroPython code for card10, you probably **won't**
-need to build the firmware yourself.  This page is for people who want to work
-on the underlying firmware itself.
+need to build the firmware yourself.  This page is for people **who want to work
+on the underlying firmware itself**.
 
 Dependencies
 ------------
@@ -21,27 +23,90 @@ Dependencies
 
        pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
 
+  - Fedora
+
+    .. code-block:: shell-session
+
+        dnf install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
+
+  - macOS (Note: The card10 firmware team used Linux so far. macOS recommendations here are experimental.)
+
+    You can use `Homebrew`_ to install the required tools.  The version of the
+    ARM crosscompiler tool chain is quite important; with the wrong version,
+    e.g. strip and/or ld might throw strange errors.
+
+    .. code-block:: shell-session
+
+        brew tap px4/px4
+        brew install px4/px4/gcc-arm-none-eabi-63
+        brew install coreutils
+
+    .. _Homebrew: https://brew.sh/
+
   - Alternative: Download `ARM's GNU toolchain`_.  **TODO**
+
+
 * **python3**:  For meson and various scripts needed for building.
 * **meson** (>0.43.0) & **ninja**:  Unfortunately most distros only have very old versions
   of meson in their repositories.  Instead, you'll probably save yourself a lot
   of headaches by installing meson from *pip*.
 
-   - Ubuntu / Debian:
+  - Ubuntu / Debian:
 
     .. code-block:: shell-session
 
        apt install ninja-build
        pip3 install --user meson
 
-   - Arch (has latest *meson* in the repos):
+  - Arch (has latest *meson* in the repos):
 
     .. code-block:: shell-session
 
        pacman -S meson
 
-* **python3-crc16**: Install with ``pip3 install --user crc16``.
-* **python3-pillow**: Python Image Library ``pip3 install --user PIL``.
+  - macOS
+
+    .. code-block:: shell-session
+
+        brew install ninja
+        pip3 install --user meson  # see https://mesonbuild.com/Getting-meson.html - you will have to add ~/.local/bin to your PATH.
+
+* One of two CRC packages is required. Pick one:
+
+  - Ubuntu / Debian / macOS
+
+    .. code-block:: shell-session
+
+        pip3 install --user crc16
+
+or
+
+    .. code-block:: shell-session
+
+        apt install python3-crcmod
+
+or
+
+    .. code-block:: shell-session
+
+        pip3 install --user crcmod
+
+  - Arch
+
+    .. code-block:: shell-session
+
+       pacman -S python-crc16
+
+* **python3-pillow**: Python Image Library
+       .. code-block:: shell-session
+
+            pip3 install --user pillow
+
+  - Arch
+
+    .. code-block:: shell-session
+
+       pacman -S python-pillow
 
 .. _ARM's GNU toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
 
@@ -68,6 +133,8 @@ firmware features:
 - ``-Ddebug_prints=true``: Print more verbose debugging log messages
 - ``-Dble_trace=true``: Enable BLE tracing.  This will output lots of status
   info related to BLE.
+- ``-Ddebug_core1=true``: Enable the core 1 SWD lines which are exposed on the
+  SAO connector.  Only use this if you have a debugger which is modified for core 1.
 
 .. warning::
 
@@ -103,3 +170,44 @@ In order to do a rebuild you can issue a clean command to ninja via
   $ ninja -C build/ -t clean
 
 Otherwise, rerunning ``./bootstrap.sh`` will also clean the build-directory.
+
+.. note::
+
+   **macOS**: If ``strip`` fails to work on the freshly compiled ``mpy-cross``:
+   "strip: object: (...)/lib/micropython/micropython/mpy-cross/mpy-cross
+   malformed object (unknown load command 9)", you a likely not using the
+   `strip` that matches to your ``clang``. Do ``which strip && which clang``,
+   and if the paths don't match, clean up your PATHs, or as a quick hack,
+   create a symlink for strip.
+
+.. note::
+
+   If you try to flash pycardium_epicardium.bin (renamed to card10.bin)
+   and the bootloader does not finish updating, the file might be too large.
+   ~700kB is the normal size, but problems were reported where the file size
+   was >1MB. This was caused by the ``tr`` tool in the build process
+   (it's supposed to create a large file with 0xff in it) - this requires the
+   LC_ALL environment variable to be not set, or set to "C"
+   (but not UTF8 or similar).
+
+Docker
+======
+Alternatively, clone the ``master`` branch of the firmware repository and enter it:
+
+.. code-block:: shell-session
+
+   $ git clone https://git.card10.badge.events.ccc.de/card10/firmware.git
+   $ cd firmware
+
+Afterwards, build a docker-container which will build the firmware via:
+
+.. code-block:: shell-session
+
+   $ docker build -f docker/Dockerfile_fwbuild -t card10-firmware-builder .
+
+Now, you can start the container with the firmware directory mounted, which will build the
+firmware into the firmware/build directory:
+
+.. code-block:: shell-session
+
+   $ docker run -v $(pwd):/firmware card10-firmware-builder

Documentation/how-to-flash.rst

@@ -5,27 +5,14 @@ method of flashing:
 
 Flash Without Debugger
 ----------------------
-If you do not have a debugger, you have to update the firmware using our
-bootloader.  To do so, you need to reboot card10 while keeping the buttom on
-the bottom right pressed.  Rebooting is done by either short pressing the power
-button (top left) while you have a working firmware, or turning the card10 off
-completely (by pressing the power button for 8 seconds) and then starting it again.
-
-.. image:: static/bootloader-buttons.png
-
-If you did everything correctly, the bootloader will display:
 
-.. code-block:: text
-
-   Bootloader
-   Jul 28 2019
-   USB activated.
-   Ready.
+If you do not have a debugger, you have to update the firmware using our
+bootloader by going into :ref:`usb_file_transfer`.
 
-On your host, you should now see an 8MB flash-device appear.  You can now drop
-the firmware's ``.bin`` (from ``build/pycardium/pycardium_epicardium.bin`` in
-most cases) into this flash-storage.  You **must** call the file ``card10.bin``
-for the bootloader to use it.
+After you get your badge into :ref:`usb_file_transfer`, you can drop the firmware's
+``.bin`` (from ``build/pycardium/pycardium_epicardium.bin`` in most cases) into
+this flash-storage.  You **must** call the file ``card10.bin`` for the
+bootloader to use it.
 
 The bootloader will then display ``Writing.`` in red while it is actually
 writing the file to external flash.  Please wait until it displays ``Ready.``

Documentation/index.rst

@@ -21,23 +21,42 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    :caption: Pycardium
 
    pycardium/overview
+   pycardium/stdlib
+   pycardium/bhi160
+   pycardium/ble_hid
+   pycardium/bme680
+   pycardium/max30001
+   pycardium/max86150
+   pycardium/buttons
    pycardium/color
+   pycardium/config
    pycardium/display
+   pycardium/gpio
    pycardium/leds
    pycardium/light-sensor
+   pycardium/os
+   pycardium/personal_state
+   pycardium/png
+   pycardium/power
+   pycardium/pride
+   pycardium/simple_menu
    pycardium/utime
    pycardium/vibra
+   pycardium/ws2812
 
 .. toctree::
    :maxdepth: 1
    :caption: Firmware
 
    overview
+   card10-cfg
+   usb-file-transfer
    how-to-build
    how-to-flash
    debugger
    pycardium-guide
    memorymap
+   epicardium/mutex
    epicardium/sensor-streams
 
 .. toctree::
@@ -47,6 +66,18 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    epicardium/overview
    epicardium/api
    epicardium-guide
+   epicardium/internal
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Bluetooth
+
+   bluetooth/overview
+   bluetooth/ess
+   bluetooth/file-transfer
+   bluetooth/card10
+   bluetooth/ecg
+   bluetooth/nimble
 
 Indices and tables
 ==================

Documentation/overview.rst

@@ -14,47 +14,72 @@ 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:
 
-* **Dispatcher**:  The dispatcher task handles API calls from core 1.
-* **PMIC**:  The power manager task checks the battery level and other interesting
-  statistics that can be gathered from our power manager IC (MAX77650).
-* **Serial**:  Handles serial communication via *UART*, *CDC ACM* and possibly
-  Bluetooth.
-* **BHI160**: Housekeeping task for interaction with the `BHI160`_.
-
++--------------------+-------------------------------+----------+-------------------------------------------+
+| 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
 
-.. todo::
-
-   The following tasks have not yet been implemented/are currently in the works:
-
-   - **Bluetooth**: The bluetooth stack (`#23`_)
-   - **Payload Controller**: Control what is running on core 1
-
-   .. _#23: https://git.card10.badge.events.ccc.de/card10/firmware/issues/23
-
 Epicardium API
 --------------
 Epicardium exposes lots of functionality via the *Epicardium API*.  The
-technical details if this API can be found in this :ref:`overview
-<epicardium_api_overview>`.  If you are interesting in adding new API calls,
+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:
+
+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
+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`.
 
-.. todo::
+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.
 
-   Provide more details how this works
+.. _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
 --------------------

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

@@ -9,17 +9,69 @@ Color Class
 
 Constants
 ---------
-
 The color module also contains a few constanst for commonly used colors:
 
-.. py:data:: color.BLACK
-.. py:data:: color.WHITE
-.. py:data:: color.RED
-.. py:data:: color.GREEN
-.. py:data:: color.YELLOW
-.. py:data:: color.BLUE
-.. py:data:: color.MAGENTA
-.. py:data:: color.CYAN
+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
 
@@ -28,143 +80,562 @@ The color module also contains a few constanst for commonly used colors:
 The ``htmlcolor`` module contains even more color constants.  Note
 that loading the ``htmlcolor`` module will require ~12K of RAM.
 
-.. py:data:: htmlcolor.ALICEBLUE
-.. py:data:: htmlcolor.ANTIQUEWHITE
-.. py:data:: htmlcolor.AQUA
-.. py:data:: htmlcolor.AQUAMARINE
-.. py:data:: htmlcolor.AZURE
-.. py:data:: htmlcolor.BEIGE
-.. py:data:: htmlcolor.BISQUE
-.. py:data:: htmlcolor.BLACK
-.. py:data:: htmlcolor.BLANCHEDALMOND
-.. py:data:: htmlcolor.BLUE
-.. py:data:: htmlcolor.BLUEVIOLET
-.. py:data:: htmlcolor.BROWN
-.. py:data:: htmlcolor.BURLYWOOD
-.. py:data:: htmlcolor.CADETBLUE
-.. py:data:: htmlcolor.CHARTREUSE
-.. py:data:: htmlcolor.CHOCOLATE
-.. py:data:: htmlcolor.CORAL
-.. py:data:: htmlcolor.CORNFLOWERBLUE
-.. py:data:: htmlcolor.CORNSILK
-.. py:data:: htmlcolor.CRIMSON
-.. py:data:: htmlcolor.CYAN
-.. py:data:: htmlcolor.DARKBLUE
-.. py:data:: htmlcolor.DARKCYAN
-.. py:data:: htmlcolor.DARKGOLDENROD
-.. py:data:: htmlcolor.DARKGRAY
-.. py:data:: htmlcolor.DARKGREEN
-.. py:data:: htmlcolor.DARKKHAKI
-.. py:data:: htmlcolor.DARKMAGENTA
-.. py:data:: htmlcolor.DARKOLIVEGREEN
-.. py:data:: htmlcolor.DARKORANGE
-.. py:data:: htmlcolor.DARKORCHID
-.. py:data:: htmlcolor.DARKRED
-.. py:data:: htmlcolor.DARKSALMON
-.. py:data:: htmlcolor.DARKSEAGREEN
-.. py:data:: htmlcolor.DARKSLATEBLUE
-.. py:data:: htmlcolor.DARKSLATEGRAY
-.. py:data:: htmlcolor.DARKTURQUOISE
-.. py:data:: htmlcolor.DARKVIOLET
-.. py:data:: htmlcolor.DEEPPINK
-.. py:data:: htmlcolor.DEEPSKYBLUE
-.. py:data:: htmlcolor.DIMGRAY
-.. py:data:: htmlcolor.DODGERBLUE
-.. py:data:: htmlcolor.FIREBRICK
-.. py:data:: htmlcolor.FLORALWHITE
-.. py:data:: htmlcolor.FORESTGREEN
-.. py:data:: htmlcolor.FUCHSIA
-.. py:data:: htmlcolor.GAINSBORO
-.. py:data:: htmlcolor.GHOSTWHITE
-.. py:data:: htmlcolor.GOLD
-.. py:data:: htmlcolor.GOLDENROD
-.. py:data:: htmlcolor.GRAY
-.. py:data:: htmlcolor.GREEN
-.. py:data:: htmlcolor.GREENYELLOW
-.. py:data:: htmlcolor.HONEYDEW
-.. py:data:: htmlcolor.HOTPINK
-.. py:data:: htmlcolor.INDIANRED
-.. py:data:: htmlcolor.INDIGO
-.. py:data:: htmlcolor.IVORY
-.. py:data:: htmlcolor.KHAKI
-.. py:data:: htmlcolor.LAVENDER
-.. py:data:: htmlcolor.LAVENDERBLUSH
-.. py:data:: htmlcolor.LAWNGREEN
-.. py:data:: htmlcolor.LEMONCHIFFON
-.. py:data:: htmlcolor.LIGHTBLUE
-.. py:data:: htmlcolor.LIGHTCORAL
-.. py:data:: htmlcolor.LIGHTCYAN
-.. py:data:: htmlcolor.LIGHTGOLDENRODYELLOW
-.. py:data:: htmlcolor.LIGHTGRAY
-.. py:data:: htmlcolor.LIGHTGREEN
-.. py:data:: htmlcolor.LIGHTPINK
-.. py:data:: htmlcolor.LIGHTSALMON
-.. py:data:: htmlcolor.LIGHTSEAGREEN
-.. py:data:: htmlcolor.LIGHTSKYBLUE
-.. py:data:: htmlcolor.LIGHTSLATEGRAY
-.. py:data:: htmlcolor.LIGHTSTEELBLUE
-.. py:data:: htmlcolor.LIGHTYELLOW
-.. py:data:: htmlcolor.LIME
-.. py:data:: htmlcolor.LIMEGREEN
-.. py:data:: htmlcolor.LINEN
-.. py:data:: htmlcolor.MAGENTA
-.. py:data:: htmlcolor.MAROON
-.. py:data:: htmlcolor.MEDIUMAQUAMARINE
-.. py:data:: htmlcolor.MEDIUMBLUE
-.. py:data:: htmlcolor.MEDIUMORCHID
-.. py:data:: htmlcolor.MEDIUMPURPLE
-.. py:data:: htmlcolor.MEDIUMSEAGREEN
-.. py:data:: htmlcolor.MEDIUMSLATEBLUE
-.. py:data:: htmlcolor.MEDIUMSPRINGGREEN
-.. py:data:: htmlcolor.MEDIUMTURQUOISE
-.. py:data:: htmlcolor.MEDIUMVIOLETRED
-.. py:data:: htmlcolor.MIDNIGHTBLUE
-.. py:data:: htmlcolor.MINTCREAM
-.. py:data:: htmlcolor.MISTYROSE
-.. py:data:: htmlcolor.MOCCASIN
-.. py:data:: htmlcolor.NAVAJOWHITE
-.. py:data:: htmlcolor.NAVY
-.. py:data:: htmlcolor.OLDLACE
-.. py:data:: htmlcolor.OLIVE
-.. py:data:: htmlcolor.OLIVEDRAB
-.. py:data:: htmlcolor.ORANGE
-.. py:data:: htmlcolor.ORANGERED
-.. py:data:: htmlcolor.ORCHID
-.. py:data:: htmlcolor.PALEGOLDENROD
-.. py:data:: htmlcolor.PALEGREEN
-.. py:data:: htmlcolor.PALETURQUOISE
-.. py:data:: htmlcolor.PALEVIOLETRED
-.. py:data:: htmlcolor.PAPAYAWHIP
-.. py:data:: htmlcolor.PEACHPUFF
-.. py:data:: htmlcolor.PERU
-.. py:data:: htmlcolor.PINK
-.. py:data:: htmlcolor.PLUM
-.. py:data:: htmlcolor.POWDERBLUE
-.. py:data:: htmlcolor.PURPLE
-.. py:data:: htmlcolor.RED
-.. py:data:: htmlcolor.ROSYBROWN
-.. py:data:: htmlcolor.ROYALBLUE
-.. py:data:: htmlcolor.SADDLEBROWN
-.. py:data:: htmlcolor.SALMON
-.. py:data:: htmlcolor.SANDYBROWN
-.. py:data:: htmlcolor.SEAGREEN
-.. py:data:: htmlcolor.SEASHELL
-.. py:data:: htmlcolor.SIENNA
-.. py:data:: htmlcolor.SILVER
-.. py:data:: htmlcolor.SKYBLUE
-.. py:data:: htmlcolor.SLATEBLUE
-.. py:data:: htmlcolor.SLATEGRAY
-.. py:data:: htmlcolor.SNOW
-.. py:data:: htmlcolor.SPRINGGREEN
-.. py:data:: htmlcolor.STEELBLUE
-.. py:data:: htmlcolor.TAN
-.. py:data:: htmlcolor.TEAL
-.. py:data:: htmlcolor.THISTLE
-.. py:data:: htmlcolor.TOMATO
-.. py:data:: htmlcolor.TURQUOISE
-.. py:data:: htmlcolor.VIOLET
-.. py:data:: htmlcolor.WHEAT
-.. py:data:: htmlcolor.WHITE
-.. py:data:: htmlcolor.WHITESMOKE
-.. py:data:: htmlcolor.YELLOW
-.. py:data:: htmlcolor.YELLOWGREEN
+.. 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/config.rst

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

Documentation/pycardium/display.rst

 ``display`` - Display
 =====================
 
+The display module let's you draw on the card10's display.
+Pixels are addressed from top left to bottom right with a range of x: 0 to 159 and y: 0 to 79.
+
+.. code-block:: text
+
+   0,0
+      +---------------------+
+      |                     |
+      |                     |
+      |                     |
+      |                     |
+      +---------------------+
+                           159,79
+
+Drawing operations are clipped, pixels outside of the screen will be ignored.
+
 .. automodule:: display
    :members:

Documentation/pycardium/gpio.rst

+.. py:module:: gpio
+
+``gpio`` - GPIO Pins
+==========================
+The :py:mod:`gpio` module allows you to use card10's GPIO pins as input and
+output in your scripts.
+
+**Example**:
+
+.. code-block:: python
+
+   import gpio
+
+   gpio.set_mode(gpio.WRISTBAND_1, gpio.mode.OUTPUT)
+   gpio.write(gpio.WRISTBAND_1, True)
+
+   gpio.set_mode(gpio.WRISTBAND_2, gpio.mode.INPUT | gpio.mode.PULL_UP)
+   state = gpio.read(gpio.WRISTBAND_2)
+   print("State of Wristband pin 2:", state)
+
+.. py:function:: set_mode(pin, mode)
+
+   Configure GPIO pin state.
+
+   :param int pin: ID of the pin to be configured.
+   :param int mode: An integer with the bits for the wanted mode set. Create your
+      integer by ORing :py:data:`gpio.mode.OUTPUT`, :py:data:`gpio.mode.INPUT`,
+      :py:data:`gpio.mode.ADC`, :py:data:`gpio.mode.PULL_UP`,
+      :py:data:`gpio.mode.PULL_DOWN`.
+
+   .. note:: On WRISTBAND_3, there is no ADC functionality available
+
+.. py:function:: get_mode(pin)
+
+   Get GPIO pin state.
+
+   :param int pin: ID of the pin of to get the mode of.
+   :returns: An integer with the configure mode bits set.
+
+.. py:function:: write(pin, value)
+
+   Write a value to a GPIO pin.
+
+   :param int pin: ID of the pin of to get the mode of.
+   :param bool value: New pin value.
+
+.. py:function:: read(pin)
+
+   Read GPIO pin value.
+
+   :param int pin: ID of the pin of to get the mode of.
+   :returns: Current value of the GPIO pin.
+      If the pin is configured as ADC, the value returned
+      will be between 0 and 1000, representing voltages from
+      0V to 3.3V (:py:data:`gpio.ADC` is only available in 1.9+).
+
+.. py:data:: WRISTBAND_1
+
+   Pin ID for Wristband GPIO 1.
+
+.. py:data:: WRISTBAND_2
+
+   Pin ID for Wristband GPIO 2.
+
+.. py:data:: WRISTBAND_3
+
+   Pin ID for Wristband GPIO 3.
+
+.. py:data:: WRISTBAND_4
+
+   Pin ID for Wristband GPIO 4.
+
+
+.. py:module:: gpio.mode
+
+.. py:data:: OUTPUT
+
+   Configures a pin as output.
+
+.. py:data:: INPUT
+
+   Configures a pin as input.
+
+.. py:data:: ADC
+
+   Configure pin as ADC input.
+
+   .. versionadded: 1.9
+
+.. py:data:: PULL_UP
+
+   Enables the internal pull-up resistor of a pin.
+
+.. py:data:: PULL_DOWN
+
+   Enables the internal pull-down resistor of a pin.

Documentation/pycardium/light-sensor.rst

@@ -6,15 +6,15 @@ On the harmonic board, there is an IR-LED which can be used in reverse as a
 crude brightness sensor.  Values returned are in no particular unit but seem to
 be fairly stable.
 
-.. py:function:: light_sensor.start()
+.. py:function:: start()
 
-   Turn on the ADC and start reading brightness values.  This function must be
-   called before any measurements can be taken.
+   Turn on the ADC and start reading brightness values.  (In past this function must be
+   called before any measurements can be taken.)
 
-.. py:function:: light_sensor.get_reading()
+.. py:function:: get_reading()
 
    Get an ambient brightness reading.  The returned value is in no particular
-   unit, though it seems to be fairly stable.  Common values:
+   unit, though it seems to be fairly stable. The value could be between 0 and 400.  Common values:
 
    - ~8: Very dark are
    - ~17: Typical hackerspace brightness
@@ -22,6 +22,16 @@ be fairly stable.
 
    :returns: A brightness reading in no particular unit
 
-.. py:function:: light_sensor.stop()
+.. py:function:: stop()
 
    Stop the ADC.
+
+.. py:function:: read()
+
+   Direct readout of the light-sensor.
+
+   Use this function for low latency readout.  The time between polls can have
+   an effect on the values measures.  If you do not need low latency, prefer
+   :py:func:`light_sensor.get_reading`.
+
+   .. versionadded:: 1.8

Documentation/pycardium/max30001.rst

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