Commit 8a2de29e authored by dx's avatar dx

Merge 'Documentation: get rid of jailbreak, document alternatives'

See merge request card10/firmware!294
parents 428281b3 f51f0a39
.. _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.
=============== ========== ===========
......@@ -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::
......
......@@ -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.``
......
......@@ -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
......
......@@ -55,25 +55,28 @@ 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`.
.. _Rustcardium: https://git.card10.badge.events.ccc.de/astro/rust-card10
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.
.. todo::
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
Program Flow Diagram
--------------------
......
.. _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
1. If the badge is on, hold the top-left (power) button until the sleep screen appears, then release.
2. Start holding the bottom-right button.
3. Quickly press and release the top-left (power) button to turn the badge on.
4. 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.
......@@ -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"
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment