4. How to setup for development

Overview

Development for the Wunderkiste firmware can be done with many different tools, but here's the recommended setup:

• git for sourcecode management
• Visual Studio Code as a text editor / debugging host / IDE
• clang-format auto-formatting
• gcc-arm-none-eabi compiler and toolchain (version 9-2020-q2-update)
• openocd gdb debugging server for connecting to the board

Setup instructions

Git and Github

Wunderkiste is hosted as a git repository. It is helpful to have a basic understanding of what git is and how it's used. I recommend to read this tutorial if you feel unsure.

git can be fully used from the command line, but many prefer to user a graphical user interface like Fork, Sourcetree or Github Desktop. Any of these will be very helpful for a beginner as they visualize the history of changes and the state of your local working copy of the code. A graphical git client (like the ones mentioned above) often brings its own version of git, so you usually don't have to install your own version of git.

If you plan on contributing code to the project, you'll need an account on github. Also make sure to configure your git client (or your local git installation) so that any changes (commits) you make to the code are correctly attributed to your user account on github. Here's a guide that shows you how to do that while hiding your personal email adress. A graphical git client (like the ones mentioned above) typically allows you to configure these settings via their own settings dialog.

clang-format

clang-format is a handy tool for helping you to tidy up your code formatting. It can assist you in fixing indentation, spacing and line breaks to provide a clean, even code style across the project. You don't have to use this tool, but i would recommend to have it installed.

• Windows: Download and install the LLVM setup from here
• linus: Just use your local package manager to install it
• macOS: Homebrew can be used to install clang-format

gcc-arm-none-eabi

gcc-arm-none-eabi is the compiler and toolchain used to build the Wunderkiste source code. Wunderkiste currently uses the version 9-2020-q2-update. Other versions will likely work but produce slightly different machine code. This will typically be irrelevant but we recommend top stick to this version nonetheless.

• Windows:
  1. Download the 9-2020-q2-update installer from https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
  2. Install to the default directory for seamless integration with the build environment: C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update
• macOS / linux:
  1. I recommend simply to place the toolchain into a folder and not use any particular installer. This allows you to use different versions along each other.
  2. Download the 9-2020-q2-update archive from https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
  3. Extract to this directory for seamless integration with the build environment: ~/dev/gcc-arm-none-eabi-9-2020-q2-update

Various other build tools

During the build process, various other build tools are required.

• Windows:
  1. These linux-like build tools are provided via cygwin.
  2. Download the cygwin installer from the cygwin website
  3. Run the installer and install the following packages:
     • gcc-core
     • gcc-g++
     • gdb
     • make
     • pkg-config
• macOS:
  1. Install Xcode and the Xcode command line utilities
• linux:
  1. Install the build-essential package via your package manager.

openocd & hardware drivers

openocd connects to the Wunderkiste hardware, programs it and is a debugging server for gdb.

• Windows:
  1. Download and install openocd from the xpack project
  2. Make sure it is available via the system PATH variable
  3. Download and install the ST-LINK/V2-1 USB driver from the ST website
• macOS:
  1. Download and install openocd from the xpack project
  2. Make sure it is available via the system PATH variable
• linux:
  1. Install openocd via your package manager.

Visual Studio Code

Any text editor can be used to modify the source code. However, it is recommended to use Visual Studio Code as the Wunderkiste project provides integration files for

• syntax highlighting
• compiling
• debugging
• auto-formatting

1. Download and install Visual Studio Code
2. Install the following extensions:
   • C/C++ (syntax highlighting, auto-completion, etc.)
   • Clang-Format (auto-formatting via a keyboard shortcut)
   • GoogleTest Adapter (for displaying and running the unit tests locally)

First steps

1. Open your git client and clone the Wunderkiste repository to a location of your choice. Make sure to also checkout the submodules.
2. Open that folder in Visual Studio Code.
3. Press Ctrl-Shift-B or Cmd-Shift-B and run the build-Wunderkiste task.
4. The code should compile - if not: Check the output from the Visual Studio Code terminal to see what's missing.
5. To run a debugging session:
   1. Connect the board to your computer via a USB cable. Connect to the USB-mini-B connector on the ST-Link side of the board, not the USB-micro-B connector on the other side.
   2. Click on the Run and Debug tab on the left of the Visual Studio Code window.
   3. Run the Launch On Hardware job. A debugging session should start.
6. To run the unit tests locally:
   1. Click on the Run and Debug tab on the left of the Visual Studio Code window.
   2. Run the Launch Tests Locally job.
   3. You can also run tests from the Test tab on the left of the Visual Studio Code window.
7. You can build the firmware directly from the commandline by executing make all in the firmware directory
8. You can program the firmware directly from the commandline by executing make upload in the firmware directory
9. You can build the unit tests directly from the commandline by executing make in the firmware/tests directory
10. You can run the unit tests directly from the commandline by executing Wunderkiste_gtest(.exe) in the tests/build/bin/ directory