diff --git a/README.md b/README.md index c4592ff..479ed8f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + # FSFW Example Application @@ -54,17 +54,22 @@ as long as OpenOCD integration is given. The example demo uses newlib nano (glib Some system calls were overriden so the C and C++ stdio functions work. IO is sent via the HUART3, so debug output can be read directly from the USB connection to the board. -## Prerequisite +## Prerequisites -1. [MinGW64](https://www.msys2.org/) or [Ninja Build](https://ninja-build.org/) installed on Windows. - Not required on Linux. -2. [GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/) installed, recommended - to add binaries to system path. -3. Recommended for application code development: +If you have not set up the prerequisites yet, go to the [prerequisites chapter](#prereq) for +detailed instructions on how to install these. + +Here is a brief overview of the required tools to develop software for the STM32H7 microcontroller: + +1. CMake build system generator installed +2. Build system like [Ninja Build](https://ninja-build.org/) or [Make](https://www.msys2.org/) + installed. +3. Bare-Metal ARM toolchain installed +4. Recommended for application code development: [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU plugin -4. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging -5. STM32 USB drivers installed, separate steps for +5. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging +6. STM32 USB drivers installed, separate steps for [Windows](https://www.st.com/en/development-tools/stsw-link009.html) or [Linux](https://fishpepper.de/2016/09/16/installing-using-st-link-v2-to-flash-stm32-on-linux/) @@ -131,79 +136,143 @@ after installing MSYS2 or inside another Unix shell like `git bash`. The debug output is also sent via the connected USB port and a blink pattern (1 second interval) can be used to verify the software is running properly. -## Setting up the prerequisites +## Setting up Prerequisites -### Windows +### CMake -It is recommended to install [MSYS2](https://www.msys2.org/) first. -Open MinGW64 and run the following commands to update it and install make and cmake -(replace x86_64 if compiling on different architecture): +**Linux** ```sh -pacman -Syu +sudo apt-get install cmake ``` -```sh -pacman -S mingw-w64-x86_64-make mingw-w64-x86_64-cmake -``` +**Windows** -Alternatively, you can install [Ninja Build](https://ninja-build.org/), but you need -to add the folder containing the `ninja.exe` executable to the system path so you -can run `ninja -v` from the command line. If you do this, you can also use -`git bash` or the Windows command lines with the CMake Ninja generator -to build the software. +On Windows, you can use `pacman -S mingw-w64-x86_64-cmake`, but you can also install the Windows +CMake via the [installer](https://cmake.org/download/). It is recommended to pick the install +option `Add CMake to system PATH for all users` to CMake can be used from the command line. +Please note that you need to add the Windows CMake path to the MinGW64 path manually +if you want to use it in CMake. -The code needs to be cross-compiled for the ARM target system and we will use the -[GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/). +### Cross-Compiler -1. Install NodeJS LTS. Add nodejs folder (e.g. "C:\Program Files\nodejs\") - to system variables. Test by running `npm --version` in command line -2. Install [XPM](https://www.npmjs.com/package/xpm) - ```sh - npm install --global xpm - ``` - -3. Install gnu-arm Toolchain for Eclipse (version can be specified) - ```sh - xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@latest - ``` - - `xpm` will display where the package was installed. Search in that path for - the hidden `.content` folder, which will contain a `bin` folder and store - the full path to that `bin` folder for later. - - Install OpenOCD for STM32 debugging - ```sh - xpm install --global @xpack-dev-tools/openocd@latest - ``` - -4. If you want to build from the command line, you need to add the `arm-none-eabi-gcc` - binary location in the xPack folder to system variables. You can do this in a Unix - shell like `git bash` or `MinGW64` with the following command - - ```sh - export PATH=$PATH:"" - ``` - - You can also add these lines to a shell script like `path_setter.sh` and then source - the script with `. path_setter.sh` to do this conveniently. You can test whether - the path was set up properly by running `arm-none-eabi-gcc -v` - -5. Install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html) +The instuctions here specify how to install and use a specific version of the xPacks cross-compiler +but you can use any other ARM cross-compiler which can generate bare-metal code, usually denoted by +the `arm-none-eabi` cross-compiler triplet. If you don't want to install nodejs you may go with the [four-command manual installation](https://xpack.github.io/arm-none-eabi-gcc/install/#manual-install). -### Linux +**Windows** + +On Windows, it is recommended to perform the `xpm` and toolchain installation from the Windows +command line.The simple way required npm, which can be installed by installing +[NodeJS](https://nodejs.org/en/). Make sure `npm` can be run from the command line by adding +the folder containing `npm.exe` to the system path and running the following command -Install the [GNU ARM toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/) -like explained above. - -To install general buildtools for the linux binary, run: ```sh -sudo apt-get install build-essential +npm install --global xpm@latest +xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@10.3.1-2.3.1 --verbose ``` +On Windows, the toolchain binaries will be located in a folder like this + +```sh +C:\Users\\AppData\Roaming\xPacks\@xpack-dev-tools\arm-none-eabi-gcc\\.content\bin +``` + +You can now run the following commands in the repository root: + +```sh +xpm init +xpm install @xpack-dev-tools/arm-none-eabi-gcc@10.3.1-2.3.1 +``` + +to create symlinks to the toolchain in `./xpacks/.bin`. +You can now set up the environment by using `. load_path.sh` or the following command + +```sh +export PATH="$(pwd)/xpacks/.bin":$PATH +``` + +On Windows, you can use the graphical system environmental variables editor to add the +`.bin` path to the system variables permanently or use the appriate command for `CMD` or +PowerShell to update the `PATH` + + +**Linux** + +Install `npm` and `nodejs` first. Example for Ubuntu according to +[this guide](https://linuxize.com/post/how-to-install-node-js-on-ubuntu-20-04/). + +```sh +curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - +sudo apt-get update && sudo apt-get install nodejs +``` + +Check that `npm` is installed with `npm --version`. +Then `xpm` and the cross-compiler are installed. + +```sh +sudo npm install --global xpm@latest +xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@10.3.1-2.3.1 --verbose +``` + +You can now run the following commands in the repository root: + +```sh +xpm init +xpm install @xpack-dev-tools/arm-none-eabi-gcc@10.3.1-2.3.1 +``` + +to create symlinks to the toolchain in `./xpacks/.bin`. +You can now set up the environment by using `. load_path.sh` or the following command + +```sh +export PATH="$(pwd)/xpacks/.bin":$PATH +``` + +### Build System + +It is recommended to use `ninja` or `make` as the software build system. + +**Windows** + +It is recommended to use the [Ninja build system](https://ninja-build.org/). Download the ninja +executable and place it somewhere. +You need to add the folder containing the ninja executable to the system environmental variables +so it can be used in the build process. You can test whether `ninja` works by running +`ninja --version` in the command line. + +Alternatively or additionally, you can also install `mingw32-make` +which comes bundled with [MinGW64](https://www.msys2.org/). Make sure to add the binaries path to +the Windows path during installation. Otherwise, you need to add `msys64/mingw64/bin` to the +Windows path so you can run installed binaries from the command line. +Open the `MinGW64` shell and run the following commands. + +```sh +pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-make mingw-w64-x86_64-cmake +``` + +You can test successfull installation with `mingw32-make -v` from the Windows Command Line. + +**Linux** + +On Linux, `make` is pre-installed and it is recommended to use it directly. +You can install `ninja` with + +```sh +sudo apt-get install ninja-build +``` + +### USB Drivers + +**Windows** + +Install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html). + +**Linux** + Install the [USB drivers](https://github.com/stlink-org/stlink) on Linux. On Ubuntu, you can run the following command to install it: