###### tags: `F'` `FS` `Flight software`

# :computer: Quick-start guide - CHESS FS

[TOC]

## 1. Set up development environment

### Development platform
#### Windows with WSL2
We made our development on Windows 10 by using *Windows Subsytem for Linux 2* 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 **WSL2**. 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).

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 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.

## 2. Clone code and compile it

### Get repository
Clone [main repository](https://github.com/CHESS-mission/05_FS.git) and F' submodule.

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

git clone --recurse-submodules -j8 https://github.com/CHESS-mission/05_FS.git

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

:warning: To use [PUSOpen](https://12gfs.com/) lib, you will have to clone [CHESS-mission/pusopen](https://github.com/CHESS-mission/pusopen) into `fprime` as a Lib folder.

cd fprime
git clone https://github.com/CHESS-mission/pusopen.git Lib

### 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
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 source reload before launch. Without the `-e` option, you will have to reinstall FPrime and Gds command 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
In the `05_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`:

05_FS/App
├── build-fprime-automatic-native
└── build-fprime-automatic-native-ut

You can now build components implementation and full App topology with

fprime-util build -j8

The `-j8` option allows parallel build job for better performances. Use `nproc` to know the maximum cores you have on your computer.

The compiled binary will be in `build-fprime-automatic-native/bin/Linux/App`.

#### Raspberry Pi compilation
F' can easily be build for Raspberry Pi. In order to cross-compile for the a specific architecture, 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/bin/arm-linux-gnueabihf/App/`.

## 3. Launch flight software

### Launch F'
Launch flight software program in the `App` directory:

./build-fprime-automatic-native/bin/Linux/App -a 127.0.0.1 -p [port]

IP and port are the ones of the ground software used.

#### [port] value
- 50000 - F' GDS server (no PUS support)
- 27015 - Custom GS (PUS support)

### Lauch ground software

#### Use F' GDS (no PUS support)
Launch GDS (F' ground software) with its HTML GUI

fprime-gds -n

:::info
`fprime-gds` without the `-n` argument will launch F' and GDS together
:::

#### Use custom GS (PUS support)

cd 05_FS/gs/gs
cmake .
make
./gs

The `main_gs.cpp` file contains the ground software code. It simply receives telemetry and event reports and dispay them in the console. Commands can be send to the flight software at launch by un-commenting macros at the beginning of the file.

## 4. 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")

:::

:::info
Debug has only been tested on Linux (Virtual Machine) and on Windows with VSCode opening WSL project.
:::

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.

## 5. 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 five 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
- **launch-gds**: Launch F' GDS alone without application
- **launch-app**: Launch application and connect it to GS

Depending on task, parameters will be prompt to user when launching application. The followings are available:
* **platform**: Linux (default) or FreeRTOSSim
* **GS_port**: 50000 (default, for GDS) or 27015 (for PUS GS) →

Copy the following json content in the `.vscode/tasks.json` at the root of your workspace.

{
    // 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 -j 8",
            "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",
            "problemMatcher": []
        },
        {
            "label": "launch",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-gds --app ./build-fprime-automatic-native/bin/${input:platform}/App",
            "problemMatcher": []
        },
        {
            "label": "launch-app",
            "type": "shell",
            "command": "./App/build-fprime-automatic-native/bin/${input:platform}/App -a 127.0.0.1 -p ${input:GS_port}",
            "problemMatcher": []
        },
        {
            "label": "launch-gds",
            "type": "shell",
            "command": ". ./fprime-venv/bin/activate; cd App; fprime-gds -n --dictionary ./Top/AppTopologyAppDictionary.xml",
            "problemMatcher": []
        }
    ],
    "inputs": [
      {
        "id": "platform",
        "type": "pickString",
        "description": "Specify platform",
        "options": [
            "Linux",
            "FreeRTOSSim"
        ],
        "default": "Linux"
      },
      {
        "id": "GS_port",
        "type": "pickString",
        "description": "Specify GS port",
        "options": [
            "50000",
            "27015"
        ],
        "default": "27015"
      }
    ]
}

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).
:::