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,6 +34,7 @@ Otherwise, documentation comments are passed through verbatim.
 """
 
 import enum
+import re
 import sys
 
 from clang.cindex import CursorKind, TypeKind
@@ -166,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:
+    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)
@@ -193,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():
@@ -210,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
@@ -266,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/index.rst

@@ -23,8 +23,10 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    pycardium/overview
    pycardium/stdlib
    pycardium/bhi160
+   pycardium/ble_hid
    pycardium/bme680
    pycardium/max30001
+   pycardium/max86150
    pycardium/buttons
    pycardium/color
    pycardium/config
@@ -34,6 +36,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    pycardium/light-sensor
    pycardium/os
    pycardium/personal_state
+   pycardium/png
    pycardium/power
    pycardium/pride
    pycardium/simple_menu
@@ -63,13 +66,17 @@ 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

@@ -29,8 +29,6 @@ number of tasks that will have been keeping card10 running.  These are:
 +--------------------+-------------------------------+----------+-------------------------------------------+
 | `vInterruptsTask`_ | ``interrupts_task`` (static)  | +2       | Interrupt dispatcher worker               |
 +--------------------+-------------------------------+----------+-------------------------------------------+
-| `vLedTask`_        | -/-                           | +1       | LED Animations                            |
-+--------------------+-------------------------------+----------+-------------------------------------------+
 | `vMAX30001Task`_   | ``max30001_task_id`` (static) | +1       | `MAX30001`_ ECG driver                    |
 +--------------------+-------------------------------+----------+-------------------------------------------+
 | `vBhi160Task`_     | ``bhi160_task_id`` (static)   | +1       | `BHI160`_ sensor fusion driver            |
@@ -75,11 +73,13 @@ 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.
+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
 --------------------

Documentation/pycardium/bhi160.rst

@@ -28,18 +28,18 @@ The coordinate system of the BHI160 sensor data looks like this:
 .. code-block:: python
 
    import bhi160
-   import utime
+   import time
 
    bhi = bhi160.BHI160Orientation()
 
     while True:
         samples = bhi.read()
         if len(samples) == 0:
-            utime.sleep(0.25)
+            time.sleep(0.25)
             continue
         # print the latest sample
         print(samples[-1])
-        utime.sleep(0.25)
+        time.sleep(0.25)
 
 
 Orientation

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

@@ -4,11 +4,50 @@
 =================================
 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, utime
+   import bme680, time
 
    with bme680.Bme680() as environment:
        while True:
@@ -19,7 +58,15 @@ Allows access to environmental data of card10's surroundings.
            print("Pressure:       {:10.2f} hPa".format(d.pressure))
            print("Gas Resistance: {:10.2f} Ω".format(d.resistance))
 
-           utime.sleep(1)
+           time.sleep(1)
+
+You can use the return type of :py:meth:`~bme680.Bme680.get_data` to decide
+if you want to use/display the additonal fields returned if BSEC is enabled.
+
+.. code-block:: python
+
+    if isinstance(d, bme680.BSECData):
+        print("Air quality:    {:7d}".format(d.iaq))
 
 Sensor Class
 ------------

Documentation/pycardium/config.rst

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

Documentation/pycardium/max86150.rst

+``max86150`` - MAX86150
+=======================
+
+.. automodule:: max86150
+   :members:

Documentation/pycardium/os.rst

@@ -115,3 +115,17 @@ Card10-Specific
 .. py:data:: USB_FLASH
 
    Mass-Storage device active.
+
+.. py:function:: fs_is_attached()
+
+   Check whether the filesystem is currently attached to card10 (or whether a connected
+   USB host is currently holding control over it and possibly writing to it).
+
+   :returns:
+
+      - ``True`` if the filesystem is attached to card10 and an app can read and
+        write files.
+      - ``False`` if the filesystem is not available to card10 because a USB
+        host is currently controlling it.
+
+   .. versionadded: 1.18

Documentation/pycardium/png.rst

+``png`` - PNG Decoder
+=====================
+The ``png`` module provides functions to decode PNG files into raw pixel data
+which can be displayed using the card10's display or its LEDs.
+
+.. automodule:: png
+   :members:

Documentation/pycardium/stdlib.rst

 MicroPython Standard Library
 ============================
-Pycardium contains some modules from the MicroPython standard library.  These
-are:
+Pycardium contains some modules from the MicroPython standard library.
+
+Some modules below use a standard Python name, but prefixed with “u”,
+e.g. ujson instead of json. This is to signify that such a module is a
+micro-library, i.e. implements only a subset of CPython module
+functionality. Please refer to the official `MicroPython docs`_ for an
+explanation why.
+
+All u-name modules can also be imported using their non-u-name. E.g.
+``import utime`` and import ``import time`` will both work.
+
+.. _MicroPython docs: http://docs.micropython.org/en/latest/library/index.html#python-standard-libraries-and-micro-libraries
 
 .. py:module:: framebuf
 

Documentation/pycardium/utime.rst

@@ -8,6 +8,9 @@ CPython but wouldn't fit anywhere else in our implementation.  Most
 prominently,  this is the :py:func:`utime.alarm` function for setting an RTC
 alarm.
 
+Like all other u-name modules, ``utime`` can also imported using the standard
+``import time`` statement.
+
 .. |time| replace:: ``time``
 .. _time: https://docs.python.org/3/library/time.html
 
@@ -135,13 +138,13 @@ alarm.
 
    .. code-block:: python
 
-      import utime
+      import time
 
       def minute_timer(x):
-         current = utime.time()
+         current = time.time()
          print("Current: " + str(current))
          alarm = (current // 60 + 1) * 60
-         utime.alarm(alarm, minute_timer)
+         time.alarm(alarm, minute_timer)
 
       minute_timer(None)
 
@@ -150,13 +153,13 @@ alarm.
 
    .. code-block:: python
 
-      import interrupt, utime
+      import interrupt, time
 
       def 5_second_timer(x):
-         current = utime.time()
+         current = time.time()
          print("Current: " + str(current))
          alarm = (current // 10) * 10 + 5
-         utime.alarm(alarm)
+         time.alarm(alarm)
 
       # This time, we need to register and enable the callback manually
       interrupt.set_callback(interrupt.RTC_ALARM, 5_second_timer)

Documentation/pycardium/ws2812.rst

@@ -19,7 +19,9 @@ The ``ws2812`` module controls LEDs of the WS2812 type. Just as the ``leds`` mod
 
    .. code-block:: python
 
-      import color, utime, ws2812, gpio
+      import color, time, ws2812, gpio
+
+      gpio.set_mode(gpio.WRISTBAND_2, gpio.mode.OUTPUT)
 
       i = 0
       while True:
@@ -28,6 +30,6 @@ The ``ws2812`` module controls LEDs of the WS2812 type. Just as the ``leds`` mod
           col3 = color.from_hsv((i + 40) % 360, 1.0, 0.1)
           ws2812.set_all(gpio.WRISTBAND_2, [col1, col2, col3])
           i += 1
-          utime.sleep_ms(10)
+          time.sleep_ms(10)
 
    .. versionadded:: 1.10

bootloader/bootloader-display.c

@@ -8,13 +8,12 @@
 
 static void bootloader_display_splash(void)
 {
-	gfx_copy_region(
+	gfx_copy_region_rle_mono(
 		&display_screen,
 		0,
 		0,
 		160,
 		80,
-		GFX_RLE_MONO,
 		sizeof(splash),
 		(const void *)(splash)
 	);

bootloader/build_multi_image.sh

@@ -6,8 +6,12 @@ BIN1="$2"
 BIN2="$3"
 BINOUT="$4"
 
-dd if=/dev/zero ibs=1k count=448 2>/dev/null | LANG=C LC_CTYPE=C LC_ALL=C LC_COLLATE=C tr "\000" "\377" > "$BINOUT"
-dd if="$BIN1" of="$BINOUT" conv=notrunc 2>/dev/null
-dd if="$BIN2" >> "$BINOUT" 2>/dev/null
+if [ "$(stat -c "%s" "${BIN1}")" -gt 589824 ]; then
+    echo "$0: ${BIN1} is too big to fit!" >&2
+    exit 1
+fi
+
+objcopy -I binary -O binary --pad-to=589824 --gap-fill=255 "${BIN1}" "$BINOUT"
+cat "$BIN2" >>"$BINOUT"
 
 "$PYTHON" "$(dirname "$0")/crc_patch.py" "$BINOUT"

bootstrap.sh

@@ -4,7 +4,9 @@ set -xe
 cd "$(dirname "$0")"
 test -d build/ && rm -r build/
 
-git submodule update --init ./lib/micropython
+# Get external libs (MicroPython, tiny-AES-c, SHA256)
+git submodule deinit --all
+git submodule update --init ./lib
 meson --cross-file card10-cross.ini build/ "$@"
 
 set +x

card10-cross.ini

@@ -6,7 +6,7 @@ strip = 'arm-none-eabi-strip'
 [properties]
 c_args      = ['-mthumb', '-mcpu=cortex-m4', '-mfloat-abi=softfp', '-mfpu=fpv4-sp-d16', '-Wa,-mimplicit-it=thumb', '-ffunction-sections', '-fdata-sections', '-fsingle-precision-constant', '-fno-isolate-erroneous-paths-dereference']
 
-c_link_args = ['-mthumb', '-mcpu=cortex-m4', '-mfloat-abi=softfp', '-mfpu=fpv4-sp-d16', '-Wl,--start-group', '-lc', '-lnosys', '-Wl,--end-group', '--specs=nano.specs']
+c_link_args = ['-mthumb', '-mcpu=cortex-m4', '-mfloat-abi=softfp', '-mfpu=fpv4-sp-d16', '-Wl,--start-group', '-lc', '-lnosys', '-Wl,--end-group', '--specs=nano.specs', '-Wl,-wrap,BbBleDrvRand']
 
 target_defs = ['-DTARGET=32665', '-DTARGET_REV=0x4131', '-DBOARD_CARD10=1']
 

demos/ble-ws2812-card10.py

+import ws2812, gpio, bluetooth, time, display
+from micropython import const
+
+_IRQ_GATTS_WRITE = const(3)
+
+WS2812_SERVICE_UUID = \
+    bluetooth.UUID("23238000-2342-2342-2342-234223422342")
+SET_ALL = (
+    bluetooth.UUID("23238001-2342-2342-2342-234223422342"),
+    bluetooth.FLAG_WRITE
+)
+WS2812_SERVICE = (
+    WS2812_SERVICE_UUID,
+    (SET_ALL,)
+)
+
+def irq(event, data):
+    if event == _IRQ_GATTS_WRITE:
+        conn_handle, value_handle = data
+        value = ble.gatts_read(value_handle)
+        ws2812.set_all(gpio.WRISTBAND_3, [value] * 3)
+
+if __name__ == "__main__":
+    display.open().backlight(0)
+    gpio.set_mode(gpio.WRISTBAND_3, gpio.mode.OUTPUT)
+
+    ble = bluetooth.BLE()
+    ble.active(True)
+    ble.irq(irq)
+    ble.gatts_register_services((WS2812_SERVICE,))
+
+    print("Waiting for connection!")
+
+    while True:
+        time.sleep(1)