###### tags: `FP-Mission` `F'` `FS` `Flight software`

# :computer: Quick-start guide - FP-Mission FS

[TOC]

## 1. Introduction

The current document describes how to start with the developement of the FP-Mission flight software (FS) used during FP1, the first mission with the goal of launching a flight software in a weather balloon at HE-Arc. It has been implemented with the [NASA F' framework](https://github.com/nasa/fprime).

The flight software runs on a [Raspberry Pi Zero](https://www.raspberrypi.org/products/raspberry-pi-zero/). A [Sense Hat (B)](https://www.waveshare.com/wiki/Sense_HAT_(B)) board is added to provide sensors and a [FlexTrak](https://store.uputronics.com/index.php) is used to ensure downlink communication through LoRa. The uplink communication is handled by a [RockBlock 9603](https://www.rock7.com/products/rockblock-9603-compact-plug-play-satellite-transmitter) sattelite module. Furthermore, a [PiCamera module V2](https://www.raspberrypi.org/products/camera-module-v2/) allows to take pictures.


In the polystyrene probe, a [SPOT Trace](https://www.stratoflights.com/fr/boutique/spot-trace/) and a [GPS Tracker TK102](https://www.stratoflights.com/en/shop/gps-tracker-tk102) are used for recovery and a GoPro records the entire flight.

On the ground, the [LoRaGo](https://store.uputronics.com/index.php?route=product/product&product_id=111) module has been used connected to a computer. We adapted the FPrime GDS software to interract with the flight software through LoRa. At any time, the software can be used with IP communication intead of LoRa by changing [the code](https://github.com/FP-Mission/FS/blob/9ba06e7d787c82e7c64b5991a5382afd0f878854/App/Top/AppTopologyAppAi.xml#L107).

The codes used during the development are on the [FP-Mission GitHub](https://github.com/FP-Mission), accessible by invitation. A [Google Drive](https://drive.google.com/drive/folders/1Gx93EYfRDdGkLCHztBa9lvdN69dLiy0t?usp=sharing) has been used for file storage.

To discover the FPrime framework, read the [F´ Discerning User’s Guide](https://nasa.github.io/fprime/UsersGuide/guide.html). The [Tutorials](https://nasa.github.io/fprime/Tutorials/README.html) are a very good way to understand it. More resources (Community Forum, Reference Application, F' Architecture Overview) are available on [nasa.github.io/fprime](https://nasa.github.io/fprime/)

The report of the Master thesis made for CHESS by Jonathan Michel can be found [here](https://drive.google.com/file/d/1exxebI5Ru-1k3Oo5sElTctQnxZj8tmkx/view?usp=sharing). Among others, it presents F' and the OSAL implementation for FreeRTOS.

The topology implemented is presented in the picture below. This document can be read on Lucidchart with [this link](https://lucid.app/lucidchart/invitations/accept/inv_4fc482fa-d2d0-4862-acf7-e2d0177fe08f?viewport_loc=798%2C-2%2C4069%2C1954%2C0_0).


### Devices info
#### On the RaspberryPi
RockBlock: /dev/ttyUSB0 @19200Bd
FlexTrak: /dev/ttyAMA0 @38400Bd

#### On the ground station
LoRaGo: /dev/ttySx @57600Bd, x depends on the windows COMx port

## 2. Set up development environment

### Development platform
#### Windows with WSL2
We made our development on Windows 10 by using *Windows Subsytem for Linux* for compilation. It allows running a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.

Follow [this tutorial](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to enable and install **WSL**. Concerning distribution, we used *Ubuntu 18.04.5 LTS*, we recommend downloading it directly from the [Windows Store](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot:overviewtab).

:::danger
We recommend using WSL and not WLS**2**. WSL2 does not allow to access Windows COM port. According to their GitHub, there is no support for serial and USB, see [FAQ](https://docs.microsoft.com/en-us/windows/wsl/wsl2-faq#can-i-access-the-gpu-in-wsl-2--are-there-plans-to-increase-hardware-support-) and [issue 4322](https://github.com/microsoft/WSL/issues/4322) for details. In our case, it means that the LoRaGo module can not be used with GDS. We also encountered problems with WSL2 for IP communication.
:::

Once started, user arrives in standard `/home/[username]/` folder. Windows files will be accessible on `/mnt/c/Users/[username]/`. It will allow accessing Windows files through the Windows explorer but use Linux commands through WSL. On the other hand, user can access Linux directories from Windows in `\\wsl$` (Network drive in Windows).

:::info
:wink: We recommend downloading new [Windows terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab) instead of using the default distribution console available after installation. You can configure the default profile (Powershell, Command prompt or Distribution) in the settings, see [here](https://docs.microsoft.com/en-us/windows/terminal/customize-settings/profile-settings#unique-identifier) for detail.
:::

We also used virtual machines running Ubuntu but encoured network issues during development. The WSL is a lighter and better choice.

#### Linux
If you have a Linux distribution installed on your computer, you can directly use it for FS development. We recommend using Ubunutu but didn't expect any major issues with other Linux distributions.

### Requirements
- GCC compiler GCC 7.5.0
`sudo apt install build-essential`
- CMake 3.5 or newer (3.10.2 used)
`sudo apt install cmake`
- Python 3.5+, PIP and Python Virtual Environment
`sudo apt install python3 python3-pip python3-venv
`

### Visual Studio Code

We used [Visual Studio Code](https://code.visualstudio.com/) for code editing. It is a light, free but poweful IDE with many extensions for customisation. It is available on Windows, Linux and MacOS. You can simply open the base code folder with `code .` from the WSL2 terminal and VSCode will index all files and facilitate development.

Please note you need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension to open a WSL project in VSCode. You can ensure that VSCode is correctly using WSL by checking on bottom left.


You will also need the [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension that adds language support for C/C++, including features such as IntelliSense and debugging.

The [CMake](https://marketplace.visualstudio.com/items?itemName=twxs.cmake) extension can also be usefull when dealing with CMake files.

:::info
See [Advanced configuration](#5-Visual-Studio-Code-advanced-configuration) to configure VSCode for compilation and debug.
:::

### OhMyZsh

:::warning
:nerd_face: For advanced users only
:::

Using F' requires to use the command line frequently, we recommend upgrading the default terminal by installing [OhMyZsh](https://github.com/ohmyzsh/ohmyzsh). Some plugins will facilitate development : [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions), [syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting) and [zsh-completions](https://github.com/zsh-users/zsh-completions). [Here](https://gist.github.com/dogrocker/1efb8fd9427779c827058f873b94df95) is an example how to install Zsh plugins.

For visual preferences, [Powerlevel10k](https://github.com/romkatv/powerlevel10k) Zsh theme allow customising the command line display.

In case character display doesn't work correctly in Windows Terminal with OhMyZsh, check [this tutorial](https://docs.microsoft.com/en-us/windows/terminal/tutorials/powerline-setup) about Powerline set up.

## 3. Clone code and compile it

### Get repository
Clone main repository [FP-Mission/FS](https://github.com/FP-Mission/FS) with F' submodule ([FP-Mission/fprime](https://github.com/FP-Mission/fprime)).

:warning: We recommand cloning the repository in the Linux directories, for example in `/home/[user]`. You could also chose to use Windows directory but the compilation will be slower.

git clone --recurse-submodules -j$("nproc") https://github.com/FP-Mission/FS.git

Checkout the branch you want, current development is under [dev](https://github.com/FP-mission/FS/tree/dev).

:::info
The `-j$("nproc")` argument allow parallel processing
:::

### Tools installation

Create Python virtual environment and install `fprime-util` and `fprime-gds` Python commands. Ensure Python 3, pip and venv are corretly installed as listed in [Requirements](#Requirements).

cd 05_FS
python3 -m venv ./fprime-venv
. ./fprime-venv/bin/activate
python3 -m pip install --upgrade wheel setuptools pip
python3 -m pip install pyserial PyYAML requests
cd fprime
python3 -m pip install ./Fw/Python ./Gds

:::warning
:warning: You will have to activate Python virtual environment each time you would like to use `fprime-util` and `fprime-gds`!
:::

:::warning
:computer: In case you want to develop GDS or FPrime python code, use `python3 -m pip install -e ./Fw/Python ./Gds` to force sources reload before launch. Without the `-e` option, you will have to reinstall FPrime and Gds modules for changes.
:::

:::info
:bulb: Add alias with `alias fu=fprime-util` for faster usage. Add it to `~/.bashrc` (or `~/.zshrc` if using Zsh) to save it between terminal restart.
:::

### F' compilation

:::danger
The current version of the flight software can not be cross-compiled for the RapsberryPi because of libraries (*WiringPi* used by the SenseHat component and *RaspiCam* used by the PiCamera component) that are not available in the standard RaspberryPi toolchain. We recommend to deploy the flight software code on a Raspberry Pi 3(B)(+)/4 for compilation and use VSCode to access files remotely through SSH (tutorial [here](https://code.visualstudio.com/docs/remote/ssh)). Once compiled, the executable binary can be copied to the Raspberry Pi Zero for execution. Note that the Pi Zero does not support remote SSH access from VSCode and that the compilation is pretty slow on it.

The only specificity for this configuration is that the code has to be cloned on the host computer (running Ubuntu) for GDS launch and on a target computer (Pi) for compilation. More details in [chapter 4](#4-Launch-flight-software).

If required the `flextrak` branch can be easily cross-compiled because it does not contain SenseHat or PiCamera components. Details [below](#Raspberry-Pi-compilation).
:::

In the `FS/App` directory, generate build directories. This step will parse F' .xml files and autocoder will create base F' codes.

fprime-util generate

New build folders should have appeared in `App`:

FS/App
└── build-fprime-automatic-native

You can now build components implementation and full App topology with

fprime-util build -j$("nproc")

The `-j$("nproc")` option allows parallel build job for better performances. `nproc` returns the maximum cores you have on your computer.

The compiled binary will be in `build-fprime-automatic-native/bin/Linux/App`. If you build the code on a Raspberry Pi, the path will be slighty different.

#### Raspberry Pi cross-compilation
F' can be cross-compiled for Raspberry Pi (see [above note](#F’-compilation)!). By default, the flight software is compiled for the host architecture (Linux if the code is deployed on Ubuntu for example). In order to cross-compile for a specific architecture (ARM in our case), the user needs to generate a new build directory using a toolchain file for that architecture. F´ includes a toolchain for the Raspberry Pi called “raspberrypi”. It requires to have the Raspberry Pi cross-compile tools installed. They can be cloned from [github.com/raspberrypi/tools](https://github.com/raspberrypi/tools) in `/opt/rpi`. If the tools are installed elsewhere, the user can set the environment variable `RPI_TOOLCHAIN_DIR` to the tools directory.

The build can be generated by running the following commands in the `App` directory:

fprime-util generate rapsberrypi
fprime-util build raspberrypi

The generated binary will be in `App/build-fprime-automatic-raspberrypi/bin/arm-linux-gnueabihf/App/`.

:::info
If the code is deployed on a Raspberry Pi, standard `fprime-util generate` and `fprime-util build` commands will compile the software for ARM.
:::

## 4. Launch flight software

### Launch F'
Launch flight software program on the RaspberryPi:

./App -a [hostIp] -p 50000

`[hostIp]` has to be the IP of the host computer running GDS.
`50000` represents the port of the GDS server

### Lauch F' GDS
Launch GDS (F' ground software) with its HTML GUI on the host computer.

fprime-gds --no-app

:::info
`fprime-gds` without the `--no-app` argument would launch F' and GDS together, both on the host computer.
:::

GDS requires a dictionnary (`/App/Top/AppTopologyAppDictionary.xml`) that is generated during compilation. It describes all the commands/events/channels in the application. If the flight software is compiled on a target computer (Pi), this file can be manually cloned on the host computer and passed to GDS with the following command:

fprime-gds --dictionary [path]/FS/App/Top/AppTopologyAppDictionary.xml --no-app

## 5. Debug F' application

:::warning
In order to debug the F' application, debug symbols must be generated in the application binary. Make sure following lines is in your `App/Cmakelists.txt` **before any other CMake file inclusion**.

// Enable debug symbols and disable optimization for easier debug
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -O0")

:::

:::danger
Debug has only been tested when running previous version of the flight software on Linux (Virtual Machine) and on Windows with VSCode opening WSL project. Remote debug when running the FS on the Pi has no been used.
If required, `gdb-multiarch` should be used on the host computer and `gdb-server` on the Pi.
:::

Type `Debug: Open launch.json` in the VSCode Command Palette (`Ctrl+Shift+P`). Copy the following code into the opened `launch.json` file:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Launch",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/App/build-fprime-automatic-native/bin/Linux/App",
            "args": ["-a127.0.0.1", "-p50000"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [ 

            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

If need, adapt the `program` variable with the path to your binary.

You can now compile your code from the terminal using standard `fprime-util build -j 8` and debug the application in VS Code by choosing *Run* → *Start debugging* or directly with press *F5*.


You can add a new terminal in VS Code to launch build command from the IDE. See [here](https://code.visualstudio.com/docs/editor/integrated-terminal#_managing-multiple-terminals) for details.

## 6. Visual Studio Code advanced configuration

### Configure CMake in VSCode

F´ typically builds by-hand using the F´ utility `fprime-util` . This utility automates away many of the details of setting up an F´ build and should make it easy for users to build, run, and test F´ from the commandline.

However, if need, the user can chose to configure VSCode's CMake plugin to have full IDE support. To do such, user will have to identify F' build information and setting up CMake and build variables. More information can be found [here](https://nasa.github.io/fprime/UsersGuide/dev/configure-ide.html).

:::info
At the time this guide was written, detailed explanations for IDE configuration weren't described. Instead of configuring CMake plugin, we recommend using VSCode's tasks as presented in [next chapter](#Using-tasks-to-automatically-build-project-launch-gds-%E2%80%A6).
:::

### Using tasks to automatically build project, launch gds, ...
In order to avoid typing commands into the terminal, we can automate their execution with VSCode tasks. More details can be found [here](https://code.visualstudio.com/docs/editor/tasks).

To simplify development mutliple tasks are proposed :
- **build-app**: Launch `fprime-build` to compile App topology. (Configured as default build task)
- **generate**: Purge and generate build directories for App
- **launch**: Launch F' GDS and application, both on the host computer (deprecated)
- **launch-gds**: Launch F' GDS alone without application
- **deploy-pi**: Copy the application binary to the PiZero
- **launch-pi**: Launch the application on the PiZero

For the last two tasks, we recommend setting a passwordless SSH access with the PiZero, tutorial [here](https://www.raspberrypi.org/documentation/remote-access/ssh/passwordless.md).

Depending on task, parameters will be prompt to user when launching application. The followings are available:
* **toolchain**: "raspberrypi" or "" (default - depends on the host)

Copy the following json content in the `.vscode/tasks.json` at the root of your workspace. Change `[piIp]` with the PiZero IP and `[hostIP]` with the IP of the host computer running GDS.

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build-app",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-util build ${input:toolchain} -j\"$(nproc)\"",
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "generate",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-util purge -f;  rm -rf build-*; fprime-util generate ${input:toolchain}",
            "problemMatcher": []
        },
        {
            "label": "launch",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-gds --app ./build-fprime-automatic-native/bin/Linux/App",
            "problemMatcher": []
        }
        {
            "label": "launch-gds",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-gds -n --dictionary ./Top/AppTopologyAppDictionary.xml",
            "problemMatcher": []
        },
        {
            "label": "deploy-pi",
            "type": "shell",
            "command": "scp App/build-fprime-automatic-raspberrypi/bin/arm-linux-gnueabihf/App pi@[piIp]:/home/pi/ ",
            "problemMatcher": []
        },
        {
            "label": "launch-pi",
            "type": "shell",
            "command": "ssh pi@[piIp] \"./App -a [hostIP] -p 50000\" ",
            "problemMatcher": []
        }
    ],
    "inputs": [
      {
        "id": "toolchain",
        "type": "pickString",
        "description": "Specify toolchain",
        "options": [
            "",
            "raspberrypi"
        ],
        "default": "raspberrypi"
      }
    ]
}

You can launch tasks from the Command Palette (`Ctrl+Shift+P`) by typing *Run tasks* and selecting the one you want. Default build task (build-app) can be launched with `Ctrl+Shift+B`.

If wanted, you can compile the application before debugging. To do it, append this attribute to the `configurations` array in the inital `launch.json` file :

"preLaunchTask": "build-app"

### Code formatting

:::danger
Currently the following doesn't work when opening a WSL project. *(VSCode v1.52)*
:::

To facilitate versionning and code analysis betwen different members, we chose to use a clang-format through our code. To configure it, go to *File* → *Preferences* → *Settings* (or type `Ctrl+,`) and type format in the search bar. In the *Remote [WSL]* tab, select *C/C++* in the result list and set *C_Cpp: Clang_format_fallback Style* as follow :

{ BasedOnStyle: Google, IndentWidth: 4 }


You can now reformat a document by typing `Shift+Alt+F`.

:::warning
F' developers are currently working on setting up clang-format on F'. It will allow us to facilitate code merging of future releases on our fork. However, the specific format has not been chosen. We recommend avoiding using clang format in F' core code for now. More details [here](https://groups.google.com/g/fprime-community/c/mh1oDGauTwI).
:::