Commit 715aac63 authored by zenox's avatar zenox

Merge branch 'master' into blink_multi_rocket

parents beafdeea 861d604a
Pipeline #4544 passed with stages
in 1 minute and 21 seconds
......@@ -4,7 +4,7 @@ image: "derq3k/card10-build-env:20190806-195837Z-f95b541-dirty"
stage: build
- ./
- ./ --werror
- ninja -C build/
- arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
......@@ -14,7 +14,7 @@ build:
stage: build
- ./
- ./ --werror
- ninja -C build/
- arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
......@@ -6,6 +6,115 @@ The format is based on [Keep a Changelog](
## [Unreleased]
## [v1.15] - 2020-02-02 - [Okra]
### Added
- Show a fault screen on the display when epicardium panics
### Fixed
- Prevent MicroPython garbage collector from delting ISRs
- Fix race conditoin when reading/writing BLE MAC address at boot.
- Fix locking of LEDs.
- Fix bug which only allowed to have a single file open at any time.
- Put all chips into standby when going to sleep
- Misc BLE fixes
## [v1.14] - 2019-12-29 - [Nettle]
### Added
- Scripts for profiling card10 (`tools/poor-profiler`)
- `tools/` script for displaying ECG logs in audio programs like
### Changed
- Ported hardware-locks & bhi160 to new mutex API
- The menu now tries to display apps without a `metadata.json` as well, if
### Fixed
- Fixed an unguarded i2c bus transaction which caused strange issues all
- Fixed copying large files freezing card10.
- Fixed BHI160 initialization interrupt behavior.
- Properly disable BHI160 if an error occurs during init.
- Fixed bhi160 app overflowing sensor queues.
- Fixed neopixel driver not properly writing the first pixel the first
- Fixed some l0dables crashing because the SysTick timer interrupt was not
## [v1.13] - 2019-12-09 - [Mushroom]
### Added
- ECG plotter tool (for desktop machines) which can plot ECG logs taken with card10.
- The `input()` Python function.
- Enabled the MicroPython `framebuf` module for a Pycardium-only framebuffer
- Added the `utime.ticks_us()` and `utime.ticks_ms()` functions for very
accurate timing of MicroPython code.
- Added an option to use the right buttons for scrolling and the left one for
selecting. This will be made configurable in a future release.
- Made timezone configurable with a new `timezone` option in `card10.cfg`.
- Added a setting-menu to the ECG App.
### Changed
- Changed default timezone to CET.
- Made a few library functions callable without any parameters so they are
easier to use.
- Refactored the `card10.cfg` config parser.
### Fixed
- Fixed the Pycardium delay implementation in preparation for features like
button-interrupts. Should also be more accurate now.
- Fixed the filter which is used by the ECG app.
- Fixed the display staying off while printing the sleep-messages.
- Improved the USB-Storage mode in the menu app.
- Fixed GPIO module not properly configuring a pin if both IN and ADC are given.
- Added missing documentation for `os.mkdir()` and `os.rename()`.
- Fixed all `-Wextra` warnings, including a few bugs. Warnings exist for a reason!
### Removed
- Removed unnecessary out-of-bounds checks in display module. Drawing outside
the display is now perfectly fine and the pixels will silently be ignored.
## [v1.12] - 2019-10-19 - [Leek]
### Added
- **USB Storage mode**! You can now select 'USB Storage' in the menu and
access card10's filesystem via USB. No more rebooting into bootloader!
- LED feedback on boot. If your display is broken, you can still see it doing
something now.
- `./tools/ --set-time` to set card10's system time from your host.
- 4 new functions in `utime` modules:
* `set_time_ms()`
* `set_unix_time_ms()`
* `unix_time()`
* `unix_time_ms()`
### Changed
- Updated BLE stack
- Refactored gfx API for drawing images (internal).
- Draw partially clipped primitives in all cases (Fixes menu scrolling
- Fatal errors are now handled in a central 'panic' module.
### Fixed
- Make BLE interrupts higher priority than anything else to hopefully increase
- Turn off BLE encryption after closing a connection.
- Fixed mainline bootloader being broken.
- Fixed menu entries being ordered by path instead of name.
- Fixed menu crashing without a message.
- Fixed QSTR build-system.
## [v1.11] - 2019-09-24 - [Karotte]
......@@ -281,7 +390,11 @@ fbf7c8c0 fix( Refactored based on !138
## [v1.0] - 2019-08-21 00:50
Initial release.
......@@ -185,3 +185,31 @@ The light sensor characteristic makes it possible to read the current value of t
The range of this sensor is between 0 (``0x0``) and 400 (``0x9001``).
- reading of ``0x0e00`` means **14**
Access via btgatt-client
Accessing services from a linux system is possible via ``btgatt-client``. The inbuilt gatt client of ``bluetoothctl`` as well as ``libgatt`` were tested, but struggled with the card10's BLE stack.
.. code-block::
# pairing the card10:
$ bluetoothctl
[bluetooth]# power on
[bluetooth]# scan on
[bluetooth]# pair CA:4D:10:xx:xx:xx #replace xx:xx:xx with scan result
# if this query doesn't appear, remove and re-pair:
[agent] Confirm passkey ###### (yes/no): [CHG] Device CA:4D:10:xx:xx:xx Name: card10
[card10-xxxxxx]# disconnect CA:4D:10:xx:xx:xx
# using a service:
$ btgatt-client -d CA:4D:10:xx:xx:xx
# wait until services have been discovered, may take a minute
[GATT client]# write-value 0x0926 31 31 31
# if this error appears remove and re-pair:
[GATT client]# Device disconnected: Software caused connection abort
On the card10 the ARM Cordio-B50 stack is used, which is in a very early experimental state and has some incompatibilities with some smartphones.
Therefore some alternative stacks are evaluated, which meight be used as a replacement in the long term.
Here a stack called NimBLE is presented, which claims to be feature complete. Originally it has been developed for Mynewt, an open source embedded operating system by Apache (
There is a working port for the ESP32 espressif ESP-IDF framework.
Like Epicardium, ESP-IDF is based on FreeRTOS. Therefore it can be used for evaluation purposes.
Getting NimBLE run on the ESP32
Install required packages:
.. code-block:: shell-session
sudo apt install git virtualenv python2.7 cmake
.. code-block:: shell-session
sudo pacman -S git python2 python2-virtualenv cmake
Download and extract xtensa ESP32 compiler:
.. code-block:: shell-session
tar -xf xtensa-esp32-elf-gcc8_2_0-esp32-2018r1-linux-amd64.tar.xz
Clone esp-idf:
.. code-block:: shell-session
git clone
Add xtensa and ESP-IDF path to $PATH:
bash shell:
.. code-block:: shell-session
export IDF_PATH=$PWD/esp-idf
export PATH=${PATH}:$PWD/xtensa-esp32-elf/bin:$PWD/esp-idf/tools
fish shell:
.. code-block:: shell-session
set -gx IDF_PATH $PWD/esp-idf
set -gx PATH $PWD/xtensa-esp32-elf/bin/ $PWD/esp-idf/tools $PATH
Create a python2.7 virtualenv:
.. code-block:: shell-session
cd esp-idf
virtualenv -p /usr/bin/python2.7 venv
Enter the virtualenv:
bash shell:
.. code-block:: shell-session
. venv/bin/activate
fish shell:
.. code-block:: shell-session
. venv/bin/
Init git submodules and install all required Python packages:
.. code-block:: shell-session
git submodule update --init --recursive
pip install -r requirements.txt
Now you are ready to build!
The following steps assume that your ESP32 is connected via USB and
is accessible via /dev/ttyUSB0. This meight be different on your system.
There are a few NimbLE examples which can be used for playing around:
Build a BLE server example (host mode):
.. code-block:: shell-session
cd examples/bluetooth/nimble/bleprph -p /dev/ttyUSB0 flash monitor
This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.
After the flashing process the ESP32 will anounce itself as **nimble-bleprph** device via BLE.
Build a BLE client example (central mode):
.. code-block:: shell-session
cd examples/bluetooth/nimble/blecent -p /dev/ttyUSB0 flash monitor
This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.
After the flashing process the ESP32 creates a GATT client and performs passive scan, it then connects to peripheral device if the device advertises connectability and the device advertises support for the Alert Notification service (0x1811) as primary service UUID.
.. _card10_cfg:
Certain high-level settings can be configured using a filed named ``card10.cfg``. It is accessed from the :ref:`usb_file_transfer` of the bootloader. Once you are in this mode and have mounted the badge's flash device, you can either create or update a file named ``card10.cfg``.
The file is in the well-known INI-style format, with one setting per line. For instance, if there were an option called ``answer_to_life``, you could set it by writing the following line in the ``card10.cfg`` file:
.. code-block:: text
answer_to_life = 42
Don't forget to unmount the filesystem before rebooting your badge after changing any setting.
Syntax and Types
Lines that start with a ``#`` character are ignored.
Any other line will have the overall syntax of ``option_name = option_value``, with spaces around the ``=`` character optional.
Option names are internal to card10 and described below. Each option has a defined type.
========= ===========
Type name Description
========= ===========
Boolean A true/false value. ``1`` or ``true`` is true, ``0`` or ``false`` is false. Example: ``foo = true``.
String An unquoted string value of maximum 20 bytes. Values longer than 20 bytes are trimmed. Example: ``foo = bar``.
Integer A signed 32-bit integer in base 10. Example: ``foo = 42`` or ``bar = -1337``.
Float A single-precision (32-bit) floating-point number in base 10. Example: ``foo = 13.37``.
========= ===========
Supported options
=============== ========== ===========
Option name Type Description
=============== ========== ===========
``execute_elf`` Boolean Allow running of binary :ref:`l0dables`. These files can be nefarious, so this option is off by default.
--------------- ---------- -----------
``timezone`` String Timezone for card10; must be of format ``[+-]HHMM``. Examples: ``+0800``, ``-0200``
--------------- ---------- -----------
``default_app`` String Full path to the exectutable file of the default application. If this option is not set,``apps/analog_clock/`` is used.
=============== ========== ===========
......@@ -3,6 +3,8 @@ import subprocess
import sys
import time
import sphinx.util.logging
from docutils import nodes
from docutils.parsers import rst
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
......@@ -47,6 +49,23 @@ todo_include_todos = True
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["output", "Thumbs.db", ".DS_Store", "hawkmoth"]
# -- Extensions -------------------------------------------------------------- {{{
class ColorExample(rst.Directive):
has_content = False
required_arguments = 1
optional_arguments = 0
option_spec = {}
def run(self):
color = self.arguments[0]
html_text = '<div style="width: 30px;height: 30px;background: {};border: black 1px solid;border-radius: 15px;"></div>'
return [nodes.raw("", html_text.format(color), format="html")]
# }}}
# -- Options for HTML output ------------------------------------------------- {{{
# The Read the Docs theme is available from
......@@ -91,9 +110,11 @@ autodoc_mock_imports = [
......@@ -124,3 +145,4 @@ except ImportError as e:
# -- Sphinx Setup ------------------------------------------------------------
def setup(app):
app.add_config_value("has_hawkmoth", has_hawkmoth, "")
app.add_directive("color-example", ColorExample)
Ontop of FreeRTOS, we have our own mutex implementation. **Never use the
FreeRTOS mutexes directly! Always use this abstraction layer instead**. This
mutex implementation tries to make reasoning about program flow and locking
behavior easier. And most importantly tries to help with debugging possible
There are a few guiding design principles:
- Mutexes can only be used from tasks, **never** from interrupts!
- Timers can use mutexes, but only with :c:func:`mutex_trylock`, **never** with
:c:func:`mutex_lock` (Because they are not allowed to block).
- Locking can *never* fail (if it does, we consider this a fatal error ⇒ panic).
- No recursive locking.
- An unlock can only occur from the task which previously acquired the mutex.
- An unlock is only allowed if the mutex was previously acquired.
For a more elaborate explanation of the rationale behind these rules take a
look at the :ref:`mutex-design-reasons`.
.. c:autodoc:: epicardium/modules/mutex.h
.. _mutex-design-reasons:
Reasons for this Design
Locking can *never* fail
This might seem like a bold claim at first but in the end, it is just a matter
of definition and shifting responsibilities. Instead of requiring all code to
be robust against a locking attempt failing, we require all code to properly
lock and unlock their mutexes and thus never producing a situation where
locking would fail.
Because all code using any of the mutexes is contained in the Epicardium
code-base, we can - *hopefully* - audit it properly behaving ahead of time and
thus don't need to add code to ensure correctness at runtime. This makes
downstream code easier to read and easier to reason about.
History of this project has shown that most code does not properly deal with
locking failures anyway: There was code simply skipping the mutexed action on
failure, code blocking a module entirely until reboot, and worst of all: Code
exposing the locking failure to 'user-space' (Pycardium) instead of retrying.
This has lead to spurious errors where technically there would not need to be
Only from tasks
Locking a mutex from an ISR, a FreeRTOS software timer or any other context
which does not allow blocking is complicated to do right. The biggest
difficulty is that a task might be holding the mutex during execution of such a
context and there is no way to wait for it to release the mutex. This requires
careful design of the program flow to choose an alternative option in such a
case. A common approach is to 'outsource' the relevant parts of the code into
an 'IRQ worker' which is essentially just a task waiting for the IRQ to wake it
up and then attempts to lock the mutex.
If you absolutely do need it (and for legacy reasons), software timers *can*
lock a mutex using :c:func:`mutex_trylock` (which never blocks). I strongly
recommend **not** doing that, though. As shown above, you will have to deal
with the case of the mutex being held by another task and it is very well
possible that your timer will get starved of the mutex because the scheduler
has no knowledge of its intentions. In most cases, it is a better idea to use
a task and attempt locking using :c:func:`mutex_lock`.
.. todo::
We might introduce a generic IRQ worker queue system at some point.
No recursive locking
Recursive locking refers to the ability to 'reacquire' a mutex already held by
the current task, deeper down in the call-chain. Only the outermost unlock
will actually release the mutex. This feature is sometimes implemented to
allow more elegant abstractions where downstream code does not need to know
about the mutexes upstream code uses and can still also create a larger region
where the same mutex is held.
But exactly by hiding the locking done by a function, these abstractions make
it hard to trace locking chains and in some cases even make it impossible to
create provably correct behavior. As an alternative, I would suggest using
different mutexes for the different levels of abstraction. This also helps
keeping each mutex separated and 'local' to its purpose.
Only unlock from the acquiring task
Because of the above mentioned mutex locking semantics, there should never be a
need to force-unlock a forgein mutex. Even in cases of failures, all code
should still properly release all mutexes it holds. One notable exceptions is
``panic()``\s which will abort all ongoing operations anyway.
Only unlock once after acquisition
Justified with an argument of robustness, sometimes the :c:func:`mutex_unlock`
call is written in a way that allows unlocking an already unlocked mutex. But
robustness of downstream code will not really be improved by the upstream API
dealing with arguably invalid usage. For example, this could encourage
practices like unlocking everything again at the end of a function "just to be
Instead, code should be written in a way where the lock/unlock pair is
immediately recognizable as belonging together and is thus easily auditable to
have correct locking behavior. A common pattern to help with readability in
this regard is the *Single Function Exit* which looks like this:
.. code-block:: cpp
int function()
int ret;
ret = foo();
if (ret) {
/* Return with an error code */
ret = -ENODEV;
goto out_unlock;
ret = bar();
if (ret) {
/* Return the return value from foo */
goto out_unlock;
ret = 0;
return ret;
......@@ -63,22 +63,44 @@ Dependencies
.. code-block:: shell-session
pacman -S meson
- macOS
- macOS
.. code-block:: shell-session
brew install ninja
pip3 install --user meson # see - you will have to add ~/.local/bin to your PATH.
* **python3-crc16**: Install with ``pip3 install --user crc16``.
* **python3-pillow**: Python Image Library ``pip3 install --user pillow``.
* One of two CRC packages is required. Pick one:
- Ubuntu / Debian / macOS
.. code-block:: shell-session
pip3 install --user crc16
.. 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-crc16 python-pillow
pacman -S python-pillow
.. _ARM's GNU toolchain:
......@@ -107,7 +129,6 @@ firmware features:
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.
- ``-Djailbreak_card10=true``: Enable execution of .elf l0dables on core 1.
.. warning::
......@@ -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