Documentation: get rid of jailbreak, document alternatives

We update the documentaiton and CI tooling to remove references to the jailbreak firmware.

We also slightly update the docs to mention USB mode in a separate page, for unification purposes.

Documentation/card10-cfg.rst

+.. _card10_cfg:
+
+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.
+=============== ========== ===========

Documentation/how-to-build.rst

@@ -107,7 +107,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::
 

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

@@ -45,6 +45,8 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    :caption: Firmware
 
    overview
+   card10-cfg
+   usb-file-transfer
    how-to-build
    how-to-flash
    debugger

Documentation/overview.rst

@@ -41,23 +41,26 @@ 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
 linker script and should link against the api-caller library so they can
 interface with the :ref:`epicardium_api`.
-Note: this feature is disabled by default and has to be enabled at build time.
-To do this, run ``bootstrap.sh`` with the option ``-Djailbreak_card10=true``
-and rebuild the firmware as described in :ref:`how_to_build`.
 
-.. 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.
 
-   Provide more details how this works
+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.
 
 Program Flow Diagram
 --------------------

Documentation/usb-file-transfer.rst

+.. _usb_file_transfer:
+
+USB File Transfer
+=================
+
+The card10 badge bootloader offers a USB Mass Storage mode to access its 8MB external flash.
+
+This flash contains a FAT32 filesystem and files on it will be visible to software running on the badge.
+
+Getting to the USB mode
+-----------------------
+
+To get to the USB mode, you will need to boot the badge while keeping the bottom-right button pressed.
+
+.. image:: static/bootloader-buttons.png
+
+There are a few ways you can get to re(boot) the badge.
+
+============== ======
+Press duration Action
+============== ======
+400-1000ms     Reboot in Firmware
+1000ms+        Power off in Firmware
+8000ms+        Power off in Hardware
+============== ======
+
+**Method A**, when your badge is on, via Firmware Reboot:
+
+1. Start holding the bottom-right button.
+2. Press the top-left (power) button for 0.4-1s and then release it. Your badge should reboot.
+3. Your badge should now be in file transfer mode, and you can then release the bottom-right button.
+
+**Method B**, when your badge is on, via Firmware/Hardware Power off:
+
+1. Press the top-left (power) button until the badge turns off.
+2. Release the top-left button.
+3. Start holding the bottom-right button.
+4. Quickly press and release the top-left (power) button to turn the badge on.
+5. Your badge should now be in file transfer mode, and you can then release the bottom-right button.
+
+**Method C**, when your badge is off:
+
+1. Start holding the bottom-right button.
+2. Quickly press and release the top-left (power) button to turn the badge on.
+3. Your badge should now be in file transfer mode, and you can then release the bottom-right button.
+
+If you succesfully got into USB File Transfer mode, the screen will display its version and notify about the USB mode by displaying ``USB activated. Ready.``. If you connect the badge via USB to your computer, it should now detect 8MB of flash storage that you can mount in the same way as a pendrive.
+
+This pendrive can contain multiple files with different functions, some of them outlined here:
+
+============== ========
+File name      Function
+============== ========
+``card10.bin`` Firmware update file for the badge. If this file is present, the bootloader will perform an internal update to boot from this firmware file, then it will be deleted.
+``main.py``    This file contains the default `application` to be run on power on.
+``menu.py``    This file contains the default `menu` to be run when the power button is short-pressed.
+``*.py``       These are application files written in (Micro)Python that can be run from the menu.
+``*.elf``      These are :ref:`l0dables` that can be run from the menu.
+============== ========
+
+Updating files and rebooting
+----------------------------
+
+No matter which file you are writing, the bootloader will display a red ``Writing`` status message while write operations are pending. Please wait until it displays ``Ready`` again before resetting the badge by pressing the power button again.
+

tools/make-release.sh

@@ -52,11 +52,11 @@ fi
 release_dir="release-$version"
 mkdir "$release_dir"
 
-message "Building (non-jailbreak) release version ..."
+message "Building release version ..."
 ./bootstrap.sh
 ninja -C build/
 
-message "Creating (non-jailbreak) release archive ..."
+message "Creating release archive ..."
 mkdir "$release_dir/$release_name"
 cp -r -t "$release_dir/$release_name" preload/*
 cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name/card10.bin"
@@ -66,20 +66,5 @@ cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name/card10.b
 mkdir "$release_dir/elfs"
 cp -t "$release_dir/elfs" build/epicardium/epicardium.elf build/pycardium/pycardium.elf build/bootloader/bootloader.elf
 
-message "Building (jailbreak) release version ..."
-./bootstrap.sh -Djailbreak_card10=true
-ninja -C build/
-
-message "Creating (jailbreak) release archive ..."
-mkdir "$release_dir/$release_name-jailbreak"
-cp -r -t "$release_dir/$release_name-jailbreak" preload/*
-cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name-jailbreak/card10.bin"
-( cd "$release_dir"; zip -r "$release_name-jailbreak"{.zip,}; )
-
-# Copy ELFs
-mkdir "$release_dir/elfs-jailbreak"
-cp -t "$release_dir/elfs-jailbreak" build/epicardium/epicardium.elf build/pycardium/pycardium.elf
-
 message "Done!"
-echo "Archive (non-jailbreak): $release_dir/$release_name.zip"
-echo "Archive (jailbreak):     $release_dir/$release_name-jailbreak.zip"
+echo "Archive: $release_dir/$release_name.zip"