how-to-build.rst 6.2 KB
Newer Older
swym's avatar
swym committed
1
2
.. _how_to_build:

Rahix's avatar
Rahix committed
3
4
5
How To Build
============
If you just want to write MicroPython code for card10, you probably **won't**
6
7
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
8
9
10
11
12
13

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

14
15
16
17
18
19
20
21
22
23
24
  - 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
25

torben's avatar
torben committed
26
  - Fedora
Rahix's avatar
Rahix committed
27

torben's avatar
torben committed
28
    .. code-block:: shell-session
Rahix's avatar
Rahix committed
29

torben's avatar
torben committed
30
        dnf install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
Rahix's avatar
Rahix committed
31

Rahix's avatar
Rahix committed
32
  - macOS (Note: The card10 firmware team used Linux so far. macOS recommendations here are experimental.)
Rahix's avatar
Rahix committed
33
34
35
36
37

    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.

38
    .. code-block:: shell-session
Rahix's avatar
Rahix committed
39

40
41
42
        brew tap px4/px4
        brew install px4/px4/gcc-arm-none-eabi-63
        brew install coreutils
43

Rahix's avatar
Rahix committed
44
45
    .. _Homebrew: https://brew.sh/

Rahix's avatar
Rahix committed
46
  - Alternative: Download `ARM's GNU toolchain`_.  **TODO**
Rahix's avatar
Rahix committed
47

48

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

54
  - Ubuntu / Debian:
Rahix's avatar
Rahix committed
55
56
57
58
59
60

    .. code-block:: shell-session

       apt install ninja-build
       pip3 install --user meson

61
  - Arch (has latest *meson* in the repos):
Rahix's avatar
Rahix committed
62
63
64
65

    .. code-block:: shell-session

       pacman -S meson
66
67
68

  - macOS

69
    .. code-block:: shell-session
70

71
72
        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
73

schneider's avatar
schneider committed
74
* One of two CRC packages is required. Pick one:
Rahix's avatar
Rahix committed
75

76
77
  - Ubuntu / Debian / macOS

Stormwind's avatar
Stormwind committed
78
    .. code-block:: shell-session
79

Stormwind's avatar
Stormwind committed
80
        pip3 install --user crc16
81
82
83

or

Stormwind's avatar
Stormwind committed
84
    .. code-block:: shell-session
85

Stormwind's avatar
Stormwind committed
86
        pip3 install --user crcmod
87
88
89

  - Arch

Stormwind's avatar
Stormwind committed
90
    .. code-block:: shell-session
91
92
93

       pacman -S python-crc16

Stormwind's avatar
Stormwind committed
94
95
* **python3-pillow**: Python Image Library
       .. code-block:: shell-session
96

Stormwind's avatar
Stormwind committed
97
            pip3 install --user pillow
98

99
100
101
102
  - Arch

    .. code-block:: shell-session

103
       pacman -S python-pillow
104

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

107
108
Cloning
-------
Rahix's avatar
Rahix committed
109
Clone the ``master`` branch of the firmware repository:
110
111
112
113
114

.. code-block:: shell-session

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

Rahix's avatar
Rahix committed
115
116
117
Build Configuration
-------------------
Initialize the build-system using
Rahix's avatar
Rahix committed
118
119
120
121
122

.. code-block:: shell-session

   $ ./bootstrap.sh

Rahix's avatar
Rahix committed
123
124
125
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
126

Rahix's avatar
Rahix committed
127
128
129
- ``-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.
130
131
- ``-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
132
133
134

.. warning::

Rahix's avatar
Rahix committed
135
136
137
138
139
140
   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
141
142
143
144
145
146
147
148
149
150
151
152
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
153
154
155
156
157
158

- ``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.
159
160
161
162
163
164

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
165
166

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

168
169
170
171
172
173
174
175
176
.. note::

   **macOS**: If ``strip`` fails to work on the freshly compiled ``mpy-cross``:
   "strip: object: (...)/lib/micropython/micropython/mpy-cross/mpy-cross
   malformed object (unknown load command 9)", you a likely not using the
   `strip` that matches to your ``clang``. Do ``which strip && which clang``,
   and if the paths don't match, clean up your PATHs, or as a quick hack,
   create a symlink for strip.

177
178
.. note::

Rahix's avatar
Rahix committed
179
   If you try to flash pycardium_epicardium.bin (renamed to card10.bin)
180
   and the bootloader does not finish updating, the file might be too large.
Rahix's avatar
Rahix committed
181
182
183
184
   ~700kB is the normal size, but problems were reported where the file size
   was >1MB. This was caused by the ``tr`` tool in the build process
   (it's supposed to create a large file with 0xff in it) - this requires the
   LC_ALL environment variable to be not set, or set to "C"
185
   (but not UTF8 or similar).
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207

Docker
======
Alternatively, clone the ``master`` branch of the firmware repository and enter it:

.. code-block:: shell-session

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

Afterwards, build a docker-container which will build the firmware via:

.. code-block:: shell-session

   $ docker build -f docker/Dockerfile_fwbuild -t card10-firmware-builder .

Now, you can start the container with the firmware directory mounted, which will build the
firmware into the firmware/build directory:

.. code-block:: shell-session

   $ docker run -v $(pwd):/firmware card10-firmware-builder