how-to-build.rst 4.47 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
How To Build
============
If you just want to write MicroPython code for card10, you probably **won't**
4
5
need to build the firmware yourself.  This page is for people **who want to work
on the underlying firmware itself**.
Rahix's avatar
Rahix committed
6
7
8
9
10
11

Dependencies
------------
* **gcc**, **binutils** & **newlib** for ``arm-none-eabi``:  The packages have
  slightly different names on different distros.

12
13
14
15
16
17
18
19
20
21
22
  - Ubuntu / Debian:

    .. code-block:: shell-session

       apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi

  - Arch:

    .. code-block:: shell-session

       pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
Rahix's avatar
Rahix committed
23

torben's avatar
torben committed
24
  - Fedora
Rahix's avatar
Rahix committed
25

torben's avatar
torben committed
26
    .. code-block:: shell-session
Rahix's avatar
Rahix committed
27

torben's avatar
torben committed
28
        dnf install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
29
30
31
32
33
34
35
36
37
38
39
        
  - 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
40

Rahix's avatar
Rahix committed
41
  - Alternative: Download `ARM's GNU toolchain`_.  **TODO**
42
43
.. _Homebrew: https://brew.sh/

Rahix's avatar
Rahix committed
44
* **python3**:  For meson and various scripts needed for building.
Rahix's avatar
Rahix committed
45
* **meson** (>0.43.0) & **ninja**:  Unfortunately most distros only have very old versions
Rahix's avatar
Rahix committed
46
  of meson in their repositories.  Instead, you'll probably save yourself a lot
Rahix's avatar
Rahix committed
47
48
  of headaches by installing meson from *pip*.

49
  - Ubuntu / Debian:
Rahix's avatar
Rahix committed
50
51
52
53
54
55

    .. code-block:: shell-session

       apt install ninja-build
       pip3 install --user meson

56
  - Arch (has latest *meson* in the repos):
Rahix's avatar
Rahix committed
57
58
59
60

    .. code-block:: shell-session

       pacman -S meson
61
62
63
64
65
66
67
       
  - 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.
Rahix's avatar
Rahix committed
68

Rahix's avatar
Rahix committed
69
* **python3-crc16**: Install with ``pip3 install --user crc16``.
70
* **python3-pillow**: Python Image Library ``pip3 install --user pillow``.
Rahix's avatar
Rahix committed
71

72
73
74
75
76
77
  - Arch

    .. code-block:: shell-session

       pacman -S python-crc16 python-pillow

Rahix's avatar
Rahix committed
78
79
.. _ARM's GNU toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads

80
81
Cloning
-------
Rahix's avatar
Rahix committed
82
Clone the ``master`` branch of the firmware repository:
83
84
85
86
87

.. code-block:: shell-session

   $ git clone https://git.card10.badge.events.ccc.de/card10/firmware.git

Rahix's avatar
Rahix committed
88
89
90
Build Configuration
-------------------
Initialize the build-system using
Rahix's avatar
Rahix committed
91
92
93
94
95

.. code-block:: shell-session

   $ ./bootstrap.sh

Rahix's avatar
Rahix committed
96
97
98
Additional arguments to ``bootstrap.sh`` will be passed to *meson*.  You can
use this to for example, to enable one or more of the following optional
firmware features:
Rahix's avatar
Rahix committed
99

Rahix's avatar
Rahix committed
100
101
102
- ``-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.
103
104
- ``-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.
Rahix's avatar
Rahix committed
105
106
107

.. warning::

Rahix's avatar
Rahix committed
108
109
110
111
112
113
   Our build-system contains a few workarounds around short-comings in meson.
   These workarounds might break on some setups which we did not yet test.  If
   this is the case for you, please open an issue in our `issue tracker`_!

.. _issue tracker: https://git.card10.badge.events.ccc.de/card10/firmware/issues

Rahix's avatar
Rahix committed
114
115
116
117
118
119
120
121
122
123
124
125
Building
--------
Build using *ninja*:

.. code-block:: shell-session

   $ ninja -C build/

If ninja succeeds, the resulting binaries are in ``build/``.  They are
available in two formats:  As an ``.elf`` which can be flashed using a debugger
and as a ``.bin`` which can be loaded using the provided bootloader.  Here is a
list of the binaries:
Rahix's avatar
Rahix committed
126
127
128
129
130
131

- ``build/bootloader/bootloader.elf``: Our bootloader.  It should already be on
  your card10.  The bootloader can only be flashed using a debugger.
- ``build/pycardium/pycardium_epicardium.bin``: The entire firmware in one ``.bin``.
- ``build/epicardium/epicardium.elf``: The core 0 part of the firmware, called Epicardium.
- ``build/pycardium/pycardium.elf``: Our MicroPython port, the core 1 part of the firmware.
132
133
134
135
136
137

In order to do a rebuild you can issue a clean command to ninja via

.. code-block:: shell-session

  $ ninja -C build/ -t clean
Rahix's avatar
Rahix committed
138
139

Otherwise, rerunning ``./bootstrap.sh`` will also clean the build-directory.